日期和时间输入呈现系统规范¶
意图¶
同一个 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-017FR28–FR44,codemod 则遵循spec:AST-040。
需求¶
-
FR1——Prop、取值和表面。
DateInput、DateTimeInput和TimeInputMUST 接受可选的presentation,默认值为'adaptive-native':值 精确指针 粗略指针 text-input文本字段 文本字段 popoverAstryx 桌面端 Astryx 桌面端 bottom-sheetAstryx 底部面板 Astryx 底部面板 native原生 原生 adaptive-bottom-sheetAstryx 桌面端 Astryx 底部面板 adaptive-nativeAstryx 桌面端 原生(FR2) 表面 DateInputDateTimeInputTimeInput文本字段 —(不接受) —(不接受) 键入字段(今天的 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-111FR15)。presentation="adaptive-native"——包括默认值以及nativePicker="touch"——MUST 保留已发布的回退逻辑:在同样的这些状态下,它会回退到组件的 Astryx 表面(对于DateTimeInput按段回退:日期可以走原生,而时间回退),与今天发布的行为完全相同。未带显式presentation的已弃用nativePicker="always"是第三种情况(FR3):它 MUST 保留自己已发布的 回退逻辑,因此其行为不会改变——只有显式的presentation="native"才会选择无回退。 -
FR3——默认值和
nativePicker完全保留。 同时省略两个 prop 时,MUST 表现与今天的nativePicker="touch"相同。nativePicker及其导出的类型 MUST 继续保留,标记为@deprecated,对于未迁移和已迁移的调用点都必须解析为与发布时完全一致:nativePickerDateInput/DateTimeInputTimeInputtouchadaptive-nativeadaptive-nativealwaysnative(旧行为,FR2)native(旧行为,FR2)neveradaptive-bottom-sheettext-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,
presentationMUST 获胜,nativePickerMUST 被忽略,无论顺序或指针如何。只要使用了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-017FR8 迁移 + 非破坏性 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