# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<RelativeTime>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/relative-time.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 格式化本地化的相对时间，例如 2 小时前。`<RelativeTime>` 组件的 API 参考。

`<RelativeTime>` 组件使用当前区域设置的时间单位和措辞惯例来渲染相对时间表述。它既可以根据 `Date` 自动选择最合适的时间单位，也可以根据显式指定的值和时间单位进行渲染。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

## 概览 [#overview]

将 `Date` 作为子元素传入后，`<RelativeTime>` 会自动选择最合适的时间单位，并基于 `baseDate` 格式化相对时间。

```tsx
<RelativeTime>{someDate}</RelativeTime>
// 输出："2 hours ago"
```

所有格式化都在本地通过 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat) 完成。

*注意：在服务器端渲染的应用中，`<RelativeTime>` 可能会引发 React 的 hydration 错误。请参阅[避免 hydration 错误](#hydration)。*

## 工作方式 [#how-it-works]

* **两种模式。** 你可以提供 `Date` (通过 `children` 或 `date`) ，组件会根据 `baseDate` 自动选择最合适的时间单位；也可以显式提供 `value` 和 `unit`，其行为与 `Intl.RelativeTimeFormat` 保持一致。
* **本地格式化。** 相对时间会在浏览器中计算并格式化；该值绝不会发送到 General Translation API。
* **无输入时不渲染任何内容。** 如果既未提供日期也未提供值，组件会渲染 `null`。

## 属性 [#props]

| Prop                     | 描述                              | Type                             | 可选 | 默认值                                  |
| ------------------------ | ------------------------------- | -------------------------------- | -- | ------------------------------------ |
| [`children`](#children)  | 用于计算相对时间的 `Date` 对象。            | `Date`                           | 是  | —                                    |
| [`date`](#date)          | 用于计算的 `Date` 对象，优先于 `children`。 | `Date`                           | 是  | —                                    |
| [`value`](#value)        | 显式指定的数值。需要配合 `unit` 使用。         | `number`                         | 是  | —                                    |
| [`unit`](#unit)          | 时间单位，与 `value` 搭配使用。            | `Intl.RelativeTimeFormatUnit`    | 是  | —                                    |
| [`baseDate`](#base-date) | 作为基准的日期。                        | `Date`                           | 是  | `new Date()`                         |
| [`options`](#options)    | `Intl.RelativeTimeFormat` 的选项。  | `Intl.RelativeTimeFormatOptions` | 是  | `{ numeric: 'auto', style: 'long' }` |
| [`locales`](#locales)    | 用于覆盖格式化时的区域设置。                  | `string[]`                       | 是  | 当前区域设置                            |
| [`name`](#name)          | 该条目的变量名。                        | `string`                         | 是  | —                                    |

### `children` [#children]

**类型** `Date` · **可选**

一个 `Date` 对象。组件会自动选择最合适的时间单位 (从秒到年) ，并基于 `baseDate` 格式化相对时间。

### `date` [#date]

**类型** `Date` · **可选**

用于计算相对时间的 `Date`。当同时提供 `date` 和 `children` 时，优先使用 `date`。

### `value` [#value]

**类型** `number` · **可选**

相对时间的明确数值 (例如，`-1` 表示“昨天”) 。必须与 `unit` 搭配使用。

### `unit` [#unit]

**类型** `Intl.RelativeTimeFormatUnit` · **可选**

时间单位，例如 `'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'` 或 `'year'`。使用 `value` 时，此项为必填。

### `baseDate` [#base-date]

**类型** `Date` · **可选** · **默认值** `new Date()`

用于计算相对时间的基准日期。默认为渲染时的 `new Date()`。请显式设置该值以避免 hydration 错误——参见[下文](#hydration)。

### `options` [#options]

**类型** `Intl.RelativeTimeFormatOptions` · **可选** · **默认值** `{ numeric: 'auto', style: 'long' }`

该 prop 使用 [`Intl.RelativeTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options)。`<RelativeTime>` 目前会读取以下选项：

| 选项              | 描述                         | 类型                              | 可选 | 默认值          |
| --------------- | -------------------------- | ------------------------------- | -- | ------------ |
| `localeMatcher` | 区域设置匹配算法。                  | `'lookup' \| 'best fit'`        | 是  | `'best fit'` |
| `style`         | 相对时间表述的长度。                 | `'long' \| 'short' \| 'narrow'` | 是  | `'long'`     |
| `numeric`       | 是否始终使用数字，或允许使用“昨天”“明天”等表述。 | `'always' \| 'auto'`            | 是  | `'auto'`     |

`Intl.RelativeTimeFormatOptions` TypeScript 类型中定义的其他字段不会传递给 `<RelativeTime>`。

有关最新的标准选项，请参阅 [`Intl.RelativeTimeFormat` 选项文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options)。`<RelativeTime>` 当前支持的选项请参见上表。

### `locales` [#locales]

**类型** `string[]` · **可选** · **默认值** 当前区域设置

用于格式化的区域设置。省略时，将使用当前区域设置。请参阅 [locales 参数](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。

### `name` [#name]

**类型** `string` · **可选**

条目的可选名称，用作元数据。

## 示例 [#examples]

*示例从 `gt-react` 导入；请改为从您所用框架的包中导入。*

```tsx title="PostTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
  return <RelativeTime>{post.createdAt}</RelativeTime>; // [!code highlight]
  // 输出："2 hours ago"、"3 days ago"、"in 5 minutes" 等。
}
```

```tsx title="PostTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function PostTimestamp({ post }) {
  return <RelativeTime date={post.createdAt} />; // [!code highlight]
}
```

```tsx title="Reminder.tsx"
import { RelativeTime } from 'gt-react';

export default function Reminder() {
  return (
    <p>
      Your trial ends <RelativeTime value={3} unit="day" />. // [!code highlight]
    </p>
  );
  // 输出："Your trial ends in 3 days."
}
```

```tsx title="Comment.tsx"
import { T, RelativeTime } from 'gt-react';

export default function Comment({ comment }) {
  return (
    <T>
      Posted <RelativeTime>{comment.createdAt}</RelativeTime> // [!code highlight]
    </T>
  );
}
```

```tsx title="NumericTimestamp.tsx"
import { RelativeTime } from 'gt-react';

export default function NumericTimestamp({ date }) {
  return (
    <RelativeTime
      options={{
        numeric: 'always', // [!code highlight]
        style: 'narrow', // [!code highlight]
      }}
    >
      {date}
    </RelativeTime>
  );
  // 使用 numeric: 'always' 时，输出 "1 day ago" 而非 "yesterday"
}
```

## 避免 hydration 错误 [#hydration]

由于 `<RelativeTime>` 会在本地计算相对时间，因此服务器端和客户端可能会产生不同的输出，从而导致 hydration 错误。通常会在以下情况下发生：

* **`baseDate` 在渲染时默认设为 `new Date()`。** 服务器端和客户端的渲染时刻会略有差异。如果相对时间在这段间隔内跨过了某个时间单位的边界 (例如，&quot;59 seconds ago&quot; → &quot;1 minute ago&quot;) ，输出就会不一致。
* **不同环境中的默认区域设置不一致**，从而生成不同的字符串 (例如，&quot;hace 2 horas&quot; vs. &quot;2 hours ago&quot;) 。

请固定区域设置，并使用共享的 `baseDate`，这样服务器端和客户端始终会生成相同的字符串：

```tsx
const now = new Date(); // 只计算一次，同时传递给服务端和客户端

<RelativeTime locales={['en-US']} baseDate={now}>
  {post.createdAt}
</RelativeTime>
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.