# 计时器 · Timer

- 页面: https://jiguang132.com/zh/resources/astryx/docs/timer
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

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

## 安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **计时器 · 综合展示 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

```tsx
<Timer />
```

### Stopwatch clock

```tsx
<Timer format="clock" />
```

### Operation that started before mount

```tsx
<Timer startTime={operationStartedAt} />
```

### Match surrounding text

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

### Prominent elapsed time

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

### 主题 API

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

### 组件结构

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

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt