在此页

• 句法
• 描述
• Polyfill
• 范例
• 规范
• 浏览器兼容性
• 另请参阅
• 相关话题

Intl.DateTimeFormat.prototype.formatToParts() method allows locale-aware formatting of strings produced by DateTimeFormat formatters.

句法

dateTimeFormat.formatToParts(date)
					

参数

date 可选

The date to format.

返回值

Array of objects containing the formatted date in parts.

描述

formatToParts() method is useful for custom formatting of date strings. It returns an Array of objects containing the locale-specific tokens from which it possible to build custom strings while preserving the locale-specific parts. The structure the formatToParts() method returns, looks like this:

[
  { type: 'day', value: '17' },
  { type: 'weekday', value: 'Monday' }
]
					

Possible types are the following:

day

The string used for the day, for example "17" .

dayPeriod

The string used for the day period, for example, "AM", "PM" , "in the morning" ，或 "noon"

era

The string used for the era, for example "BC" or "AD" .

fractionalSecond

The string used for the fractional seconds, for example "0" or "00" or "000" .

hour

The string used for the hour, for example "3" or "03" .

literal

The string used for separating date and time values, for example "/" , "," , "o'clock" , "de" ，等。

minute

The string used for the minute, for example "00" .

month

The string used for the month, for example "12" .

relatedYear

The string used for the related 4-digit Gregorian year, in the event that the calendar's representation would be a yearName instead of a year, for example "2019" .

second

The string used for the second, for example "07" or "42" .

timeZoneName

The string used for the name of the time zone, for example "UTC" .

weekday

The string used for the weekday, for example "M" , "Monday" ，或 "Montag" .

year

The string used for the year, for example "2012" or "96" .

yearName

The string used for the yearName in relevant contexts, for example "geng-zi"

Polyfill

A polyfill for this feature is available in the proposal repository .

范例

DateTimeFormat outputs localized, opaque strings that cannot be manipulated directly:

var date = Date.UTC(2012, 11, 17, 3, 0, 42);
var 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"
					

However, in many User Interfaces there is a desire to customize the formatting of this string. The formatToParts method enables locale-aware formatting of strings produced by DateTimeFormat formatters by providing you the string in parts:

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'     }
]
					

Now the information is available separately and it can be formatted and concatenated again in a customized way. For example by using Array.prototype.map() , 箭头函数 ， switch statement , template literals ，和 Array.prototype.reduce() .

var dateString = formatter.formatToParts(date).map(({type, value}) => {
  switch (type) {
    case 'dayPeriod': return `<b>${value}</b>`;
    default : return value;
  }
}).reduce((string, part) => string + part);
					

This will make the day period bold, when using the formatToParts() 方法。

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 <b>AM</b>"
					

Named Years and Mixed calendars

In some cases, calendars use named years.  Chinese and Tibetan calendars, for example, use a 60-year sexagenary cycle of named years.  These years are disambiguated by relationship to corresponding years on the Gregorian calendar.  When this is the case, the result of formatToParts() will contain an entry for relatedYear when a year would normally be present, containing the 4-digit Gregorian year, instead of an entry for year .  Setting an entry in the bag for year (with any value) will yield both the and the yearName Gregorian relatedYear:

let opts = { year: "numeric", month: "numeric", day: "numeric" };
let 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 option is not set in the bag (to any value), the result will include only the relatedYear :

let 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' }
]
					

In cases where the year would be output, .format() may commonly present these side-by-side:

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

This also makes it possible to mix locale and calendar in both format :

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

And formatToParts :

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

规范

规范
ECMAScript 国际化 API (ECMA-402) The definition of 'Intl.DateTimeFormat.prototype.formatToParts' in that specification.

浏览器兼容性

The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request. 更新 GitHub 上的兼容性数据

	Desktop						Mobile						Server
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet	Node.js
formatToParts	Chrome 57 57 Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 71 and later use the specification defined dayPeriod 。见 Chromium bug 865351 .	Edge 18	Firefox 51	IE No	Opera 44 44 Before version 58, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 58 and later use the specification defined dayPeriod 。见 Chromium bug 865351 .	Safari 11	WebView Android 57 57 Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 71 and later use the specification defined dayPeriod 。见 Chromium bug 865351 .	Chrome Android 57 57 Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 71 and later use the specification defined dayPeriod 。见 Chromium bug 865351 .	Firefox Android 56	Opera Android 43 43 Before version 50, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 50 and later use the specification defined dayPeriod 。见 Chromium bug 865351 .	Safari iOS 11	Samsung Internet Android 7.0 7.0 Before version 71, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 71 and later use the specification defined dayPeriod 。见 Chromium bug 865351 .	nodejs 8.0.0 8.0.0 Before version 12.0.0, formatToParts() returned an object with an incorrectly cased type key of dayperiod . Version 12.0.0 and later use the specification defined dayPeriod 。见 Chromium bug 865351 . Before version 13.0.0, only the locale data for en-US is available by default. See the DateTimeFormat() 构造函数 了解更多细节。

图例

完整支持

完整支持

不支持

不支持

见实现注意事项。

另请参阅

• Intl.DateTimeFormat
• Intl.DateTimeFormat.prototype.format
• Date.prototype.toLocaleString()
• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleTimeString()

元数据

• 最后修改： May 20, 2020

相关话题

1. 标准内置对象
2. Intl
3. 方法
   1. Intl.getCanonicalLocales()
4. 相关页面：
5. Collator
6. DateTimeFormat
7. ListFormat
8. NumberFormat
9. PluralRules
10. RelativeTimeFormat
11. 继承：
12. Object
13. 特性
    1. Object.prototype.__proto__
    2. Object.prototype.constructor
14. 方法
    1. Object.prototype.__defineGetter__()
    2. Object.prototype.__defineSetter__()
    3. Object.prototype.__lookupGetter__()
    4. Object.prototype.__lookupSetter__()
    5. Object.prototype.hasOwnProperty()
    6. Object.prototype.isPrototypeOf()
    7. Object.prototype.propertyIsEnumerable()
    8. Object.prototype.toLocaleString()
    9. Object.prototype.toSource()
    10. Object.prototype.toString()
    11. Object.prototype.valueOf()
    12. Object.setPrototypeOf()