Intl.DateTimeFormat.prototype.formatRangeToParts()

Baseline 已广泛支持

此特性已发展成熟,可在多种设备和浏览器版本上使用。自 ⁨2021 年 8 月⁩ 起,它已在所有浏览器中可用。

formatRangeToParts() 方法是 Intl.DateTimeFormat 实例的一个方法,它返回一个对象数组,这些对象表示由 formatRange() 返回的格式化字符串中的每个部分。这对于根据本地化令牌构建自定义字符串非常有用。

试一试

const startDate = new Date(Date.UTC(2007, 0, 10, 10, 0, 0)); // > 'Wed, 10 Jan 2007 10:00:00 GMT'
const endDate = new Date(Date.UTC(2007, 0, 10, 11, 0, 0)); // > 'Wed, 10 Jan 2007 11:00:00 GMT'

const dateTimeFormat = new Intl.DateTimeFormat("en", {
  hour: "numeric",
  minute: "numeric",
});

const parts = dateTimeFormat.formatRangeToParts(startDate, endDate);
for (const part of parts) {
  console.log(part);
}
// Expected output (in GMT timezone):
// Object { type: "hour", value: "2", source: "startRange" }
// Object { type: "literal", value: ":", source: "startRange" }
// Object { type: "minute", value: "00", source: "startRange" }
// Object { type: "literal", value: " – ", source: "shared" }
// Object { type: "hour", value: "3", source: "endRange" }
// Object { type: "literal", value: ":", source: "endRange" }
// Object { type: "minute", value: "00", source: "endRange" }
// Object { type: "literal", value: " ", source: "shared" }
// Object { type: "dayPeriod", value: "AM", source: "shared" }

语法

js
formatRangeToParts(startDate, endDate)

参数

startDate

日期范围的开始。可以是 DateTemporal.PlainDateTime 对象。此外,如果 DateTimeFormat 对象被配置为打印至少一个相关的日期部分,它也可以是 Temporal.PlainTimeTemporal.PlainDateTemporal.PlainYearMonthTemporal.PlainMonthDay 对象。

注意: Temporal.ZonedDateTime 对象总是会抛出 TypeError;请使用 Temporal.ZonedDateTime.prototype.toLocaleString() 或将其转换为 Temporal.PlainDateTime 对象。

endDate

日期范围的结束。必须与 startDate 的类型相同。

返回值

一个包含格式化日期范围(按部分)的 Array。每个对象有三个属性:typevaluesource,每个属性都包含一个字符串。按顺序连接 value 字符串将产生与 formatRange() 相同的字符串。type 可以具有与 formatToParts() 相同的值。source 可以是以下之一:

startRange

该令牌是开始日期的一部分。

endRange

该令牌是结束日期的一部分。

shared

该令牌在开始和结束日期之间共享;例如,如果开始和结束日期共享相同的 day period,该令牌可能会被重用。所有属于范围模式本身的字面量,例如 " – " 分隔符,也被标记为 shared

如果开始日期和结束日期在输出精度上是等效的,那么输出将具有与对开始日期调用 formatToParts() 相同的令牌列表,所有令牌都标记为 source: "shared"

示例

使用 formatRangeToParts()

formatRange() 方法输出本地化的、不透明的字符串,这些字符串无法直接操作

js
const date1 = new Date(Date.UTC(1906, 0, 10, 10, 0, 0)); // Wed, 10 Jan 1906 10:00:00 GMT
const date2 = new Date(Date.UTC(1906, 0, 10, 11, 0, 0)); // Wed, 10 Jan 1906 11:00:00 GMT

const fmt = new Intl.DateTimeFormat("en", {
  hour: "numeric",
  minute: "numeric",
});

console.log(fmt.formatRange(date1, date2)); // '10:00 – 11:00 AM'

然而,在许多用户界面中,您可能希望自定义此字符串的格式,或者将其与其他文本交错。formatRangeToParts() 方法以部分形式生成相同的信息

js
console.log(fmt.formatRangeToParts(date1, date2));

// return value:
[
  { type: "hour", value: "10", source: "startRange" },
  { type: "literal", value: ":", source: "startRange" },
  { type: "minute", value: "00", source: "startRange" },
  { type: "literal", value: " – ", source: "shared" },
  { type: "hour", value: "11", source: "endRange" },
  { type: "literal", value: ":", source: "endRange" },
  { type: "minute", value: "00", source: "endRange" },
  { type: "literal", value: " ", source: "shared" },
  { type: "dayPeriod", value: "AM", source: "shared" },
];

规范

规范
ECMAScript® 2026 国际化 API 规范
# sec-Intl.DateTimeFormat.prototype.formatRangeToParts

浏览器兼容性

另见