# General Translation React SDKs (gt-react, gt-next, gt-react-native): `<DateTime>`
URL: https://generaltranslation.com/zh/docs/react/reference/components/datetime.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 按当前区域设置格式化日期和时间。`<DateTime>` 组件的 API 参考。

`<DateTime>` 组件会将 `Date` 值显示为本地化日期、时间或两者兼有。它支持自定义格式化方式的选项和区域设置覆盖。

*可用于 `gt-react`、`gt-next`、`gt-tanstack-start` 和 `gt-react-native`。*

## 概览 [#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` · **可选** · **默认值** `{}`

该 prop 接受 [`Intl.DateTimeFormatOptions`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options)。常用选项包括：

| 选项                       | 描述                                       | 类型                                                                                      | 可选 | 默认值                    |
| ------------------------ | ---------------------------------------- | --------------------------------------------------------------------------------------- | -- | ---------------------- |
| `localeMatcher`          | 区域设置匹配算法。                                | `'lookup' \| 'best fit'`                                                                | 是  | `'best fit'`           |
| `calendar`               | 日历系统，例如 `gregory`、`chinese` 或 `persian`。 | `string`                                                                                | 是  | `'gregory'`            |
| `numberingSystem`        | 数字系统，例如 `latn` 或 `arab`。                 | `string`                                                                                | 是  | `'latn'`               |
| `hour12`                 | 是否使用 12 小时制。覆盖 `hourCycle`。              | `boolean`                                                                               | 是  | 取决于区域设置                |
| `hourCycle`              | 时钟使用的小时制。                                | `'h11' \| 'h12' \| 'h23' \| 'h24'`                                                      | 是  | 取决于区域设置                |
| `timeZone`               | IANA 时区或 UTC 偏移量。                        | `string`                                                                                | 是  | 运行时时区                  |
| `weekday`                | 星期名称的显示长度。                               | `'long' \| 'short' \| 'narrow'`                                                         | 是  | —                      |
| `era`                    | 纪元标签的显示长度。                               | `'long' \| 'short' \| 'narrow'`                                                         | 是  | —                      |
| `year`                   | 数字或两位数年份。                                | `'numeric' \| '2-digit'`                                                                | 是  | 未设置样式或组件时为 `'numeric'` |
| `month`                  | 数字或名称形式的月份。                              | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'`                               | 是  | 未设置样式或组件时为 `'numeric'` |
| `day`                    | 数字或两位数日期。                                | `'numeric' \| '2-digit'`                                                                | 是  | 未设置样式或组件时为 `'numeric'` |
| `dayPeriod`              | “上午”或“夜间”等标签的显示长度。                       | `'long' \| 'short' \| 'narrow'`                                                         | 是  | —                      |
| `hour`                   | 数字或两位数小时。                                | `'numeric' \| '2-digit'`                                                                | 是  | —                      |
| `minute`                 | 数字或两位数分钟。                                | `'numeric' \| '2-digit'`                                                                | 是  | —                      |
| `second`                 | 数字或两位数秒。                                 | `'numeric' \| '2-digit'`                                                                | 是  | —                      |
| `fractionalSecondDigits` | 秒的小数位数。                                  | `1 \| 2 \| 3`                                                                           | 是  | —                      |
| `timeZoneName`           | 时区标签的显示长度和样式。                            | `'long' \| 'short' \| 'shortOffset' \| 'longOffset' \| 'shortGeneric' \| 'longGeneric'` | 是  | —                      |
| `formatMatcher`          | 将组件选项与区域设置格式进行匹配的算法。                     | `'basic' \| 'best fit'`                                                                 | 是  | `'best fit'`           |
| `dateStyle`              | 预设日期格式。                                  | `'full' \| 'long' \| 'medium' \| 'short'`                                               | 是  | —                      |
| `timeStyle`              | 预设时间格式。                                  | `'full' \| 'long' \| 'medium' \| 'short'`                                               | 是  | —                      |

* `dateStyle` 和 `timeStyle` 可以同时使用，但不能与 `weekday`、`year`、`month`、`day`、`hour`、`minute` 或 `second` 等组件选项一起使用。
* `hour12` 覆盖 `hourCycle`。
* `dayPeriod` 仅影响 12 小时制格式。
* 支持的日历、数字系统、时区标签和选项值取决于 JavaScript 运行时。

有关最新可用选项和运行时行为，请参阅 [`Intl.DateTimeFormat` 选项文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options)。

### `locales` [#locales]

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

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

### `name` [#name]

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

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

## 示例 [#examples]

*示例中从 `gt-react` 导入；请改为从你的框架 package 导入。*

```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>
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.