DatePicker 日期选择

以 YYYY-MM-DD 字符串为值的日期选择器

已验证自 0.3.4

用法

弹层、字段与内联

v-model:visible 控制弹层，variant 选择形态，popup="false" 内联渲染。

示例加载中...

最佳实践

日期只存 YYYY-MM-DD 字符串；组件不处理时区与时间。
桌面密集表单用 variant="field"，移动优先流程用 variant="picker"；两种形态都在同一布局里验证过才用 adaptive。
外层卡片已负责展开与留白时，用 picker 形态加 popup="false" 内联渲染。
有明确的地区习惯时，显式设置 weekStartsOn。

API 参考

属性

属性名	类型	默认值	说明
`modelValue`	`string \| DateRangeValue`	`''`	`YYYY-MM-DD` 日期；`range` 时为 `[start, end]`。
`visible`	`boolean`	`false`	弹层显示状态，配合 `v-model:visible`。
`popup`	`boolean`	`true`	仅 `picker` 形态：`false` 时内联渲染。
`variant`	`'picker' \| 'field' \| 'adaptive'`	`'picker'`	`picker` 为滚轮，`field` 为字段日历，`adaptive` 按视口宽度切换。
`title`	`string`	`'Select date'`	工具栏标题，转发给 `TxPicker`。
`placeholder`	`string`	`'Select date'`	字段日历空值时的占位文本。
`min`	`string`	-	最早可选日期（`YYYY-MM-DD`），非法值被忽略。
`max`	`string`	-	最晚可选日期（`YYYY-MM-DD`），非法值被忽略。
`disabled`	`boolean`	`false`	禁止交互。
`showToolbar`	`boolean`	`true`	显示 Picker 工具栏。
`confirmText`	`string`	`'Confirm'`	确认按钮文案，转发给 `TxPicker`。
`cancelText`	`string`	`'Cancel'`	取消按钮文案，转发给 `TxPicker`。
`closeOnClickMask`	`boolean`	`true`	点击遮罩关闭弹层。
`adaptiveBreakpoint`	`number`	`768`	`adaptive` 切换到字段日历的最小视口宽度。
`weekStartsOn`	`0 \| 1`	`0`	字段日历的周起始日：`0` 为周日，`1` 为周一。
`range`	`boolean`	`false`	仅字段日历：选择起止两个日期；滚轮形态忽略。
`rangeSeparator`	`string`	`' → '`	字段显示值中两个日期之间的分隔文本。

事件

事件名	参数	说明
`update:modelValue`	`(value: string \| DateRangeValue)`	日期变化时触发，参数已格式化。
`change`	`(value: string \| DateRangeValue)`	与 `update:modelValue` 同时触发。
`update:visible`	`(visible: boolean)`	请求切换显示状态时触发。
`confirm`	`(value: string)`	点击确认时触发，参数为当前日期。
`cancel`	-	点击取消时触发。
`open`	-	打开时触发。
`close`	-	关闭时触发。

概述

值始终按 YYYY-MM-DD 输出；空值或非法值按本地今天初始化，再限制在 min / max 内。
picker 形态由 v-model:visible 控制弹层；field 形态经 TxPopover 渲染，同样同步 update:visible、open、close。
滚动列变化即触发 update:modelValue 与 change；confirm 后按 Picker 的行为关闭。
字段日历宽度跟随月历网格（280–360px），不跟随输入框；标题按钮逐级拉远：日 → 月 → 12 年区块，箭头按当前视图步进，关闭后回到日期网格。
range：第一次点击定起点并预览区段，第二次闭合并按先后顺序输出 [start, end]；两端齐全前不派发事件，中途关闭即放弃。
日历使用 grid / gridcell 与 aria-selected；减少动态效果时，滑动与缩放降级为短促淡入淡出。

技术实现

区间内的日期带 is-in-range，两端带 is-range-start / is-range-end。
源码：packages/tuffex/packages/components/src/date-picker/。

packages/tuffex/packages/components/src/date-picker/index.ts