# General Translation Platform: formatDateTime
URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-date-time.mdx
---

title: formatDateTime
description: 无需 GT 实例即可格式化日期和时间。formatDateTime 的 API 参考。

---

[`formatDateTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-date-time) 是 General Translation 的 Core 库提供的独立实用函数，可根据区域设置的惯例格式化日期和时间。它会为 `Date` 返回一个符合区域设置的字符串。

## 概览 [#overview]

直接从 `generaltranslation` 导入 `formatDateTime`，然后传入一个 `Date` 对象和一个选项对象进行调用。它不需要 API 密钥，也不需要 [GT](/docs/platform/core/reference/gt-class/constructor) 实例。若要使用会继承实例区域设置的实例格式化方式，请改用 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上的 [`formatDateTime`](/docs/platform/core/reference/gt-class-methods/formatting/format-date-time) 方法。

```typescript
import { formatDateTime } from 'generaltranslation';

const formatted = formatDateTime(new Date(), {
  locales: 'de-DE',
  dateStyle: 'medium',
  timeStyle: 'short',
});
// 返回按区域设置格式化的字符串，例如 "26.09.2025, 17:33"
```

签名：

```typescript
formatDateTime(
  date: Date,
  options?: { locales?: string | string[] } & Intl.DateTimeFormatOptions
): string
```

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

* **底层 API。** 使用与 GT 类方法相同的 [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)，因此支持所有标准的 `Intl.DateTimeFormat` 选项。
* **区域设置解析。** 当 `locales` 为数组时，会按顺序依次尝试各个区域设置。省略 `locales` 时，则回退到库的默认区域设置 `en`。
* **时区。** 提供 `timeZone` 选项时，输出会遵循该选项；否则将使用运行时的本地时区。不同区域设置的默认日期/时间格式，以及 12 小时制或 24 小时制偏好，可能各不相同。
* **缓存。** 为了提升重复使用相同区域设置和选项组合时的性能，结果会在内部缓存。

## 参数 [#parameters]

| 参数                    | 描述                                          | Type                                                            | 可选 | 默认值  |
| --------------------- | ------------------------------------------- | --------------------------------------------------------------- | -- | ---- |
| [`date`](#date)       | 要格式化的日期对象。                                  | `Date`                                                          | 否  | —    |
| [`options`](#options) | 格式化配置，包括目标区域设置和任意 `Intl.DateTimeFormat` 选项。 | `{ locales?: string \| string[] } & Intl.DateTimeFormatOptions` | 是  | `{}` |

### `date` [#date]

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

要进行格式化的 `Date` 对象。

### `options` [#options]

**类型** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **可选** · **默认值** `{}`

格式化配置。除了 `locales` 之外，还支持 [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 的任意选项。常见字段：

| 属性          | 描述                        | 类型                                                        | 可选 | 默认值  |
| ----------- | ------------------------- | --------------------------------------------------------- | -- | ---- |
| `locales`   | 用于格式化的区域设置。传入数组时会按顺序依次尝试。 | `string \| string[]`                                      | 是  | `en` |
| `dateStyle` | 整体日期格式样式。                 | `'full' \| 'long' \| 'medium' \| 'short'`                 | 是  | —    |
| `timeStyle` | 整体时间格式样式。                 | `'full' \| 'long' \| 'medium' \| 'short'`                 | 是  | —    |
| `weekday`   | 星期的表示方式。                  | `'long' \| 'short' \| 'narrow'`                           | 是  | —    |
| `year`      | 年份的表示方式。                  | `'numeric' \| '2-digit'`                                  | 是  | —    |
| `month`     | 月份的表示方式。                  | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | 是  | —    |
| `day`       | 日期的表示方式。                  | `'numeric' \| '2-digit'`                                  | 是  | —    |
| `hour`      | 小时的表示方式。                  | `'numeric' \| '2-digit'`                                  | 是  | —    |
| `minute`    | 分钟的表示方式。                  | `'numeric' \| '2-digit'`                                  | 是  | —    |
| `second`    | 秒的表示方式。                   | `'numeric' \| '2-digit'`                                  | 是  | —    |
| `timeZone`  | IANA 时区标识符。               | `string`                                                  | 是  | —    |
| `hour12`    | 是否使用 12 小时制。              | `boolean`                                                 | 是  | —    |

## 返回值 [#returns]

**类型** `string`

按照区域设置约定格式化后的日期和时间。

## 示例 [#examples]

```typescript
import { formatDateTime } from 'generaltranslation';

const date = new Date('2024-03-14T14:30:45Z');

// 使用显式区域设置进行基本格式化
console.log(formatDateTime(date, { locales: 'en-US', timeZone: 'UTC' }));
// 输出："3/14/2024"

// 德语格式化
console.log(formatDateTime(date, { locales: 'de-DE', timeZone: 'UTC' }));
// 输出："14.3.2024"

// 多个区域设置回退
console.log(formatDateTime(date, { locales: ['ja-JP', 'en-US'], timeZone: 'UTC' }));
// 输出："2024/3/14"（日语格式）
```

```typescript
// 日期和时间样式
const date = new Date('2024-03-14T14:30:45Z');

// 完整日期样式
console.log(formatDateTime(date, {
  locales: 'en-US',
  dateStyle: 'full',
  timeZone: 'UTC',
}));
// 输出："Thursday, March 14, 2024"

// 长日期与短时间
console.log(formatDateTime(date, {
  locales: 'fr-FR',
  dateStyle: 'long',
  timeStyle: 'short',
  timeZone: 'UTC',
}));
// 输出："14 mars 2024 à 14:30"
```

```typescript
// 时区处理
const date = new Date('2024-03-14T14:30:45Z');

const timeZones = ['America/New_York', 'Europe/London', 'Asia/Tokyo'];

timeZones.forEach((timeZone) => {
  const formatted = formatDateTime(date, {
    locales: 'en-US',
    timeZone,
    dateStyle: 'medium',
    timeStyle: 'medium',
  });
  console.log(`${timeZone}: ${formatted}`);
});
// 输出结果因夏令时而异
```

## 注意事项 [#notes]

* 底层使用与 GT 类方法相同的 `Intl.DateTimeFormat`。
* 为了在重复使用相同区域设置/选项组合时提升性能，结果会在内部缓存。
* 支持所有标准的 `Intl.DateTimeFormat` 选项。
* 指定时区时，会正确处理时区。若未固定 `timeZone`，输出结果取决于运行时环境。