跳转至

DateRangeInput 组件契约

意图

DateRangeInput 通过一个带标签的字段表面呈现一个受控的日期范围。 其触发器打开一个基于 Calendar 的 Popover,并且可以在日历旁边包含一个快速选择预设列表;当两者无法并排放下时,列表显示在日历上方。 触发器文本和日历显示应用程序的日历系统,而范围始终保持公历 ISO 日期。

兼容性与迁移

  • 默认行为保持已发布版本行为:yes;规范的 DateRangeInput 行为不变
  • calendar prop 是新增的;它默认使用提供方的日历,否则为 gregory,因此没有提供方日历的字段保持其公历文本。带 -u-ca- 关键字的提供方 locale 保持公历日期(spec:AST-111 DEC-2);设置 calendar 可选择其他日历
  • 0.7.0 移除了 date-range-input-clear-icon 别名;共享清除图标仍可通过 input-clear-icon 使用
  • 预设约束修正保持不变
  • 受控/非受控行为:不变;DateRangeInput 仍然保持受控
  • 迁移决策:将已移除的主题键和 CSS 类替换为 input-clear-icon 和 .astryx-input-clear-icon,或运行 astryx upgrade --from 0.6.3 --apply --path .

消费者迁移说明属于消费者文档和发布说明。

所有权边界

拥有

  • 复合日期范围字段表面及其范围显示触发器。
  • 可选的预设列表、每个预设操作,以及预设当前状态和禁用状态的呈现。
  • 将选中的 Calendar 范围或预设转换为 onChange 和 changeAction 输出。

不拥有 / 非目标

  • 标签、描述和状态展示——由 component:Field 和 component:FieldStatus 拥有。
  • 日历网格渲染和日期单元格交互——由 component:Calendar 拥有。
  • 层叠承载和关闭——由 component:Popover 和 family:overlay-dismissal 拥有。
  • 共享清除按钮展示——由 component:Field 拥有。

公共概念

概念 封闭值或状态 含义 可用性 默认值 所有者 稳定性 无效值行为
calendar 一个 CalendarSystem(spec:AST-111 FR1) 触发器文本和弹出 Calendar 所显示的日历系统 触发器和日历 提供方解析后的日历,否则为 gregory(spec:AST-111 FR2) spec:AST-111 稳定 解析为 gregory,并在开发模式下警告一次;需要 Temporal 的日历在缺少 Temporal 的环境下回退到 gregory

本契约还记录了现有的预设列表结构及其新增的主题化表面。

行为与布局契约

ID 候选不变式 依据 评审状态
FR1 DateRangeInput MUST 呈现受控的 value,并发出范围变更,且不维护与之竞争的内部选中范围。 当前源码、文档和定向测试 已验证当前行为
FR2 当存在预设时,每个预设仍然是一个独立按钮,位于一个带标签的组内;已应用的预设反映当前状态,而端点违反 min、max 或 dateConstraints,或其范围违反 minRangeSpan 或 maxRangeSpan 的预设反映禁用状态。 当前源码、无障碍注释和定向测试 已验证当前行为
FR3 预设组和每个预设按钮暴露稳定的主题目标;选中和禁用是预设按钮目标的状态,而不是独立目标。 architecture:component-theming-surface;消费者对预设主题化的需求 已批准的新增契约
FR4 添加主题目标 MUST NOT 改变这些元素已拥有的 Popover、Calendar、按钮、焦点或选择语义。 组合边界与兼容性目标 已批准的附加性契约
FR5 当预设组和单月日历无法在层中并排容纳时,预设组堆叠在日历上方,并且每个月份网格和月份导航都保持在层内(spec:AST-020 FR1、WCAG 2.2 SC 1.4.10)。视觉顺序与 DOM 顺序一致。当它们可并排容纳时,预设保持在日历旁边。当内容高于层的视口上限时,内容在层内滚动。 spec:AST-020 FR1;390 px、390 × 664 px 和 440 px 回流检查 已验证的当前行为
FR6 触发器文本、其可访问名称以及 Popover 中的 Calendar 显示已解析的日历(spec:AST-111 FR2、FR17):触发器将范围的每个端点写入日历,当任一端点落在当前日历年之外时包含年份,Calendar 则布局日历月份。该字段不允许键入。value、onChange、min、max、预设和跨度边界保持为公历 ISO 日期(spec:AST-111 FR3)。 spec:AST-111 FR3、FR17;当前源代码和日历测试 已验证的当前行为

