# react-native: DateTime
URL: https://generaltranslation.com/zh/docs/react-native/api/components/datetime.mdx
---
title: DateTime
description: DateTime 组件的 API 参考文档
---

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


## 概述

`<DateTime>` 组件会渲染格式化后的日期或时间字符串，并支持通过格式化选项、区域设置等进行自定义。
日期或时间会根据当前区域设置及传入的可选参数进行格式化。

```jsx
<DateTime>{1738010355}</DateTime>
// 输出：1/27/2025
```

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

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

## 参考

### 属性

<TypeTable
  type={{
  "children?": {
      description: '要格式化的日期内容。',
      type: 'any',
      optional: true,
      default: 'undefined',
  },
  "name?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
  "value?": {
      type: 'string | number | Date',
      optional: true,
      default: 'undefined',
  },
  "options?": {
      type: 'Intl.DateTimeFormatOptions',
      optional: true,
      default: '{}',
  },
  "locales?": {
      type: 'string[]',
      optional: true,
      default: 'undefined',
  },
}}
/>

### 说明

| 属性名        | 说明                                                                                                                                                                                        |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | 在组件内部渲染的内容，通常是日期或时间值。若提供此属性，其优先级高于 `value` 属性。                                                                                                                                            |
| `value`    | 日期或时间的默认值。可以是字符串、数字 (时间戳) 或 Date 对象。                                                                                                                                                      |
| `options`  | 可选的日期或时间格式化选项，遵循 [`Intl.DateTimeFormatOptions` specification](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 规范。可用来定义星期名称、时区等格式样式。 |
| `locales`  | 可选的 `locales`，用于指定格式化时使用的区域设置。若未提供，则使用用户的区域设置。有关如何指定 `locales` 的更多信息，请参阅[这里](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。     |

### 返回值

一个包含格式化后的日期或时间字符串的 `JSX.Element`。

***

## 示例

### 基本用法

`<DateTime>` 组件可用于显示本地化的日期或时间。

```jsx title="EventDate.jsx" copy
import { DateTime } from 'gt-react-native';

export default function EventDate(event) {
    return (
        <DateTime> {event.date} </DateTime>. // [!code highlight]
    );
}
```


### 指定区域设置

`<DateTime>` 组件可用于按特定区域设置显示日期或时间值。

```jsx title="EventDate.jsx" copy

import { DateTime } from 'gt-react-native';

export default function EventDate(event) {
    return (
        <DateTime locales={['fr-FR']}> {event.date} </DateTime>. // [!code highlight]
    );
}
```


### 翻译 DateTime

假设你想在一个同样需要翻译的句子中显示日期和时间。
你可以将 `<DateTime>` 组件包裹在 `<T>` 组件内。

```jsx title="EventDate.jsx" copy
import { T, DateTime } from 'gt-react-native';

export default function EventDate(event) {
    return (
        <T id="eventDate">
            The time of the event is <DateTime> {event.date} </DateTime>. // [!code highlight]
        </T>
    );
}
```


### 自定义格式

`<DateTime>` 组件支持自定义格式选项。

```jsx title="EventDate.jsx" copy
import { DateTime } from 'gt-react-native';

export default function EventDate(event) {
    return (
        <DateTime options={{
            dateStyle: 'full', // [!code highlight]
            timeStyle: 'long', // [!code highlight]
            timeZone: 'Australia/Sydney', // [!code highlight]
        }}>
            {event.date}
        </DateTime>.
    );
}
```

***


## 避免 hydration 错误

由于 `<DateTime>` 使用 `Intl.DateTimeFormat` 在本地对日期进行格式化，因此它可能会在**服务器和客户端产生不同的输出**。当 React 比较服务器端渲染的 HTML 与客户端 render 的结果，而两者又不一致时，就会出现 hydration 错误。

这通常发生在以下情况：

* **未显式设置 `timeZone`。** 服务器可能运行在 UTC (或其他时区) ，而用户的浏览器使用的是本地时区。像 `1738010355` 这样的时间戳，如果时区不同，在服务器上可能会 render 为 `"1/27/2025"`，而在客户端上则会 render 为 `"1/28/2025"`。
* **不同环境的默认区域设置不一致。** 如果服务器的默认区域设置与客户端不一致，格式化后的字符串可能会不同 (例如 `"27/01/2025"` 与 `"1/27/2025"`) 。

### 如何解决

**在 `options` 中显式设置 `timeZone`**，以确保输出保持一致：

```jsx
<DateTime options={{ timeZone: 'America/New_York' }}>
  {event.date}
</DateTime>
```

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

```jsx
<DateTime locales={['en-US']} options={{ timeZone: 'UTC' }}>
  {event.date}
</DateTime>
```

通过同时固定区域设置和时区，服务器和客户端将始终生成相同的格式化后字符串。


## 注意事项

* `<DateTime>` 组件是一个变量组件，可用于格式化日期和时间。
* 该组件使用 [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 来进行格式化。

## 后续步骤

* 如需了解有关 `<DateTime>` 组件以及其他变量组件 (如 `<Currency>`、`<Num>` 和 `<Var>`) 的更多信息和使用示例，请参阅[使用变量组件](/docs/react-native/guides/variables)文档。