DatePicker 日期时间

通用布局能力：RenderDatePicker 实例统一支持 width、height、min/max、margin 和槽位对齐；日期 popup 的 viewport 定位不属于普通 RenderBox 盒模型。详见组件通用布局属性。

RenderDatePicker 用于录入日期或日期时间。它不是自由文本输入框，而是“触发框 + 日历弹窗 + 分段数字输入”的日期组件。

日期表单框负责显示、清除、分段编辑和打开日历；DatePickerPopup 负责日历面板、年月日视图、确认取消、今日按钮和可选的时间分段输入。

API 总览

主类：

• RenderDatePicker
• DatePickerPopup

相关 public type：

• ISODate
• CalendarTime
• CalendarTimePrecision
• FormFieldStatus

导入：

import {  DatePickerPopup,  RenderDatePicker,  type CalendarTime,  type CalendarTimePrecision,  type FormFieldStatus,  type ISODate,} from 'ds-ui'

RenderDatePicker 的构造参数是公开 options 对象，但当前没有单独导出的 DatePicker options 类型。业务代码直接按本文参数表传入对象。

何时使用

• 出生日期、入院日期、出院日期、就诊日期。
• 开始日期、结束日期。
• 需要选择日期和时间的业务字段。
• 医疗文书日期数据元。
• 表格单元格或弹窗中的日期选择。

不适合：

• 普通文本输入，使用 TextField。
• 时间范围选择器。当前 DatePicker 是单值组件，范围应由两个 DatePicker 组合。
• 复杂排班、周视图、日程视图。应开发独立业务组件。
• 自由格式日期输入。DatePicker 当前只支持受控的分段数字输入和日历选择。

最小示例

import { RenderDatePicker, type ISODate } from 'ds-ui' const visitDateState: { visitDate: ISODate } = {  visitDate: '',} const visitDatePicker = new RenderDatePicker({  value: visitDateState.visitDate,  placeholder: '选择就诊日期',  clearable: true,  onChange: value => {    visitDateState.visitDate = value  },})

日期时间示例

import { RenderDatePicker, type ISODate } from 'ds-ui' const visitDateTimeState: { visitDateTime: ISODate } = {  visitDateTime: '2026-05-14T09:30:00',} const visitDateTimePicker = new RenderDatePicker({  value: visitDateTimeState.visitDateTime,  showTime: true,  placeholder: '选择就诊时间',  onChange: value => {    visitDateTimeState.visitDateTime = value  },})

值格式

ISODate 是字符串类型：

RenderDatePicker 的 showTime 为 true 时，输出值使用 T 连接日期和时间；绘制时显示为空格连接。

parseISO() 当前只识别 YYYY-MM-DD 开头的字符串。传入无法解析的字符串时，组件会进入空日期状态。

RenderDatePicker 构造参数

new RenderDatePicker(options) 的 options：

const dischargeDatePicker = new RenderDatePicker({  value: '',  placeholder: '选择出院日期',  status: 'default',  helperText: '',  prefixText: '出院',  suffixText: '',  clearable: true,  onChange: value => {    state.dischargeDate = value  },})

RenderDatePicker 属性

showTime 目前是构造参数，不提供运行时 setter。需要切换日期/日期时间模式时，建议重建组件或由业务层重新组合。

RenderDatePicker 方法

组件还实现了 GET_POPUP_ANCHOR_RECT，popup 会使用输入框主体作为定位锚点。外部通常不需要直接调用。

输入与鼠标行为

日期字段不是普通文本框，不支持直接输入任意字符串。业务如果要求“日期数据元不能自由打字”，应使用 DatePicker 这种受控录入方式。

键盘行为

未激活分段时：

激活分段时：

RenderDatePicker 表单框分段顺序：

• 日期模式：year -> month -> day
• 日期时间模式：year -> month -> day -> hour -> minute -> second

分段值会被约束到有效范围：

• year：1..9999
• month：1..12
• day：当前年月的有效天数
• hour：0..23
• minute：0..59
• second：0..59

const segmentDatePicker = new RenderDatePicker({  value: '2026-05-14',  onChange: value => {    state.segmentDate = value  },}) FocusManager.instance.setFocus(segmentDatePicker)

清除行为

清除按钮显示条件：

• clearable === true
• value.length > 0
• 非 disabled
• 非 readonly

点击清除按钮会：

• 关闭弹窗。
• 把 value 设为 ''。
• 清空内部日期解析状态。
• 退出分段输入。
• 触发 onChange('')。

const clearableDatePicker = new RenderDatePicker({  value: '2026-05-14',  clearable: true,  onChange: value => {    state.clearableDate = value  },})

只读和禁用

readonly 和 disabled 都会让组件关闭 popup 并退出分段输入。视觉上 readonly 不展示聚焦态，disabled 使用禁用态颜色。

DatePickerPopup

DatePickerPopup 是可独立使用的日历浮层。RenderDatePicker 内部持有一个 popup；表格单元格编辑器、病历编辑器等也可以复用它。

