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

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


## 概述

`<RelativeTime>` 组件用于渲染本地化的相对时间字符串，例如“2 小时前”或“3 天后”。
它支持两种用法：根据 `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 名称    | 说明                                                                                                                                                                                                   |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | 一个 `Date` 对象。组件会自动选择最合适的时间单位 (秒、分钟、小时、天、周、月或年) ，并基于 `baseDate` 对时间进行相对格式化。                                                                                                                           |
| `date`     | 用于计算相对时间的 `Date` 对象。如果同时提供了 `date` 和 `children`，则优先使用 `date`。                                                                                                                                        |
| `value`    | 相对时间的显式数值 (例如，`-1` 表示“昨天”) 。必须与 `unit` 一起使用。                                                                                                                                                         |
| `unit`     | 时间单位 (例如，`'second'`、`'minute'`、`'hour'`、`'day'`、`'week'`、`'month'`、`'year'`) 。使用 `value` 时为必填。                                                                                                       |
| `baseDate` | 用于计算相对时间的基准日期。默认为 render 时的 `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-next';

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-next';

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


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

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

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

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-next';

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-next';

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-next';

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/next/guides/variables)。