# 时间戳 · Timestamp

- 页面: https://jiguang132.com/zh/resources/astryx/docs/timestamp
- 资源: 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**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **时间戳 · 交互示例 5**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **时间戳 · 交互示例 6**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **时间戳 · 交互示例 7**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

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

## Timestamp

Timestamp formats a date or time value into human-readable text. Use it to show when something was created, updated, or is scheduled; picking relative for recency, absolute for precision, or auto to let the component decide.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value * | string \| number |  | 要显示的日期/时间。接受 Unix 时间戳（秒）或 ISO 8601 字符串。 |
| format | 'relative' \| 'relative_short' \| 'auto' \| 'date' \| 'date_long' \| 'date_weekday' \| 'date_time' \| 'time' \| 'system_date' \| 'system_date_time' \| 'system_time' \| 'unix_seconds' | 'auto' | 显示格式。'relative' 显示 '2小时前'，'date' 显示日期，'date_long' 显示长月份日期，'date_weekday' 显示星期+日期，'auto' 根据时间远近自动切换。 |
| autoThreshold | number | 604800 | auto 格式从相对时间切换到 date_time 的阈值秒数。 |
| hasTooltip | boolean | true | 悬停时是否显示包含完整日期/时间的可复制悬停卡片（相对时间模式，或配置 tooltipEntries 的任意格式）。 |
| tooltipEntries | ReadonlyArray<{timezoneID?: string; format?: TimestampTooltipFormat; label?: string; isCopyable?: boolean}> |  | 悬停时要显示的行，用于同时展示多个时区和/或多种格式。每项为一行，按顺序渲染；省略 timezoneID（或传入 'local'）表示查看者本地时区。悬停面板始终是可逐行复制到剪贴板的交互式卡片，这些配置项自定义其行；未配置时卡片显示一行默认的完整绝对时间。配置后绝对时间格式也会因此获得悬停面板。 |
| isTimezoneShown | boolean | false | 是否在可见文本后附加时区缩写（仅 date_time 和 time；system_* 格式不附加）。 |
| isLive | boolean | false | 相对时间是否实时更新。 |
| type | 'body' \| 'large' \| 'label' \| 'supporting' \| 'code' \| 'display-1' \| 'display-2' \| 'display-3' \| 'inherit' | 'supporting' | 来自 Text 的语义文本类型。 |
| size | '4xs' \| '3xs' \| '2xs' \| 'xsm' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' |  | 显式字体大小覆盖。 |
| color | 'primary' \| 'secondary' \| 'disabled' \| 'placeholder' \| 'accent' \| 'inherit' | 'secondary' | 文字颜色。 |
| weight | 'normal' \| 'medium' \| 'semibold' \| 'bold' |  | 字体粗细覆盖。 |

### 使用建议

- Use the auto format in feeds and lists so recent items show "2 hours ago" and older items show the full date automatically.
- Keep formatting consistent within the same list or table; mixing relative and absolute timestamps in the same column confuses scanning.
- Enable isTimezoneShown when the audience spans multiple time zones, like a global team calendar or audit log.
- Use tooltipEntries when readers must compare zones, such as an incident log where the reader's time and the event's origin zone both matter.
- Label every entry once a tooltip shows more than one zone; a bare abbreviation is not always recognizable (Tokyo renders as "GMT+9", not "JST").
- Use isLive for active dashboards or real-time feeds so the relative time stays accurate without a page refresh.
- Reach for tooltipEntries when readers need to grab an exact value: an incident log or deploy record where someone pastes the UTC time or Unix seconds elsewhere; configuring entries turns the hover into copy-to-clipboard rows.
- 避免：Don't display raw Unix timestamps or ISO strings to users; always pass them through Timestamp to get a human-readable format.
- 避免：Avoid system_date or system_time formats in user-facing UI; they are meant for developer tools, logs, and machine-readable contexts.
- 避免：Don't disable the hover card on relative timestamps; users expect to hover for the full date when they see "3 hours ago".
- 避免：Don't stack many zones into one card; it is capped at 300px wide and long labelled lines wrap. Two or three entries read well.
- 避免：Don't pass a fixed-offset abbreviation like "EST" as timezoneID; it is a valid identifier but never observes daylight saving, so it reads an hour wrong for half the year. Use the region id, "America/New_York".

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-timestamp",
      "visualProps": [
        "type",
        "color",
        "format"
      ]
    },
    {
      "className": "astryx-timestamp-copy-button"
    }
  ]
}
```

### 组件结构

- **Formatted text**: The rendered date, time, or relative label like "2 hours ago" or "Mar 21, 2025".
- **Hover card**: A copyable hover card showing the full absolute date and time when the display is relative, or the rows configured via tooltipEntries. Its default single row carries the full absolute time.
- **Hover card row**: One row of the card: an optional label beside the instant rendered in one time zone and format. Rows opt into a copy button via isCopyable.
- **Copy button**: Per-row copy-to-clipboard button in the hover card; copies that row's formatted value.

---

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