允许的变化

  • AV1 — 预设内容。 调用方可以省略预设,或提供任意数量的带标签范围。
  • AV2 — 日历布局。 日历月份数、日期约束和范围边界可以变化,而不会改变预设目标身份。
  • AV3 — 主题输出。 主题可以重新设置预设组和按钮的样式,而组件的按钮语义和状态保持不变。

代表性状态

状态 必需不变量 允许的变化
日历 触发器文本和 Calendar 显示已解析的日历;值保持为公历 ISO。 日历、区域设置、数字
无预设 不渲染预设组或预设按钮目标。 日历配置
有预设但无匹配 每个按钮都携带预设目标,且没有选中状态。 预设数量和标签
已应用预设 匹配的按钮携带 aria-current="true" 以及目标的选中状态。 选中的范围
禁用预设 违反端点日期约束或范围跨度约束的预设会按照 spec:AST-085 被禁用,并携带目标的禁用状态。 约束来源

转换与优先级顺序

  • ORD1 — 预设状态。 一次性解析每个预设的范围,将其与受控值进行比较,针对两个端点评估 min、max 和 dateConstraints,针对整个范围评估 minRangeSpan 和 maxRangeSpan,然后在同一个预设按钮目标上反映选中和禁用状态。
  • ORD2 — 预设激活。 已启用的预设发出已解析的范围;激活不会再次解析该预设。

端点约束与 Calendar 的选择行为一致:它们应用于预设的开始和结束日期,而不是两者之间的每个日期。

性能与资源

未引入新的性能或资源约束。

无障碍契约

  • AR1 — 预设语义。 预设仍然是单个带标签组中的原生按钮,可通过 Tab 独立导航。
  • AR2 — 当前状态。 已应用的预设继续以 aria-current="true" 暴露;主题状态反映是附加性的。
  • AR3 — 禁用状态。 违反端点日期约束或范围跨度约束的预设会被禁用,并保持可聚焦(spec:AST-085);主题状态反映不会替代该行为。

实现差距:在深色模式下,已应用预设的标签位于其柔和强调色填充上,对比度为 3.88:1(在 Popover 表面上),低于 4.5:1。

设计关系

结构或状态 设计要求 呈现权威 层级角色 组件契约
---------------- --------------------------------------------------------------- ------------------------------------- -------------- ------------------
字段表面 呈现一个连贯的输入边界。 当前源码和输入字段族 突出 FR1
日历弹出框 提供范围选择,同时不改变字段归属。 Popover 和 Calendar 组件 突出 FR1, FR4
预设侧边栏 将可选快捷方式分组在日历旁边。 当前源码和公开文档 辅助 FR2, FR3
预设按钮 呈现一个快速选择范围及其当前/禁用状态。 当前源码和公开文档 辅助 FR2–FR4, AR1–AR3

主题结构

{
  "Label": {
    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
  },
  "Field surface": {"target": "date-range-input"},
  "Trigger button": {
    "none": {
      "reason": "unsettled: The composite field surface has a target, but the inner range-display button has no separate current target."
    }
  },
  "Calendar icon": {"target": "date-range-input-toggle-icon"},
  "Calendar popover": {
    "delegatesTo": {"owner": "component:Popover", "target": "popover"}
  },
  "Preset sidebar": {"target": "date-range-input-presets"},
  "Preset button": {"target": "date-range-input-preset"},
  "Clear button": {
    "delegatesTo": {"owner": "component:Field", "target": "input-clear-button"}
  },
  "Status message": {
    "delegatesTo": {"owner": "component:FieldStatus", "target": "field-status"}
  }
}

