跳转至

日期和时间输入呈现系统规范

意图

同一个 prop 问题——由哪个表面收集值——目前有两个答案:

  • ContextMenu、DropdownMenu、MoreMenu、Selector 和 MultiSelector 使用 presentation('popover' | 'bottom-sheet' | 'adaptive')。
  • DateInput、DateTimeInput 和 TimeInput 使用 nativePicker ('touch' | 'always' | 'never'),后者只命名了原生表面, 却掩盖了 Astryx 桌面端、Astryx 触控端(底部面板),以及——对于 TimeInput——不带选择器的纯文本字段是不同表面。

本规范为这三个日期/时间输入提供了一个 presentation prop,其取值可区分每一种表面,完全保留今天的默认行为和弃用 prop 行为,并弃用——但不会移除——nativePicker。目前没有任何现有记录拥有这一跨组件词汇表(已搜索:组件契约、architecture:public-component-api、family:input-fields,以及代码和记录中的 nativePicker / presentation / AdaptivePresentation)。

非目标

  • 任何表面的外观、结构或交互——保持不变,并由各组件自己负责,除非 DEC-3 批准了新的表面。资格/回退行为仅在 FR2 规定的情况下发生变化(针对 native)。
  • 重命名菜单/选择器的 presentation 或它们的 adaptive(OQ1)。
  • 移除 nativePicker——其具体映射仍归本规范所有,而弃用记录、清理 ID、Changeset、配对 minor 版本处理以及迁移证据遵循 spec:AST-017 FR28–FR44,codemod 则遵循 spec:AST-040。

需求

  • FR1——Prop、取值和表面。 DateInput、DateTimeInput 和 TimeInput MUST 接受可选的 presentation,默认值为 'adaptive-native':

    值 精确指针 粗略指针
    text-input 文本字段 文本字段
    popover Astryx 桌面端 Astryx 桌面端
    bottom-sheet Astryx 底部面板 Astryx 底部面板
    native 原生 原生
    adaptive-bottom-sheet Astryx 桌面端 Astryx 底部面板
    adaptive-native Astryx 桌面端 原生(FR2)
    表面 DateInput DateTimeInput TimeInput
    文本字段 —(不接受) —(不接受) 键入字段(今天的 never)
    Astryx 桌面端 键入字段 + 日历弹层 键入字段 + 日期/时间弹层 —(精确指针通过文本字段解析;popover 不是 TimeInput 的独立表面)
    Astryx 底部面板 BottomSheet 日历 BottomSheet 日期/时间滚轮 BottomSheet 时间滚轮(DEC-3)
    原生 浏览器/系统日期选择器 浏览器/系统日期 + 时间选择器 浏览器/系统时间选择器

text-input 是 TimeInput 专用的(维护者确认:imdreamrunner,2026-09-25)——它完全是为已发布的 never(FR3)而存在;不带选择器的日期字段没有已发布的场景,并且会静默丢弃日历可供性:DateInput 和 DateTimeInput MUST NOT 接受它——它们导出的 presentation 类型已将其排除,因此这是编译期错误,也没有为其定义运行时表面。它们的五个取值是 popover | bottom-sheet | native | adaptive-bottom-sheet | adaptive-native;只有 TimeInput 接受全部六个值。

粗略指针使用输入组件现有的指针测试,不包含宽度条件。强制值(粗略指针上的 popover、今天尚未覆盖到的 bottom-sheet,以及 TimeInput 上的 text-input)MUST 渲染指定表面,绝不可静默替换为其他表面。在 gregory 或 iso8601 以外的日历中,DateInput 和 DateTimeInput 在精确指针下将 native 和 adaptive-native 解析为 Astryx 桌面端,在粗略指针下解析为 Astryx 底部面板(FR2、spec:AST-111 FR15)。

  • FR2——针对 native 的回退拆分。 显式 presentation="native" MUST 始终显示原生表面,且没有任何资格回退——原生控件无法表达的状态(秒、非默认步长/增量、预设时间选项、没有可用的原生控件)是调用者的显式选择。 唯一的例外是日历:当使用 gregory 或 iso8601 以外的日历时,显式 native 会使用 Astryx 表面,并在开发环境中发出警告 (spec:AST-111 FR15)。 presentation="adaptive-native"——包括默认值以及 nativePicker="touch"——MUST 保留已发布的回退逻辑:在同样的这些状态下,它会回退到组件的 Astryx 表面(对于 DateTimeInput 按段回退:日期可以走原生,而时间回退),与今天发布的行为完全相同。未带显式 presentation 的已弃用 nativePicker="always" 是第三种情况(FR3):它 MUST 保留自己已发布的 回退逻辑,因此其行为不会改变——只有显式的 presentation="native" 才会选择无回退。

  • FR3——默认值和 nativePicker 完全保留。 同时省略两个 prop 时,MUST 表现与今天的 nativePicker="touch" 相同。nativePicker 及其导出的类型 MUST 继续保留,标记为 @deprecated,对于未迁移和已迁移的调用点都必须解析为与发布时完全一致:

    nativePicker DateInput / DateTimeInput TimeInput
    touch adaptive-native adaptive-native
    always native(旧行为,FR2) native(旧行为,FR2)
    never adaptive-bottom-sheet text-input

