# dy-date-time-picker 日期时间选择器

用于 uni-app 的日期 + 时间筛选组件，支持日期/月份/年份/周单选与范围选择，并提供独立时间段选择。

## 🎯 适用场景
- 列表筛选（订单、报表、日志等）
- 统计时间区间选择
- 需要日期/月份/年份/周一体化筛选的业务

## ✨ 特性
- 双触发器（日期 / 时间）
- 日期/月份/年份/周：单选与范围合一
- 时间段：全天/上午/下午快捷选择 + 自定义范围（00:00-23:59，半小时刻度）
- 支持按类型启用/禁用日期筛选项
- 统一返回数据结构，便于接口对接
- Vue2/Vue3 兼容（已适配 v-model 与 update:modelValue）
- 支持 `date-trigger` / `time-trigger` 具名作用域插槽，可完整自定义日期/时间触发器样式
- 支持通过 `ref` 主动打开日期或时间弹窗

## ✅ 已测试平台
- 微信小程序

## ⚠️ 其他平台
以下平台尚未验证，理论上兼容，请自行测试：
- App (app-vue、app-nvue)
- H5 (移动端/PC端)
- 支付宝/百度/抖音/QQ/钉钉/快手/飞书/京东 小程序
- 华为快应用、联盟快应用
- 云端：腾讯云 tcb、阿里云 aliyun、支付宝小程序云

## 📦 安装
在 DCloud 插件市场导入本插件（uni_modules 规范）。

## 🧩 快速上手
```html
<template>
  <view>
    <dy-date-time-picker
      v-model="dateFilterValue"
      placeholder="选择年份/月份/日期/周"
      @change="handleChange"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      dateFilterValue: null
    }
  },
  methods: {
    handleChange(val) {
      console.log('选择结果:', val)
    }
  }
}
</script>
```

## 🧩 完整用法
```html
<template>
  <view>
    <dy-date-time-picker
      v-model="dateFilterValue"
      :minYear="2020"
      :maxYear="2030"
      :typeEnabled="{ date: true, month: true, year: true, week: true }"
      placeholder="选择年份/月份/日期/周"
      timePlaceholder="筛选时间"
      @change="handleChange"
      @input="handleInput"
      @update:modelValue="handleModelUpdate"
    />
  </view>
</template>

<script>
export default {
  data() {
    return {
      dateFilterValue: {
        startDate: '2026-01-01',
        endDate: '2026-01-07',
        time: { startTime: '09:00', endTime: '18:00' }
      }
    }
  },
  methods: {
    handleChange(val) {
      console.log('change(确认):', val)
    },
    handleInput(val) {
      console.log('input(Vue2同步):', val)
    },
    handleModelUpdate(val) {
      console.log('update:modelValue(Vue3同步):', val)
    }
  }
}
</script>
```

## 🎨 自定义触发器插槽

组件提供 `date-trigger` 和 `time-trigger` 两个具名作用域插槽。传入插槽后，会替换对应的默认触发器，使用者可以完全自定义入口样式。

```html
<template>
  <view>
    <dy-date-time-picker v-model="dateFilterValue">
      <template #date-trigger="{ text, hasValue, open, clear }">
        <view class="my-trigger" @click="open">
          <text>{{ text }}</text>
          <text v-if="hasValue" @click.stop="clear">清空</text>
        </view>
      </template>

      <template #time-trigger="{ text, hasValue, open, clear }">
        <view class="my-trigger" @click="open">
          <text>{{ text }}</text>
          <text v-if="hasValue" @click.stop="clear">清空</text>
        </view>
      </template>
    </dy-date-time-picker>
  </view>
</template>
```

### 插槽参数

| 插槽名 | 参数 | 类型 | 说明 |
| --- | --- | --- | --- |
| `date-trigger` / `time-trigger` | `text` | `String` | 当前展示文案；没有值时为对应占位文案 |
| `date-trigger` / `time-trigger` | `displayText` | `String` | 当前值格式化后的展示文案；没有值时为空字符串 |
| `date-trigger` / `time-trigger` | `placeholder` | `String` | 占位文案 |
| `date-trigger` / `time-trigger` | `hasValue` | `Boolean` | 当前日期或时间是否已有值 |
| `date-trigger` / `time-trigger` | `open` | `Function` | 打开对应弹窗 |
| `date-trigger` / `time-trigger` | `clear` | `Function` | 清空对应日期或时间值 |
| `date-trigger` / `time-trigger` | `value` | `String` / `Object` | 当前绑定值 |

> 注意：如果自定义插槽内有“清空”按钮，建议使用 `@click.stop="clear"`，避免点击清空时同时触发打开弹窗。

