# react-native: RelativeTime
URL: https://generaltranslation.com/zh/docs/react-native/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 对象。其优先级高于子元素。',
      type: 'Date',
      optional: true,
      default: 'undefined',
  },
  "value?": {
      description: '相对时间的显式数值。需要指定时间单位。',
      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-react-native';

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

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

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

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

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

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 与客户端 render 的结果时，如果两者不一致，就会出现 hydration 错误。

这通常发生在以下情况：

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

### 如何解决

**显式设置 `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-native/guides/variables)文档。