更新记录

1.0.0（2026-11-03） 下载此版本

新增

• 基于 picker-view 的日期时间选择器组件 v-datetime-picker
• 多列联动：默认 5 级（年 / 月 / 日 / 时 / 分），format 含秒时扩展为 6 级
• 格式设置：format 决定显示列与顺序（可为仅年月、仅时分等任意组合），value-format 决定输出类型（Date / 时间戳 / 自定义格式字符串）
• 联动逻辑：日列随「年 + 月」联动（闰年 2 月自动 29 天）；各列按 start / end 边界逐级收缩可选区间
• 双模式：弹层模式（底部抽屉 + 遮罩）与 inline 内嵌模式
• 自带触发区：弹层模式默认渲染显示框，点击打开弹层、确认后选中值按 format 显示在触发区；支持 placeholder 占位、默认插槽自定义外观、show-trigger 关闭后改由外部 visible 控制，新增 open 事件
• Vue2 / Vue3 双兼容：v-model（value + input / modelValue + update:modelValue / v-model:value）与 v-model:visible（Vue2 用 :visible.sync）
• 支持 labels 自定义单位文字、item-height / visible-item-count 调整外观、z-index 调整层级
• 兼容微信 / 支付宝 / 抖音 / 百度 / 快手 / QQ / 京东 / 飞书 / 小红书小程序，以及 H5、App（vue）

修复

• 修复 1月31日切到 2 月时日期进位跳月的问题（如 2024-01-31 切 2 月会跳成 3 月 2 日），现正确收敛为 2 月最后一天
• 修复 挂载时 visible 即为 true 弹层不出现的问题

优化

• 5/6 级联动时年列适度加宽（flex: 1.25），缓解 4 位年份 + 单位在均分列宽下的拥挤感；H5 与 App（vue）生效，小程序端 picker-view 列宽由基础库均分、该样式被忽略（无害回退为等宽）
• 模板去重：内嵌 / 弹层两种模式共用同一份头部与选择器结构
• 脚本去重：format 符号表统一为单一数据源（token 解析、显示格式化、字符串输出共用）；删除死代码（maskStyle 空实现、parseDigits 未使用的 fillEnd 分支等）
• 样式改为原生 CSS（去除 lang="scss"，组件不再依赖项目安装 sass）；删除空规则与冗余占位符样式
• 组件源码由 687 行精简至 583 行（约 -15%）

说明

• 选项单位文字（年 / 月 / 日 / 时 / 分 / 秒）与数字同行显示，与数字基线对齐
• nvue、uni-app-x、鸿蒙、快应用暂不支持（受 picker-view 支持范围限制）

平台兼容性

uni-app(3.8.10)

uni-app x(3.8.10)

时间选择器 v-datetime-picker

基于 picker-view 的多列联动日期时间选择器。默认 5 级联动（年 / 月 / 日 / 时 / 分），format 含秒时自动扩展为 6 级；也可通过 format 只保留其中几列（如仅年月、仅时分）。

特性

• 列由 format 决定：显示哪些列、列的顺序全部由 format 推导，最多 6 级。
• 格式双向可控：format 控制显示与选择粒度，value-format 控制 v-model 输出（Date / 时间戳 / 自定义字符串）。
• 智能联动：日列随「年 + 月」联动（闰年 2 月自动 29 天）；每列按 start / end 边界逐级收缩可选区间。
• 双模式：弹层模式（底部抽屉 + 遮罩）与 inline 内嵌模式。
• 自带触发区：默认渲染一个显示框，点击弹出选择器，确认后选中值直接显示在框内；也可用插槽自定义或关闭触发区改由外部控制。
• Vue2 / Vue3 双兼容：v-model 同时支持 Vue2（value + input）与 Vue3（modelValue + update:modelValue / v-model:value）。
• 多端一致：微信 / 支付宝 / 抖音 / 百度 / 快手 / QQ / 京东 / 飞书 / 小红书小程序，以及 H5、App（vue）。

安装

本组件为 uni_modules 规范组件，无需 npm 安装：

1. 将 uni_modules/v-datetime-picker 目录放入项目 uni_modules 下；
2. 直接使用 <v-datetime-picker> 标签，easycom 会自动注册，无需 import 与 components 声明。

快速开始

最简用法——组件自带触发区，无需自己写按钮和 visible 状态：

<template>
    <view>
        <v-datetime-picker v-model="time" format="YYYY-MM-DD HH:mm" placeholder="请选择时间" />
    </view>
</template>

<script>
    export default {
        data() {
            return {
                time: null // 未选择时触发区显示 placeholder；确认后自动显示选中值
            }
        }
    }
</script>

需要外部控制弹层（如自定义按钮样式）时，关闭内置触发区并用 visible 控制：

<template>
    <view>
        <button @click="show = true">选择时间</button>
        <text>当前：{{ text }}</text>

        <v-datetime-picker
            v-model="time"
            :visible.sync="show"
            :show-trigger="false"
            format="YYYY-MM-DD HH:mm"
            @confirm="onConfirm"
        />
    </view>