## 🕹️ 主动打开/关闭弹窗

可以通过组件 `ref` 主动打开日期或时间弹窗。

```html
<template>
  <view>
    <dy-date-time-picker ref="dateTimePicker" v-model="dateFilterValue" />

    <button @click="openDate">打开日期弹窗</button>
    <button @click="openTime">打开时间弹窗</button>
    <button @click="closePicker">关闭弹窗</button>
  </view>
</template>

<script>
export default {
  data() {
    return {
      dateFilterValue: null
    }
  },
  methods: {
    openDate() {
      this.$refs.dateTimePicker.open('date')
    },
    openTime() {
      this.$refs.dateTimePicker.open('time')
    },
    closePicker() {
      this.$refs.dateTimePicker.close()
    }
  }
}
</script>
```

也可以直接调用原方法：

```js
this.$refs.dateTimePicker.openPopup('date')
this.$refs.dateTimePicker.openPopup('time')
this.$refs.dateTimePicker.openDatePopup()
this.$refs.dateTimePicker.openTimePopup()
this.$refs.dateTimePicker.closePopup()
```

## ⚙️ Props

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `value` / `v-model` | `String` / `Object` | `''` | 绑定值（字符串或对象） |
| `modelValue` | `String` / `Object` | `undefined` | Vue3 v-model 值 |
| `minYear` | `Number` | `2004` | 年份最小值 |
| `maxYear` | `Number` | `当前年份` | 年份最大值 |
| `placeholder` | `String` | `'选择日期'` | 日期触发器占位 |
| `timePlaceholder` | `String` | `'筛选时间'` | 时间触发器占位 |
| `typeEnabled` | `Object` | `{ date: true, month: true, year: true, week: true }` | 类型开关（date/month/year/week），设置为 `false` 时不显示对应类型 |

## 📣 Events

| 事件名 | 说明 | 回调参数 |
| --- | --- | --- |
| `change` | 用户点击弹窗“确定”时触发，业务处理主入口 | `(value: Object)` |
| `input` | Vue2 v-model 同步事件 | `(value: Object)` |
| `update:modelValue` | Vue3 v-model 同步事件 | `(value: Object)` |

## 🧰 Methods

通过 `ref` 调用：

| 方法名 | 参数 | 说明 |
| --- | --- | --- |
| `open(type)` | `type?: 'date' \| 'time'`，默认 `'date'` | 打开日期或时间弹窗 |
| `openPopup(type)` | `type?: 'date' \| 'time'`，默认 `'date'` | 打开日期或时间弹窗 |
| `openDatePopup()` | - | 打开日期弹窗 |
| `openTimePopup()` | - | 打开时间弹窗 |
| `close()` | - | 关闭弹窗 |
| `closePopup()` | - | 关闭弹窗 |

## 📄 Value 数据结构

**日期选择（单选/范围）**
```js
{ date: '2023-10-01', time: { startTime: '09:00', endTime: '12:00' } }
{ startDate: '2023-10-01', endDate: '2023-10-07', time: { startTime: '00:00', endTime: '23:59' } }
```

**月份选择（单选/范围）**
```js
{ month: '2023-10', time: { ... } }
{ startMonth: '2023-09', endMonth: '2023-12', time: { ... } }
```

**年份选择（单选/范围）**
```js
{ year: '2023', time: { ... } }
{ startYear: '2025', endYear: '2026', time: { ... } }
```

**周选择（单选/范围）**
```js
{
  week: '2026-W03',
  weekStartDate: '2026-01-12',
  weekEndDate: '2026-01-18',
  time: { ... }
}
{
  startWeek: '2026-W03',
  endWeek: '2026-W12',
  weekStartDate: '2026-01-12',
  weekEndDate: '2026-03-22',
  time: { ... }
}
```

## 🔁 兼容说明
- 本次新增 `timePlaceholder`、插槽和实例方法均为增量能力。
- 不传 `date-trigger` / `time-trigger` 插槽时，默认触发器结构、样式、点击行为保持原样。
- 原有 `v-model` / `value` / `modelValue`、`change` / `input` / `update:modelValue`、返回值结构均保持兼容。
- 原内部方法 `openDatePopup()`、`openTimePopup()`、`closePopup()` 保留，可继续通过 `ref` 调用。

## 📝 注意事项
- 组件依赖 `uni-app` 环境。
- 需要项目启用 `scss/sass` 支持。
- 时间“全天”回显为 `00:00-23:59`。
- 关闭某个 type 后，该类型 Tab 不显示，但原有值结构仍兼容回显。

## 📄 License
MIT