# General Translation Platform: formatDateTime URL: https://generaltranslation.com/zh/docs/platform/core/reference/utility-functions/formatting/format-date-time.mdx Docs index: https://generaltranslation.com/llms.txt 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` · **可选** · **默认值** `{}` 格式化配置。下表列出了已发布的 Core 类型提供的常用选项及其实际采用的 Core 默认值。 (有关标准补充信息和运行时特定详情，请参阅 [`Intl.DateTimeFormat` 构造函数选项](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options)。) | 属性 | 描述 | 类型 | 可选 | 默认值 | | ------------------------ | ------------------------- | --------------------------------------------------------------------------------------- | -- | ---------------------- | | `locales` | 用于格式化的区域设置。传入数组时会按顺序尝试。 | `string \| string[]` | 是 | `en` | | `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'` | 是 | 未设置样式或组件时为 `'numeric'` | | `month` | 月份的表示形式。 | `'numeric' \| '2-digit' \| 'long' \| 'short' \| 'narrow'` | 是 | 未设置样式或组件时为 `'numeric'` | | `day` | 日期的表示形式。 | `'numeric' \| '2-digit'` | 是 | 未设置样式或组件时为 `'numeric'` | | `dayPeriod` | 12 小时制下时段的宽度。 | `'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 时区名称或受支持的 UTC 偏移标识符。 | `string` | 是 | 运行时时区 | | `hour12` | 是否使用 12 小时制。 | `boolean` | 是 | 取决于区域设置 | | `hourCycle` | 小时制偏好。 | `'h11' \| 'h12' \| 'h23' \| 'h24'` | 是 | 取决于区域设置 | | `calendar` | 要使用的日历系统。 | `string` | 是 | `'gregory'` | | `numberingSystem` | 数字编号系统。 | `string` | 是 | `'latn'` | | `formatMatcher` | 格式匹配算法。 | `'basic' \| 'best fit'` | 是 | `'best fit'` | `dateStyle` 和 `timeStyle` 可以搭配使用，但不能与 `year`、`month` 或 `hour` 等单独的日期时间组件选项搭配使用。`hour12` 会覆盖 `hourCycle`，而 `dayPeriod` 仅对 12 小时制有效。Core 会设置 `calendar: 'gregory'` 和 `numberingSystem: 'latn'`；其他情况下，上游 `Intl.DateTimeFormat` 会根据区域设置选择这两项。 ## 返回值 [#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`，输出结果取决于运行时环境。 ## Sitemap See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.