# gt-react: General Translation React SDK: RelativeTime
URL: https://generaltranslation.com/zh/docs/react/api/components/relativetime.mdx
---
title: RelativeTime
description: RelativeTime 组件的 API 参考
---

{/* 自动生成：请勿直接编辑。请改为编辑 content/docs-templates/ 中的 template。 */}


## 概述

`<RelativeTime>` 组件会渲染本地化的相对时间字符串，例如 &quot;2 小时前&quot; 或 &quot;3 天后&quot;。
它支持两种用法：根据 `Date` 自动选择最佳时间单位，或显式指定值和时间单位。

```jsx
<RelativeTime>{someDate}</RelativeTime>
// 输出："2小时前"
```

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

<Callout type="warn">
  `<RelativeTime>` 可能会在采用服务器端渲染的应用中导致 **React hydration 错误**。请参阅下方的[避免 hydration 错误](#avoiding-hydration-errors)。
</Callout>


## 参考

### 属性

<TypeTable
  type={{
  "children?": {
      description: '用于计算相对时间的 Date 对象。',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "date?": {
      description: '用于计算相对时间的 Date 对象。优先于 children。',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "value?": {
      description: '相对时间的显式数值。使用时需要提供 unit。',
      type: 'number',
      optional: true,
      default: 'undefined',
  },
  "unit?": {
      description: '时间单位。使用 value 时必填。',
      type: 'Intl.RelativeTimeFormatUnit',
      optional: true,
      default: 'undefined',
  },
  "baseDate?": {
      description: '用于计算相对时间的基准日期。默认值为渲染时的 new Date()。',
      type: 'Date',
      optional: true,
      default: 'new Date()',
  },
  "name?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
  "options?": {
      type: 'Intl.RelativeTimeFormatOptions',
      optional: true,
      default: "{ numeric: 'auto', style: 'long' }",
  },
  "locales?": {
      type: 'string[]',
      optional: true,
      default: 'undefined',
  },
}}
/>

### 说明

| Prop Name  | 说明                                                                                                                                                                                                   |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | 一个 `Date` 对象。组件会自动选择最合适的时间单位 (秒、分钟、小时、天、周、月或年) ，并基于 `baseDate` 将时间格式化为相对时间。                                                                                                                          |
| `date`     | 用于计算相对时间的 `Date` 对象。如果同时提供 `date` 和 `children`，则优先使用 `date`。                                                                                                                                         |
| `value`    | 相对时间的显式数值 (例如，`-1` 表示“昨天”) 。必须与 `unit` 一起使用。                                                                                                                                                         |
| `unit`     | 时间单位 (例如 `'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'`、`'year'`) 。使用 `value` 时必填。                                                                                                        |
| `baseDate` | 用于计算相对时间的基准日期。默认为渲染时的 `new Date()`。**请显式设置此项以避免 hydration 错误**——参见[下文](#avoiding-hydration-errors)。                                                                                                  |
| `options`  | 可选的格式化选项，遵循 [`Intl.RelativeTimeFormatOptions` 规范](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)。默认为 `numeric: 'auto'` 和 `style: 'long'`。 |
| `locales`  | 可选的 `locales`，用于指定格式化时使用的区域设置。如果未提供，则使用用户的区域设置。有关如何指定 `locales` 的更多信息，请参见[此处](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。               |

### 返回值

返回一个 `JSX.Element`，其中包含以字符串形式表示的格式化相对时间；如果未提供日期或值，则返回 `null`。

***

## 示例

### 根据 Date 自动选择时间单位

将 `Date` 作为子元素传入，组件会自动选择最合适的时间单位。

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

export default function PostTimestamp({ post }) {
    return (
        <RelativeTime>{post.createdAt}</RelativeTime> // [!code highlight]
    );
    // 输出："2 小时前"、"3 天前"、"5 分钟后"等。
}
```


### 使用 `date` prop

你也可以通过 `date` prop 传入日期，而不通过 `children` 传递。

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

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


### 显式指定值和时间单位

指定精确的数值和时间单位，与 `Intl.RelativeTimeFormat` API 一致。

```jsx title="Reminder.jsx" copy
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."
}
```


### 指定区域设置

按特定区域设置显示相对时间。

```jsx title="FrenchTimestamp.jsx" copy
import { RelativeTime } from 'gt-react';

export default function FrenchTimestamp({ date }) {
    return (
        <RelativeTime locales={['fr-FR']}>{date}</RelativeTime> // [!code highlight]
    );
    // 输出："il y a 2 heures"
}
```


### 翻译 RelativeTime

将 `<RelativeTime>` 包装在 `<T>` 组件中，以便将其纳入翻译后的句子中。

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

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


### 自定义格式化选项

通过 `Intl.RelativeTimeFormat` 选项控制输出格式。

```jsx title="NumericTimestamp.jsx" copy
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 错误

由于 `<RelativeTime>` 会在本地计算相对时间，因此它在**服务器和客户端上的输出**可能不同。当 React 比较服务器端渲染的 HTML 与客户端渲染结果时，如果两者不一致，就会出现 hydration 错误。

这种情况通常发生在以下场景中：

* **`baseDate` 默认在渲染时使用 `new Date()`。** 服务器会在某一时刻完成渲染，而客户端会在几秒后 (甚至更久) 才开始 hydration。如果相对时间在这两个时刻之间跨过了某个时间单位的边界 (例如，“59 秒前” → “1 分钟前”) ，输出就会不一致。
* **不同环境中的默认区域设置不一致。** 如果服务器的默认区域设置与客户端不一致，格式化后的字符串可能会不同 (例如，&quot;hace 2 horas&quot; 与 &quot;2 hours ago&quot;) 。

### 如何解决

**显式设置 `baseDate`**，以确保服务器和客户端计算出相同的相对时间：

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

<RelativeTime baseDate={now}>{post.createdAt}</RelativeTime>
```

**显式指定 `locales`**，以避免区域设置不匹配：

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

将区域设置和基准日期都固定后，服务器和客户端始终会生成相同的格式化字符串。


## 备注

* `<RelativeTime>` 组件是一个变量组件，用于格式化相对时间值。
* 使用自动模式 (传入 `Date`) 时，组件会自动选择最合适的时间单位。
* 该组件底层基于 [`Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat)。
* 默认格式化选项为 `numeric: 'auto'` 和 `style: 'long'`。

## 后续步骤

* 有关 `<RelativeTime>` 组件以及 `<DateTime>`、`<Currency>`、`<Num>` 和 `<Var>` 等其他变量组件的更多详情和使用示例，请参阅[使用变量组件](/docs/react/guides/variables)文档。