Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More information about formatToParts pages #37658

Merged
merged 2 commits into from
Jan 16, 2025
Merged

More information about formatToParts pages #37658

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
016b305
Fix issue in Named Year: Fix Issue #37609
SurajKharkwal Jan 15, 2025
05d8609
Fix more
Josh-Cena Jan 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...-us/web/javascript/reference/global_objects/intl/datetimeformat/format/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ format(date)
### Parameters

- `date`
- : The date to format.
- : The date to format. Omitting it results in formatting the current date (as returned by {{jsxref("Date.now()")}}), which could be slightly confusing, so it is advisable to always explicitly pass a date.

### Return value

Expand Down
63 changes: 42 additions & 21 deletions ...script/reference/global_objects/intl/datetimeformat/formatrangetoparts/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,7 @@ browser-compat: javascript.builtins.Intl.DateTimeFormat.formatRangeToParts

{{JSRef}}

The **`formatRangeToParts()`** method of {{jsxref("Intl.DateTimeFormat")}} instances returns an array of locale-specific tokens representing each part of the formatted date
range produced by this `Intl.DateTimeFormat` object.
The **`formatRangeToParts()`** method of {{jsxref("Intl.DateTimeFormat")}} instances returns an array of objects representing each part of the formatted string that would be returned by {{jsxref("Intl/DatetimeFormat/formatRange", "formatRange()")}}. It is useful for building custom strings from the locale-specific tokens.

{{EmbedInteractiveExample("pages/js/intl-datetimeformat-prototype-formatrangetoparts.html", "taller")}}

Expand All @@ -18,15 +17,31 @@ range produced by this `Intl.DateTimeFormat` object.
formatRangeToParts(startDate, endDate)
```

## Examples
### Parameters

- `startDate`
- : A {{jsxref("Date")}} object representing the start of the date range.
- `endDate`
- : A {{jsxref("Date")}} object representing the end of the date range.

### Return value

An {{jsxref("Array")}} of objects containing the formatted date range in parts. Each object has three properties, `type`, `value`, and `source`, each containing a string. The string concatenation of `value`, in the order provided, will result in the same string as {{jsxref("Intl/DateTimeFormat/formatRange", "formatRange()")}}. The `type` may have the same values as {{jsxref("Intl/DateTimeFormat/formatToParts", "formatToParts()")}}. The `source` can be one of the following:

- `startRange`
- : The token is a part of the start date.
- `endRange`
- : The token is a part of the end date.
- `shared`
- : The token is shared between the start and end; for example, if the start and end dates share the same day period, that token may get reused. All literals that are part of the range pattern itself, such as the `" – "` separator, are also marked as `shared`.

If the start and end dates are equivalent at the precision of the output, then the output has the same list of tokens as calling {{jsxref("Intl/DateTimeFormat/formatToParts", "formatToParts()")}} on the start date, with all tokens marked as `source: "shared"`.

### Basic formatRangeToParts usage
## Examples

This method receives two {{jsxref("Date")}}s and returns an {{jsxref("Array")}} of
objects containing the _locale-specific_ tokens representing each part of the formatted date range.
### Using formatRangeToParts()

> [!NOTE]
> The return values shown in your locale may differ from those listed below.
The `formatRange()` method outputs localized, opaque strings that cannot be manipulated directly:

```js
const date1 = new Date(Date.UTC(1906, 0, 10, 10, 0, 0)); // Wed, 10 Jan 1906 10:00:00 GMT
Expand All @@ -38,19 +53,25 @@ const fmt = new Intl.DateTimeFormat("en", {
});

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

However, in many user interfaces you may want to customize the formatting of this string, or interleave it with other texts. The `formatRangeToParts()` method produces the same information in parts:

fmt.formatRangeToParts(date1, date2);
// [
// { 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" }
// ]
```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" },
];
```

## Specifications
Expand All @@ -63,5 +84,5 @@ fmt.formatRangeToParts(date1, date2);

## See also