</template>

<script>
    export default {
        data() {
            return {
                show: false,
                time: new Date(), // 也支持时间戳(Number) 或字符串
                text: ''
            }
        },
        methods: {
            onConfirm({ formatted }) {
                this.text = formatted
            }
        }
    }
</script>

Vue3 中把 :visible.sync="show" 换成 v-model:visible="show" 即可，v-model 用法不变。

常用示例

仅选择日期 / 年月 / 时分

<!-- 仅日期：3 列 -->
<v-datetime-picker v-model="d1" :visible.sync="s1" format="YYYY-MM-DD" />

<!-- 仅年月：2 列 -->
<v-datetime-picker v-model="d2" :visible.sync="s2" format="YYYY-MM" />

<!-- 仅时分：2 列 -->
<v-datetime-picker v-model="d3" :visible.sync="s3" format="HH:mm" />

精确到秒（6 级）

<v-datetime-picker v-model="d" :visible.sync="s" format="YYYY-MM-DD HH:mm:ss" />

输出时间戳

<v-datetime-picker
    v-model="ts"
    :visible.sync="s"
    format="YYYY-MM-DD HH:mm"
    value-format="timestamp"
/>
<!-- 确认后 ts 为毫秒时间戳（Number） -->

限制可选范围

<v-datetime-picker
    v-model="d"
    :visible.sync="s"
    format="YYYY-MM-DD HH:mm"
    start="2026-01-01 00:00"
    end="2026-12-31 23:59"
/>

内嵌到页面

<v-datetime-picker inline v-model="d" format="YYYY-MM-DD HH:mm" @confirm="onConfirm" />

触发区

弹层模式下组件默认渲染一个触发区（显示框）：

• 点击触发区打开弹层，确定/取消/点遮罩关闭；
• 触发区文字按 format 显示当前 v-model 值，无值时显示 placeholder；
• 默认外观可通过默认插槽整体替换（替换后点击打开行为保留）：

<v-datetime-picker v-model="d" format="YYYY-MM-DD HH:mm">
    <view class="my-trigger">到期时间：{{ myText }}</view>
</v-datetime-picker>

• 不需要触发区时传 :show-trigger="false"，由外部元素通过 visible 控制开关（见快速开始第二种用法）。
• inline 内嵌模式始终不渲染触发区。

格式设置

format：决定列

format 中的符号按顺序决定显示哪几列，重复的单位只保留一列；不在符号表内的字符（如 -、:、空格）仅用于生成 formatted 字符串，不参与列。

hh / h 同样映射到 24 小时制，本组件不提供 12 小时制（AM/PM）。

value-format：决定输出

API

Props

labels 默认值：{ year: '年', month: '月', day: '日', hour: '时', minute: '分', second: '秒' }

Events

回调载荷说明：

• value：按 value-format 转换后的值，即写回 v-model 的值；
• date：原生 Date 对象；
• formatted：始终按 format 生成的显示字符串，与 value-format 无关。

change 仅用于实时预览，不会写回 v-model；只有 confirm（或用户确认动作）才会更新绑定值。 input / update:modelValue / update:value / update:visible 为 v-model 通道事件，正常使用无需手动监听。

Methods

打开弹层请将 visible 置为 true（或使用 ref.close() 配合外部状态）。

联动与边界规则

• 日列随年月联动：2024 年（闰年）2 月显示 29 天，2023 年（平年）2 月显示 28 天。
• 边界逐级收缩：由 start / end 决定。例如 start 为 2026-01-01 时，年份列从 2026 起、1 月之前的月份不可选；选中边界日后，时/分列也会相应收缩。
• 默认范围：未设置 start / end 时，年份范围为「当前年 -10」至「当前年 +10」。
• 非法值兜底：传入值超出范围会被自动 clamp 到最近合法值；区间配置若出现 lo > hi（如自定义 labels 或极端 start/end）会自动交换，避免空列。

常见问题

Q：Vue2 下弹层打不开？ 需用 :visible.sync="show"（Vue2 语法）；v-model:visible 仅 Vue3 可用。

Q：inline 模式下点击确定会关闭吗？ 不会。内嵌模式不弹层，confirm 只触发事件、不回写 visible。

Q：弹层被自定义弹窗盖住？ 调大 z-index 即可，遮罩取该值、面板取其 +1。

Q：为什么 formatted 和 value 不一致？ 两者用途不同：formatted 恒按 format 输出（用于展示），value 按 value-format 输出（用于存储）。

兼容性

• 框架：Vue2、Vue3。
• 小程序：微信 / 支付宝 / 抖音（头条）/ 百度 / 快手 / QQ / 京东 / 飞书 / 小红书。
• Web：H5（Chrome / Safari）。
• App：App（vue）。
• 不支持：nvue、uni-app-x、鸿蒙、快应用（受 picker-view 支持范围限制）。

更新日志

见 changelog.md。