# General Translation Platform: formatDateTime URL: https://generaltranslation.com/zh/docs/platform/core/reference/gt-class-methods/formatting/format-date-time.mdx --- title: formatDateTime description: 按区域设置格式化日期和时间。formatDateTime 的 API 参考。 --- 在 [GT](/docs/platform/core/reference/gt-class/constructor) 实例上，根据区域设置的惯例格式化日期和时间。General Translation 使用内置的 `Intl.DateTimeFormat` API，自动处理目标区域设置的日期格式、时间格式、日历和时区。 ## 概览 [#overview] 在 [`GT`](/docs/platform/core/reference/gt-class/constructor) 实例上调用 `formatDateTime`，传入一个 `Date` 和可选的选项对象。该方法会返回格式化后的日期和时间字符串。 ```typescript const gt = new GT({ targetLocale: 'de-DE' }); const formatted = gt.formatDateTime(new Date(), { dateStyle: 'medium', timeStyle: 'short', }); // "25.09.2025, 18:06"（德语日期/时间格式） ``` 签名： ```typescript formatDateTime( date: Date, options?: { locales?: string | string[] } & Intl.DateTimeFormatOptions ): string ``` *注意：`formatDateTime` 基于 `Intl.DateTimeFormat` 在本地运行，无需 API Key。默认会使用该实例的渲染区域设置；传入 `locales` 可覆盖默认设置。若要在没有 `GT` 实例的情况下进行格式化，请参阅独立使用的 [`formatDateTime`](/docs/platform/core/reference/utility-functions/formatting/format-date-time)。* ## 工作原理 [#how-it-works] * **区域设置解析。** 默认情况下，此方法会根据实例的 locales 进行格式化。你可以在选项中传入 `locales`，仅覆盖这一次调用的设置。 * **由 Intl 提供支持。** 格式化由浏览器原生的 [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat) 处理，因此支持所有标准的 `Intl.DateTimeFormatOptions`。 * **时区。** 指定 `timeZone` 时，会正确处理时区；否则将使用运行时的本地时区。 ## 参数 [#parameters] | 参数 | 描述 | Type | 可选 | 默认值 | | --------------------- | --------------------------------------------------------- | -------- | -- | --- | | [`date`](#date) | 要格式化的日期对象。 | `Date` | 否 | — | | [`options`](#options) | 格式化配置，基于 `Intl.DateTimeFormatOptions` 扩展，并支持覆盖 `locales`。 | `object` | 是 | — | ### `date` [#date] **类型** `Date` · **必填** 要进行格式化的 `Date` 对象。 ### `options` [#options] **类型** `{ locales?: string | string[] } & Intl.DateTimeFormatOptions` · **可选** 格式化配置。在 `Intl.DateTimeFormatOptions` 的基础上额外扩展了 `locales` 字段： | 名称 | 描述 | 类型 | 可选 | 默认值 | | ------------------------ | ---------------- | --------------------------------------------------------------------------------------- | -- | ------------ | | `locales` | 覆盖格式化时使用的区域设置。 | `string \| string[]` | 是 | 实例的区域设置 | | `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` | IANA 时区标识符。 | `string` | 是 | 运行时时区 | | `hour12` | 是否使用 12 小时制时间格式。 | `boolean` | 是 | — | | `hourCycle` | 小时周期偏好。 | `'h11' \| 'h12' \| 'h23' \| 'h24'` | 是 | — | | `calendar` | 要使用的日历系统。 | `string` | 是 | `'gregory'` | | `numberingSystem` | 数字系统。 | `string` | 是 | `'latn'` | | `formatMatcher` | 格式匹配算法。 | `'basic' \| 'best fit'` | 是 | `'best fit'` | ## 返回值 [#returns] **类型** `string` 按目标区域设置的惯例格式化的日期和时间。 ## 示例 [#examples] *注意：未显式指定 `timeZone` 的示例会按运行时所在的本地时区渲染；下方的时间输出均假定为 `America/Los_Angeles` (该日期当天为 UTC−7) 。* ```typescript 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 // 日期和时间样式 const date = new Date('2024-03-14T14:30:45Z'); // 完整日期样式 console.log(gt.formatDateTime(date, { dateStyle: 'full' })); // Output: "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', })); // Output: "Thursday, March 14, 2024" ``` ```typescript // 时区和小时格式 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" ``` ## 注意事项 [#notes] * 日期格式会自动遵循相应区域设置的惯例。 * 该方法使用浏览器原生的 `Intl.DateTimeFormat`，以兼顾性能和准确性。 * 指定时区后会得到正确处理。