- {{jsxref("Intl/DateTimeFormat/formatRange", "Intl.DateTimeFormat.prototype.formatRange()")}}
- {{jsxref("Intl.DateTimeFormat")}}
- {{jsxref("Intl/DateTimeFormat/formatRange", "Intl.DateTimeFormat.prototype.formatRange()")}}
159 changes: 45 additions & 114 deletions .../javascript/reference/global_objects/intl/datetimeformat/formattoparts/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ browser-compat: javascript.builtins.Intl.DateTimeFormat.formatToParts

{{JSRef}}

The **`formatToParts()`** method of {{jsxref("Intl.DateTimeFormat")}} instances allows locale-aware formatting of strings produced by this `Intl.DateTimeFormat` object.
The **`formatToParts()`** method of {{jsxref("Intl.DateTimeFormat")}} instances returns an array of objects representing each part of the formatted string that would be returned by {{jsxref("Intl/DatetimeFormat/format", "format()")}}. It is useful for building custom strings from the locale-specific tokens.

{{EmbedInteractiveExample("pages/js/intl-datetimeformat-prototype-formattoparts.html", "taller")}}

Expand All @@ -19,66 +19,52 @@ formatToParts(date)

### Parameters

- `date` {{optional_inline}}
- : The date to format.
- `date`
- : The date to format. Omitting it results in formatting the current date (as returned by {{jsxref("Date.now()")}}), which could be slightly confusing, so it is advisable to always explicitly pass a date.

### Return value

An {{jsxref("Array")}} of objects containing the formatted date in parts.

## Description

The `formatToParts()` method is useful for custom formatting of date
strings. It returns an {{jsxref("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:

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

Possible types are the following:
An {{jsxref("Array")}} of objects containing the formatted date in parts. Each object has two properties, `type` and `value`, each containing a string. The string concatenation of `value`, in the order provided, will result in the same string as {{jsxref("Intl/DateTimeFormat/format", "format()")}}. The `type` may be one of the [date-time components](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#date-time_component_options):

- `weekday`
- : For example `"M"`, `"Monday"`, or `"Montag"`.
- `era`
- : For example `"BC"` or `"AD"`.
- `year`
- : For example `"2012"` or `"96"`.
- `month`
- : For example `"12"` or `"January"`.
- `day`
- : The string used for the day, for example `"17"`.
- : For example `"17"`.
- `dayPeriod`
- : The string used for the day period, for example, `"AM"`,
`"PM"`, `"in the morning"`, or `"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"`.
- : For example `"AM"`, `"PM"`, `"in the morning"`, or `"noon"`.
- `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"`, etc.
- : For example `"3"` or `"03"`.
- `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"`.
- : For example `"00"`.
- `second`
- : The string used for the second, for example `"07"` or `"42"`.
- : For example `"07"` or `"42"`.
- `fractionalSecond`
- : For example `"0"`, `"00"`, or `"000"`.
- `timeZoneName`
- : The string used for the name of the time zone, for example `"UTC"`. Default is the timezone of the current environment.
- `weekday`
- : The string used for the weekday, for example `"M"`, `"Monday"`, or `"Montag"`.
- `year`
- : The string used for the year, for example `"2012"` or `"96"`.
- : For example `"UTC"`, `"CET"`, or `"Central European Time"`.

The `type` may also be one of the following:

- `literal`
- : Any string that's a part of the format pattern and not influenced by the `date`; for example `"/"`, `", "`, `"o'clock"`, `"de"`, `" "`, etc.
- `relatedYear`
- : A 4-digit Gregorian year, in the event that the calendar's representation would be a `yearName` instead of a year; for example `"2019"`. See [named years](#named_years) for more details.
- `yearName`
- : The string used for the yearName in relevant contexts, for example `"geng-zi"`
- : The name given to the year, usually in calendars without the concept of continuous years; for example `"geng-zi"`.
- `unknown`
- : Reserved for any token that's not recognized as any of the above; should be rarely encountered.

## Examples

`DateTimeFormat` outputs localized, opaque strings that cannot be
manipulated directly:
### Using formatToParts()

The `format()` method outputs localized, opaque strings that cannot be manipulated directly:

```js
const date = Date.UTC(2012, 11, 17, 3, 0, 42);
Expand All @@ -100,9 +86,7 @@ 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:
However, in many user interfaces you may want to customize the formatting of this string, or interleave it with other texts. The `formatToParts()` method produces the same information in parts:

```js
formatter.formatToParts(date);
Expand All @@ -128,12 +112,7 @@ formatter.formatToParts(date);
];
```

Now the information is available separately and it can be formatted and concatenated
again in a customized way. For example by using {{jsxref("Array.prototype.map()")}},
[arrow functions](/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions),
a [switch statement](/en-US/docs/Web/JavaScript/Reference/Statements/switch),
[template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals),
and {{jsxref("Array.prototype.join()")}}.
Now the information is available separately and it can be formatted and concatenated again in a customized way. For example by using {{jsxref("Array.prototype.map()")}}, [arrow functions](/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions), a [switch statement](/en-US/docs/Web/JavaScript/Reference/Statements/switch), [template literals](/en-US/docs/Web/JavaScript/Reference/Template_literals), and {{jsxref("Array.prototype.join()")}}, to insert additional markup for certain components.

```js
const dateString = formatter
Expand All @@ -147,36 +126,20 @@ const dateString = formatter
}
})
.join("");
```

This will emphasize the day period when using the `formatToParts()` method.

```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>"
```

### Named Years and Mixed calendars
### Named years

In some cases, calendars use named years. Chinese and Tibetan calendars, for example,
use a 60-year [sexagenary cycle](https://en.wikipedia.org/wiki/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`:
Some calendars use named years; for example, the Chinese and Tibetan calendars use a 60-year [sexagenary cycle](https://en.wikipedia.org/wiki/Sexagenary_cycle) of named years. These calendars do not have a universal way to unambiguously number each year, so years are disambiguated by relationship to corresponding years on the Gregorian calendar. In this case, when the `DateTimeFormat` is configured to output the year component, a token for `relatedYear` is output instead of `year`.

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

// return value
// return value:
[
{ type: "relatedYear", value: "2012" },
{ type: "literal", value: "年" },
Expand All @@ -185,53 +148,24 @@ df.formatToParts(Date.UTC(2012, 11, 17, 3, 0, 42));
];
```

If the `year` option is not set in the bag (to any value), the result will
include only the `relatedYear`:
Sometimes, the combination of date-time component options maps to a format that also includes a `yearName`. There isn't a separate option that controls whether `yearName` is displayed or not. For example, the options below sets `month` to `"long"` and results in a `yearName` token, despite `year` still being `"numeric"`:

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

// return value
// return value:
[
{ type: "relatedYear", value: "2012" },
{ type: "yearName", value: "壬辰" },
{ 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:

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

This also makes it possible to mix locale and calendar in both `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)
```

And `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' }
// ]
```
Because `format()` just concatenates all the `value` strings together, you will see the Gregorian year and the year name together in the output in this case.

## Specifications

Expand All @@ -245,6 +179,3 @@ df.formatToParts(date);

- {{jsxref("Intl.DateTimeFormat")}}
- {{jsxref("Intl/DateTimeFormat/format", "Intl.DateTimeFormat.prototype.format()")}}
- {{jsxref("Date.prototype.toLocaleString()")}}
- {{jsxref("Date.prototype.toLocaleDateString()")}}
- {{jsxref("Date.prototype.toLocaleTimeString()")}}
2 changes: 1 addition & 1 deletion ...javascript/reference/global_objects/intl/durationformat/durationformat/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ new Intl.DurationFormat(locales, options)
- `numberingSystem`
- : The numbering system to use for number formatting, such as `"arab"`, `"hans"`, `"mathsans"`, and so on. For a list of supported numbering system types, see [`Intl.Locale.prototype.getNumberingSystems()`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getNumberingSystems#supported_numbering_system_types). This option can also be set through the `nu` Unicode extension key; if both are provided, this `options` property takes precedence.
- `style`
- : The style of the formatted duration. Possible values are:
- : The style of the formatted duration. This value is used as the default for all other unit options, and also corresponds to the `style` option of {{jsxref("Intl/ListFormat/ListFormat", "Intl.ListFormat()")}} when concatenating the list of duration units. Possible values are:
- `"long"`
- : E.g., 1 hour and 50 minutes
- `"short"` (default)
Expand Down
Loading
Loading