计时器 · Timer

计时器用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

计时器 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
计时器 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
计时器 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
计时器 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Timer

Displays a standardized elapsed duration for active work without scheduling a React render on every tick. Elapsed format updates by second below one hour and by minute after one hour; clock format remains second-precise.

属性	类型	默认值	说明
startTime	number		Unix time in milliseconds when the measured operation began. Omit it to start from this Timer's mount.
format	'elapsed' \| 'clock'	'elapsed'	Standard duration representation. Elapsed uses compact units and drops seconds after one hour; clock uses m:ss or h:mm:ss.
type	'body' \| 'large' \| 'label' \| 'supporting' \| 'code' \| 'display-1' \| 'display-2' \| 'display-3' \| 'inherit'	'supporting'	Semantic text type. Uses the same typography behavior as Timestamp.
size	'4xs' \| '3xs' \| '2xs' \| 'xsm' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl'		Explicit font size override. Overrides the size from type.
color	'primary' \| 'secondary' \| 'disabled' \| 'placeholder' \| 'accent' \| 'inherit'	'secondary'	Text color.
weight	'normal' \| 'medium' \| 'semibold' \| 'bold'		Font weight override.
xstyle	StyleXStyles		StyleX styles for the Text wrapper. Must be a stylex.create() value.
className	string		CSS class name for the Text wrapper. Prefer xstyle for styling.
style	CSSProperties		Inline styles for the Text wrapper. Prefer xstyle for styling.

使用建议

Use elapsed for compact duration text that may span seconds, minutes, or hours.
Use clock for stopwatch-like surfaces where seconds remain meaningful after an hour.
Pass startTime when the operation began before Timer mounted so the display reflects the complete wait.
避免：Do not use Timer for dates, time zones, or relative calendar language; use Timestamp instead.
避免：Do not add aria-live unless hearing an announcement every tick is appropriate for the specific task.

Elapsed duration

<Timer />

Stopwatch clock

<Timer format="clock" />

Operation that started before mount

<Timer startTime={operationStartedAt} />

Match surrounding text

<Text>
  Processing for <Timer type="inherit" color="inherit" />
</Text>

Prominent elapsed time

<Timer type="body" size="lg" color="primary" weight="semibold" />

主题 API

{
  "targets": [
    {
      "className": "astryx-timer"
    }
  ]
}

组件结构

Elapsed time: Semantic time element containing a standardized elapsed duration.