族系与系统关系

  • family:input-fields 负责字段尺寸、状态放置、加载、禁用原因和末端控件几何结构。
  • family:overlay-dismissal 负责 Popover 的关闭栈。
  • architecture:component-theming-surface 负责目标准入、状态反映和结构映射。
  • spec:AST-111 负责日历选择、公历 ISO 值和 Temporal 边界;FR6 映射其 FR3 和 FR17。component:Calendar 负责日历中的 Popover 网格。

spec:AST-013 FR12 例外——需要 Temporal 的日历

  • 能力: 在除公历、佛历、民国历和日本历之外的日历中,触发文本和弹出框中的 Calendar 需要运行时的 Temporal。
  • 降级: 当缺少 Temporal 时(如 macOS 和 iOS 上的 Safari),字段会显示公历日期,并在开发环境中发出一次警告,指明某个 polyfill(spec:AST-111 FR5)。加载 Temporal polyfill 的应用程序即可获得完整日历。当服务器和浏览器使用的中国历或檀君历实现对于月份起始日判断不一致时,React 会在客户端再次渲染不同的文本(spec:AST-111 FR19)。
  • 保留的义务: spec:AST-013 的 FR7 和 FR8,以及在中国历和檀君历该情形之外的 FR9。公历字段保留所有交互、标签和公告,佛历、民国历和日本历文本无需 Temporal 也可正常工作。
  • 证据: 使用原生 Temporal 的真实 Chromium 和 Firefox,以及移除 Temporal 后带或不带 polyfill 的真实 Chromium、Firefox 和 WebKit,均显示波斯历触发文本。
  • 负责人: nynexman4464.
  • 审查条件: Safari 内置 Temporal。

验证映射

契约 验证 代表性状态 变更或失败预期 审计区块
FR1, FR2, AR1–AR3 DateRangeInput.test.tsx;禁用预设的可聚焦性(AR3)待一致性确认 无匹配、已应用预设、端点无效预设、跨度无效预设 语义或状态属性消失 audit:DateRangeInput/presets
FR3, FR4 DateRangeInput.test.tsx、themingTargets.test.ts、生成的探针主题 组目标、选中按钮、禁用按钮 目标类/状态缺失、未记录,或被放置在错误的元素上 audit:DateRangeInput/theming
FR5 DateRangeInputReflow.interaction.browser.spec.ts 含预设和两个月的 390 px 页面;桌面页面 日历或其导航越过图层边缘,或预设栏在桌面宽度下脱离日历侧边 audit:DateRangeInput/reflow
FR6 DateRangeInput.calendar.test.tsx(“在波斯历中写入触发器文本及其可访问名称”、“当范围超出当前日历年时显示年份”、“打开波斯历弹出日历并报告公历 ISO 日期”,以及不使用 Temporal 的用例);Calendar.calendarSystems.test.tsx “DateRangeInput 在该日历中打开其弹出日历”;真实 Chromium、Firefox 和 WebKit 中的触发器文本 波斯历、佛教历、跨日历年范围、无 Temporal 触发器文本或日历使用其他历法,或出现非 ISO 值,则失败 audit:DateRangeInput/behavior
主题结构映射 scripts/check-knowledge.mjs 所有已记录的结构 目标所有权或结构名称漂移 audit:DateRangeInput/theming

决策日志

DEC-1 — 预设组和按钮是公开主题结构

参考: component:DateRangeInput/DEC-1 决策者: cixzhang,2026-09-14

可选的预设侧边栏和每个快速选择按钮都是稳定且消费方可识别的部分。date-range-input-presets 归属于负责侧边栏展示的组;date-range-input-preset 归属于每个按钮,选中和禁用通过状态而非独立目标来反映。新增目标保持了默认视觉和按钮语义;预设约束的强制执行遵循 FR2 和 ORD1–ORD2。

开放问题

  • OQ1 — 内部范围显示触发器是否应拥有自己的目标,还是仍仅由复合字段表面表示?(human-api)

内容边界

本文件不重复消费方属性表、使用示例、Calendar 或 Popover 契约、当前审计结果或下游主题实现。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx