跳转至

非渲染型经过时间计时器系统规格

契约一览

领域 契约
公开契约 添加 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 或 format MUST 生效,且无需重新挂载,也不得创建超过一个活跃的计时器资源。
  • FR7 — 完整的生命周期所有权。 每个已挂载的 Timer 至多拥有一个活跃的浏览器计时器资源。每次 Effect 设置 MUST 在依赖变化、节点替换、卸载和 StrictMode 重放期间释放其获取的资源。任何 tick 都不得更新已分离或已被替换的节点。
  • FR8 — 稳定的公共 DOM 与排版表面。 根元素 MUST 暴露 Timer、TimerProps、TimerFormat、其 HTMLTimeElement ref、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 和 elapsed MUST 在下一个整秒边界进行调度。一小时及以上的 elapsed MUST 在下一个整分钟边界进行调度,因为其可见输出省略了秒。未来的起点 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