简体中文
DateRangePicker 日期范围选择器
将起止两组可键入的分段日期框、范围分隔符、日历触发器和范围日历浮层组合成一个字段。
用法
输入或选择起止日期
旅行日期
yyyy
/mm
/dd
yyyy
/mm
/dd
组件结构
加粗的是必需部件。
data-scope="date-range-picker"：root · label · control · segment-group · range-separator · trigger · clear-trigger · positioner · content · preset-group · preset · calendar · column-group · column-group-label · time-column · time-item · footer · confirm-trigger
示例
两页并排
起止常跨月时设置 visibleCount=2，两页一起翻
入住与退房
yyyy
/mm
/dd
yyyy
/mm
/dd
区间：（未选）
快捷选项
常用区间一键写入两端
统计区间
yyyy
/mm
/dd
yyyy
/mm
/dd
不可用日期
周末不可选，区间允许跨过不可用的日期
工作日区间
yyyy
/mm
/dd
yyyy
/mm
/dd
周期区间
granularity 决定两组输入行铺设哪几段、浮层铺设哪一档格子
周报区间
yyyy
/ww
周yyyy
/ww
周月报区间
yyyy
/mm
yyyy
/mm
季报区间
yyyy
/Qq
yyyy
/Qq
年报区间
yyyy
yyyy
日期加时间
showTime 让起止都带上时刻，defaultTime 在只点日期时补 00:00:00 与 23:59:59；起止同一天时终点早于起点的时刻不可选，由确认钮收口
查询区间
当前值：（未填齐）yyyy
/mm
/dd
hh
:mm
:ss
yyyy
/mm
/dd
hh
:mm
:ss
只改终点
点终点那组段位展开时 activeIndex 为 1，日历以起点为锚、点在起点之后只改终点；从触发钮展开照旧重新挑一段
旅行日期
正在编辑：起点；区间：2026-10-05 → 2026-10-092026
/10
/05
2026
/10
/09
设计指引
何时使用
- 用户需要选择一段起止日期：报表区间、入住与退房、有效期。
- 需要先查看月份分布再确定起止，或直接键入两端。
- 区间要精确到时刻、可能跨天：日志查询、活动起止。开启
showTime。
何时不用
特性
- 值始终为区间两端
[start, end]，按位存放：只填了终点时是['', 终点]，受控回写按同一下标对应。 - 不写结构时按标准结构铺出整套部件（Vue 不写默认插槽、React 不给 children、Web Components 不写部件或只写
root），三端出自同一个结构函数：标题（label给文字），盒里的起止两组段位、分隔符、清空钮与日历钮，起止两份表单影子，浮层里依次是快捷选项列、每个面板一份日历、showTime的起止两组时间列（各带小标题）与底栏的确认钮（文字取translations.confirmTrigger）。翻月、换层级与选中变化时结构随之重铺。Web Components 里标题可以写在宿主的直接子节点上接管：slot="label"。自己写结构时，Vue / React 的时间列可以用XhDateRangePickerTimePanel整组铺，也可以逐组写XhDateRangePickerColumnGroup（index），组里不写内容时铺小标题XhDateRangePickerColumnGroupLabel与各列XhDateRangePickerTimeColumn（unit），列里不写内容时按可选值铺XhDateRangePickerTimeItem。 - 起止各一组段位，
range-separator隔在中间；方向键换段不跨组，name与endName各自决定两份隐藏输入参不参与提交。 - 输入行与别的字段同取缺省宽
--xh-control-w。起止两组按日带时刻放不进时，两组按各自内容宽一起收、各在组内裁掉放不下的段位，键盘走到被裁的段位时组跟着滚过去；分隔符与日历钮始终留在框里。要整段露出，经--xh-date-range-picker-control-w钉宽。 startPlaceholder/endPlaceholder是两组段位各自的整条占位：哪一端一段都没填、焦点也不在它的段上，就在那一组显示这句文字（「开始日期」「结束日期」）；placeholder是两端共用的逐段占位串。- 浮层内是日历范围选择器：先选起点再选终点，两端都落定后才写值并收起浮层；支持按住拖选与拖动已选区间的一端。
granularity支持 day / week / month / quarter / year，输入段、网格和周期边界一起切换。周粒度按 ISO 周（星期一到星期日）成段，输入行的「2026-33」按 ISO 周年计，与locale和firstDayOfWeek都无关：en-US 这类星期日开头的 locale 下，日视图的一行比所挑的 ISO 周早一天开始。- 浮层里的日历由作者照插槽数据渲染：日视图读
weeks，周、月、季度与年读按行切好的rows（多面板读panels[i].rows），一行写一个week-row、格子放进行里，写法同日历范围选择器。 min、max、isDateUnavailable（第二个参数是当前起点）与allowsNonContiguousRanges一并转给日历。presets提供“近 7 天”“本月”等整段快捷项，值使用 ISO 8601 的区间写法拼接两端；每项是一颗淡底小钮，当前值落在哪一项就在它末端画对号。- 终点早于起点、任一端越界或不可用时整个字段标为不合法，也可以用
invalid显式声明。 - 输入值、展开状态和聚焦日期均可受控；点击输入行可以继续逐段键入，点击日历图标则把焦点送入日历。
- 两组输入行的写法随
locale与granularity/segments走，不接受formatOptions或格式串，理由见日期字段。 firstDayOfWeek（0 = 星期日 … 6 = 星期六）原样交给浮层里的日历，只改表头、行首与 Home / End，两组段位的段序仍按locale；用法见日历选择器的示例。showTime（仅granularity=day）让两端都升格为不带时区的YYYY-MM-DDTHH:mm[:ss]：两组段位带上时刻段，浮层里起止各多出一组时间列（column-group里的time-column/time-item：列与格与日期选择器的时间部件同名，一端的外壳与小标题与时间范围选择器同名），选完日期不收起，由confirm-trigger收口。timeZone仍只决定「今天」。- 起止两组时间列的顶边接着日历标题栏的分隔线、底边与日期网格对齐；日历与起点组、起点组与终点组之间各隔一道竖线，组内列与列之间不画线。
- 确认钮写在底栏（
footer）里：底栏是浮层底部的通栏操作区，落在日历与两组时间列下面独占一行，上沿一道分隔线、四周 8 的内衬；作者另放的说明文字排在行首、取弱化的说明档字，确认钮落在行尾。底栏里只有确认钮时，未开showTime它随确认钮一并收起，不留空栏。 defaultTime（如['00:00:00', '23:59:59']）在只点日期时给起止各补上对应时刻；已经挑过时刻的一端换日期时时刻原样留着。快捷选项同样是「日期拼上这一端此刻的时刻」，没有就按defaultTime。- 时间列与时间选择器共用一份约束：
hourCycle、按单位的timeStep、带上下文的isTimeUnavailable（context.index是哪一端、context.date是这一端的日期）；min/max可以带时间段，同一天界外的时刻标为不可选。起止落在同一天时，终点列早于起点时刻的格自动不可选；两端按日期时间比先后，终点早于起点即整份标为不合法。 activeIndex表示当前编辑哪一端，可受控：从终点那组段位展开（点它或在它上面按 Alt+ArrowDown）为 1，其余为 0；聚焦某一组段位、点某一端的时间格时随之改写；正在编辑的那一组时间列与小标题投影data-editing，缺省皮肤不据此给两组标题分档，起止两组标题同一副样式。为 1 且已有起点时日历只改终点——点在起点那一天或之后即落终点、起点不动，点在起点之前的日子从那一天重新开始挑；从触发钮展开照旧是先点起点再点终点。这与 antd 的「从终点输入框继续改」一致，React Aria 的区间日历每次点选都重新开始、没有这一档。
组合
- 浮层内嵌日历范围选择器，翻月、层级切换、拖选与键盘导航由它负责。
- 输入行内嵌两组日期字段的段位，逐段键入与加减由它负责。
- 直接放入表单字段：字段的标题并进日历钮的名字，说明与错误文案进描述链；只读、必填与校验由各段报告，日历钮是普通按钮，不带 aria-readonly / aria-required。有值时清空钮顶替日历钮，点字段标题焦点落在第一段。
最佳实践
- 使用明确的字段标签，两组段位各自报告“开始日期”“结束日期”。
- 起止段组之间必须渲染
range-separator，不依赖空白区分两端。 - 起止常跨月时显式传
visibleCount="2"，并排查看两页。两页始终联动、一起翻页，不提供解绑，理由见日历范围选择器。 - 需要统一查询值时，读取
api.periodValue得到周期首尾与回显键。 - 常用区间优先提供快捷项，日期在 computed / memo 中计算后再传入。
- 开了
showTime时把确认钮放进底栏，不在content里另写带样式的包裹块。
反模式
- 用两个日期选择器拼接一个区间：两端之间没有轨道、没有拖选，也不校验先后顺序。
- 未经说明就预先选好一段。
- 让浮层遮挡当前输入值。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-date-range-picker> |
| Vue 组件 | XhDateRangePickerCalendar XhDateRangePickerCell XhDateRangePickerCellTrigger XhDateRangePickerClearTrigger XhDateRangePickerColumnGroup XhDateRangePickerColumnGroupLabel XhDateRangePickerConfirmTrigger XhDateRangePickerContent XhDateRangePickerControl XhDateRangePickerFooter XhDateRangePickerGrid XhDateRangePickerGridBody XhDateRangePickerGridHead XhDateRangePickerHeader XhDateRangePickerHeading XhDateRangePickerHeadingMonthTrigger XhDateRangePickerHeadingYearTrigger XhDateRangePickerHiddenInput XhDateRangePickerLabel XhDateRangePickerNextTrigger XhDateRangePickerNextYearTrigger XhDateRangePickerPositioner XhDateRangePickerPreset XhDateRangePickerPresetGroup XhDateRangePickerPrevTrigger XhDateRangePickerPrevYearTrigger XhDateRangePickerRangeSeparator XhDateRangePickerRoot XhDateRangePickerSegment XhDateRangePickerSegmentGroup XhDateRangePickerTimeColumn XhDateRangePickerTimeItem XhDateRangePickerTimePanel XhDateRangePickerTrigger XhDateRangePickerWeekDay XhDateRangePickerWeekNumber XhDateRangePickerWeekRow |
| 组合式函数 | useDateRangePicker |
| 状态机 | dateRangePickerMachine |
| 皮肤 | @xihan-ui/styles/date-range-picker.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
labelled | boolean | 作者渲染了 label 部件时置真，由适配器统计而不是判断标题文字是否有值。 为假时可聚焦部件不把 label 的 id 写进 aria-labelledby：指向未渲染的 id 是无效引用，作者写在控件上的 aria-label 也会被它压住。 | |
ariaLabel | string | 不显示出来的名字，写成 aria-label 落在与字段标签同一个部件上。 放进字段（字段接线）或渲染了 label 部件时名字以它们为准，aria-labelledby 盖过它。 | |
value | string[] | 区间两端，ISO 串。提供即受控：读取直取 prop，写入只发 onValueChange 不落内部值。 按位存放，空缺的一端为空串。 | |
defaultValue | 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。 | |
isDateUnavailable | (value: string, anchor: string | null) => boolean | 不可用判定，接收 ISO 串。界外与判定为真的日期同等处理。 第二个参数是区间选到一半时的起点，其余时候为 null。 | |
allowsNonContiguousRanges | boolean | 区间允许跨过不可用的日期，默认关闭；关闭时落下起点之后只能选到两侧最近的不可用日为止。 | |
disabled | boolean | 整个控件禁用：trigger 为原生 disabled，段位退出 Tab 序列，日历格子全部为 aria-disabled。 | |
readOnly | boolean | 只读：浮层照常展开、日历照常翻月浏览，但选中值不可修改。 | |
invalid | boolean | 校验失败：段位报告 aria-invalid，各角色节点带 data-invalid。 未提供时也会自行判定：任一端越界，或终点早于起点。 | |
required | boolean | 必填标注，写入每一段的 aria-required。 | |
name | string | 起点隐藏输入的表单字段名；提供后才带 name，ISO 串随表单一并提交。 | |
endName | string | 终点隐藏输入的表单字段名；未提供时终点不参与提交。 | |
placeholder | DateSegmentPlaceholders | 逐段的占位串，两组段位共用，覆盖内置的 yyyy / mm / dd。 | |
startPlaceholder | string | 起点那组段位的整条占位：一段都没填、焦点也不在段上时显示这句文字（「开始日期」），焦点进到段上即换回段位。 | |
endPlaceholder | string | 终点那组段位的整条占位，规则同 startPlaceholder。 | |
granularity | CalendarGranularity | 选择粒度。输入行与周期网格都由它决定。 | |
activeView | CalendarView | 面板当前所在的层级。提供即受控；未提供时跟随 granularity，每次展开都回到目标粒度。 点击标题中的年 / 月会修改它。 | |
segments | DateSegmentSet | 输入行铺设的段。未提供时按 granularity 推导：按周为「2026-33」、按月为「2026-05」、 按季度为「2026-Q2」、按年为「2026」，按天则按 locale 排列年月日。 | |
presets | DateRangePickerPreset[] | 快捷选项（「近 7 天」「本月」等）。提供后浮层中多出一列，点击即整份写入两端。 日期需计算后传入：连接层每帧求值，把 today() 放进渲染期会跨零点得出两个结果。 不是恰好两端、落在 min / max 之外或被 isDateUnavailable 判定不可用的选项自动不可按下。 | |
visibleCount | number | 展示的连续日历面板数；默认 1。起止常跨月，并排两页时显式提供 2。 | |
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<DateRangePickerTranslations> | ||
closeOnSelect | boolean | 选完即收起，默认 true。两端都落定才视为选完；showTime 下不收，由确认按钮收口。 | |
showTime | boolean | 一体化时间：两端都升格为 'YYYY-MM-DDTHH:mm[:ss]'（不带时区），输入行两组段位带上时刻段， 浮层里起止各多出一组时间列，选完日期不收起、由确认按钮收口。只在 granularity=day 下生效。 此时 min / max 可以带时间段：日历按日期段收，时间列在与它同一天时按时间段标不可选。 | |
timeGranularity | DatePickerTimeGranularity | showTime 的时间段精度，默认 minute。 | |
hourCycle | TimeHourCycle | showTime 的小时制，缺省按 locale 推断（与 TimePicker 同一口径，没给 locale 时 24）。12 时两组时间列多出上下午列、两组段位多出上下午段。 | |
timeStep | TimeStep | showTime 时间列按单位的步进：{ hour?, minute?, second? }，各单位缺省 1。 | |
isTimeUnavailable | TimeUnavailablePredicate | showTime 时间列的逐格可选性。value 是两位补零的格值，时列恒按 24 小时制给出； context 带这一端已选的时（24 小时制）与分、这一端所属的日期与端号（index）。 判定为真的格子仍可聚焦，只是按不下去。起止同一天时，终点列早于起点的时刻另由组件自己标不可选。 | |
defaultTime | [string, string] | showTime 下只点日期时两端各补的时刻，例如 ['00:00:00', '23:59:59']（区间查询最常用）。 只补还没有时刻的那一端：已挑过时刻的一端换日期时时刻原样留着。按 timeGranularity 归一，写坏的一端按零点补。 | |
activeIndex | DateRangePickerEndIndex | 当前编辑区间的哪一端。提供即受控；未提供时每次展开都重新定：从终点那组段位展开为 1，其余为 0。 聚焦某一组段位、点某一端的时间格时随之改写。为 1 且已有起点时日历只改终点： 点在起点那一天或之后即落终点、起点不动，点在起点之前从那一天重新开始挑。 没有配套的 defaultActiveIndex：它每次展开都会重定，非受控初值没有生效时刻。 | |
onActiveIndexChange | (details: DateRangePickerActiveIndexChangeDetails) => void | 当前编辑的一端变化；受控时是唯一出口。 | |
onValueChange | (details: DateRangePickerValueChangeDetails) => void | value 变化意图回调；受控时是唯一出口，非受控时随内部写入一并通知。 | |
onClear | () => void | 用户按清空钮（clear-trigger）清掉了值；先发值变化，再发它。程序化的 clear() 不发。 | |
onOpenChange | (details: DateRangePickerOpenChangeDetails) => void | open 变化意图回调；受控时是唯一出口，非受控时随内部转移一并通知。 | |
onFocusedValueChange | (details: DateRangePickerFocusChangeDetails) => void | 聚焦日变化（方向键、翻月、展开、段位输入都会发出）。 网格由外部渲染，不监听该事件时日历不会换月。 | |
onActiveViewChange | (details: CalendarViewChangeDetails) => void | 面板所在层级变化（点击标题向上、点击格子向下都会发出）；受控时是唯一出口。 |
事件
自定义元素将载荷放在 detail；Vue 使用同名 emit。
| 事件 | 载荷 | 说明 |
|---|---|---|
value-change | DateRangePickerValueChangeDetails | 区间两端变化；detail 为 { value: string[] }，只填终点时为 ['', end] |
clear | `` | 用户按清空钮（clear-trigger）清掉了值；先发值变化，再发它。程序化的 clear() 不发。 |
open-change | DateRangePickerOpenChangeDetails | open 状态变化；detail 为 { open: boolean } |
focused-value-change | DateRangePickerFocusChangeDetails | 聚焦日变化（展示月可能随之变化）；detail 为 { focusedValue: string }，作者据此重绘网格 |
active-view-change | CalendarViewChangeDetails | 切换到另一层级（点击标题向上、点击格子向下）；detail 为 { activeView: 'day'|'week'|'month'|'quarter'|'year' }，作者据此重绘网格 |
active-index-change | DateRangePickerActiveIndexChangeDetails | 当前编辑的一端变化；detail 为 { activeIndex: 0 | 1 } |
插槽
仅列出带载荷的插槽。
| Vue 组件 | 插槽 | 载荷 | 说明 |
|---|---|---|---|
XhDateRangePickerColumnGroup | default | — | 自行铺小标题与各列；未写时按这一端的列自动铺。 |
XhDateRangePickerColumnGroupLabel | default | — | 小标题的内容；未写时显示这一端的名字。 |
XhDateRangePickerPreset | default | — | 条目内容；未写时使用数据中的 label。 |
XhDateRangePickerPresetGroup | default | DateRangePickerPresetsSlotProps | 自行铺设条目；未写时按 presets 数据自动铺设，两者产出的 DOM 一致。 |
XhDateRangePickerRoot | default | DateRangePickerRootSlotProps | |
XhDateRangePickerRoot | label | — | 不写默认插槽时标题的内容，盖过 label 文字。 |
XhDateRangePickerSegment | default | DateRangePickerSegmentSlotProps | |
XhDateRangePickerTimeColumn | default | — | 自行铺 XhDateRangePickerTimeItem；未写时按这一列的可选值自动铺。 |
XhDateRangePickerTimeItem | default | — | 格里的内容；未写时显示按 locale 译好的文字。 |
React 适配器 props
只列各组件自己声明的那些：继承自 ComponentPropsWithRef 的 DOM 属性不在其中，根组件上与上面 Props 表同名的也不重复列。Vue 的对应物是上面的插槽表。
| React 组件 | 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
XhDateRangePickerCalendar | index | number | string | 并排的第几张面板，默认 0。写在这里，面板内的标题、网格与格子就不必各写一遍。 | |
XhDateRangePickerCell | value | string | 是 | ISO 日期串。 |
XhDateRangePickerCell | index | number | string | 属于第几个面板；未写时跟随所在的日历。同一天会同时出现在两个面板中 （8 月末的几天也铺在 9 月的首行），是否为本月只有连同面板一起看才能判定。 | |
XhDateRangePickerColumnGroup | index | number | string | 0 起点、1 终点，兼收字符串。 | |
XhDateRangePickerGrid | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDateRangePickerHeading | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDateRangePickerHeadingMonthTrigger | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDateRangePickerHeadingYearTrigger | index | number | string | 属于第几个面板；未写时跟随所在的日历。 | |
XhDateRangePickerHiddenInput | index | number | string | 写在分段容器外面时用它指明属于哪一端；写在容器内时不必提供，跟随容器。 | |
XhDateRangePickerPositioner | container | () => Element | null | 浮层挂载的容器；未提供时按全局配置，再未提供时挂载到 body。 | |
XhDateRangePickerPreset | value | string | 是 | 该条目的身份，与 presets 数据中的 value 逐字对应。 |
XhDateRangePickerPresetGroup | children | SlotChildren<DateRangePickerPresetsSlotProps> | 自行铺设条目；未写时按 presets 数据自动铺设，两者产出的 DOM 一致。 | |
XhDateRangePickerRoot | label | ReactNode | 标题。不给 children 时铺 label 部件。 | |
XhDateRangePickerRoot | children | SlotChildren<DateRangePickerRootSlotProps> | 不给时照标准结构铺整套部件。 | |
XhDateRangePickerSegment | index | number | string | 段位下标，兼收字符串。 | |
XhDateRangePickerSegment | segment | DateSegmentType | 按段名声明该格。段集中没有该段时它收起；与 index 二选一，两个都写时按段名计算。 | |
XhDateRangePickerSegment | children | SlotChildren<DateRangePickerSegmentSlotProps> | ||
XhDateRangePickerSegmentGroup | index | number | string | 组号：0 起点、1 终点，兼收字符串。 | |
XhDateRangePickerTimeColumn | unit | DatePickerTimeUnit | 是 | 这一列的单位：hour、minute、second 或 dayPeriod。 |
XhDateRangePickerTimeItem | value | string | 是 | 这一格的值，与时间列的可选值逐字对应：两位补零（上下午列写 '00' / '01'）。 |
XhDateRangePickerWeekDay | value | number | string | 是 | 列序 0-6，兼收字符串。 |
XhDateRangePickerWeekNumber | 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 · FOCUSED.SET · VIEW.SET · ACTIVE_INDEX.SET · FORM.RESET · PRESS.START · PRESS.END
判据：isOpenControlled · closesOnSelect · canPress
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
open | boolean | |
value | string[] | 区间两端，ISO 串；按位存放，空缺的一端为空串。 |
start | string | null | 起点；未填时为 null。 |
end | string | null | 终点；未填时为 null。 |
periodValue | CalendarPeriodValue | null | 两端都落定时的规范化周期值；缺少一端时为 null。 |
focusedValue | string | 生效聚焦日（三路收口后的结果），恒非空。日历展示哪个月由它决定。 |
granularity | CalendarGranularity | 作者选择的粒度。 |
activeView | CalendarView | 面板当前所在的层级。 |
disabled | boolean | |
readOnly | boolean | |
invalid | boolean | 校验失败：作者标记的、任一端越界，或终点早于起点。 |
canClear | boolean | 清空按钮当前是否可按。 |
setOpen | (next: boolean) => void | |
setValue | (next: string[]) => void | |
clear | () => void | |
setActiveView | (next: CalendarView) => void | 直接切换到某一层级。 |
presets | readonly DateRangePickerPresetState[] | 快捷选项逐条的状态，数据顺序。未提供 presets 时为空数组。 |
activeIndex | DateRangePickerEndIndex | 当前编辑区间的哪一端。 |
setActiveIndex | (next: DateRangePickerEndIndex) => void | 直接改写当前编辑的一端。 |
showTime | boolean | showTime 生效（已开启且 granularity=day）。 |
timeColumnGroups | readonly [DateRangePickerTimeColumnGroup, DateRangePickerTimeColumnGroup] | 起止两组时间列；未开启 showTime 时两组的列都是空数组。 |
timeValues | readonly [string | null, string | null] | 两端各自的时间段（'HH:mm[:ss]'）；那一端还没有时刻时为 null。 |
hourCycle | TimeHourCycle | 时间列与时刻段实际生效的小时制。 |
timeStep | ResolvedTimeStep | 实际生效的按单位步进。 |
getTimeItemText | (props: DateRangePickerTimeItemTextProps) => string | 某一格显示的文字：数字列即格值，上下午列按 locale 给出「上午 / 下午」。各适配器都用它填字。 |
isTimeItemDisabled | (props: DateRangePickerTimeItemProps) => boolean | 某一格按不下去：界外、被 isTimeUnavailable 判为不可用、终点早于同一天的起点，或整个控件禁用。 |
calendar | CalendarRangePickerApi<T> | 内嵌日历：选区间、翻月、键盘导航都在它身上。 |
field | DateRangePickerFieldApi<T> | 起点分段输入。 |
fieldEnd | DateRangePickerFieldApi<T> | 终点分段输入。 |
translations | DateRangePickerTranslations | 解析后的文案：作者给的 translations 盖在当前语言包上。 |
getRootProps | () => T['element'] | |
getLabelProps | () => T['element'] | |
getControlProps | () => T['element'] | |
getSegmentGroupProps | (props?: DateRangePickerSegmentGroupProps) => T['element'] | role=group 的分段容器，段位挂在其中。index 选择起止两组，不传即起点。 |
getRangeSeparatorProps | () => T['element'] | 起止输入之间的视觉分隔。 |
getTriggerProps | () => T['button'] | |
getClearTriggerProps | () => T['button'] | |
getPositionerProps | () => T['element'] | |
getContentProps | () => T['element'] | |
getPresetGroupProps | () => T['element'] | 快捷选项列（role=listbox）；未提供 presets 时带 hidden。 |
getPresetProps | (props: DateRangePickerPresetProps) => T['element'] | 一条快捷选项（role=option）：点击把整段区间写入两端。 |
getCalendarProps | () => T['element'] | 内嵌日历的挂载点，同时充当日历的根节点。 |
getColumnGroupProps | (props: DateRangePickerColumnGroupProps) => T['element'] | 一端的时间列外壳（role=group）：起止各一个并排，data-index 区分，各报「开始时间」「结束时间」；未开启 showTime 时带 hidden。 |
getColumnGroupLabelProps | (props: DateRangePickerColumnGroupProps) => T['element'] | 时间组顶部的小标题，纯视觉，退出可访问树。 |
getTimeColumnProps | (props: DateRangePickerTimeColumnProps) => T['element'] | 一端的一列（role=listbox）：时 / 分[/ 秒][/ 上下午]。 |
getTimeItemProps | (props: DateRangePickerTimeItemProps) => 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 | 展开浮层并把焦点移入；触发按钮是可选部件，键盘入口不能只挂在它上面 |
Enter | focus in 某一段, open | 收起浮层。段位里敲出来的值不触发「选完即收」（那时人还在打字），这是那条路的收口手势 |
Enter / Space | held on trigger（not disabled）、clear-trigger（可清）或 preset（open, not disabled/readOnly, 该条可按） | 按住期间该部件投影 data-pressed，与指针 :active 同一副按压面；抬起或失焦撤下，浮层收起时一并撤下。日历里的部件由 calendar-range-picker 自己投影 |
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
segment-group | aria-disabled | 'true' | 'false' |
segment-group | aria-label | label.endDate | label.startDate |
segment-group | role | 'group' |
range-separator | aria-hidden | 'true' |
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' |
column-group | aria-label | label.endTime | label.startTime |
column-group | role | 'group' |
column-group-label | aria-hidden | 'true' |
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-range-picker.css 按 [data-scope="date-range-picker"][data-part="root"] 部件选择器书写，发布产物以挂载类 .xh-scope-date-range-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-size | props.size |
segment-group | data-complete | ''（条件成立时才出现） |
segment-group | data-disabled | ''（条件成立时才出现） |
segment-group | data-empty | ''（条件成立时才出现） |
segment-group | data-index | String(index) |
segment-group | data-invalid | ''（条件成立时才出现） |
segment-group | data-out-of-range | ''（条件成立时才出现） |
segment-group | data-placeholder-shown | ''（条件成立时才出现） |
segment-group | data-placeholder-text | props.endPlaceholder | props.startPlaceholder | 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' |
column-group | data-editing | ''（条件成立时才出现） |
column-group | data-index | String(index) |
column-group-label | data-editing | ''（条件成立时才出现） |
column-group-label | data-index | String(index) |
time-column | data-index | String(index) |
time-column | data-unit | target.getAttribute('data-unit') as DatePickerTimeUni… |
time-item | data-disabled | ''（条件成立时才出现） |
time-item | data-index | String(index) |
time-item | data-pressed | ''（条件成立时才出现） |
time-item | data-state | 'checked' | 'unchecked' |
time-item | data-unit | target.getAttribute('data-unit') as DatePickerTimeUni… |
time-item | data-value | current.getAttribute('data-value') |
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 | '' |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-date-range-picker-action-bg | clear-triggertrigger | --xh-ink-surfacebackground-color | defaultxh-ink-surface | --xh-_action-variant-bg-rest | date-range-picker 的 clear-trigger、trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 clear-trigger、trigger 部件 background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 clear-trigger、trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-date-range-picker-action-fg | clear-triggertrigger | color | default | --xh-fg-field-clear--xh-fg-muted | date-range-picker 的 clear-trigger、trigger 部件 color 覆盖槽。 |
--xh-date-range-picker-action-fg-hover | clear-triggertrigger | color | disabledhoverloadingnot([data-disabled])not([data-loading])state=open | --xh-fg-default | date-range-picker 的 clear-trigger、trigger 部件 color 覆盖槽。 |
--xh-date-range-picker-action-font-size | clear-triggertrigger | font-size | default | --xh-text-secondary-size | date-range-picker 的 clear-trigger、trigger 部件 font-size 覆盖槽。 |
--xh-date-range-picker-action-radius | clear-triggertrigger | border-radius | default | --xh-shape-circle--xh-shape-inset | date-range-picker 的 clear-trigger、trigger 部件 border-radius 覆盖槽。 |
--xh-date-range-picker-action-size | clear-triggertrigger | block-sizeinline-sizemin-inline-size | defaultxh-action-profile=field-inset | --xh-_action-profile-visual-size | date-range-picker 的 clear-trigger、trigger 部件 block-size、inline-size、min-inline-size 覆盖槽。 |
--xh-date-range-picker-calendar-gap | calendar | gap | default | --xh-space-0 | date-range-picker 的 calendar 部件 gap 覆盖槽。 |
--xh-date-range-picker-column-divider | column-grouppreset-grouptime-column | border-block-endborder-block-startborder-inline-endborder-inline-start | @media (min-width: 768px)default | --xh-material-solid-border | date-range-picker 的 column-group、preset-group、time-column 部件 border-block-end、border-block-start、border-inline-end、border-inline-start 覆盖槽。 |
--xh-date-range-picker-column-group-gap | column-group | margin-inline-start | default | --xh-space-0 | date-range-picker 的 column-group 部件 margin-inline-start 覆盖槽。 |
--xh-date-range-picker-column-group-label-fg | column-group-label | color | default | --xh-fg-subtle | date-range-picker 的 column-group-label 部件 color 覆盖槽。 |
--xh-date-range-picker-column-group-label-px | column-group-label | padding-inline | default | --xh-space-1 | date-range-picker 的 column-group-label 部件 padding-inline 覆盖槽。 |
--xh-date-range-picker-column-group-offset | column-groupcolumn-group-label | block-sizepadding-block-start | default | --xh-control-action-size | date-range-picker 的 column-group、column-group-label 部件 block-size、padding-block-start 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-bg | confirm-trigger | --xh-ink-surfacebackground-color | defaultxh-ink-surface | --xh-_action-variant-bg-rest | date-range-picker 的 confirm-trigger 部件 --xh-ink-surface、background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 confirm-trigger 部件 background-color 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-bg-hover | confirm-trigger | background-color | disabledhoverloadingnot([data-disabled])not([data-loading]) | --xh-_action-variant-bg-hover | date-range-picker 的 confirm-trigger 部件 background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 confirm-trigger 部件 color 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-font-size | confirm-trigger | font-size | default | --xh-text-caption-size | date-range-picker 的 confirm-trigger 部件 font-size 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-h | confirm-trigger | block-sizeinline-size | defaultxh-action-profile=field-inset | --xh-_action-profile-visual-size | date-range-picker 的 confirm-trigger 部件 block-size、inline-size 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-margin | confirm-triggercontent | margin | has(> [data-part='column-group']) | --xh-space-2 | date-range-picker 的 confirm-trigger、content 部件 margin 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-px | confirm-trigger | padding-inline | default | --xh-space-2 | date-range-picker 的 confirm-trigger 部件 padding-inline 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-radius | confirm-trigger | border-radius | default | --xh-shape-control | date-range-picker 的 confirm-trigger 部件 border-radius 覆盖槽。 |
--xh-date-range-picker-confirm-trigger-shadow | confirm-trigger | box-shadow | defaultdisabledhoveris(:active, [data-pressed])loadingnot([data-disabled])not([data-loading])pressed | none | date-range-picker 的 confirm-trigger 部件 box-shadow 覆盖槽。 |
--xh-date-range-picker-content-bg | content | background | default | --xh-bg-surface | date-range-picker 的 content 部件 background 覆盖槽。 |
--xh-date-range-picker-content-border | content | border | default | --xh-border-default | date-range-picker 的 content 部件 border 覆盖槽。 |
--xh-date-range-picker-content-fg | content | color | default | --xh-fg-default | date-range-picker 的 content 部件 color 覆盖槽。 |
--xh-date-range-picker-content-px | content | padding-inline | default | --xh-space-0 | date-range-picker 的 content 部件 padding-inline 覆盖槽。 |
--xh-date-range-picker-content-py | content | padding-block | default | --xh-space-0 | date-range-picker 的 content 部件 padding-block 覆盖槽。 |
--xh-date-range-picker-content-radius | content | border-radius | default | --xh-shape-overlay | date-range-picker 的 content 部件 border-radius 覆盖槽。 |
--xh-date-range-picker-content-shadow | content | box-shadow | default | --xh-elevation-floating | date-range-picker 的 content 部件 box-shadow 覆盖槽。 |
--xh-date-range-picker-control-bg | control | background-color | xh-field-chrome | --xh-_field-variant-bg-rest | date-range-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-range-picker-control-bg-disabled | control | background-color | disabledxh-field-chrome | --xh-_field-variant-bg-disabled | date-range-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-range-picker-control-bg-readonly | control | background-color | readonlyxh-field-chrome | --xh-_field-variant-bg-read-only | date-range-picker 的 control 部件 background-color 覆盖槽。 |
--xh-date-range-picker-control-border | control | border | xh-field-chrome | --xh-_field-variant-border-rest | date-range-picker 的 control 部件 border 覆盖槽。 |
--xh-date-range-picker-control-border-focus | control | border-colorbox-shadow | disabledfocus-withinnot([data-disabled])xh-field-chrome | --xh-_field-variant-border-focus | date-range-picker 的 control 部件 border-color、box-shadow 覆盖槽。 |
--xh-date-range-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-range-picker 的 control 部件 border-color 覆盖槽。 |
--xh-date-range-picker-control-border-invalid | control | border-color | invalidxh-field-chrome | --xh-_field-variant-border-invalid | date-range-picker 的 control 部件 border-color 覆盖槽。 |
--xh-date-range-picker-control-fg | control | color | xh-field-chrome | --xh-fg-default | date-range-picker 的 control 部件 color 覆盖槽。 |
--xh-date-range-picker-control-gap | controlrange-separator | gapmargin-inline | defaultxh-field-chrome | --xh-_date-range-picker-gap | date-range-picker 的 control、range-separator 部件 gap、margin-inline 覆盖槽。 |
--xh-date-range-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-range-picker-control-h | date-range-picker 的 control 部件 block-size、min-block-size 覆盖槽。 |
--xh-date-range-picker-control-min-w | controlroot | min-inline-size | defaultxh-field-chrome | --xh-control-min-w | date-range-picker 的 control、root 部件 min-inline-size 覆盖槽。 |
--xh-date-range-picker-control-px | control | padding-inline | xh-field-chrome | --xh-_date-range-picker-control-px | date-range-picker 的 control 部件 padding-inline 覆盖槽。 |
--xh-date-range-picker-control-radius | control | border-radius | xh-field-chrome | --xh-shape-control | date-range-picker 的 control 部件 border-radius 覆盖槽。 |
--xh-date-range-picker-control-shadow | control | box-shadow | xh-field-chrome | none | date-range-picker 的 control 部件 box-shadow 覆盖槽。 |
--xh-date-range-picker-control-w | root | inline-sizemin-inline-size | default | --xh-control-w | date-range-picker 的 root 部件 inline-size、min-inline-size 覆盖槽。 |
--xh-date-range-picker-font-size | segment-group | font-size | default | --xh-_date-range-picker-font-size | date-range-picker 的 segment-group 部件 font-size 覆盖槽。 |
--xh-date-range-picker-footer-border | footer | border-block-start | default | --xh-material-solid-border | date-range-picker 的 footer 部件 border-block-start 覆盖槽。 |
--xh-date-range-picker-footer-fg | footer | color | default | --xh-fg-muted | date-range-picker 的 footer 部件 color 覆盖槽。 |
--xh-date-range-picker-footer-font-size | footer | font-size | default | --xh-text-caption-size | date-range-picker 的 footer 部件 font-size 覆盖槽。 |
--xh-date-range-picker-footer-gap | footer | gapinline-size | default | --xh-space-2 | date-range-picker 的 footer 部件 gap、inline-size 覆盖槽。 |
--xh-date-range-picker-footer-px | footer | inline-size | default | --xh-space-2 | date-range-picker 的 footer 部件 inline-size 覆盖槽。 |
--xh-date-range-picker-footer-py | footer | padding-block | default | --xh-space-2 | date-range-picker 的 footer 部件 padding-block 覆盖槽。 |
--xh-date-range-picker-gap | labelroot | gapmargin-block-end | default | --xh-space-1 | date-range-picker 的 label、root 部件 gap、margin-block-end 覆盖槽。 |
--xh-date-range-picker-heading-font-weight | calendarheadingheading-month-triggerheading-year-trigger | font-weight | default | --xh-font-weight-regular | date-range-picker 的 calendar、heading、heading-month-trigger、heading-year-trigger 部件 font-weight 覆盖槽。 |
--xh-date-range-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-range-picker 的 control、positioner、root 部件 --xh-icon-size 覆盖槽。 |
--xh-date-range-picker-label-fg | label | color | default | --xh-fg-muted | date-range-picker 的 label 部件 color 覆盖槽。 |
--xh-date-range-picker-label-fg-disabled | label | color | disabled | --xh-fg-muted | date-range-picker 的 label 部件 color 覆盖槽。 |
--xh-date-range-picker-label-font-size | label | font-size | default | --xh-text-label-size | date-range-picker 的 label 部件 font-size 覆盖槽。 |
--xh-date-range-picker-label-font-weight | label | font-weight | default | --xh-text-label-weight | date-range-picker 的 label 部件 font-weight 覆盖槽。 |
--xh-date-range-picker-label-gap | label | margin-block-end | default | --xh-space-2 | date-range-picker 的 label 部件 margin-block-end 覆盖槽。 |
--xh-date-range-picker-layer | positioner | z-index | default | --xh-_layer | date-range-picker 的 positioner 部件 z-index 覆盖槽。 |
--xh-date-range-picker-literal-fg | segment-group | color | not([data-scope]) | --xh-fg-subtle | date-range-picker 的 segment-group 部件 color 覆盖槽。 |
--xh-date-range-picker-max-h | content | max-block-size | default | --xh-_date-range-picker-available-h | date-range-picker 的 content 部件 max-block-size 覆盖槽。 |
--xh-date-range-picker-placeholder-fg | segment-group | color | placeholder-shown | --xh-fg-subtle | date-range-picker 的 segment-group 部件 color 覆盖槽。 |
--xh-date-range-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-range-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-range-picker-preset-check-fg | preset | background-color | default | --xh-_date-range-picker-check-fg | date-range-picker 的 preset 部件 background-color 覆盖槽。 |
--xh-date-range-picker-preset-check-size | preset | block-sizeinline-sizepadding-inline-end | default | --xh-control-indicator-sm | date-range-picker 的 preset 部件 block-size、inline-size、padding-inline-end 覆盖槽。 |
--xh-date-range-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-range-picker 的 preset 部件 color 覆盖槽。 |
--xh-date-range-picker-preset-fg-disabled | preset | background-colorcolor | defaultdisabled | --xh-fg-disabled | date-range-picker 的 preset 部件 background-color、color 覆盖槽。 |
--xh-date-range-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-range-picker 的 preset 部件 color 覆盖槽。 |
--xh-date-range-picker-preset-font-size | preset | font-size | default | --xh-text-caption-size | date-range-picker 的 preset 部件 font-size 覆盖槽。 |
--xh-date-range-picker-preset-group-gap | preset-group | gap | default | --xh-space-1 | date-range-picker 的 preset-group 部件 gap 覆盖槽。 |
--xh-date-range-picker-preset-group-h | preset-group | max-block-size | default | --xh-viewport-h-lg | date-range-picker 的 preset-group 部件 max-block-size 覆盖槽。 |
--xh-date-range-picker-preset-group-px | preset-group | padding-inline | default | --xh-space-2 | date-range-picker 的 preset-group 部件 padding-inline 覆盖槽。 |
--xh-date-range-picker-preset-group-py | preset-group | padding-block | default | --xh-space-2_5 | date-range-picker 的 preset-group 部件 padding-block 覆盖槽。 |
--xh-date-range-picker-preset-h | preset | block-sizeline-height | default | --xh-control-action-size | date-range-picker 的 preset 部件 block-size、line-height 覆盖槽。 |
--xh-date-range-picker-preset-px | preset | inset-inline-endpadding-inlinepadding-inline-end | default | --xh-space-2 | date-range-picker 的 preset 部件 inset-inline-end、padding-inline、padding-inline-end 覆盖槽。 |
--xh-date-range-picker-preset-radius | preset | border-radius | default | --xh-shape-control | date-range-picker 的 preset 部件 border-radius 覆盖槽。 |
--xh-date-range-picker-range-separator-fg | range-separator | color | default | --xh-fg-subtle | date-range-picker 的 range-separator 部件 color 覆盖槽。 |
--xh-date-range-picker-range-separator-mx | range-separator | margin-inline | default | --xh-_date-range-picker-range-separator-mx | date-range-picker 的 range-separator 部件 margin-inline 覆盖槽。 |
--xh-date-range-picker-range-separator-px | range-separator | margin-inlinepadding-inline | default | --xh-space-1 | date-range-picker 的 range-separator 部件 margin-inline、padding-inline 覆盖槽。 |
--xh-date-range-picker-time-column-gap | time-columntime-item | gapinset-block | default | --xh-space-2 | date-range-picker 的 time-column、time-item 部件 gap、inset-block 覆盖槽。 |
--xh-date-range-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-range-picker 的 time-column 部件 block-size、padding-block 覆盖槽。 |
--xh-date-range-picker-time-column-min-w | time-column | min-inline-size | default | --xh-overlay-column-min-w | date-range-picker 的 time-column 部件 min-inline-size 覆盖槽。 |
--xh-date-range-picker-time-column-min-w-mobile | time-column | min-inline-size | @media not all and (min-width: 768px) | --xh-overlay-column-min-w | date-range-picker 的 time-column 部件 min-inline-size 覆盖槽。 |
--xh-date-range-picker-time-column-px | time-column | padding-inline | default | --xh-space-1 | date-range-picker 的 time-column 部件 padding-inline 覆盖槽。 |
--xh-date-range-picker-time-column-py | time-column | padding-block | default | --xh-space-1 | date-range-picker 的 time-column 部件 padding-block 覆盖槽。 |
--xh-date-range-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-range-picker 的 time-item 部件 background-color 覆盖槽。 |
--xh-date-range-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-range-picker 的 time-item 部件 background-color 覆盖槽。 |
--xh-date-range-picker-time-item-check-fg | time-item | background-color | default | --xh-_date-range-picker-check-fg | date-range-picker 的 time-item 部件 background-color 覆盖槽。 |
--xh-date-range-picker-time-item-check-size | time-item | block-sizeinline-sizeinset-inline-endpadding-inline | @media not all and (min-width: 768px)default | --xh-_date-range-picker-time-item-check-size | date-range-picker 的 time-item 部件 block-size、inline-size、inset-inline-end、padding-inline 覆盖槽。 |
--xh-date-range-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-range-picker 的 time-item 部件 color 覆盖槽。 |
--xh-date-range-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-range-picker-time-item-fg | date-range-picker 的 time-item 部件 color 覆盖槽。 |
--xh-date-range-picker-time-item-font-size | time-item | font-size | default | --xh-_date-range-picker-font-size | date-range-picker 的 time-item 部件 font-size 覆盖槽。 |
--xh-date-range-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-range-picker 的 time-item 部件 font-weight 覆盖槽。 |
--xh-date-range-picker-time-item-h | time-columntime-item | block-sizepadding-block | default | --xh-control-action-size | date-range-picker 的 time-column、time-item 部件 block-size、padding-block 覆盖槽。 |
--xh-date-range-picker-time-item-px | time-item | inset-inline-endpadding-inline | default | --xh-space-0_5 | date-range-picker 的 time-item 部件 inset-inline-end、padding-inline 覆盖槽。 |
--xh-date-range-picker-time-item-radius | time-item | border-radius | default | --xh-shape-inset | date-range-picker 的 time-item 部件 border-radius 覆盖槽。 |
动效
动效角色：按压 · 状态 · 出现（见动效规范）。
共享关键帧 xh-overlay-pop-in · xh-pop-out 由 family/motion.css 提供，皮肤 @import 它，单独引入仍成立；opacity 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。
皮肤之外还有一段：退场由适配器的退场闸门把关，动画播完才真收起。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
响应式
皮肤按视口分档：min-width: 768px。
皮肤另按输入能力分档：hover: hover · hover: none · pointer: coarse：同一份皮肤在触屏与带指针的设备上不一样，与视口宽度无关。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。