# General Translation React SDKs (gt-react, gt-next): DateTime
URL: https://generaltranslation.com/zh/docs/react/reference/components/datetime.mdx
---

title: DateTime
description: 使用 General Translation gt-react 按当前区域设置格式化日期和时间。DateTime 的 API 参考。

---

`<DateTime>` 组件会渲染按当前区域设置格式化的日期或时间。它支持自定义格式选项和区域设置覆盖。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。示例从 `gt-react` 导入；请改为从你的框架对应的包中导入。*

## 概览 [#overview]

将 `Date` 作为子元素传入后，`<DateTime>` 会按当前区域设置将其格式化。

```tsx
<DateTime>{new Date(1738010355000)}</DateTime>
// 输出：1/27/2025
```

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

*注意：在服务器端渲染应用中，`<DateTime>` 可能会导致 React hydration 错误。请参阅[避免 hydration 错误](#hydration)。*

## 工作原理 [#how-it-works]

* **本地格式化。** 日期会在浏览器中使用 `Intl.DateTimeFormat` 进行格式化，其值绝不会发送到 General Translation API。
* **区域设置解析。** 除非用 `locales` 覆盖，否则会由当前生效的区域设置决定格式化方式。
* **时区很重要。** 如果未显式指定 `timeZone`，输出结果将取决于运行时所在的时区，而服务器与客户端的时区可能不一致。

## 属性 [#props]

| 属性                      | 描述                        | 类型                           | 可选 | 默认值    |
| ----------------------- | ------------------------- | ---------------------------- | -- | ------ |
| [`children`](#children) | 要格式化的日期。                  | `Date`                       | 否  | —      |
| [`options`](#options)   | `Intl.DateTimeFormat` 选项。 | `Intl.DateTimeFormatOptions` | 是  | `{}`   |
| [`locales`](#locales)   | 用于格式化的区域设置，会覆盖当前设置。       | `string[]`                   | 是  | 当前区域设置 |
| [`name`](#name)         | 条目的变量名。                   | `string`                     | 是  | —      |

### `children` [#children]

**类型** `Date` · **必填**

要格式化的日期或时间，需为 `Date` 对象。

### `options` [#options]

**类型** `Intl.DateTimeFormatOptions` · **可选** · **默认值** `{}`

用于设置格式化方式的选项，遵循 [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 规范，例如 `dateStyle`、`timeStyle` 和 `timeZone`。

### `locales` [#locales]

**类型** `string[]` · **可选** · **默认** 当前区域设置

用于格式化的区域设置。省略时，使用当前区域设置。参见 [locales 参数](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument)。

### `name` [#name]

**类型** `string` · **可选**

日期字段的可选名称，用作元数据。

## 示例 [#examples]

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

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

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

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

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

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

```tsx title="EventDate.tsx"
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 错误 [#hydration]

由于 `<DateTime>` 会按本地方式格式化日期，因此在服务器端和客户端上可能产生不同的输出。当 React 比较服务器端渲染的 HTML 与客户端渲染结果时，如果两者不一致，就会出现 hydration 错误。通常发生在以下情况：

* **未显式设置 `timeZone`。** 服务器可能运行在 UTC，而浏览器使用本地时间，因此同一个时间戳在服务器端可能会渲染为 `"1/27/2025"`，而在客户端则渲染为 `"1/28/2025"`。
* **不同环境的默认区域设置不同。** 默认区域设置不一致会产生不同的字符串 (例如，`"27/01/2025"` 与 `"1/27/2025"`) 。

请同时固定区域设置和时区，这样服务器端和客户端始终会生成相同的字符串：

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