非渲染型经过时间计时器系统规格¶
契约一览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | 添加 Timer、TimerProps、TimerFormat、以 Unix 毫秒为单位的可选 startTime、封闭的 format 值 elapsed 与 clock、与 Timestamp 等效的 type、size、 |
color 和 weight 排版属性、根 HTMLTimeElement 引用,以及标准 BaseProps<HTMLTimeElement> 接口。 |
|
| 行为 | 从所选原点渲染标准化的经过时长,在不触发 React tick 渲染的情况下更新所属的 <time> 节点,并且仅当所选格式能产生可见变化时才进行调度。 |
| 最终用户影响 | 观看进行中操作的人们能看到稳定的时长,从秒级扩展到分钟和小时级,且不会让不必要的计时器工作与周围界面争抢资源。 |
| 构建者影响 | 构建者使用零配置的经过时间格式、提供更早的操作开始时间,或选择标准化的类秒表时钟格式。他们使用与 Timestamp 相同的 |
| 可选排版属性和默认值,无需编写时长 | |
| 格式化器或选择计时器节奏。 | |
| 兼容性 | 增量式,尚未发布。运行时、可访问性、文档和主题化证据必须在发布前落实。 |
| 审查检查 | 拒绝自定义格式化器或节奏 API、用于 tick 的 React 状态更新、回调计数漂移、经过时间输出不再显示秒后仍每秒唤醒、计时器泄漏、负值输出、丢失根透传/ref 行为,或超过一个可见的组成部分。 |
| 治理规则 | architecture:public-component-api;architecture:react-component-runtime;architecture:component-theming-surface;AST-002 DEC-1、DEC-2 和 DEC-5。 |
此表为审查预览;下方正文具有权威性。
意图¶
产品需要一个共享的经过时间原语,用于时长在可见期间不断变化的操作。其定义性价值在于拥有由时钟驱动的 DOM 更新,该更新不会在每个 tick 上调度 React 渲染。随着时长从秒增长到分钟和小时,其格式化保持一致,其资源节奏遵循人们实际能看到的精度。
Timer 与 Timestamp 不同:Timestamp 描述某个瞬间,可能呈现相对的日历语言,而 Timer 度量从某个原点开始的时长。它也与 Text 不同:Text 呈现调用方拥有的内容,而 Timer 拥有不断变化的时长值、标准化表示和资源生命周期。
组件台账¶
| 来源需求 | 建议目标 | 归属理由 | 完成标准 |
|---|---|---|---|
| 在活跃工作期间显示已用时间,且不产生周期性的 React 渲染工作或产品本地的格式漂移。 | 稳定的 Core Timer 组件。 |
该行为在加载、处理、录制与活动界面中重复出现;产品不应在每个调用点重建格式化、生命周期、漂移处理或调度节奏。 | 封闭格式、感知格式的调度、直接的属主节点更新、时钟推导的时长、清理、ref 与透传行为、主题目标、消费者文档、stories 和针对性测试均符合此契约。 |
所有权边界¶
AST-037 拥有 Timer 的公共已用时间起点与格式概念、表示阶梯、感知格式的调度节奏、非渲染 tick 需求、语义化时长输出、资源生命周期以及初始 Core 准入。Timer 组件记录在实现后拥有具体的组件投影与证据。
architecture:public-component-api 拥有导出、BaseProps、样式、ref 与调用者选择规则。architecture:react-component-runtime 拥有 Effect 与资源生命周期的正确性。architecture:component-theming-surface 拥有目标限定。
非目标¶
- 加载指示器、等待消息、状态标签,或产品自行选择显示或隐藏已用时间的行为。
- 挂钟日期、相对日历表述、时区或绝对时刻。
- 暂停、恢复、截止时间、闹钟、计圈历史或命令式计时器控制。
- 倒计时推迟到后续契约处理;如果 Timer 后续支持结束时间起点,标准化的时长格式与调度节奏仍保持可复用。
- 亚秒级显示精度、任意格式化回调,或调用者对内部调度节奏的控制。
- 向辅助技术播报每次 tick。
- 新的全局 token 或组件专属主题变量。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 默认值 | 无效值行为 |
|---|---|---|---|---|
| 已用时间起点 | 挂载时间或 startTime Unix 毫秒数 |
推导已用时长的起始时刻 | 挂载时间 | 非有限值回退到挂载时间 |
| 时长格式 | elapsed、clock |
标准化的可见表示及其隐含精度 | elapsed |
类型拒绝其他值;运行时回退到 elapsed |
| Tick 呈现 | 单个 <time> 根元素上的当前已用时间值 |
以所选格式精度呈现的可见文本与机器可读时长 | elapsed 为 0s;客户端同步前 clock 为 0:00 |
起点之前的 clock 值钳制为零 |
startTime 由调用者所有,因为 Timer 无法推导其在挂载之前操作开始的时间。format 由调用者所有,因为紧凑文本与秒表读数是不 同的呈现需求。格式化细节与调度节奏仍归 Timer 所有:调用者选择含义,而非机制。
标准格式¶
| 已用时长 | elapsed |
clock |
|---|---|---|
| 零 | 0s |
0:00 |
| 34 秒 | 34s |
0:34 |
| 2 分 8 秒 | 2m 08s |
2:08 |
| 1 小时 2 分 33 秒 | 1h 02m |
1:02:33 |
elapsed 最多显示两个单位,最大的单位在前。当秒是唯一单位时不补零,在分钟之后出现时补零,在小时之后则省略。clock 使用冒号分隔的秒表记法:一小时以下为 m:ss,一小时起为 h:mm:ss。
需求¶
- FR1 — 单一语义根。 Timer MUST 渲染一个
<time>根元素,其可见文本使用所选的标准格式。 - FR2 — 可推导的起点默认值。 在没有
startTime时,已用时间 MUST 从组件的挂载生命周期开始计算;在存在有限的startTime时,已用时间 MUST 从该 Unix 毫秒起点推导。 - FR3 — 时钟推导、非负的时长。 Timer MUST 从当前时钟中减去解析后的起点,将负时长钳制为零,并从此结果推导输出。它 MUST NOT 依据回调次数累积已用时间,因此延迟的回调可以追赶上来而不产生累积漂移。
- FR4 — 无 tick 渲染。 时钟 tick MUST 直接更新属主的
<time>节点,并且 MUST 为 Timer 及其周围子树产生零次 React 更新提交。由无关工作引起的父级渲染仍不在 Timer 的控制范围内。 - FR5 — 机器可读的一致性。 Timer MUST 将
dateTime更新为 ISO 8601 时长,其精度与可见值相同:clock以及低于一小时的elapsed使用整秒,一小时及以上的elapsed使用整分钟。 - FR6 — 使用当前 props 且不产生重复资源。 更改
startTime或formatMUST 生效,且无需重新挂载,也不得创建超过一个活跃的计时器资源。 - FR7 — 完整的生命周期所有权。 每个已挂载的 Timer 至多拥有一个活跃的浏览器计时器资源。每次 Effect 设置 MUST 在依赖变化、节点替换、卸载和 StrictMode 重放期间释放其获取的资源。任何 tick 都不得更新已分离或已被替换的节点。
- FR8 — 稳定的公共 DOM 与排版表面。 根元素 MUST 暴露
Timer、TimerProps、TimerFormat、其HTMLTimeElementref、Text 系列的type、size、color和weight,以及BaseProps<HTMLTimeElement>允许的标准 DOM、data、ARIA、style、class、event 和xstyle输入。排版解析与默认值 MUST 与 Timestamp 一致:type="supporting"、size="supporting"、color="secondary"、weight="normal"。 - FR9 — 不主动进行实时播报。 Timer 在默认情况下 MUST NOT 添加 live-region 角色或
aria-live值。调用者可以出于需要,通过标准 DOM 表面有意地为某个上下文提供 ARIA 属性。 - FR10 — 单一可主题化的结构部件。 可见根元素 MUST 携带
timer主题目标。任何子部件、格式、计时状态或调度机制都不会获得单独的目标。 - FR11 — 初始渲染是确定性的。 初始标记 MUST 以
dateTime="PT0S"显示所选格式的零值,且不得将客户端时钟读入服务端可见的标记中。随后由客户端同步应用所选的起点。 - FR12 — 感知格式的调度节奏。 低于一小时的
clock和elapsedMUST 在下一个整秒边界进行调度。一小时及以上的elapsedMUST 在下一个整分钟边界进行调度,因为其可见输出省略了秒。未来的起点 MUST 直接面向第一次可见变化进行调度,而不是在输出仍为零时每秒唤醒一次。延迟运行的回调 MUST 依据当前时钟进行调度,而非错过的截止时间。 - FR13 — 有界的 DOM 写入。 当所选格式所表示的值没有变化时,Timer 应当跳过可见文本与
dateTime的写入。
转换与优先级¶
解析有限调用方起始点或挂载起始点,将其从当前时钟中减去,钳制到零,按所选格式的当前精度向下取整,格式化该值,在同一所属节点上更新可见及机器可读输出,然后调度该格式下次可变更的边界。Timer 拥有 dateTime;否则,标准消费者属性和样式会到达根节点。
平台支持¶
- 受支持的功能/引擎基线:与当前 Core 包支持保持一致。
- 不支持的行为:没有 Effects 的环境会保留所选格式的确定性零值和
PT0S,并且不会获取定时器资源。 - 浏览器证据:真实浏览器的 stories 验证了两种格式阶梯、小时边界、稳定的内联几何、语义时长一致性,以及不存在组件更新提交。
当前状态影响¶
- Core 新增一个稳定的已用时长组件与类型、两种封闭格式、与 Timestamp 等效的排版属性、一个
timer主题目标、消费者文档、Storybook 覆盖,以及一个展示块。 - Timestamp 保持不变,继续拥有瞬时、日历相关语言、时区和绝对格式化。
- 默认路径不增加构建器选择。只有挂载前开始的操作才提供
startTime;只有类似秒表的界面才选择format="clock"。 - 自定义格式化和定时器节奏刻意不作为公共 API。
- 现有组件、导出、DOM 结构、主题、令牌或调用点均无更改。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR5, FR11–FR13 | 使用受控时钟和模拟定时器进行有针对性的 Timer 测试 | 初始状态、默认/更早/未来起始点及未来调度、延迟回调、每种格式阶梯、59:59→1:00:00 边界、已用小时边界 | 若出现状态驱动的 tick、回调计数累积、负值、不必要的起始点前唤醒、错误的填充/单位阶梯、过期的 dateTime、错误的初始标记、冗余写入,或整点后一秒钟的已用时长唤醒,则失败 |
| FR4 | React Profiler 提交计数测试 | 若干已用时长 tick 和一个组合的兄弟节点 | 用 React 状态替换所属节点变更会产生额外的更新提交 |
| FR6–FR7 | 在重新渲染、卸载和 StrictMode 下的资源监视测试 | 起始点变更、格式变更、重放、清理 | 重复或泄漏的定时器资源会使设置/清理计数和分离节点防护失败 |
| FR8 | 公共导入、DOM 透传、排版、样式合并、事件和 ref 测试 | 根导入、Timestamp 默认值、每次排版覆盖,以及具有代表性的 BaseProps | 缺少导出;默认值不一致;或丢失排版、属性、处理函数、class/style 输入或根 ref,均视为失败 |
| FR9 | 可访问性属性测试 | 默认和调用方声明的 live 行为 | Timer 若添加未经请求的 live 语义或丢弃调用方有意声明的 ARIA,则失败 |
| FR10 | 主题目标和知识检查 | 跨格式的单一根目标 | 目标映射缺失、多余或位置错误都会导致仓库验证失败 |
| 浏览器契约 | Storybook 浏览器证据 | 默认已用时长、clock、更早起始点、小时级已用时长、组合的等待消息 | 可见输出、语义时长、几何或更新提交行为若与契约不一致,则失败 |
决策日志¶
DEC-1 — Timer 拥有非渲染的已用时长更新¶
参考: spec:AST-037/DEC-1
方向负责人: cixzhang, 2026-09-22
Timer 是一种稳定的共享原语,用于表示已流逝时间。它持有单一源自时钟的时长,并将不断变化的文本直接写入其拥有的 DOM 节点,因此时钟 tick 不会调度 React 渲染。构建者可以提供更早的开始时刻,或选择标准化的格式;他们不会提供 formatter,也不会控制调度。
否决:通过 React state 实现每次 tick。那会让每个 Timer 成为周期性渲染源,并加剧本已在处理实时应用更新的树中的竞争。
否决:暴露 interval、tick 频率或任意 formatter。这些选择会使组件无法维持一致的时长表述,也无法在可见精度下降时减少工作量。
DEC-2 — Timer 从 Core 开始¶
参考: spec:AST-037/DEC-2
方向负责人: cixzhang,2026-09-22
Timer 从 Core 开始,因为其定位是跨产品稳定的运行时原语,其首份契约刻意保持狭窄,且所要求的行为已在运行中得到验证。进入 Core 需要在发布前于本 spec 中提供完整证据;这并不会免除常规的组件质量门禁。
否决:发布独立的产品副本,或将非渲染行为做成应用配方。那会让表示、资源所有权和节奏决策在各调用点重复出现。
DEC-3 — 格式自行掌控可见精度与节奏¶
参考: spec:AST-037/DEC-3
方向负责人: cixzhang,2026-09-22
Timer 暴露两种标准表示:elapsed 用于紧凑文本和行元数据,clock 用于类似秒表的读数。每种格式自行掌控精度,因此运行时只在下一个能够改变可见输出的边界唤醒。特别地,达到或超过一小时的 elapsed 时长会省略秒,并在分钟边界唤醒。
否决:在继续显示秒的同时,根据已流逝时长缩放节奏。那会使可见输出变得陈旧。精度先行改变;节奏随之调整。
待解决问题¶
无。契约是最新的;实现证据仍有待提交。
内容边界¶
本记录不重复消费者示例、实现代码、私有调度机制、当前测量结果或系统运行时/主题规则。这些内容由各自的规范所有者负责。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx