GT ClassMethodsFormatting
formatDateTime
formatDateTime 方法的 API 参考:根据 locale 约定格式化日期和时间
概述
formatDateTime 方法使用 Internationalization API,依据特定 locale 的约定格式化日期和时间。
它会根据目标 locale 自动处理日期格式、时间格式、日历和时区。
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 的基础上扩展,增加了对 locale 的指定:
| Name | Type | Description |
|---|---|---|
locales? | string | string[] | 覆盖用于格式化的 locales(默认使用实例的 locales) |
localeMatcher? | 'lookup' | 'best fit' | locale 匹配算法(默认:'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 - 按照 locale 规范格式化的日期和时间。
示例
基础日期和时间格式化
import { GT } from 'generaltranslation';
const gt = new GT({ targetLocale: 'en-US' });
const date = new Date('2024-03-14T14:30:45Z');
// 基本日期格式(使用默认 options)
console.log(gt.formatDateTime(date));
// 输出:“3/14/2024”
// 德语 locale 格式
console.log(gt.formatDateTime(date, { locales: 'de-DE' }));
// 输出:“14.3.2024”
// 日语 locale 格式
console.log(gt.formatDateTime(date, { locales: 'ja-JP' }));
// 输出:“2024/3/14”日期和时间格式
const date = new Date('2024-03-14T14:30:45Z');
// 完整日期样式
console.log(gt.formatDateTime(date, { dateStyle: 'full' }));
// 输出:"2024年3月14日星期四"
// 长日期搭配短时间
console.log(gt.formatDateTime(date, {
dateStyle: 'long',
timeStyle: 'short'
}));
// 输出:"2024年3月14日 上午7:30"
// 自定义日期字段
console.log(gt.formatDateTime(date, {
weekday: 'long',
year: 'numeric',
month: 'long',
day: 'numeric'
}));
// 输出:"2024年3月14日星期四"时区与时间格式
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"注意事项
- 日期格式会自动遵循目标 locale 的本地化约定
- 该方法使用浏览器原生的
Intl.DateTimeFormat,以获得最佳性能与准确性 - 指定时区时将正确处理时区
相关方法
- 查看
Intl.DateTimeFormat文档 以获取更多 options - 参见
formatRelativeTime了解相对时间格式化(“2 days ago”) - 参见
formatMessage了解带日期插值的消息格式化 - 参见独立的
formatDateTime以在无需 GT 实例的情况下使用 - 参见
getLocaleProperties获取特定 locale 的日历信息
下一步
- 参阅 Formatting Guide,了解完整的日期/时间格式化策略
- 参阅 Internationalization Guide,了解基于 locale 的日期处理方法
本指南如何?