open 参数

popup.open(options)：

const standaloneDatePopup = new DatePickerPopup()const standaloneDateAnchor = {  [GET_POPUP_ANCHOR_RECT]: () => ({    x: 20,    y: 20,    width: 160,    height: 32,  }),} standaloneDatePopup.open({  anchor: standaloneDateAnchor,  selected: { year: 2026, month: 5, day: 14 },  selectedTime: { hour: 9, minute: 30, second: 0 },  showTime: true,  timePrecision: 'minute',  onSelect: (date, time) => {    state.popupDate = `${date.year}-${date.month}-${date.day}`    state.popupTime = time ? `${time.hour}:${time.minute}` : ''  },  onClose: () => {    state.popupClosed = true  },})

CalendarTime

CalendarTime：

CalendarTimePrecision：

Popup 方法

debugState() 返回字段包括：

• panelX、panelY、panelW、panelH
• anchorRect
• viewMode
• viewYear
• viewMonth
• yearRangeStart
• selected
• showTime
• timePrecision
• selectedTime
• activeSegment
• activeTimeSegment

日历弹窗交互

弹窗时间输入

DatePickerPopup 的时间输入行支持年月日、时分秒分段输入。

分段输入规则：

• 数字输入达到该段长度后提交。
• 年、月输入完成后自动切到下一个日期段。
• 日输入完成后停留在日段，不自动跳到时间段。
• 时、分、秒输入完成后不自动跳到下一个时间段。
• 时间段需要用户手动点击或按 Tab 切换。
• ArrowUp / ArrowDown 可以步进当前段。

这个设计避免用户快速输入秒后，焦点自动跳回日期段导致误改日期。

布局和定位

RenderDatePicker：

• 日期模式默认宽度建议为 140。
• 日期时间模式默认宽度建议为 220。
• 实际宽度由父布局约束决定。
• 高度由文本输入主题高度和 helperText 决定。
• popup 锚点始终是输入框主体区域，不包含 helper text。

DatePickerPopup：

• 根据当前主题的 DatePickerStyleTokens 计算 cell、header、footer 和时间行尺寸。
• 优先显示在锚点下方。
• 下方空间不足时显示在锚点上方。
• 右侧超出视口时向左修正。
• 弹窗位置每次基于当前 popup context 重新计算，适合滚动和布局变化后的跟随定位。

表单组合

日期范围用两个 DatePicker 组合：

const startDatePicker = new RenderDatePicker({  value: '',  placeholder: '开始日期',  clearable: true,  onChange: value => {    state.startDate = value  },}) const endDatePicker = new RenderDatePicker({  value: '',  placeholder: '结束日期',  clearable: true,  onChange: value => {    state.endDate = value  },})

医疗文书日期数据元

医疗文书中的日期数据元通常不应允许随便打字。推荐交互：

• 文档中点击日期数据元，打开 DatePickerPopup。
• 日期数据元清除由业务提供清除按钮或 DatePicker clearable 行为完成。
• 日期时间值统一保存为 ISO 字符串。
• 日期显示可用空格分隔，持久化值仍使用 T。
• 如果日期数据元断行显示，清除按钮和 popup 锚点应由业务按数据元首行或当前编辑矩形定位。

生命周期

RenderDatePicker.dispose() 会：

• 从 FocusManager 注销。
• dispose 内部 DatePickerPopup。
• 清理 hover 状态。
• 调用父类 dispose()。

DatePickerPopup.dispose() 会关闭 popup、解绑键盘路由并清理 PopupManager 当前弹窗引用。页面、表格编辑器、病历编辑器销毁时，应同步释放持有的 popup。

常见问题

为什么 DatePicker 不允许直接输入任意日期字符串？

DatePicker 是受控日期组件，目的是避免自由文本造成格式不一致。用户可以通过日历选择或分段数字输入录入日期。

为什么 showTime 为 true 时 value 里是 T，显示时是空格？

T 是持久化格式，便于和 ISO 日期时间字符串兼容；显示时用空格更符合表单阅读习惯。

为什么点击日期不会立即关闭弹窗？

弹窗提供“今日 / 确定 / 取消”三类明确操作。点击日期只改变临时选择，点击确定才提交，点击取消不提交。

为什么时间段输入完成后不自动跳到下一段？

时间输入容易连续快速输入。自动跳段可能导致用户不知道当前焦点已经移动，后续数字误改其他段。当前策略是时间段输入完成后停留在本段，手动点击或 Tab 才切换。

为什么 readonly 不能打开弹窗？

readonly 表示展示但禁止修改。打开弹窗会产生可编辑入口，因此 readonly 下不聚焦、不打开、不清除。

相关组件

• TextField：单行文本输入。
• TextArea：多行文本输入。
• Dropdown：单选下拉。
• GridView：查询表单和表格单元格编辑。
• Popup：弹窗基础机制。
• GridPanel：表单布局。