# generaltranslation: General Translation Core SDK: formatDateTime
URL: https://generaltranslation.com/zh/docs/core/class/methods/formatting/format-date-time.mdx
---
title: formatDateTime
description: 用于按区域设置惯例格式化日期和时间的 formatDateTime 方法 API 参考
---

## 概述

`formatDateTime` 方法使用 Internationalization API 按区域设置的惯例来格式化日期和时间。
它会根据目标区域设置自动处理日期格式、时间格式、日历和时区。

```typescript
const gt = new GT({ targetLocale: 'de-DE' });

const formatted = gt.formatDateTime(new Date(), {
  dateStyle: 'medium',
  timeStyle: 'short'
});
// 返回："25.09.2025, 18:06"（德语日期/时间格式）
```


## 参考

### 参数

| 名称         | 类型                      | 描述        |
| ---------- | ----------------------- | --------- |
| `date`     | `Date`                  | 要格式化的日期对象 |
| `options?` | `DateTimeFormatOptions` | 可选的格式设置   |

### DateTimeFormatOptions

在 `Intl.DateTimeFormatOptions` 的基础上扩展了额外的区域设置选项：

| 名称                        | 类型                                                                                      | 描述                                   |
| ------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------ |
| `locales?`                | `string \| string[]`                                                                    | 覆盖格式化时使用的 locales (默认使用实例的 locales)  |
| `localeMatcher?`          | `'lookup' \| 'best fit'`                                                                | 区域设置匹配算法 (默认值：`'best fit'`)          |
| `dateStyle?`              | `'full' \| 'long' \| 'medium' \| 'short'`                                               | 整体日期格式样式                             |
| `timeStyle?`              | `'full' \| 'long' \| 'medium' \| 'short'`                                               | 整体时间格式样式                             |
| `weekday?`                | `'long' \| 'short' \| 'narrow'`                                                         | 星期的表示形式                              |
| `era?`                    | `'long' \| 'short' \| 'narrow'`                                                         | 纪元的表示形式                              |
| `year?`                   | `'numeric' \| '2-digit'`                                                                | 年份的表示形式                              |
| `month?`                  | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'`                               | 月份的表示形式                              |
| `day?`                    | `'numeric' \| '2-digit'`                                                                | 日期的表示形式                              |
| `dayPeriod?`              | `'narrow' \| 'short' \| 'long'`                                                         | 时段格式 (如上午、下午等)                       |
| `hour?`                   | `'numeric' \| '2-digit'`                                                                | 小时的表示形式                              |
| `minute?`                 | `'numeric' \| '2-digit'`                                                                | 分钟的表示形式                              |
| `second?`                 | `'numeric' \| '2-digit'`                                                                | 秒的表示形式                               |
| `fractionalSecondDigits?` | `1 \| 2 \| 3`                                                                           | 秒的小数位数                               |
| `timeZoneName?`           | `'long' \| 'short' \| 'longOffset' \| 'shortOffset' \| 'longGeneric' \| 'shortGeneric'` | 时区名称格式                               |
| `timeZone?`               | `string`                                                                                | IANA 时区标识符                           |
| `hour12?`                 | `boolean`                                                                               | 是否使用 12 小时制                          |
| `hourCycle?`              | `'h11' \| 'h12' \| 'h23' \| 'h24'`                                                      | 小时周期偏好                               |
| `calendar?`               | `string`                                                                                | 要使用的日历系统                             |
| `numberingSystem?`        | `string`                                                                                | 数字使用的编号系统                            |
| `formatMatcher?`          | `'basic' \| 'best fit'`                                                                 | 格式匹配算法 (默认值：`'best fit'`)            |

### 返回值

`string` - 按区域设置惯例格式化的日期和时间。

***

## 示例

### 日期和时间的基本格式化

```typescript copy
import { GT } from 'generaltranslation';

const gt = new GT({ targetLocale: 'en-US' });
const date = new Date('2024-03-14T14:30:45Z');

// 基本日期格式化（使用默认选项）
console.log(gt.formatDateTime(date));
// Output: "3/14/2024"

// 德语区域设置格式化
console.log(gt.formatDateTime(date, { locales: 'de-DE' }));
// Output: "14.3.2024"

// 日语区域设置格式化
console.log(gt.formatDateTime(date, { locales: 'ja-JP' }));
// Output: "2024/3/14"
```


### 日期和时间样式

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

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

// 长日期加短时间
console.log(gt.formatDateTime(date, {
  dateStyle: 'long',
  timeStyle: 'short'
}));
// 输出："March 14, 2024 at 7:30 AM"

// 自定义日期组件
console.log(gt.formatDateTime(date, {
  weekday: 'long',
  year: 'numeric',
  month: 'long',
  day: 'numeric'
}));
// 输出："Thursday, March 14, 2024"
```


### 时区和小时制格式

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

// 强制使用12小时制
console.log(gt.formatDateTime(date, {
  hour: 'numeric',
  minute: '2-digit',
  hour12: true
}));
// 输出："7:30 AM"

// 强制使用24小时制
console.log(gt.formatDateTime(date, {
  hour: 'numeric',
  minute: '2-digit',
  hour12: false
}));
// 输出："07:30"

// 指定时区
console.log(gt.formatDateTime(date, {
  timeZone: 'America/New_York',
  dateStyle: 'medium',
  timeStyle: 'short'
}));
// 输出："Mar 14, 2024, 10:30 AM"
```

***


## 注意事项

* 日期格式会自动遵循对应区域设置的惯例
* 该方法使用浏览器原生的 `Intl.DateTimeFormat`，以获得最佳性能和准确性
* 指定时区时，可正确处理时区

## 相关方法

* 更多选项请参阅 [`Intl.DateTimeFormat` 文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)
* 如需了解带日期插值的消息格式化，请参阅 [`formatMessage`](/docs/core/class/methods/formatting/format-message)
* 如需在不创建 GT 实例的情况下使用，请参阅独立的 [`formatDateTime`](/docs/core/functions/formatting/format-date-time)
* 如需了解区域设置特定的日历信息，请参阅 [`getLocaleProperties`](/docs/core/class/methods/locales/get-locale-properties)

## 后续步骤