# generaltranslation: General Translation Core SDK: formatDateTime
URL: https://generaltranslation.com/zh/docs/core/functions/formatting/format-date-time.mdx
---
title: formatDateTime
description: 用于按区域设置约定格式化日期和时间的独立函数
---

## 概述

独立的 `formatDateTime` 函数可按照特定区域设置的惯例格式化日期和时间，无需 GT 实例。
它与 GT 类方法提供相同的功能，但也可单独使用。

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

const formatted = formatDateTime(new Date(), {
  locales: 'de-DE',
  dateStyle: 'medium',
  timeStyle: 'short'
});
// 返回："26.09.2025, 17:33"
```


## 参考

### 参数

| 名称        | 类型                                                         | 描述                 |
| --------- | ---------------------------------------------------------- | ------------------ |
| `date`    | `Date`                                                     | 要格式化的日期对象          |
| `options` | `DateTimeFormatOptions & { locales?: string \| string[] }` | 格式化配置，可选指定 locales |

### DateTimeFormatOptions

| 名称           | 类型                                                        | 描述                      |
| ------------ | --------------------------------------------------------- | ----------------------- |
| `locales?`   | `string \| string[]`                                      | 用于格式化的区域设置 (默认为系统区域设置)  |
| `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?`  | `string`                                                  | IANA 时区标识符              |
| `hour12?`    | `boolean`                                                 | 是否使用 12 小时制时间格式         |

### 返回值

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

***

## 示例

### 基本用法

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

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

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

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


### 日期和时间样式

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

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

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

// 各区域设置的短格式
const locales = ['en-US', 'de-DE', 'ja-JP'];
locales.forEach(locale => {
  console.log(`${locale}: ${formatDateTime(date, {
    locales: locale,
    dateStyle: 'short',
    timeStyle: 'short'
  })}`);
});
// 输出：
// en-US: 3/14/24, 7:30 AM
// de-DE: 14.03.24, 07:30
// ja-JP: 2024/03/14 7:30
```


### 时区处理

```typescript copy
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}`);
});
// 输出结果因夏令时而异
```

***


## 备注

* `locales` 参数是可选的；如果未提供，则默认使用系统区域设置
* 使用与 GT 类方法相同的底层 `Intl.DateTimeFormat`
* 为提升重复使用相同区域设置/选项组合时的性能，结果会在内部缓存
* 支持所有标准 `Intl.DateTimeFormat` 选项
* 指定时区时会正确处理
* 不同区域设置的默认日期/时间格式，以及对 12 小时制或 24 小时制的偏好，可能有所不同

## 后续步骤

* 查看 [`Intl.DateTimeFormat` 文档](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 以了解更多选项
* 独立进行数字格式化时，请参阅 [`formatNum`](/docs/core/functions/formatting/format-num)
* 独立进行消息格式化时，请参阅 [`formatMessage`](/docs/core/functions/formatting/format-message)
* 如需了解基于实例的用法，请参阅 GT 类的 [`formatDateTime`](/docs/core/class/methods/formatting/format-date-time)