时间戳 · Timestamp

时间戳用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 时间戳 · 交互示例 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.

使用建议

• 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

{
  "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.