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

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


## 概述

`<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',
  },
}}
/>

### 说明

| Prop Name  | Description                                                                                                                                                                        |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | 在组件内部渲染的内容，通常为日期或时间值。如果提供该值，则其优先级高于 `value` prop。                                                                                                                                  |
| `value`    | 日期或时间的默认值。可以是字符串、数字 (时间戳) 或 Date 对象。                                                                                                                                               |
| `options`  | 可选的日期或时间格式化选项，遵循 [`Intl.DateTimeFormatOptions` 规范](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';

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


### 指定区域设置

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

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

import { DateTime } from 'gt-react';

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

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

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

这通常发生在以下情况：

* **未显式设置 `timeZone`。** 服务端可能运行在 UTC (或其他时区) ，而用户的浏览器使用的是本地时区。像 `1738010355` 这样的时间戳，如果时区不同，可能会在服务端渲染为 `"1/27/2025"`，但在客户端渲染为 `"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/guides/variables)文档。