always 映射到每种指针类型上的 native 表面,但日历不是 gregory 或 iso8601 时除外(FR2),并保留已发布的资格回退(FR2):hasSeconds、非默认 step/increment、预设时间选项,或没有可用的原生控件时,保持 Astryx 表面,与已发布版本完全一致。因此它与显式 presentation="native" 并不相同,后者从不回退;迁移(codemod 或手工)到 presentation="native" 才是刻意改变这些状态的操作。(TimeInput 已发布的 never 是每种指针类型上的输入字段;TimeInput 的 sheet 只来自显式 presentation="bottom-sheet" | "adaptive-bottom-sheet"。)以等价含义保留该 prop 是非破坏性的(spec:AST-017 FR4)。

  • FR4 — 优先级。如果同时设置了两个 props,presentation MUST 获胜,nativePicker MUST 被忽略,无论顺序或指针如何。只要使用了 nativePicker,仅限开发环境的警告 SHOULD 指明 FR3 替代方案,并且 MUST NOT 在生产环境中触发。

  • FR5 — 文档与类型一致。每个组件的使用者文档(en + zh)、导出类型和 Storybook 控件 MUST 展示 FR1 的值/默认值(TimeInput 上有六个值,DateInput/DateTimeInput 上有五个值),并且 nativePicker 仅以已弃用的形式出现,并注明其 FR3 替代方案。

平台支持

  • 最低支持:不变(spec:AST-013,每个组件);无值时不渲染任何选择器(FR2 的 adaptive-native 回退保证提供 Astryx 表面)。
  • 浏览器依据:每个 FR1 值在 fine/coarse 浏览器上,加上 FR2 回退状态,因为 jsdom 既不报告指针类型,也不报告原生选择器。

当前状态影响

  • packages/core/src/{DateInput,DateTimeInput,TimeInput}:新增 presentation,弃用 nativePicker(FR1–FR4);文档/类型(FR5);DEC-3 新表面;实施 PR 会添加 spec:AST-017 FR8 迁移 + 非破坏性 Changeset。菜单/选择器组件:不变。

验证

契约 验证 代表性状态 变更或失败预期
FR1 每个输入的单元测试 + 真实浏览器检查 每个组件的值 × fine/coarse,包括强制值 + TimeInput sheet;text-input 类型在 TimeInput 之外被拒绝 错误/被替换的表面失败
FR2 单元测试,请求原生控件 秒、step≠default、预设、无可用原生控件:显式 native 保持原生;adaptive-native 和已弃用的 always 回退 在显式 native 下出现任何资格回退,或在 adaptive-native/always 下无回退,均失败
FR3–FR4 单元测试:默认、弃用、双 prop 省略;每个组件的 touch/always/never;两个 props 任意顺序 映射漂移(包括 TimeInput:never→sheet)或 nativePicker 获胜,均失败
FR5 文档/类型一致性测试 全部 3 个组件,en + zh 有文档但未提供类型的值/默认值失败

决策日志

DEC-1 — 统一为 presentation;值命名表面

参考:spec:AST-043/DEC-1 决策者:imdreamrunner,2026-09-24

对于这个问题,构建者已经在菜单/选择器上使用了 presentation。 已拒绝的方案:字面重命名为 'touch'|'always'|'never'(隐藏了桌面 vs sheet vs 文本字段的区分)、单个 astryx 值(同样的信息损失)、共享的 'adaptive'(隐藏了 sheet vs 原生的区分)、两个语义重叠的 props 共存。

DEC-2 — 默认 adaptive-native;弃用但不移除

参考:spec:AST-043/DEC-2 决策者:imdreamrunner,2026-09-24

adaptive-native 是今日默认值的重命名;nativePicker 继续可用(FR3/FR4)——移除才是破坏性事件,而不是重命名。 已拒绝的方案:默认设为 adaptive-bottom-sheet,以及让 nativePicker 优先于 presentation。

DEC-3 — 强制表面与 TimeInput sheet 获批

参考:spec:AST-043/DEC-3 决策者:cixzhang,2026-09-24

在 coarse 指针上强制 popover、在 fine 指针上强制 bottom-sheet,以及新增 TimeInput bottom sheet(即 DateTimeInput sheet 的时间半部分)均为获批的新表面。这结束了先前关于 FR1 强制范围的开放问题;实现可以按 FR1 的书面规定依赖它。

开放问题

  • OQ1 — 菜单/选择器重命名(human-api):以后是否在这种弃用模式下将它们的 adaptive 重命名为 adaptive-bottom-sheet?超出范围。

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