# 计时

## 使用方法

`Timer` 把一段正在增加的时长写进 `<time>`。`startTime` 是毫秒级 unix 时间。不传就从这次挂载开始计。文字和 `dateTime` 直接写在元素上。组件不会为每一次跳动重新渲染，也不使用 `aria-live`。

默认 `format="elapsed"`。不到一分钟显示 `Ns`，不到一小时显示 `Nm NNs`，满一小时显示 `Nh NNm`，文字和 `dateTime` 都不再带秒（存成 `PT{分钟数 × 60}S`）。`format="clock"` 始终精确到秒：不到一小时是 `m:ss`，超过则是 `h:mm:ss`，`dateTime` 为 `PT{秒数}S`。

未满一小时时大约每秒更新一次，elapsed 满一小时后改为每分钟一次。如果 `startTime` 还在未来，第一次变化会等到开始后再过一秒。

排版和 `Timestamp` 同一套。`type` 默认 `supporting`，`color` 默认 `secondary`。`type="inherit"` 不用 `Text` 包一层，字体跟周围走。`color="disabled"` 用禁用文字色。`size` 和 `weight` 的覆盖方式和 `Text` 一样。

```vue
<script setup lang="ts">
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'
</script>

<template>
  <Text type="body" color="primary">
    Processing for <Timer type="inherit" color="inherit" />
  </Text>
</template>
```

## 建议

| 建议 | 做法 |
| --- | --- |
| 推荐 | 状态词旁边用 `elapsed`。读者在盯着秒数时用 `clock`。 |
| 推荐 | 两个计时要一致时，传入同一个 `startTime`。 |
| 推荐 | 写进一句话里时用 `type="inherit"`，时长才跟那一行对齐。 |
| 避免 | 把每一次跳动都播报出去。时间元素就地更新，保持安静。 |
| 避免 | 满一小时后还指望 `elapsed` 精确到秒。这个格式到点就会改成按分钟显示。 |

### 结构

- **已过时间**: 装着标准化已过时长的语义 time 元素。

## 示例

### Timer — 格式

同一开始时间下，紧凑的已用单位和秒表式时钟记法。

```vue
<script setup lang="ts">
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'

const startedAt = Date.now() - 3_753_000
</script>

<template>
  <Stack direction="vertical" :gap="3">
    <Stack direction="horizontal" :gap="3" align="center">
      <Text type="supporting" color="secondary">
        Elapsed
      </Text>
      <Timer :start-time="startedAt" type="body" color="primary" />
    </Stack>
    <Stack direction="horizontal" :gap="3" align="center">
      <Text type="supporting" color="secondary">
        Clock
      </Text>
      <Timer format="clock" :start-time="startedAt" type="body" color="primary" />
    </Stack>
  </Stack>
</template>
```

### Timer — 行内

把 Timer 写进状态句子里，并继承周围的排版。

```vue
<script setup lang="ts">
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'
</script>

<template>
  <Text type="body" color="primary">
    Processing for <Timer type="inherit" color="inherit" />
  </Text>
</template>
```

### Timer — 排版

默认排版与 Timestamp 对齐，另一行用强调样式覆盖。

```vue
<script setup lang="ts">
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { Timer } from '@astryx-vue/core/Timer'

const startedAt = Date.now() - 128_000
</script>

<template>
  <Stack direction="vertical" :gap="3">
    <Text type="supporting" color="secondary">
      Default
    </Text>
    <Timer :start-time="startedAt" />
    <Text type="supporting" color="secondary">
      Emphasized
    </Text>
    <Timer :start-time="startedAt" type="body" size="xl" color="primary" weight="semibold" />
  </Stack>
</template>
```

## 属性

| 属性 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `startTime` | `number` | — | 操作开始时的 unix 时间，单位毫秒。不传则从挂载时开始。 |
| `format` | `'elapsed' \| 'clock'` | `'elapsed'` | `elapsed` 用紧凑单位，满一小时后去掉秒。`clock` 始终精确到秒。 |
| `type` | `TextType \| 'inherit'` | `'supporting'` | 语义字号，和 Timestamp 一致。`inherit` 不再包一层 Text。 |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | — | 显式字号，覆盖 `type` 带出的尺寸。 |
| `color` | `'primary' \| 'secondary' \| 'accent' \| 'inherit' \| 'disabled'` | `'secondary'` | 文字颜色。`disabled` 使用禁用文字色。 |
| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` | — | 字重覆盖。 |

## 主题

根类名是 `astryx-timer`。数字用等宽数字。`data-color` 选择 `primary`、`secondary`、`accent` 或 `disabled`。