更新记录

0.3.1（2026-10-20） 下载此版本

• 接入 nax-form 表单校验联动：注入 nax-form-item 提供的字段级校验入口，确认选择 / 清空 / 滚轮列变化按 change 回调，使规则 trigger: 'change' / ['blur', 'change'] 自动生效（此前需业务侧手动调 validateField）
• 校验使用控件当前值而非业务侧 model（model 多在 @change 才同步），选择或清空后错误提示即时消失
• 未置于 nax-form-item 内时为空实现，行为不变；仅新增注入与回调，微信小程序端系统弹层路径同样接入；全端一致

0.3.0（2026-09-04） 下载此版本

• 微信小程序端（MP-WEIXIN）可映射模式改用微信系统弹层 picker，贴合微信原生 UI：date（fields=day）/ year（fields=year）/ year-month（fields=month）/ time（未开 show-second）分别映射 mode="date" / mode="time"，min-date / max-date / min-hour / max-hour 等范围映射 start / end；滚动吸附后点「确定」回调，值即最终值，消除此前 picker-view 的 change 延迟与确认拦截问题
• 不可映射模式（datetime / month-day / time + show-second）微信端保持自建弹层（picker-view）不变
• 微信端限制：系统弹层 UI 不可定制（confirm-text / cancel-text / 颜色 / z-index 等弹层定制 props 不生效；title 仅微信安卓端显示）；v-model:show 程序化打开不生效（点击触发条弹出）；暗黑模式跟随微信宿主深色主题（需小程序开启 darkmode）
• 仅影响微信小程序端；Android / iOS / 鸿蒙 / Web 行为不变

0.2.1（2026-08-24） 下载此版本

• 触发条清除按钮样式对齐 nax-input：移除灰色圆形底徽，改为纯 close 图标；图标随 size 缩放（sm 14 / md 16 / lg 18），配色与热区内边距一致；App 深色主题沿用 custom-class nax-theme-dark 判定字面量色（APP-ANDROID / APP-IOS / APP-HARMONY），其它端浅色默认不变
• 有选中值显示清除按钮时隐藏下拉箭头，二者互斥且切换位置精确重合（箭头容器补齐相同热区内边距、图标同尺寸）
• readme 同步修正清除按钮与箭头互斥的描述

平台兼容性

uni-app x(4.25)

其他

nax-datetime-picker

uni-app x 时间选择器（底部弹层 + picker-view）。

主题

通过 CSS 变量覆盖：

依赖

• nax-icon（触发条箭头）
• nax-transition（弹层进退场动画）
• nax-ui-theme（CSS 变量 --nax-*）

基础用法

<nax-button label="选择日期时间" @click="visible = true"></nax-button>
<nax-datetime-picker
  v-model:show="visible"
  v-model="value"
  mode="datetime"
  title="选择时间"
  @confirm="onConfirm"
></nax-datetime-picker>

mode

常用 Props

预设初值

v-model 绑定非 0 的初值，进入页面触发条即显示该时间，打开弹层也直接停在它上面（preserveSelection 默认 true），无需手动 set：

<nax-datetime-picker
  v-model:show="show"
  v-model="value"
  mode="datetime"
  show-trigger
  @confirm="onConfirm"
></nax-datetime-picker>

// 今天 10:30
function todayAt(hour : number, minute : number) : number {
  const now = new Date()
  return new Date(now.getFullYear(), now.getMonth(), now.getDate(), hour, minute, 0).getTime()
}

const value = ref(todayAt(10, 30))

初值可传时间戳（ms）或日期字符串，两种写法等价：

const value = ref(new Date(2026, 0, 1, 9, 0, 0).getTime())  // 时间戳
const value = ref('2026-01-01 09:00')                        // 字符串

设为 0（或 '' / null）表示未选择，触发条显示 placeholder。若初始时间早于 min-date 或晚于 max-date，会被自动收敛到边界内。

日期时间区间

组件以单值为模型（v-model 一个时间戳），区间用两个实例组合实现，不需要额外组件。

两个 picker 并列

起止各一个内置触发条，用 min-date / max-date 互相约束，先选哪个都行：

<view class="row">
  <nax-datetime-picker
    v-model:show="startShow"
    v-model="startValue"
    mode="datetime"
    show-trigger
    placeholder="开始时间"
    :max-date="endValue"
    @confirm="onStartConfirm"
  ></nax-datetime-picker>
  <nax-datetime-picker
    v-model:show="endShow"
    v-model="endValue"
    mode="datetime"
    show-trigger
    placeholder="结束时间"
    :min-date="startValue"
    @confirm="onEndConfirm"
  ></nax-datetime-picker>
</view>

未选中时 v-model 为 0，传给 min-date / max-date 即视为「未传边界」，等价于不约束，无需额外判断。

单触发条 + 两步选择

只要一个触发条时，两个实例都不传 show-trigger（不渲染内置触发条），自己渲染触发区，并在起点 close 后自动打开终点：

<view class="range-trigger" @click="onSpanOpen">
  <text>{{ spanDisplay }}</text>
</view>

<nax-datetime-picker
  v-model:show="startShow"
  v-model="startValue"
  mode="datetime"
  title="选择开始时间"
  :max-date="endValue"
  @confirm="onStartConfirm"
  @cancel="onSpanCancel"
  @close="onStartClose"
></nax-datetime-picker>
<nax-datetime-picker
  v-model:show="endShow"
  v-model="endValue"
  mode="datetime"
  title="选择结束时间"
  :min-date="startValue"
  @confirm="onEndConfirm"
></nax-datetime-picker>

const startShow = ref(false)
const startValue = ref(0)
const endShow = ref(false)
const endValue = ref(0)
let pendingEnd = false

function onSpanOpen() {
  if (startValue.value == 0) {
    startShow.value = true
  } else if (endValue.value == 0) {
    endShow.value = true
  } else {
    startShow.value = true
  }
}

function onStartConfirm(e : UTSJSONObject) {
  // 起点确认，待弹层退场后接续选终点
  pendingEnd = true
}

function onSpanCancel() {
  pendingEnd = false
}

function onStartClose() {
  if (!pendingEnd) return
  pendingEnd = false
  endShow.value = true
}

接续时机用 @close 而非 @confirm：close 在退场动画结束后触发（面板已卸载），此时再打开第二个弹层不会出现两层遮罩叠加。

注意

• 微信小程序端可映射模式（date / year / year-month / time 无秒）走微信系统弹层，v-model:show 不生效。单触发条两步方案请用 datetime / month-day / time + show-second（自建弹层），或仅在其他端使用。
• 纯日期区间还可直接用 nax-calendar（mode="range"）或 nax-date-strip（type="range"）。

事件

confirm 回调字段：value / timestamp / formatted / year / month / day / hour / minute / second / mode。

另有 update:show、update:modelValue、cancel、change、open、close、clear。

内置触发条有选中值时，右侧显示清除按钮并隐藏下拉箭头（clearable，默认开启，二者互斥），点击后清空选中并回写空的 v-model（0）。

平台说明

• 微信小程序：date / year / year-month / time（未开 show-second）使用微信系统弹层 picker（mode="date" / mode="time"，min-date / max-date / min-hour / max-hour 等范围映射 start / end），滚动吸附后点「确定」回调，值即最终值；系统弹层 UI 不可定制（confirm-text / cancel-text / 颜色 / z-index 等弹层定制 props 不生效，title 仅微信安卓端显示为标题），v-model:show 程序化打开不生效（点击触发条弹出），暗黑模式跟随微信宿主深色主题（需小程序开启 darkmode）
• 微信小程序：datetime / month-day / time + show-second 无法映射微信系统弹层，保持自建弹层（picker-view）不变
• 鸿蒙禁用选项点选，请滑动后确认。
• 鸿蒙暗黑模式：组件自动移除原生滚轮默认的白色渐变遮罩。

说明：鸿蒙 picker-view 打开时的滚到目标动画为原生行为，无法设置 duration。未传 min-date 时默认近 30 年～当前+10 年，以缩短年列滚动距离。需要更早日期请显式传 min-date。