Intl.DateTimeFormat.prototype.formatToParts()

基线 广泛可用

此功能已完善，可在许多设备和浏览器版本中使用。它已在浏览器中可用，自 2017 年 9 月.

formatToParts() 方法 Intl.DateTimeFormat 实例允许对由该 Intl.DateTimeFormat 对象生成的字符串进行与语言环境相关的格式化。

试试

语法

js
formatToParts(date)

参数

date 可选

要格式化的日期。

返回值

一个 Array 对象，包含格式化的日期的各个部分。

描述

formatToParts() 方法对于自定义日期字符串格式化很有用。它返回一个 Array 对象，包含语言环境特定的标记，可以从中构建自定义字符串，同时保留语言环境特定的部分。formatToParts() 方法返回的结构如下

js
[
  { type: "day", value: "17" },
  { type: "weekday", value: "Monday" },
];

可能的类型如下

day

用于表示日期的字符串，例如 "17"。

dayPeriod

用于表示一日时段的字符串，例如 "AM"、"PM"、"in the morning" 或 "noon"。

era

用于表示纪元的字符串，例如 "BC" 或 "AD"。

fractionalSecond

用于表示秒小数部分的字符串，例如 "0" 或 "00" 或 "000"。

hour

用于表示小时的字符串，例如 "3" 或 "03"。

literal

用于分隔日期和时间值的字符串，例如 "/"、","、"o'clock"、"de" 等。

minute

用于表示分钟的字符串，例如 "00"。

month

用于表示月份的字符串，例如 "12"。

relatedYear

用于表示相关的 4 位数公历年份的字符串，如果日历的表示形式是年号而不是年份，例如 "2019"。

second

用于表示秒的字符串，例如 "07" 或 "42"。

timeZoneName

用于表示时区名称的字符串，例如 "UTC"。默认情况下为当前环境的时区。

weekday

用于表示星期的字符串，例如 "M"、"Monday" 或 "Montag"。

year

用于表示年份的字符串，例如 "2012" 或 "96"。

yearName

用于表示相关上下文中年号的字符串，例如 "geng-zi"。

示例

DateTimeFormat 输出本地化的、不透明的字符串，无法直接操作。

js
const date = Date.UTC(2012, 11, 17, 3, 0, 42);

const formatter = new Intl.DateTimeFormat("en-us", {
  weekday: "long",
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  fractionalSecondDigits: 3,
  hour12: true,
  timeZone: "UTC",
});

formatter.format(date);
// "Monday, 12/17/2012, 3:00:42.000 AM"

但是，在许多用户界面中，需要自定义此字符串的格式。formatToParts 方法通过提供字符串的各个部分，实现了对由 DateTimeFormat 格式化程序生成的字符串进行与语言环境相关的格式化。

js
formatter.formatToParts(date);

// return value:
[
  { type: "weekday", value: "Monday" },
  { type: "literal", value: ", " },
  { type: "month", value: "12" },
  { type: "literal", value: "/" },
  { type: "day", value: "17" },
  { type: "literal", value: "/" },
  { type: "year", value: "2012" },
  { type: "literal", value: ", " },
  { type: "hour", value: "3" },
  { type: "literal", value: ":" },
  { type: "minute", value: "00" },
  { type: "literal", value: ":" },
  { type: "second", value: "42" },
  { type: "fractionalSecond", value: "000" },
  { type: "literal", value: " " },
  { type: "dayPeriod", value: "AM" },
];

现在，这些信息可以单独获得，并可以以自定义的方式进行格式化和重新连接。例如，可以使用 Array.prototype.map()、箭头函数、switch 语句、模板字面量 和 Array.prototype.join()。

js
const dateString = formatter
  .formatToParts(date)
  .map(({ type, value }) => {
    switch (type) {
      case "dayPeriod":
        return `<em>${value}</em>`;
      default:
        return value;
    }
  })
  .join("");

这将使用 formatToParts() 方法突出显示一日时段。

js
console.log(formatter.format(date));
// "Monday, 12/17/2012, 3:00:42.000 AM"

console.log(dateString);
// "Monday, 12/17/2012, 3:00:42.000 <em>AM</em>"

命名年份和混合日历

在某些情况下，日历使用命名年份。例如，中国和西藏日历使用 60 年的 六十甲子 来命名年份。这些年份通过与公历年份的关系来区分。在这种情况下，formatToParts() 的结果将包含一个用于 relatedYear 的条目，如果通常会出现年份，则该条目包含 4 位数的公历年份，而不是用于 year 的条目。在包中设置 year 的条目（使用任何值）将产生公历的 relatedYear 和 yearName

js
const opts = { year: "numeric", month: "numeric", day: "numeric" };
const df = new Intl.DateTimeFormat("zh-u-ca-chinese", opts);
df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));

// return value
[
  { type: "relatedYear", value: "2012" },
  { type: "literal", value: "年" },
  { type: "month", value: "十一月" },
  { type: "day", value: "4" },
];

如果包中未设置 year 选项（为任何值），则结果将仅包含 relatedYear

js
const df = new Intl.DateTimeFormat("zh-u-ca-chinese");
df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));

// return value
[
  { type: "relatedYear", value: "2012" },
  { type: "literal", value: "年" },
  { type: "month", value: "十一月" },
  { type: "day", value: "4" },
];

在 year 通常会输出的情况下，.format() 通常会并排显示它们

js
const df = new Intl.DateTimeFormat("zh-u-ca-chinese", { year: "numeric" });
df.format(Date.UTC(2012, 11, 17, 3, 0, 42)); // 2012壬辰年

这使得能够在 format 中同时混合语言环境和日历

js
const df = new Intl.DateTimeFormat("en-u-ca-chinese", { year: "numeric" });
const date = Date.UTC(2012, 11, 17, 3, 0, 42);
df.format(date); // 2012(ren-chen)

和 formatToParts

js
const opts = { month: "numeric", day: "numeric", year: "numeric" };
const df = new Intl.DateTimeFormat("en-u-ca-chinese", opts);
const date = Date.UTC(2012, 11, 17, 3);
df.formatToParts(date);
// [
//   { type: 'month', value: '11' },
//   { type: 'literal', value: '/' },
//   { type: 'day', value: '4' },
//   { type: 'literal', value: '/' },
//   { type: 'relatedYear', value: '2012' }
// ]

规范

规范
ECMAScript 国际化 API 规范
# sec-Intl.DateTimeFormat.prototype.formatToParts

浏览器兼容性

BCD 表格仅在浏览器中加载

另请参阅