# gt-next: General Translation Next.js SDK: DateTime
URL: https://generaltranslation.com/zh/docs/next/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-next';

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


### 指定locales

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

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

import { DateTime } from 'gt-next';

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

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

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/next/guides/variables) 文档。