aiot-app/uni_modules/dy-date-time-picker

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 规范）。

🧩 快速上手

<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>

🧩 完整用法

<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 两个具名作用域插槽。传入插槽后，会替换对应的默认触发器，使用者可以完全自定义入口样式。

<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 主动打开日期或时间弹窗。

<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>

也可以直接调用原方法：

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 数据结构

日期选择（单选/范围）

{ 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' } }

月份选择（单选/范围）

{ month: '2023-10', time: { ... } }
{ startMonth: '2023-09', endMonth: '2023-12', time: { ... } }

年份选择（单选/范围）

{ year: '2023', time: { ... } }
{ startYear: '2025', endYear: '2026', time: { ... } }

周选择（单选/范围）

{
  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