DatePicker 日期选择器
将可键入的分段日期框、日历触发器和选择浮层组合成一个字段。
用法
输入或选择日期
交付日期
yyyy
/mm
/dd
组件结构
加粗的是必需部件。
data-scope="date-picker"：root · label · control · tag-list · segment-group · trigger · clear-trigger · positioner · content · preset-group · preset · calendar · time-column · time-item · footer · confirm-trigger
示例
不可用日期
禁止选择周末
工作日
yyyy
-mm
-dd
状态
禁用、只读与校验失败
禁用
2026
-07
-28
只读
2026
-07
-28
校验失败
2026
-07
-28
快捷选项
提供常用日期
提醒日期
yyyy
-mm
-dd
日期与时间
同时选择日期和时间
会议开始
yyyy
/mm
/dd
hh
:mm
周期选择
granularity 决定输入行铺设哪几段、浮层铺设哪一档格子
统计周期
yyyy
/mm
/dd
12 小时制
hourCycle=12 时时间列末位多出上下午列，输入行也多出上下午段；值仍是 24 小时制的 ISO 串
Pickup
当前值：2026-09-28T21:3009
/28
/2026
09
:30
PM
可约时段
timeStep 让分列每 15 分钟一格；min / max 带时间段时首尾两天界外的时刻不可选，isTimeUnavailable 再按已选的日子收掉周末的下午
到店时间
当前值：2026-10-09T10:002026
/10
/09
10
:00
多选成标签
selectionMode="multiple" 时选中的日期在输入行里排成标签，点标签上的叉或在日历钮上按退格摘掉，放不下的折进 +N；浮层选完不收起
值班日期
2026/10/082026/10/152026/10/22+1
设计指引
何时使用
- 用户需要查看月份和星期信息后选择日期。
- 需要选择日期时间，或一次挑多个不连续的日子。
何时不用
特性
granularity支持 day / week / month / quarter / year，selectionMode独立控制单选或多选。- 不写结构时按标准结构铺出整套部件（Vue 不写默认插槽、React 不给 children、Web Components 不写部件或只写
root），三端出自同一个结构函数：标题（label给文字），盒里的段组（多选时是带删除钮的标签行）、清空钮与日历钮，表单影子，浮层里依次是快捷选项列、每个面板一份日历（标题栏、表头与日期格）、showTime的时间列与底栏的确认钮（文字取translations.confirmTrigger）。翻月、换层级与选中变化时结构随之重铺。Web Components 里标题可以写在宿主的直接子节点上接管：slot="label"。 - 自己写结构时，浮层里的日历照插槽数据渲染：日视图读
weeks，周、月、季度与年读按行切好的rows（多面板读panels[i].rows），一行写一个week-row、格子放进行里，写法同日历选择器。Vue / React 的时间列可以用XhDatePickerTimePanel整组铺，也可以逐列写XhDatePickerTimeColumn（unit），列里不写内容时按可选值铺XhDatePickerTimeItem。 - 多选（
selectionMode="multiple"）时选中的日期在输入行里排成标签（库内 标签，与选择器多选同一套）：段位收起，日历钮常驻并成为键盘入口，在它上面按退格摘掉最后一个，点标签上的叉摘掉那一个；标签文字按粒度与locale排出（日 2026/10/02、月 2026年10月、周 2026-W40、季 2026-Q4），标签是定长文字、不截短，一行放不下就折到下一行，盒随行数长高、到上限后在盒内滚动；超过maxTagCount（默认 3）的折进 +N；没有选中时整条placeholder落在标签行上；表单一个选中值一份同名隐藏输入。 placeholder给字符串是整条占位：一段都没填、焦点也不在段上时输入行显示这句文字（「请选择生效时间」），段位与分隔符淡出让位，焦点一进到段上就换回 yyyy / mm / dd 段位；给对象是逐段的占位串。整条占位由皮肤以生成内容画出，段位仍可聚焦、仍在读屏树里。- 周选择直接渲染整周周期格；不再需要
weekSelection特殊开关。周粒度按 ISO 周（星期一到星期日）成段，输入行的「2026-33」按 ISO 周年计，与locale和firstDayOfWeek都无关：en-US 这类星期日开头的 locale 下，日视图的一行比所挑的 ISO 周早一天开始。 min、max与isDateUnavailable限制可选日期。presets提供常用日期快捷项：每项是一颗淡底小钮，当前值落在哪一项就在它末端画对号。firstDayOfWeek（0 = 星期日 … 6 = 星期六）与maxSelected（多选上限）原样交给浮层里的日历，用法与示例见日历选择器；输入行的段序仍按locale，带的日期比上限多的快捷选项不可按下。showTime在granularity=day + selectionMode=single时让输入行显示完整日期时间，并加入时、分或秒选择列。- 时间列与时间选择器共用一份约束：
hourCycle={12}多出上下午列与上下午段（缺省按locale推断，没给locale时 24）；timeStep按时、分、秒各设步长；isTimeUnavailable逐格判定，第三个参数带已选的时分与这份时间所属的日期。 min/max可以带时间段（2026-09-28T09:30）：日历按日期段收，与它同一天时界外的时刻留在列里、标为不可选，列长不随所选的日子变。- 日期时间组合面板的时间列顶边接着日历标题栏的分隔线、底边与日期网格对齐，列与列之间不画线；各时间列只纵向滚动，列底留白让末尾几格也能滚到列顶。
- 确认钮写在底栏（
footer）里：底栏是浮层底部的通栏操作区，独占一行，上沿一道分隔线、四周 8 的内衬；作者另放的说明文字排在行首、取弱化的说明档字，确认钮落在行尾。底栏里只有确认钮时，未开showTime它随确认钮一并收起，不留空栏。 - 输入值、展开状态和聚焦日期均可受控。
- 输入行的写法随
locale与granularity/segments走，不接受formatOptions或格式串，理由见日期字段。 - 点击输入行可以继续逐段键入，点击日历图标则把焦点送入日历；展开期间输入框保持激活边界。
- 填齐了但越界即整个字段标为不合法，也可以用
invalid显式声明。 - 切换粒度会清空旧选择，输入段、网格和周期边界随后一起切换，不做隐式转换。
- 空值时显示日历入口；有值且渲染了清空按钮时，指针落在盒上（或焦点在盒内）由清空按钮原位接替日历图标，触屏上有值即接替；焦点正在日历钮上时它不让位。
- 聚焦边界、段位强调与日期格按压都使用短过渡；减弱动效仍由全局动效轴收敛。
组合
- 浮层内嵌日历选择器，翻月、层级切换与键盘导航由它负责。
- 输入行内嵌日期字段的段位，逐段键入与加减由它负责。
- 直接放入表单字段：字段的标题并进日历钮的名字，说明与错误文案进描述链；只读、必填与校验由各段报告，日历钮是普通按钮，不带 aria-readonly / aria-required。有值时清空钮顶替日历钮，点字段标题焦点落在第一段。
最佳实践
- 使用明确的字段标签。
- 标准输入行应同时包含清空按钮与日历图标触发器；二者按值互斥显示。参与表单时同时渲染隐藏输入。
- 默认只展开一个日历面板；需要多面板时显式传
visibleCount。多个面板始终联动、一起翻页，不提供解绑（Element Plus 的unlink-panels那一档）：两张月历各翻各的之后，方向键跨出一张月历时焦点该落到哪一张、另一张跟不跟着走都没有一致的答案，读屏用户也失去「这几张是连续的月」这条线索。起止相隔很远时点标题里的年 / 月直接跳，或在输入行键入；React Aria 的visibleDuration同样只有联动一种。 - 需要统一查询值时，使用
calendarPeriodValue(granularity, 'single', value)得到周期首尾与回显键。 - 快速选年可在
year网格中渲染受范围约束的年份集合；网格使用三列紧凑布局与内部滚动。 - 不可用日期应同时提供原因。
- 常用日期优先提供快捷项。
- 开了
showTime时把确认钮放进底栏，不在content里另写带样式的包裹块。
反模式
- 未经说明就预先选择今天。
- 让浮层遮挡当前输入值。
- 用多选模拟区间：中间的日期不会自动补齐，也没有拖选与预览。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-date-picker> |
| Vue 组件 | XhDatePickerCalendar XhDatePickerCell XhDatePickerCellTrigger XhDatePickerClearTrigger XhDatePickerConfirmTrigger XhDatePickerContent XhDatePickerControl XhDatePickerFooter XhDatePickerGrid XhDatePickerGridBody XhDatePickerGridHead XhDatePickerHeader XhDatePickerHeading XhDatePickerHeadingMonthTrigger XhDatePickerHeadingYearTrigger XhDatePickerHiddenInput XhDatePickerItemDeleteTrigger XhDatePickerLabel XhDatePickerNextTrigger XhDatePickerNextYearTrigger XhDatePickerOverflowTag XhDatePickerPositioner XhDatePickerPreset XhDatePickerPresetGroup XhDatePickerPrevTrigger XhDatePickerPrevYearTrigger XhDatePickerRoot XhDatePickerSegment XhDatePickerSegmentGroup XhDatePickerTag XhDatePickerTagLabel XhDatePickerTagList XhDatePickerTimeColumn XhDatePickerTimeItem XhDatePickerTimePanel XhDatePickerTrigger XhDatePickerWeekDay XhDatePickerWeekNumber XhDatePickerWeekRow |
| 组合式函数 | useDatePicker |
| 状态机 | datePickerMachine |
| 皮肤 | @xihan-ui/styles/date-picker.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
labelled | boolean | 作者渲染了 label 部件时置真，由适配器统计而不是判断标题文字是否有值。 为假时可聚焦部件不把 label 的 id 写进 aria-labelledby：指向未渲染的 id 是无效引用，作者写在控件上的 aria-label 也会被它压住。 | |
ariaLabel | string | 不显示出来的名字，写成 aria-label 落在与字段标签同一个部件上。 放进字段（字段接线）或渲染了 label 部件时名字以它们为准，aria-labelledby 盖过它。 | |
value | string | string[] | 选中值，ISO 串。提供即受控：读取直取 prop，写入只发 onValueChange 不落内部值。 单选可写裸串，内部一律归一为数组。 | |
defaultValue | string | string[] | ||
open | boolean | 展开态。提供即受控：内部不再自行修改，只发 onOpenChange。 | |
defaultOpen | boolean | ||
min | string | 可选范围下界（含当天），ISO 串。日历与分段输入共用这一条。 | |
max | string | 可选范围上界（含当天），ISO 串。 | |
locale | string | 决定周首日、月份文案与段位先后（zh-CN 年月日、en-US 月日年）。 未提供时按宿主语言，宿主也没有时按 en-US。 | |
timeZone | string | 判定今天与格式化文案使用的时区，默认取宿主本地时区。 | |
firstDayOfWeek | number | 周首日，0 = 星期日 … 6 = 星期六（与日历选择器同一套写法）；不给按 locale。 只改浮层日历的表头、每一行的行首与 Home / End，月份名、星期名与段位先后仍按 locale。 | |
selectionMode | CalendarPickerSelectionMode | 选择模式，默认 single。区间选择是另一个组件（日期范围选择器）。 | |
maxSelected | number | multiple 下最多选几个周期，交给内嵌日历：选满后没选中的格子不可再加选，已选的仍可点掉。 带的日期比它多的快捷选项不可按下。非整数向下取整，小于 1 或不是有限数时不设上限。 | |
maxTagCount | number | 多选时输入行最多摆几枚标签，其余折进 +N 那一枚；默认 3。 | |
isDateUnavailable | (value: string) => boolean | 不可用判定，接收 ISO 串。界外与判定为真的日期同等处理。 | |
disabled | boolean | 整个控件禁用：trigger 为原生 disabled，段位退出 Tab 序列，日历格子全部为 aria-disabled。 | |
readOnly | boolean | 只读：浮层照常展开、日历照常翻月浏览，但选中值不可修改。 | |
invalid | boolean | 校验失败：段位报告 aria-invalid，各角色节点带 data-invalid。 未提供时也会自行判定：已填齐但越界。 | |
required | boolean | 必填标注，写入每一段的 aria-required。 | |
name | string | 表单字段名；提供后隐藏输入才带 name，ISO 串随表单一并提交。 | |
granularity | CalendarGranularity | 选择粒度；与 selectionMode 正交。输入行与周期网格都由它决定。 | |
activeView | CalendarView | 面板当前所在的层级。提供即受控；未提供时跟随 granularity，每次展开都回到目标粒度。 点击标题中的年 / 月会修改它。 没有配套的 defaultActiveView：面板每次展开都会重置该档，非受控初值没有生效时刻， 提供后也观察不到任何效果。修改初始层级使用 granularity。 | |
segments | DateSegmentSet | 输入行铺设的段。未提供时按 granularity 推导：按周为「2026-33」、按月为「2026-05」、 按季度为「2026-Q2」、按年为「2026」，按天则按 locale 排列年月日。 | |
placeholder | string | DateSegmentPlaceholders | 占位。给字符串是整条占位：一段都没填、焦点也不在段上时，输入行显示这句文字（「请选择生效时间」）， 焦点进到段上即换回段位。给对象是逐段的占位串，覆盖内置的 yyyy / mm / dd。 | |
presets | DatePickerPreset[] | 快捷选项（「今天」「明天」等）。提供后浮层中多出一列，点击即整份写入选中值。 日期需计算后传入：连接层每帧求值，把 today() 放进渲染期会跨零点得出两个结果。 与 selectionMode 不匹配（单选提供了多条）、落在 min / max 之外或被 isDateUnavailable 判定不可用的选项 自动不可按下；showTime 下写入的日期附带当前已选的时间。 | |
visibleCount | number | 展示的连续日历面板数；默认 1。 | |
fixedWeeks | boolean | 日历恒渲染六行，默认开启。关闭后网格按当月实际周数收缩，翻页时浮层高度随之变化。 | |
defaultFocusedValue | string | 初始聚焦日，ISO 串；同时决定展开时先落在哪一页。 未提供时回退为首个选中值，再回退为今天。表单重置回到该值。 | |
variant | ControlVariant | 形态：outline / subtle / ghost，决定输入行的描边与底色使用方式。默认 outline。 | |
tone | Tone | 语气：brand / neutral / success / warning / danger / info，决定聚焦与选中强调使用哪族颜色。 | |
size | Size | 尺寸：sm / md / lg，输入行与浮层中的日历格一并换档。 | |
placement | Placement | ||
dir | Direction | 文字方向，默认 ltr。只改写浮层在行内轴上 start 与 end 的落点。 | |
offset | number | ||
translations | Partial<DatePickerTranslations> | ||
closeOnSelect | boolean | 选完即收起，默认 true。多选不收起。 | |
showTime | boolean | 一体化时间：值升格为 'YYYY-MM-DDTHH:mm[:ss]'，面板中多出时间列， 选完日期不收起、由确认按钮收口。只在 day + single 下生效。 此时 min / max 可以带时间段（'2026-09-28T09:30'）：日历按日期段收，时间列在与它同一天时按时间段标不可选。 | |
timeGranularity | DatePickerTimeGranularity | showTime 的时间段精度，默认 minute。 | |
hourCycle | TimeHourCycle | showTime 的小时制，缺省按 locale 推断（与 TimePicker 同一口径，没给 locale 时 24）。12 时时间列多出上下午列、输入行的时刻段后面多出上下午段； 值仍是 24 小时制的 ISO 串。 | |
timeStep | TimeStep | showTime 时间列按单位的步进：{ hour?, minute?, second? }，各单位缺省 1。只影响列里的格，不限制段位上手动输入的数。 | |
isTimeUnavailable | TimeUnavailablePredicate | showTime 时间列的逐格可选性。value 是两位补零的格值，时列恒按 24 小时制给出； context 带已选的时（24 小时制）与分、这份时间所属的日期（date，还没有值时是聚焦日），index 恒为 null。 判定为真的格子仍可聚焦，只是按不下去，与 min / max 之外的时刻同等对待。 | |
onValueChange | (details: DatePickerValueChangeDetails) => void | value 变化意图回调；受控时是唯一出口，非受控时随内部写入一并通知。 | |
onClear | () => void | 用户按清空钮（clear-trigger）清掉了值；先发值变化，再发它。程序化的 clear() 不发。 | |
onOpenChange | (details: DatePickerOpenChangeDetails) => void | open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。 | |
onFocusedValueChange | (details: DatePickerFocusChangeDetails) => void | 聚焦日变化（方向键、翻月、展开、段位输入都会发出）。 网格由外部渲染，不监听该事件时日历不会换月。 | |
onActiveViewChange | (details: CalendarViewChangeDetails) => void | 面板所在层级变化（点击标题向上、点击格子向下都会发出）；受控时是唯一出口。 |
DatePickerPreset
presets 的元素。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
value | string | 是 | |
label | string | 是 | 显示文案，同时是该项的可及名。 |
disabled | boolean | 禁用该项：方向键仍可停留，但按下不写值。 |
事件
自定义元素将载荷放在 detail；Vue 使用同名 emit。
| 事件 | 载荷 | 说明 |
|---|---|---|
value-change | DatePickerValueChangeDetails | 选中集合变化；detail 为 { value: string[] } |
clear | `` | 用户按清空钮（clear-trigger）清掉了值；先发值变化，再发它。程序化的 clear() 不发。 |
open-change | DatePickerOpenChangeDetails | open 状态变化；detail 为 { open: boolean } |
focused-value-change | DatePickerFocusChangeDetails | 聚焦日变化（展示月可能随之变化）；detail 为 { focusedValue: string }，作者据此重绘网格 |
active-view-change | CalendarViewChangeDetails | 切换到另一层级（点击标题向上、点击格子向下）；detail 为 { activeView: 'day'|'week'|'month'|'quarter'|'year' }，作者据此重绘网格 |
插槽
仅列出带载荷的插槽。
| Vue 组件 | 插槽 | 载荷 | 说明 |
|---|---|---|---|
XhDatePickerPreset | default | — | 条目内容；未写时使用数据中的 label。 |
XhDatePickerPresetGroup | default | DatePickerPresetsSlotProps | 自行铺设条目；未写时按 presets 数据自动铺设，两者产出的 DOM 一致。 |
XhDatePickerRoot | default | DatePickerRootSlotProps | |
XhDatePickerRoot | label | — | 不写默认插槽时标题的内容，盖过 label 文字。 |
XhDatePickerSegment | default | DatePickerSegmentSlotProps | |
XhDatePickerTimeColumn | default | — | 自行铺 XhDatePickerTimeItem；未写时按这一列的可选值自动铺。 |
XhDatePickerTimeItem | default | — | 格里的内容；未写时显示按 locale 译好的文字。 |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhDatePickerCalendar | index | number | string | 并排的第几张面板，默认 0。写在这里，面板内的标题、网格与格子就不必各写一遍。 | |
XhDatePickerCell | value | string | 是 | ISO 日期串。 |
XhDatePickerCell | index | number | string | 属于第几个面板；未写时跟随所在的日历。同一天会同时出现在两个面板中 （8 月末的几天也铺在 9 月的首行），是否为本月只有连同面板一起看才能判定。 | |
XhDatePickerGrid | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDatePickerHeading | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDatePickerHeadingMonthTrigger | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDatePickerHeadingYearTrigger | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDatePickerPositioner | container | () => Element | null | 浮层挂载的容器；未提供时按全局配置，再未提供时挂载到 body。 | |
XhDatePickerPreset | value | string | 是 | 该条目的身份，与 presets 数据中的 value 逐字对应。 |
XhDatePickerPresetGroup | children | SlotChildren<DatePickerPresetsSlotProps> | 自行铺设条目；未写时按 presets 数据自动铺设，两者产出的 DOM 一致。 | |
XhDatePickerRoot | label | ReactNode | 标题。不给 children 时铺 label 部件。 | |
XhDatePickerRoot | children | SlotChildren<DatePickerRootSlotProps> | 不给时照标准结构铺整套部件。 | |
XhDatePickerSegment | index | number | string | 段位下标，兼收字符串。 | |
XhDatePickerSegment | segment | DateSegmentType | 按段名声明该格。段集中没有该段时它收起；与 index 二选一，两个都写时按段名计算。 | |
XhDatePickerSegment | children | SlotChildren<DatePickerSegmentSlotProps> | ||
XhDatePickerTag | value | string | 是 | 它代表哪个选中值。 |
XhDatePickerTimeColumn | unit | DatePickerTimeUnit | 是 | 这一列的单位：hour、minute、second 或 dayPeriod。 |
XhDatePickerTimeItem | value | string | 是 | 这一格的值，与时间列的可选值逐字对应：两位补零（上下午列写 '00' / '01'）。 |
XhDatePickerWeekDay | value | number | string | 是 | 列序 0-6，兼收字符串。 |
XhDatePickerWeekNumber | value | string | 是 | 该行行首那一天的 ISO 串。 |
状态
公开状态写入 data-state。
| 部件 | 取值 |
|---|---|
root | 'open' | 'closed' |
control | 'open' | 'closed' |
trigger | 'open' | 'closed' |
positioner | 'open' | 'closed' |
content | 'open' | 'closed' |
preset | 'checked' | 'unchecked' |
calendar | 'open' | 'closed' |
time-item | 'checked' | 'unchecked' |
以下名称仅用于内部状态机。
状态：open · closed
事件：OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · VALUE.SET · VALUE.CLEAR · VALUE.REMOVE · TAG_LIST.TRACKED · FOCUSED.SET · VIEW.SET · FORM.RESET · PRESS.START · PRESS.END
判据：isOpenControlled · closesOnSelect · canPress
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
open | boolean | |
value | string[] | 选中集合，ISO 串；形状不随模式变化。 |
valueAsString | string | null | 首个选中值；无选中时为 null。 |
selectionMode | CalendarPickerSelectionMode | |
periodValue | CalendarPeriodValue | null | single 的规范化周期值；multiple 没有连续区间语义，返回 null。 |
focusedValue | string | 生效聚焦日（三路收口后的结果），恒非空。日历展示哪个月由它决定。 |
granularity | CalendarGranularity | 作者选择的粒度。 |
activeView | CalendarView | 面板当前所在的层级。 |
disabled | boolean | |
readOnly | boolean | |
invalid | boolean | 校验失败：作者标记的或越界。 |
canClear | boolean | 清空按钮当前是否可按。 |
tags | DatePickerTagMeta[] | 多选时可见的标签（受 maxTagCount 截断），与 value 同序；单选恒为空数组。 |
overflowCount | number | 被 maxTagCount 折叠的标签数。 |
overflowText | string | +N 标签显示的文字（由 translations.overflowTag 计算）；没有折叠的标签时为空串。 |
deselect | (value: string) => void | 多选时摘掉一个选中值。 |
setOpen | (next: boolean) => void | |
setValue | (next: string[]) => void | |
clear | () => void | |
setActiveView | (next: CalendarView) => void | 直接切换到某一层级。 |
presets | readonly DatePickerPresetState[] | 快捷选项逐条的状态，数据顺序。未提供 presets 时为空数组。 |
showTime | boolean | showTime 生效（已开启且为单选模式）。 |
timeColumns | readonly TimePickerColumn<DatePickerTimeUnit>[] | 时间列（时 / 分[/ 秒][/ 上下午]），格按步进取样；未开启 showTime 时为空数组。 |
timeValue | string | null | 当前时间段（'HH:mm[:ss]'）；尚无值时为 null。 |
hourCycle | TimeHourCycle | 时间列与时刻段实际生效的小时制。 |
timeStep | ResolvedTimeStep | 实际生效的按单位步进。 |
getTimeItemText | (props: DatePickerTimeItemProps) => string | 某一格显示的文字：数字列即格值，上下午列按 locale 给出「上午 / 下午」。各适配器都用它填字。 |
isTimeItemDisabled | (props: DatePickerTimeItemProps) => boolean | 某一格按不下去：落在 min / max 之外、被 isTimeUnavailable 判为不可用，或整个控件禁用。 |
calendar | CalendarPickerApi<T> | 内嵌日历：选日期、翻月、键盘导航都在它身上。 |
translations | DatePickerTranslations | 解析后的文案：作者给的 translations 盖在当前语言包上。 |
field | DatePickerFieldApi<T> | 内嵌分段输入。 |
getRootProps | () => T['element'] | |
getLabelProps | () => T['element'] | |
getControlProps | () => T['element'] | |
getTagListProps | () => T['element'] | 标签行：多选时放在盒里，收纳可见标签与 +N 标签；没有选中时承载整条占位。单选时整体 hidden。 |
getTagProps | (props: DatePickerTagProps) => T['element'] | 标签：一个选中值一个，即库内 tag 的 root（data-scope="tag"）：语气、尺寸与禁用从本控件传下，形态按盒的面派生，另带 data-value。 |
getTagLabelProps | () => T['element'] | 标签文字所在的块（tag 的 label）：截断落在这一层；标签与 +N 共用。 |
getOverflowTagProps | () => T['element'] | 被折叠的标签合成的一个：同样是 tag 的 root，显示 overflowText、带 data-count；没有折叠的标签时 hidden。 |
getItemDeleteTriggerProps | (props: DatePickerTagProps) => T['button'] | 标签删除按钮：即所在标签那份 tag 的 close-trigger，可及名使用 translations.deleteItem。 不占 Tab 位、按下不夺焦；键盘在触发钮上按退格删掉最后一个。 |
getSegmentGroupProps | () => T['element'] | role=group 的分段容器，段位挂在其中；多选时整体 hidden，选中值改由标签行呈现。 |
getTriggerProps | () => T['button'] | |
getClearTriggerProps | () => T['button'] | |
getPositionerProps | () => T['element'] | |
getContentProps | () => T['element'] | |
getPresetGroupProps | () => T['element'] | 快捷选项列（role=listbox）；未提供 presets 时带 hidden。 |
getPresetProps | (props: DatePickerPresetProps) => T['element'] | 一条快捷选项（role=option）：点击把整份日期写入选中值。 |
getCalendarProps | () => T['element'] | 内嵌日历的挂载点，同时充当日历的根节点。 |
getTimeColumnProps | (props: DatePickerTimeColumnProps) => T['element'] | 时间列容器（时 / 分[/ 秒]各一列）；未开启 showTime 时带 hidden。 |
getTimeItemProps | (props: DatePickerTimeItemProps) => T['element'] | 时间选项：点击把该单位写入值（没有日期时以聚焦日作为日期段起值）。 |
getFooterProps | () => T['element'] | 浮层底部的操作区：放在 content 中、排在面板主体之后，确认按钮通常写在这里；不进入任何集合的拥有关系，方向键也无法到达。 |
getConfirmTriggerProps | () => T['button'] | 确认按钮：showTime 的收口；未开启 showTime 时带 hidden。 |
无障碍
键盘
规格出处：W3C APG
| 按键 | 生效条件 | 行为 |
|---|---|---|
Enter / Space | focus in trigger, closed | 展开日历浮层，焦点落到当前聚焦日那一格 |
Enter / Space | focus in trigger, open | 收起浮层，焦点回到 trigger |
Escape | open | 收起浮层并把焦点还给展开前那个控件（通常是 trigger），选中值不变 |
Tab / Shift+Tab | open | 不拦按键：焦点按 Tab 序列自然离开，浮层随即收起且不抢回焦点 |
Enter / Space | open, focus in grid | 选中聚焦日（由日历完成）；closeOnSelect 时收起浮层，多选不收起 |
ArrowUp / ArrowDown / Home / End | open, focus in 快捷选项列 | 在快捷选项之间移动焦点，到头回绕；不写值 |
Enter / Space | open, focus in 某条快捷选项 | 把这条快捷选项整份写进选中值；closeOnSelect 时收起浮层 |
Alt+ArrowDown | focus in 某一段, closed, not disabled | 展开浮层并把焦点移入；触发按钮是可选部件，键盘入口不能只挂在它上面 |
Backspace | focus in trigger, multiple, 有选中值, not disabled/readOnly | 摘掉最后一个选中值（标签行末尾那一枚）；多选时段位不出现，触发钮就是键盘入口 |
Enter | focus in 某一段, open | 收起浮层。段位里敲出来的值不触发「选完即收」（那时人还在打字），这是那条路的收口手势 |
Enter / Space | held on trigger / confirm-trigger（not disabled）、clear-trigger（可清）、preset 或 time-item（open, not disabled/readOnly, 该条可按） | 按住期间该部件投影 data-pressed，与指针 :active 同一副按压面；抬起或失焦撤下，浮层收起时一并撤下。日历里的部件由 calendar-picker 自己投影 |
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
segment-group | aria-disabled | 'true' | 'false' |
segment-group | aria-label | props.ariaLabel |
segment-group | aria-labelledby | label 部件的 id | undefined |
segment-group | role | 'group' |
trigger | aria-controls | content 部件的 id |
trigger | aria-expanded | 'true' | 'false' |
trigger | aria-haspopup | 'dialog' |
trigger | aria-label | props.ariaLabel |
trigger | aria-labelledby | label 部件的 id | undefined |
clear-trigger | aria-label | label.clearTrigger |
content | aria-hidden | !open || undefined |
content | aria-label | props.ariaLabel |
content | aria-labelledby | label 部件的 id | undefined |
content | aria-modal | 'false' |
content | role | 'dialog' |
preset-group | aria-disabled | 'true' | 'false' |
preset-group | aria-label | label.presets |
preset-group | aria-multiselectable | 'false' |
preset-group | aria-orientation | 'vertical' |
preset-group | role | 'listbox' |
preset | aria-disabled | 'true' | 'false' |
preset | aria-selected | 'true' | 'false' |
preset | role | 'option' |
time-column | aria-disabled | 'true' | 'false' |
time-column | aria-label | label[unit] |
time-column | aria-multiselectable | 'false' |
time-column | aria-orientation | 'vertical' |
time-column | role | 'listbox' |
time-item | aria-disabled | 'true' | 'false' |
time-item | aria-selected | 'true' | 'false' |
time-item | role | 'option' |
样式参考
皮肤
@xihan-ui/styles/date-picker.css 按 [data-scope="date-picker"][data-part="root"] 部件选择器书写，发布产物以挂载类 .xh-scope-date-picker 代替其中的 data-scope（特异性相同），位于 xihan.components 与 xihan.motion 层。覆盖样式使用 xihan.overrides，部件选择器照常可用。
forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-disabled | ''（条件成立时才出现） |
root | data-invalid | ''（条件成立时才出现） |
root | data-readonly | ''（条件成立时才出现） |
root | data-size | props.size |
root | data-state | 'open' | 'closed' |
root | data-tone | props.tone |
root | data-variant | props.variant |
label | data-disabled | ''（条件成立时才出现） |
control | data-disabled | ''（条件成立时才出现） |
control | data-invalid | ''（条件成立时才出现） |
control | data-readonly | ''（条件成立时才出现） |
control | data-state | 'open' | 'closed' |
control | data-variant | props.variant |
control | data-xh-action-owner | '' |
control | data-xh-field-chrome | '' |
control | data-xh-field-layout | 'multi-tag' | undefined |
control | data-xh-field-size | props.size |
tag-list | data-disabled | ''（条件成立时才出现） |
tag-list | data-instant | ''（条件成立时才出现） |
tag-list | data-placeholder-shown | ''（条件成立时才出现） |
tag-list | data-placeholder-text | props.placeholder | undefined | undefined |
tag-list | data-xh-tag-list | '' |
segment-group | data-complete | ''（条件成立时才出现） |
segment-group | data-disabled | ''（条件成立时才出现） |
segment-group | data-empty | ''（条件成立时才出现） |
segment-group | data-invalid | ''（条件成立时才出现） |
segment-group | data-out-of-range | ''（条件成立时才出现） |
segment-group | data-placeholder-shown | ''（条件成立时才出现） |
segment-group | data-placeholder-text | props.placeholder | undefined |
segment-group | data-readonly | ''（条件成立时才出现） |
trigger | data-disabled | ''（条件成立时才出现） |
trigger | data-pressed | ''（条件成立时才出现） |
trigger | data-state | 'open' | 'closed' |
trigger | data-xh-action-control | '' |
trigger | data-xh-action-display | 'always' |
trigger | data-xh-action-profile | 'field-inset' |
trigger | data-xh-action-size | props.size |
trigger | data-xh-action-variant | 'ghost' |
clear-trigger | data-pressed | ''（条件成立时才出现） |
clear-trigger | data-xh-action-control | '' |
clear-trigger | data-xh-action-display | 'has-value' |
clear-trigger | data-xh-action-has-value | ''（条件成立时才出现） |
clear-trigger | data-xh-action-profile | 'field-inset' |
clear-trigger | data-xh-action-size | props.size |
clear-trigger | data-xh-action-variant | 'ghost' |
positioner | data-hidden | ''（条件成立时才出现） |
positioner | data-placement | 定位引擎算出的实际落位 |
positioner | data-positioned | ''（条件成立时才出现） |
positioner | data-size | props.size |
positioner | data-state | 'open' | 'closed' |
positioner | data-tone | props.tone |
positioner | data-variant | props.variant |
content | data-instant | ''（条件成立时才出现） |
content | data-placement | 定位引擎算出的实际落位 |
content | data-state | 'open' | 'closed' |
preset | data-disabled | ''（条件成立时才出现） |
preset | data-pressed | ''（条件成立时才出现） |
preset | data-state | 'checked' | 'unchecked' |
preset | data-value | v |
preset | data-xh-collection-context | 'overlay' |
preset | data-xh-collection-item | '' |
preset | data-xh-collection-size | props.size |
calendar | data-disabled | ''（条件成立时才出现） |
calendar | data-readonly | ''（条件成立时才出现） |
calendar | data-state | 'open' | 'closed' |
time-column | data-unit | live[at]!.getAttribute('data-unit') as DatePickerTime… |
time-item | data-disabled | ''（条件成立时才出现） |
time-item | data-pressed | ''（条件成立时才出现） |
time-item | data-state | 'checked' | 'unchecked' |
time-item | data-unit | live[at]!.getAttribute('data-unit') as DatePickerTime… |
time-item | data-value | v |
time-item | data-xh-collection-context | 'overlay' |
time-item | data-xh-collection-item | '' |
time-item | data-xh-collection-size | props.size |
confirm-trigger | data-pressed | ''（条件成立时才出现） |
confirm-trigger | data-xh-action-control | '' |
confirm-trigger | data-xh-action-display | 'always' |
confirm-trigger | data-xh-action-profile | 'text' |
confirm-trigger | data-xh-action-size | 'xs' |
confirm-trigger | data-xh-action-variant | 'solid' |
confirm-trigger | data-xh-ink-surface | '' |
overflow-tag | data-count | String(overflowCount) |
tag | data-value | v |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-date-picker-action-bg | clear-triggertrigger | --xh-ink-surfacebackground-color | defaultxh-ink-surface | --xh-_action-variant-bg-rest | date-picker 的 clear-trigger、trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-date-picker-action-bg-active | clear-triggertrigger | background-color | disabledis(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | --xh-_action-variant-bg-pressed | date-picker 的 clear-trigger、trigger 部件 background-color 覆盖槽。 |
--xh-date-picker-action-bg-hover | clear-triggertrigger | --xh-ink-surfacebackground-color | disabledhoverloadingnot([data-disabled])not([data-loading])state=openxh-ink-surface | --xh-_action-variant-bg-hover | date-picker 的 clear-trigger、trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-date-picker-action-fg | clear-triggertrigger | color | default | --xh-fg-field-clear--xh-fg-muted | date-picker 的 clear-trigger、trigger 部件 color 覆盖槽。 |
--xh-date-picker-action-fg-hover | clear-triggertrigger | color | disabledhoverloadingnot([data-disabled])not([data-loading])state=open | --xh-fg-default | date-picker 的 clear-trigger、trigger 部件 color 覆盖槽。 |
--xh-date-picker-action-font-size | clear-triggertrigger | font-size | default | --xh-text-secondary-size | date-picker 的 clear-trigger、trigger 部件 font-size 覆盖槽。 |
--xh-date-picker-action-radius | clear-triggertrigger | border-radius | default | --xh-shape-circle--xh-shape-inset | date-picker 的 clear-trigger、trigger 部件 border-radius 覆盖槽。 |
--xh-date-picker-action-size | clear-triggertrigger | block-sizeinline-sizemin-inline-size | defaultxh-action-profile=field-inset | --xh-_action-profile-visual-size | date-picker 的 clear-trigger、trigger 部件 block-size、inline-size、min-inline-size 覆盖槽。 |
--xh-date-picker-calendar-gap | calendar | gap | default | --xh-space-0 | date-picker 的 calendar 部件 gap 覆盖槽。 |
--xh-date-picker-column-divider | calendarpreset-grouptime-column | backgroundborder-block-endborder-block-startborder-inline-end | @media (min-width: 768px)defaulthas(+ [data-part='time-column']) | --xh-material-solid-border | date-picker 的 calendar、preset-group、time-column 部件 background、border-block-end、border-block-start、border-inline-end 覆盖槽。 |
--xh-date-picker-confirm-trigger-bg | confirm-trigger | --xh-ink-surfacebackground-color | defaultxh-ink-surface | --xh-_action-variant-bg-rest | date-picker 的 confirm-trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-date-picker-confirm-trigger-bg-active | confirm-trigger | background-color | disabledis(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | --xh-_action-variant-bg-pressed | date-picker 的 confirm-trigger 部件 background-color 覆盖槽。 |
--xh-date-picker-confirm-trigger-bg-hover | confirm-trigger | background-color | disabledhoverloadingnot([data-disabled])not([data-loading]) | --xh-_action-variant-bg-hover | date-picker 的 confirm-trigger 部件 background-color 覆盖槽。 |
--xh-date-picker-confirm-trigger-fg | confirm-trigger | color | defaultdisabledhoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | --xh-_action-variant-fg-hover--xh-_action-variant-fg-pressed--xh-_action-variant-fg-rest | date-picker 的 confirm-trigger 部件 color 覆盖槽。 |
--xh-date-picker-confirm-trigger-font-size | confirm-trigger | font-size | default | --xh-text-caption-size | date-picker 的 confirm-trigger 部件 font-size 覆盖槽。 |
--xh-date-picker-confirm-trigger-h | confirm-trigger | block-sizeinline-size | defaultxh-action-profile=field-inset | --xh-_action-profile-visual-size | date-picker 的 confirm-trigger 部件 block-size、inline-size 覆盖槽。 |
--xh-date-picker-confirm-trigger-margin | confirm-triggercontent | margin | has(> [data-part='time-column']) | --xh-space-2 | date-picker 的 confirm-trigger、content 部件 margin 覆盖槽。 |
--xh-date-picker-confirm-trigger-px | confirm-trigger | padding-inline | default | --xh-space-2 | date-picker 的 confirm-trigger 部件 padding-inline 覆盖槽。 |
--xh-date-picker-confirm-trigger-radius | confirm-trigger | border-radius | default | --xh-shape-control | date-picker 的 confirm-trigger 部件 border-radius 覆盖槽。 |
--xh-date-picker-confirm-trigger-shadow | confirm-trigger | box-shadow | defaultdisabledhoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | none | date-picker 的 confirm-trigger 部件 box-shadow 覆盖槽。 |
--xh-date-picker-content-bg | content | background | default | --xh-bg-surface | date-picker 的 content 部件 background 覆盖槽。 |
--xh-date-picker-content-border | content | border | default | --xh-border-default | date-picker 的 content 部件 border 覆盖槽。 |
--xh-date-picker-content-fg | content | color | default | --xh-fg-default | date-picker 的 content 部件 color 覆盖槽。 |
--xh-date-picker-content-px | content | padding-inline | default | --xh-space-0 | date-picker 的 content 部件 padding-inline 覆盖槽。 |
--xh-date-picker-content-py | content | padding-block | default | --xh-space-0 | date-picker 的 content 部件 padding-block 覆盖槽。 |
--xh-date-picker-content-radius | content | border-radius | default | --xh-shape-overlay | date-picker 的 content 部件 border-radius 覆盖槽。 |
--xh-date-picker-content-shadow | content | box-shadow | default | --xh-elevation-floating | date-picker 的 content 部件 box-shadow 覆盖槽。 |
--xh-date-picker-control-bg | control | background-color | xh-field-chrome | --xh-_field-variant-bg-rest | date-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-picker-control-bg-disabled | control | background-color | disabledxh-field-chrome | --xh-_field-variant-bg-disabled | date-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-picker-control-bg-hover | control | background-color | disabledhoverinvalidloadingnot(:focus-within)not([data-disabled])not([data-invalid])not([data-loading])not([data-readonly])readonlyxh-field-chrome | --xh-_field-variant-bg-hover | date-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-picker-control-bg-readonly | control | background-color | readonlyxh-field-chrome | --xh-_field-variant-bg-read-only | date-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-picker-control-border | control | border | xh-field-chrome | --xh-_field-variant-border-rest | date-picker 的 control 部件 border 覆盖槽。 |
--xh-date-picker-control-border-focus | control | border-colorbox-shadow | disabledfocus-withinnot([data-disabled])xh-field-chrome | --xh-_field-variant-border-focus | date-picker 的 control 部件 border-color、box-shadow 覆盖槽。 |
--xh-date-picker-control-border-hover | control | border-color | disabledhoverinvalidloadingnot(:focus-within)not([data-disabled])not([data-invalid])not([data-loading])not([data-readonly])readonlyxh-field-chrome | --xh-_field-variant-border-hover | date-picker 的 control 部件 border-color 覆盖槽。 |
--xh-date-picker-control-border-invalid | control | border-color | invalidxh-field-chrome | --xh-_field-variant-border-invalid | date-picker 的 control 部件 border-color 覆盖槽。 |
--xh-date-picker-control-fg | control | color | xh-field-chrome | --xh-fg-default | date-picker 的 control 部件 color 覆盖槽。 |
--xh-date-picker-control-gap | control | gap | xh-field-chrome | --xh-_date-picker-gap | date-picker 的 control 部件 gap 覆盖槽。 |
--xh-date-picker-control-h | control | block-sizemin-block-size | has([data-xh-field-input][data-xh-field-layout='multi-tag'])has([data-xh-field-input][data-xh-field-layout='single-line'])has([data-xh-field-input][data-xh-field-layout='textarea'])xh-field-chromexh-field-inputxh-field-layout=multi-tagxh-field-layout=single-linexh-field-layout=textarea | --xh-_date-picker-control-h | date-picker 的 control 部件 block-size、min-block-size 覆盖槽。 |
--xh-date-picker-control-max-h | control | max-block-size | xh-field-layout=multi-tag | --xh-viewport-h-sm | date-picker 的 control 部件 max-block-size 覆盖槽。 |
--xh-date-picker-control-min-w | controlroot | min-inline-size | defaultxh-field-chrome | --xh-control-min-w | date-picker 的 control、root 部件 min-inline-size 覆盖槽。 |
--xh-date-picker-control-px | control | padding-inline | xh-field-chrome | --xh-_date-picker-control-px | date-picker 的 control 部件 padding-inline 覆盖槽。 |
--xh-date-picker-control-radius | control | border-radius | xh-field-chrome | --xh-shape-control | date-picker 的 control 部件 border-radius 覆盖槽。 |
--xh-date-picker-control-shadow | control | box-shadow | xh-field-chrome | none | date-picker 的 control 部件 box-shadow 覆盖槽。 |
--xh-date-picker-control-w | root | inline-sizemin-inline-size | default | --xh-control-w | date-picker 的 root 部件 inline-size、min-inline-size 覆盖槽。 |
--xh-date-picker-font-size | segment-grouptag-list | font-size | default | --xh-_date-picker-font-size | date-picker 的 segment-group、tag-list 部件 font-size 覆盖槽。 |
--xh-date-picker-footer-border | footer | border-block-start | default | --xh-material-solid-border | date-picker 的 footer 部件 border-block-start 覆盖槽。 |
--xh-date-picker-footer-fg | footer | color | default | --xh-fg-muted | date-picker 的 footer 部件 color 覆盖槽。 |
--xh-date-picker-footer-font-size | footer | font-size | default | --xh-text-caption-size | date-picker 的 footer 部件 font-size 覆盖槽。 |
--xh-date-picker-footer-gap | footer | gapinline-size | default | --xh-space-2 | date-picker 的 footer 部件 gap、inline-size 覆盖槽。 |
--xh-date-picker-footer-px | footer | inline-size | default | --xh-space-2 | date-picker 的 footer 部件 inline-size 覆盖槽。 |
--xh-date-picker-footer-py | footer | padding-block | default | --xh-space-2 | date-picker 的 footer 部件 padding-block 覆盖槽。 |
--xh-date-picker-gap | labelroot | gapmargin-block-end | default | --xh-space-1 | date-picker 的 label、root 部件 gap、margin-block-end 覆盖槽。 |
--xh-date-picker-heading-font-weight | calendarheadingheading-month-triggerheading-year-trigger | font-weight | default | --xh-font-weight-regular | date-picker 的 calendar、heading、heading-month-trigger、heading-year-trigger 部件 font-weight 覆盖槽。 |
--xh-date-picker-icon-size | controlpositionerroot | --xh-icon-size | defaultis([data-part='root'], [data-part='positioner'])size=lgsize=smxh-field-chrome | --xh-_field-size-glyph-size--xh-glyph-size-lg--xh-glyph-size-md--xh-glyph-size-sm | date-picker 的 control、positioner、root 部件 --xh-icon-size 覆盖槽。 |
--xh-date-picker-label-fg | label | color | default | --xh-fg-muted | date-picker 的 label 部件 color 覆盖槽。 |
--xh-date-picker-label-fg-disabled | label | color | disabled | --xh-fg-muted | date-picker 的 label 部件 color 覆盖槽。 |
--xh-date-picker-label-font-size | label | font-size | default | --xh-text-label-size | date-picker 的 label 部件 font-size 覆盖槽。 |
--xh-date-picker-label-font-weight | label | font-weight | default | --xh-text-label-weight | date-picker 的 label 部件 font-weight 覆盖槽。 |
--xh-date-picker-label-gap | label | margin-block-end | default | --xh-space-2 | date-picker 的 label 部件 margin-block-end 覆盖槽。 |
--xh-date-picker-layer | positioner | z-index | default | --xh-_layer | date-picker 的 positioner 部件 z-index 覆盖槽。 |
--xh-date-picker-literal-fg | segment-group | color | not([data-scope]) | --xh-fg-subtle | date-picker 的 segment-group 部件 color 覆盖槽。 |
--xh-date-picker-max-h | content | max-block-size | default | --xh-_date-picker-available-h | date-picker 的 content 部件 max-block-size 覆盖槽。 |
--xh-date-picker-placeholder-fg | segment-grouptag-list | color | placeholder-shown | --xh-fg-subtle | date-picker 的 segment-group、tag-list 部件 color 覆盖槽。 |
--xh-date-picker-preset-bg | preset | background-color | defaultdisablederroris([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])selectedxh-collection-context=overlay | --xh-bg-subtle | date-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-picker-preset-bg-hover | preset | background-color | disablederrorhighlightedhoveris(:focus-visible, [data-highlighted])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])selectedxh-collection-context=overlay | --xh-bg-subtle-hover | date-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-picker-preset-bg-pressed | preset | background-color | disablederroris(:active, [data-pressed])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])pressedselectedxh-collection-context=overlay | --xh-bg-subtle-active | date-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-picker-preset-check-fg | preset | background-color | default | --xh-_date-picker-check-fg | date-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-picker-preset-check-size | preset | block-sizeinline-sizepadding-inline-end | default | --xh-control-indicator-sm | date-picker 的 preset 部件 block-size、inline-size、padding-inline-end 覆盖槽。 |
--xh-date-picker-preset-fg | preset | color | defaultdisablederroris([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])selectedxh-collection-context=overlay | --xh-fg-muted | date-picker 的 preset 部件 color 覆盖槽。 |
--xh-date-picker-preset-fg-disabled | preset | background-colorcolor | defaultdisabled | --xh-fg-disabled | date-picker 的 preset 部件 background-color、color 覆盖槽。 |
--xh-date-picker-preset-fg-hover | preset | color | disablederrorhighlightedhoveris(:active, [data-pressed])is(:focus-visible, [data-highlighted])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])pressedselectedxh-collection-context=overlay | --xh-fg-default | date-picker 的 preset 部件 color 覆盖槽。 |
--xh-date-picker-preset-font-size | preset | font-size | default | --xh-text-caption-size | date-picker 的 preset 部件 font-size 覆盖槽。 |
--xh-date-picker-preset-group-gap | preset-group | gap | default | --xh-space-1 | date-picker 的 preset-group 部件 gap 覆盖槽。 |
--xh-date-picker-preset-group-h | preset-group | max-block-size | default | --xh-viewport-h-lg | date-picker 的 preset-group 部件 max-block-size 覆盖槽。 |
--xh-date-picker-preset-group-px | preset-group | padding-inline | default | --xh-space-2 | date-picker 的 preset-group 部件 padding-inline 覆盖槽。 |
--xh-date-picker-preset-group-py | preset-group | padding-block | default | --xh-space-2_5 | date-picker 的 preset-group 部件 padding-block 覆盖槽。 |
--xh-date-picker-preset-h | preset | block-sizeline-height | default | --xh-control-action-size | date-picker 的 preset 部件 block-size、line-height 覆盖槽。 |
--xh-date-picker-preset-px | preset | inset-inline-endpadding-inlinepadding-inline-end | default | --xh-space-2 | date-picker 的 preset 部件 inset-inline-end、padding-inline、padding-inline-end 覆盖槽。 |
--xh-date-picker-preset-radius | preset | border-radius | default | --xh-shape-control | date-picker 的 preset 部件 border-radius 覆盖槽。 |
--xh-date-picker-tag-list-gap | tag-list | gap | xh-tag-list | --xh-space-1 | date-picker 的 tag-list 部件 gap 覆盖槽。 |
--xh-date-picker-time-column-gap | time-columntime-item | gapinset-block | default | --xh-space-2 | date-picker 的 time-column、time-item 部件 gap、inset-block 覆盖槽。 |
--xh-date-picker-time-column-h | time-column | block-sizepadding-block | @media (pointer: coarse)default | --xh-overlay-calendar-column-h--xh-overlay-calendar-column-h-coarse | date-picker 的 time-column 部件 block-size、padding-block 覆盖槽。 |
--xh-date-picker-time-column-min-w | time-column | min-inline-size | default | --xh-overlay-column-min-w | date-picker 的 time-column 部件 min-inline-size 覆盖槽。 |
--xh-date-picker-time-column-min-w-mobile | time-column | min-inline-size | @media not all and (min-width: 768px) | 2.75rem | date-picker 的 time-column 部件 min-inline-size 覆盖槽。 |
--xh-date-picker-time-column-offset | time-column | margin-block-start | default | --xh-control-action-size | date-picker 的 time-column 部件 margin-block-start 覆盖槽。 |
--xh-date-picker-time-column-px | time-column | padding-inline | default | --xh-space-1 | date-picker 的 time-column 部件 padding-inline 覆盖槽。 |
--xh-date-picker-time-column-px-mobile | time-column | padding-inline | @media not all and (min-width: 768px) | --xh-space-1 | date-picker 的 time-column 部件 padding-inline 覆盖槽。 |
--xh-date-picker-time-column-py | time-column | padding-block | default | --xh-space-1 | date-picker 的 time-column 部件 padding-block 覆盖槽。 |
--xh-date-picker-time-item-bg-hover | time-item | background-color | disablederrorhighlightedhoveris(:focus-visible, [data-highlighted])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])selectedxh-collection-context=overlay | --xh-bg-subtle | date-picker 的 time-item 部件 background-color 覆盖槽。 |
--xh-date-picker-time-item-bg-pressed | time-item | background-color | disablederroris(:active, [data-pressed])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])pressedselectedxh-collection-context=overlay | --xh-bg-subtle-hover | date-picker 的 time-item 部件 background-color 覆盖槽。 |
--xh-date-picker-time-item-check-fg | time-item | background-color | default | --xh-_date-picker-check-fg | date-picker 的 time-item 部件 background-color 覆盖槽。 |
--xh-date-picker-time-item-check-size | time-item | block-sizeinline-sizeinset-inline-endpadding-inline | @media not all and (min-width: 768px)default | --xh-_date-picker-time-item-check-size | date-picker 的 time-item 部件 block-size、inline-size、inset-inline-end、padding-inline 覆盖槽。 |
--xh-date-picker-time-item-fg | time-item | color | defaultdisablederrorhighlightedhoveris(:active, [data-pressed])is(:focus-visible, [data-highlighted])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])pressedselectedxh-collection-context=overlay | --xh-material-frosted-fg | date-picker 的 time-item 部件 color 覆盖槽。 |
--xh-date-picker-time-item-fg-selected | time-item | color | disablederrorhighlightedhoveris(:active, [data-pressed])is(:focus-visible, [data-highlighted])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])pressedselectedxh-collection-context=overlay | --xh-date-picker-time-item-fg | date-picker 的 time-item 部件 color 覆盖槽。 |
--xh-date-picker-time-item-font-size | time-item | font-size | default | --xh-_date-picker-font-size | date-picker 的 time-item 部件 font-size 覆盖槽。 |
--xh-date-picker-time-item-font-weight-selected | time-item | font-weight | disablederrorhighlightedhoveris(:active, [data-pressed])is(:focus-visible, [data-highlighted])is([aria-selected='true'], [data-selected])not([aria-disabled='true'], [data-disabled], [aria-busy='true'], [data-error])pressedselectedxh-collection-context=overlay | --xh-font-weight-medium | date-picker 的 time-item 部件 font-weight 覆盖槽。 |
--xh-date-picker-time-item-h | time-columntime-item | block-sizepadding-block | default | --xh-control-action-size | date-picker 的 time-column、time-item 部件 block-size、padding-block 覆盖槽。 |
--xh-date-picker-time-item-px | time-item | inset-inline-endpadding-inline | default | --xh-space-0_5 | date-picker 的 time-item 部件 inset-inline-end、padding-inline 覆盖槽。 |
--xh-date-picker-time-item-radius | time-item | border-radius | default | --xh-shape-inset | date-picker 的 time-item 部件 border-radius 覆盖槽。 |
动效
动效角色：按压 · 状态 · 指示与换位 · 出现 · 列表（见动效规范）。
共享关键帧 xh-fade-in · xh-fade-out · xh-overlay-pop-in · xh-pop-in · xh-pop-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立；background-color · border-color · color · opacity · translate · visibility 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。
皮肤之外还有一段：退场由适配器的退场闸门把关，动画播完才真收起。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
响应式
皮肤按视口分档：min-width: 768px。
皮肤另按输入能力分档：hover: hover · hover: none · pointer: coarse：同一份皮肤在触屏与带指针的设备上不一样，与视口宽度无关。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。