Date.prototype.toDateString() - JavaScript

Date.prototype.toDateString()
=============================

**`toDateString()`** メソッドは、 `Date` オブジェクトの日付部分をローカルタイムゾーンで英語で返します。

試してみましょう
--------

構文
--
```

dateObj.toDateString()
```

### 返値

与えられた `Date` オブジェクトの「日付」部を表す文字列を人間が読める英語の表記で返します。

解説
--

`Date` インスタンスは、特定の時点を参照します。 `toDateString()` は日付をローカルタイムゾーンで解釈し、*日付* の部分を英語で整形します。英語の次の書式で空白区切りで返します。

1. 曜日名の最初の 3 文字
2. 月名の最初の 3 文字
3. 2 桁の日、必要であれば左に 0 埋め
4. 4 桁 (以上) の年、必要であれば左に 0 埋め

例 "Thu Jan 01 1970".

* *時刻* の部分を取得したい場合は、 `toTimeString()` を使用してください。
* 日付と時刻の両方を取得したい場合は、 `toString()` を使用してください。
* 日付をローカルタイムゾーンではなく UTC として解釈したい場合は、 `toUTCString()` を使用してください。
* 日付をもっとユーザーが読みやすい形式（例えばローカライズ）で整形したい場合は、 `toLocaleDateString()` を使用してください。
例
-

### toDateString() の基本的な使い方

```js
var d = new Date(1993, 5, 28, 14, 39, 7);

console.log(d.toString()); // logs Mon Jun 28 1993 14:39:07 GMT-0600 (PDT)
console.log(d.toDateString()); // logs Mon Jun 28 1993
```

**メモ:** `Date` の引数として使用する場合、月は 0 から始まります（よって、 0 は 1 月に、 11 は 12 月 に対応します）。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.todatestring |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toString()`


Date.prototype.setUTCMilliseconds() - JavaScript

Date.prototype.setUTCMilliseconds()
===================================

**`setUTCMilliseconds()`** メソッドは、協定世界時に基づき、指定された日時の「ミリ秒」を設定します。

試してみましょう
--------

構文
--

```js
setUTCMilliseconds(millisecondsValue)
```

### 引数

`millisecondsValue`

「ミリ秒」を表す 0 から 999 までの間の整数値。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日時までの間のミリ秒単位の数値。

解説
--

指定した値が期待される日付の範囲外の場合、それに応じて `setUTCMilliseconds()` が `Date` オブジェクトの日付情報の更新を試みます。例えば、`millisecondsValue` に 1100 を指定した場合、`Date` オブジェクトに格納された秒の数値に 1 が加算され、ミリ秒に 100 が使用されます。

例
-

### setUTCMilliseconds() の使用

```js
const theBigDay = new Date();
theBigDay.setUTCMilliseconds(500);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcmilliseconds |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCMilliseconds()`
* `Date.prototype.setMilliseconds()`


Date.prototype.getDate() - JavaScript

Date.prototype.getDate()
========================

**`getDate()`** メソッドは、地方時に基づき、指定された日付の「日」を返します。

試してみましょう
--------

構文
--

```js
getDate()
```

### 返値

1 から 31 までの間の整数値。地方時に基づき、指定された日付の「日」を表します。

例
-

### getDate() の使用

以下の 2 行目の文は、`Date` オブジェクトである `xmas95` の値に基づき、変数 `day` に 25 という値を代入します。

```js
const xmas95 = new Date("December 25, 1995 23:15:30");
const day = xmas95.getDate();

console.log(day); // 25
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getdate |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCDate()`
* `Date.prototype.getUTCDay()`
* `Date.prototype.setDate()`


Date.prototype.getUTCHours() - JavaScript

Date.prototype.getUTCHours()
============================

**`getUTCHours()`** メソッドは、協定世界時に基づき、指定された日時の「時」を返します。

試してみましょう
--------

構文
--

```js
getUTCHours()
```

### 返値

 数値です。
 `Date` オブジェクトが有効な日時を表している場合、指定された日時の協定世界時での「時」を表す、0 から 23 までの整数を指定します。
 それ以外の場合は、`Date` オブジェクトが有効な日時を表していなければ `NaN` が返されます。

例
-

### getUTCHours() の使用

次の例は、現在時刻の「時」の部分を変数 `hours` に代入します。

```js
const today = new Date();
const hours = today.getUTCHours();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutchours |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getHours()`
* `Date.prototype.setUTCHours()`


Date.prototype.setMinutes() - JavaScript

Date.prototype.setMinutes()
===========================

**`setMinutes()`** メソッドは、地方時に基づき、指定された日時の「分」を設定します。

試してみましょう
--------

構文
--

```js
setMinutes(minutesValue)
setMinutes(minutesValue, secondsValue)
setMinutes(minutesValue, secondsValue, msValue)
```

### 引数

`minutesValue`

「分」を表す 0 から 59 までの間の整数値。

`secondsValue`

任意。「秒」を表す 0 から 59 までの間の整数値。`secondsValue` 引数を指定した場合、`minutesValue` も指定しなければなりません。

`msValue`

任意。ミリ秒を表す 0 から 999 までの間の整数値。`msValue` 引数を指定した場合、`minutesValue` と `secondsValue` も指定しなければなりません。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日時までの間のミリ秒単位の数値。

解説
--

`secondsValue` および `msValue` 引数を指定しない場合、`getSeconds()` と `getMilliseconds()` メソッドから返される値が使われます。

指定した値が期待される日時の範囲外の場合、それに応じて `setMinutes()` が `Date` オブジェクトの日付情報の更新を試みます。例えば、`secondsValue` に 100 を指定した場合、分に 1 が加算 (`minutesValue + 1`) され、秒が 40 になります。

例
-

### setMinutes() の使用

```js
const theBigDay = new Date();
theBigDay.setMinutes(45);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setminutes |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getMinutes()`
* `Date.prototype.setUTCMinutes()`


Date.prototype.setUTCFullYear() - JavaScript

Date.prototype.setUTCFullYear()
===============================

**`setUTCFullYear()`** メソッドは、協定世界時に基づき、指定された日付の年を設定します。

試してみましょう
--------

構文
--

```js
setUTCFullYear(yearValue)
setUTCFullYear(yearValue, monthValue)
setUTCFullYear(yearValue, monthValue, dayValue)
```

### 引数

`yearValue`

「年」の数字を指定する整数値。例えば、1995。

`monthValue`

任意。1 月から 12 月を表す 0 から 11 までの間の整数値。

`dayValue`

任意。「日」を表す 1 から 31 までの間の整数値。`dayValue` 引数を指定した場合、`monthValue` も指定しなければなりません。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日時までの間のミリ秒単位の数値。

解説
--

`monthValue` 引数と `dayValue` 引数を指定しない場合、`getUTCMonth()` メソッドと `getUTCDate()` メソッドから返される値が使われます。

指定した値が期待される日付の範囲外の場合、それに応じて `setUTCFullYear()` が他の引数と `Date` オブジェクトの日付情報の更新を試みます。例えば、`monthValue` に 15 を指定した場合、年に 1 が加算 (`yearValue + 1`) され、月が 3 になります。

例
-

### setUTCFullYear() の使用

```js
const theBigDay = new Date();
theBigDay.setUTCFullYear(1997);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcfullyear |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setFullYear()`


Date.prototype.toLocaleTimeString() - JavaScript

Date.prototype.toLocaleTimeString()
===================================

**`toLocaleTimeString()`** メソッドは、日付の時間部分を言語に依存して表現した文字列を返します。`Intl.DateTimeFormat` API に対応している実装では、このメソッドは単に `Intl.DateTimeFormat` を呼び出すだけです。

試してみましょう
--------

構文
--

```js
toLocaleTimeString()
toLocaleTimeString(locales)
toLocaleTimeString(locales, options)
```

### 引数

引数 `locales` と `options` は、関数の動作をカスタマイズして、アプリケーションが書式化の慣習を使用する言語を指定することができるようにします。

`Intl.DateTimeFormat` API に対応している実装では、これらの引数は `Intl.DateTimeFormat()` コンストラクターの引数と正確に一致していることに注意してください。 `Intl.DateTimeFormat` に対応していない実装では、両方の引数を無視するように求められます。使用するロケールと返す文字列の形式は、完全に実装に依存します。

`locales` 省略可

BCP 47 の言語タグを持つ文字列、あるいはそのような文字列の配列です。 `Intl.DateTimeFormat()` コンストラクターの `locales` 引数に相当します。

`Intl.DateTimeFormat` に対応していない実装では、この引数は無視され、通常はホストのロケールを使用します。

`options` 省略可

出力書式を調整するオブジェクト。 `Intl.DateTimeFormat()` コンストラクターの `options` 引数に相当します。 `dayPeriod`, `hour`, `minute`, `second`, `fractionalSecondDigits` がすべて未定義の場合、 `hour`, `minute`, `second` は `"numeric"` に設定されます。

`Intl.DateTimeFormat` に対応していない実装では、この引数は無視されます。

これらの引数の詳細や使用方法については `Intl.DateTimeFormat()` コンストラクターを参照してください。

### 返値

与えられた `Date` インスタンスの「時刻」部を表す、言語特有の慣習による文字列。

`Intl.DateTimeFormat` がある実装では、これは `new Intl.DateTimeFormat(locales, options).format(date)` と等価です。

性能
--

大量の日付を書式化する場合は、 `Intl.DateTimeFormat` オブジェクトを生成してその `format()` プロパティで提供される関数を使用したほうが得策です。

例
-

### toLocaleTimeString() の使用

ロケールを指定しない基本的な使い方では、既定のロケールと既定のオプションによる書式の文字列が返されます。

```js
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleTimeString() に引数を与えなければ実装に依存し、
// 既定のロケールとタイムゾーンを返す
console.log(date.toLocaleTimeString());
// → "7:00:00 PM" アメリカ/ロサンゼルスのタイムゾーンの en-US ロケールで実行した場合
```

### locales の使用

この例では、国ごとに異なる時刻書式を示します。アプリケーションのユーザーインターフェイスで使用されている言語の書式を得るには、 `locales` 引数でその言語 (あるいはフォールバック先の言語) を指定してください。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下の書式はその地域のタイムゾーンとロケールを想定
// 米国のアメリカ大陸/ロサンゼルス

// 米国英語は AM/PM 表記の 12 時間制
console.log(date.toLocaleTimeString("en-US"));
// → "7:00:00 PM"

// 英国英語は AM/PM 表記なしの 24 時間制
console.log(date.toLocaleTimeString("en-GB"));
// → "03:00:00"

// 韓国は AM/PM 表記の 12 時間制
console.log(date.toLocaleTimeString("ko-KR"));
// → "오후 12:00:00"

// 多くのアラビア語圏ではアラビア数字を使用
console.log(date.toLocaleTimeString("ar-EG"));
// → "٧:٠٠:٠٠ م"

// 対応していない可能性のある言語を要求した場合、例えば
// バリ語とし、フォールバック言語にインドネシア語を指定した場合
console.log(date.toLocaleTimeString(["ban", "id"]));
// → "11.00.00"
```

### options の使用

`toLocaleTimeString()` メソッドから得られる結果は、 `options` 引数でカスタマイズできます。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// アプリケーションで UTC を用い、それを表示したい場合
const options = { timeZone: "UTC", timeZoneName: "short" };
console.log(date.toLocaleTimeString("en-US", options));
// → "3:00:00 AM GMT"

// 米国でも 24 時間制を使うことがある
console.log(date.toLocaleTimeString("en-US", { hour12: false }));
// → "19:00:00"

// 既定のロケールのオプション - 空の配列を使用して時と分のみを表示
console.log(
  date.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit" }),
);
// → "20:01"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocaletimestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocaletimestring |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toString()`


Date.prototype.getDay() - JavaScript

Date.prototype.getDay()
=======================

**`getDay()`** メソッドは、地方時に基づき、指定された日付の曜日を返します。 0 は日曜日を表します。「日」を取得する方法は `Date.prototype.getDate()` をご覧ください。

試してみましょう
--------

構文
--

```js
getDay()
```

### 返値

整数値で、 0 から 6 までの値を取り、地方時に基づいて指定された日付の曜日に対応し、 0 は日曜日、 1 は月曜日、 2 は火曜日のようになります。

例
-

### getDay の使用

以下の 2 行目の文は、 `Date` オブジェクトである `xmas95` の値に基づき、`weekday` に 1 という値を代入します。1995 年 12 月 25 日は月曜日です。

```js
const xmas95 = new Date("December 25, 1995 23:15:30");
const weekday = xmas95.getDay();

console.log(weekday); // 1
```

**メモ:** 必要であれば、曜日の完全な名前 (例えば "`Monday`") は `Intl.DateTimeFormat` に `options` 引数を設定することで取得することができます。このメソッドを使用すれば、国際化がより簡単になります。

```js
const options = { weekday: "long" };
console.log(new Intl.DateTimeFormat("en-US", options).format(Xmas95));
// Monday
console.log(new Intl.DateTimeFormat("de-DE", options).format(Xmas95));
// Montag
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getday |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCDate()`
* `Date.prototype.getUTCDay()`
* `Date.prototype.setDate()`


Date.prototype.toLocaleString() - JavaScript

Date.prototype.toLocaleString()
===============================

**`toLocaleString()`** メソッドは、この日付の言語依存の表現による文字列を返します。`Intl.DateTimeFormat` API に対応している実装では、このメソッドは単に `Intl.DateTimeFormat` を呼び出すだけです。

試してみましょう
--------

構文
--

```js
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
```

### 引数

引数 `locales` と `options` は、関数の動作をカスタマイズして、アプリケーションが書式化の慣習を使用する言語を指定することができるようにします。

`Intl.DateTimeFormat` API に対応している実装では、これらの引数は `Intl.DateTimeFormat()` コンストラクターの引数と正確に一致していることに注意してください。 `Intl.DateTimeFormat` に対応していない実装では、両方の引数を無視するように求められます。使用するロケールと返す文字列の形式は、完全に実装に依存します。

`locales` 省略可

BCP 47 の言語タグを持つ文字列、あるいはそのような文字列の配列です。 `Intl.DateTimeFormat()` コンストラクターの `locales` 引数に相当します。

`Intl.DateTimeFormat` に対応していない実装では、この引数は無視され、通常はホストのロケールを使用します。

`options` 省略可

出力書式を調整するオブジェクト。 `Intl.DateTimeFormat()` コンストラクターの `options` 引数に相当します。 `timeStyle` オプションは未定義でなければならず、そうでない場合は `TypeError` が発生します。 `weekday`, `year`, `month`, `day`, `dayPeriod`, `hour`, `minute`, `second`, `fractionalSecondDigits` がすべて未定義の場合、 `year`, `month`, `day`, `hour`, `minute`, `second` は `"numeric"` に設定されます。

`Intl.DateTimeFormat` に対応していない実装では、この引数は無視されます。

これらの引数の詳細や使用方法については `Intl.DateTimeFormat()` コンストラクターを参照してください。

### 返値

指定された日付を、言語固有の仕様に従って表現した文字列。

`Intl.DateTimeFormat` がある実装では、これは `new Intl.DateTimeFormat(locales, options).format(date)` と等価です。

例
-

### toLocaleString() の使用

ロケールを指定しない基本的な使い方では、既定のロケールと既定のオプションによる書式の文字列が返されます。

```js
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleString() メソッドに引数を与えなければ実装に依存し、
// 既定のロケールとタイムゾーンを返す
console.log(date.toLocaleString());
// → "12/11/2012, 7:00:00 PM" : アメリカ/ロサンゼルスのタイムゾーンの en-US ロケールで実行した場合
```

### locales と options に対応しているか確認する

`locales` と `options` は、まだすべてのブラウザーが対応している訳ではありません。これらが実装されているかどうかは、不適切な言語タグを与えて `RangeError` 例外で拒否されるかどうかで確かめられます。

```js
function toLocaleStringSupportsLocales() {
  try {
    new Date().toLocaleString("i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}
```

### locales の使用

この例では、国ごとに異なる日時の書式を示します。ご使用のアプリケーションのユーザーインターフェイスで使用される言語の書式を得るには、 `locales` でその言語 (あるいは代替言語) を指定してください。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下の書式はその地域のタイムゾーンとロケールを想定
// 米国のアメリカ大陸/ロサンゼルス

// 米国英語は月-日-年の順で AM/PM 表記の 12 時間制
console.log(date.toLocaleString("en-US"));
// → "12/19/2012, 7:00:00 PM"

// 英国英語は日-月-年の順で AM/PM 表記なしの 24 時間制
console.log(date.toLocaleString("en-GB"));
// → "20/12/2012 03:00:00"

// 韓国は年-月-日の順で AM/PM 表記の 12 時間制
console.log(date.toLocaleString("ko-KR"));
// → "2012. 12. 20. 오후 12:00:00"

// 多くのアラビア語圏ではアラビア数字を使用
console.log(date.toLocaleString("ar-EG"));
// → "٢٠/١٢/٢٠١٢ ٥:٠٠:٠٠ ص"

// 日本のアプリケーションでは元号を用いることがある
// 2012 年は平成 24 年
console.log(date.toLocaleString("ja-JP-u-ca-japanese"));
// → "24/12/20 12:00:00"

// 対応していない可能性のある言語を要求した場合、たとえば
// ここではバリ語とし、代替言語にインドネシア語
console.log(date.toLocaleString(["ban", "id"]));
// → "20/12/2012 11.00.00"
```

### options の使用

`toLocaleString()` メソッドから得られる結果は、`options` でカスタマイズできます。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 曜日を加えて月とともに長い書式で表す
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};

console.log(date.toLocaleString("de-DE", options));
// → "Donnerstag, 20. Dezember 2012"

// アプリケーションで UTC を用いてそれを示したい場合
options.timeZone = "UTC";
options.timeZoneName = "short";

console.log(date.toLocaleString("en-US", options));
// → "Thursday, December 20, 2012, GMT"

// 米国でも 24 時間制を使うことがある
console.log(date.toLocaleString("en-US", { hour12: false }));
// → "12/19/2012, 19:00:00"
```

### 書式化した日付値を固定値と比較しないでください

たいていの場合、 `toLocaleString()` が返す書式は一貫しています。しかし、これは将来的に変更される可能性があり、すべての言語で保証されているわけではありません。

特に注目すべきは、IE および Edge ブラウザーは日付の周りに書字方向の制御文字を挿入するため、出力テキストが他のテキストと連結されたときに適切に流れるようになっています。

このことから、 `toLocaleString()` を固定値と比較できると期待してはいけません。

```js
"1/1/2019, 01:00:00" ===
  new Date("2019-01-01T01:00:00Z").toLocaleString("en-US");
// true in Firefox and others
// false in IE and Edge
```

**メモ:** 詳細および例についてはこの StackOverflow のスレッドをご覧ください。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocalestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocalestring |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleTimeString()`
* `Date.prototype.toString()`


Date.prototype.getUTCMilliseconds() - JavaScript

Date.prototype.getUTCMilliseconds()
===================================

**`getUTCMilliseconds()`** メソッドは、協定世界時に基づき、指定された日時の「ミリ秒」を返します。

試してみましょう
--------

構文
--

```js
getUTCMilliseconds()
```

### 返値

 数値です。
 もし `Date` オブジェクトが有効な日時を表している場合には、指定された `Date` オブジェクトの世界時によるミリ秒単位を表す 0 から 999 までの整数値です。
 それ以外の場合は、`Date` オブジェクトが有効な日時を表していなければ `NaN` が返されます。

Unix 元期の時刻と混同しないでください。 1970/01/01 からの経過ミリ秒を取得するには、 `getTime()` メソッドを使用してください。

例
-

### getUTCMilliseconds() の使用

次の例は、現在時刻の「ミリ秒」部を変数 `milliseconds` に代入します。

```js
const today = new Date();
const milliseconds = today.getUTCMilliseconds();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcmilliseconds |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getMilliseconds()`
* `Date.prototype.setUTCMilliseconds()`


Date.prototype.getUTCMinutes() - JavaScript

Date.prototype.getUTCMinutes()
==============================

**`getUTCMinutes()`** メソッドは、協定世界時に基づき、指定された日時の「分」を返します。

試してみましょう
--------

構文
--

```js
getUTCMinutes()
```

### 返値

 数値です。
 もし `Date` オブジェクトが有効な日時を表している場合は、0 から 59 までの整数で、指定された日時の世界時での分の値を表します。
 それ以外の場合は、`Date` オブジェクトが有効な日時を表していなければ `NaN` が返されます。

例
-

### getUTCMinutes() の使用

次の例は、現在時刻の「分」部を変数 `minutes` に代入します。

```js
const today = new Date();
const minutes = today.getUTCMinutes();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcminutes |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getMinutes()`
* `Date.prototype.setUTCMinutes()`


Date.prototype.getUTCDay() - JavaScript

Date.prototype.getUTCDay()
==========================

**`getUTCDay()`** メソッドは、協定世界時に基づき、指定された日時の「曜日」を返します。0 は日曜日を表します。

試してみましょう
--------

構文
--

```js
getUTCDay()
```

### 返値

 数値です。
 `Date` オブジェクトが有効な日時を表している場合、世界時で指定された日時の曜日を表した整数値（日曜日は 0、月曜日は 1、火曜日は 2、...）です。
 それ以外の場合は、`Date` オブジェクトが有効な日時を表していなければ `NaN` が返されます。

例
-

### getUTCDay() の使用

次の例は、現在日時の曜日の部分を変数 `weekday` に代入します。

```js
const today = new Date();
const weekday = today.getUTCDay();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcday |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCDate()`
* `Date.prototype.getDay()`
* `Date.prototype.setUTCDate()`


Date.prototype.toLocaleDateString() - JavaScript

Date.prototype.toLocaleDateString()
===================================

**`toLocaleDateString()`** メソッドは、この Date オブジェクトの「日付」部を表す言語に依存した文字列を返します。新しい `locales` 引数と `options` 引数により、アプリケーションは、使用される書式変換の言語の指定や、関数の振る舞いのカスタマイズができます。古い実装のアプリケーションは、`locales` 引数と `options` 引数を無視します。使用されるロケールや返される文字列の書式は、完全に実装依存です。

試してみましょう
--------

構文
--

```js
toLocaleDateString()
toLocaleDateString(locales)
toLocaleDateString(locales, options)
```

### 引数

引数 `locales` と `options` は、関数の動作をカスタマイズして、アプリケーションが書式化の慣習を使用する言語を指定することができるようにします。

`Intl.DateTimeFormat` API に対応している実装では、これらの引数は `Intl.DateTimeFormat()` コンストラクターの引数と正確に一致していることに注意してください。 `Intl.DateTimeFormat` に対応していない実装では、両方の引数を無視するように求められます。使用するロケールと返す文字列の形式は、完全に実装に依存します。

`locales` 省略可

BCP 47 の言語タグを持つ文字列、あるいはそのような文字列の配列です。 `Intl.DateTimeFormat()` コンストラクターの `locales` 引数に相当します。

`Intl.DateTimeFormat` に対応していない実装では、この引数は無視され、通常はホストのロケールを使用します。

`options` 省略可

出力書式を調整するオブジェクト。 `Intl.DateTimeFormat()` コンストラクターの `options` 引数に相当します。 `timeStyle` オプションは未定義でなければならず、そうでない場合は `TypeError` が発生します。 `weekday`, `year`, `month`, `day` がすべて未定義の場合、 `year`, `month`, `day` は `"numeric"` に設定されます。

`Intl.DateTimeFormat` に対応していない実装では、この引数は無視されます。

これらの引数の詳細や使用方法については `Intl.DateTimeFormat()` コンストラクターを参照してください。

### 返値

指定された `Date` インスタンスの日付部分を、言語固有の仕様にしたがって表現した文字列を表します。

`Intl.DateTimeFormat` のある実装では、 `new Intl.DateTimeFormat(locales, options).format(date)` と等価であり、 `options` は上記のように正規化されます。

性能
--

大量の日付を書式化する場合は、 `Intl.DateTimeFormat` オブジェクトを生成してその `format()` プロパティで提供される関数を使用したほうが得策です。

例
-

### toLocaleDateString() の使用

ロケールを指定しない基本的な使い方では、既定のロケールと既定のオプションによる書式の文字列が返されます。

```js
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

// toLocaleDateString() に引数を与えなければ実装に依存し、
// 既定のロケールとタイムゾーンを返す
console.log(date.toLocaleDateString());
// → "12/11/2012" : アメリカ/ロサンゼルスのタイムゾーンの ja ロケールで実行した場合
```

### locales と options の各引数に対応しているか確認する

`locales` および `options` 引数は、まだすべてのブラウザーが対応しているわけではありません。これらが実装されているかどうかをチェックするには、不適切な言語タグを与えると `RangeError` 例外で拒否されるという要件を使用することができます。

```js
function toLocaleDateStringSupportsLocales() {
  try {
    new Date().toLocaleDateString("i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}
```

### locales の使用

この例では、国ごとに異なる日付書式を示します。アプリケーションのユーザーインターフェイスで使用されている言語の書式を得るには、 `locales` 引数でその言語 (あるいはフォールバック先の言語) を指定してください。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 以下の書式はその地域のタイムゾーンとロケールを想定
// 米国のアメリカ大陸/ロサンゼルス

// 米国英語は月-日-年の順
console.log(date.toLocaleDateString("en-US"));
// → "12/20/2012"

// 英国英語は日-月-年の順
console.log(date.toLocaleDateString("en-GB"));
// → "20/12/2012"

// 韓国は年-月-日の順
console.log(date.toLocaleDateString("ko-KR"));
// → "2012. 12. 20."

// Event for Persian, It's hard to manually convert date to Solar Hijri
console.log(date.toLocaleDateString("fa-IR"));
// → "۱۳۹۱/۹/۳۰"

// 多くのアラビア語圏ではアラビア数字
console.log(date.toLocaleDateString("ar-EG"));
// → "٢٠/١٢/٢٠١٢"

// 日本語では、アプリケーションは元号を用いることがある
// 2012 年は平成 24 年
console.log(date.toLocaleDateString("ja-JP-u-ca-japanese"));
// → "24/12/20"

// 対応していない可能性のある言語を要求した場合、例えば
// バリ語とし、フォールバック言語にインドネシア語を指定した場合
console.log(date.toLocaleDateString(["ban", "id"]));
// → "20/12/2012"
```

### options の使用

`toLocaleDateString()` メソッドから得られる結果は、 `options` 引数でカスタマイズできます。

```js
const date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 曜日を加えて月とともに長い書式で表す
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(date.toLocaleDateString("de-DE", options));
// → "Donnerstag, 20. Dezember 2012"

// アプリケーションで UTC を用いてそれを示したい場合
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleDateString("en-US", options));
// → "Thursday, December 20, 2012, UTC"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tolocaledatestring |
| ECMAScript Internationalization API Specification # sup-date.prototype.tolocaledatestring |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toLocaleTimeString()`
* `Date.prototype.toString()`


Date.prototype.setFullYear() - JavaScript

Date.prototype.setFullYear()
============================

**`setFullYear()`** メソッドは、地方時に基づき、指定された日付の「年」を設定します。新しいタイムスタンプを返します。

試してみましょう
--------

構文
--

```js
setFullYear(yearValue)
setFullYear(yearValue, monthValue)
setFullYear(yearValue, monthValue, dateValue)
```

### 引数

`yearValue`

「年」の数字を指定する整数値。例えば、1995。

`monthValue`

任意。1 月から 12 月を表す 0 から 11 までの間の整数値。

`dateValue`

「日」を表す 1 から 31 までの間の整数値。`dateValue` 引数を指定した場合、`monthValue` も指定しなければなりません。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日付までの間のミリ秒単位の数値。

解説
--

`monthValue` 引数と `dateValue` 引数を指定しない場合、 `getMonth()` メソッドと `getDate()` メソッドから返される値が使われます。

指定した値が期待される日付の範囲外の場合、それに応じて `setFullYear()` が他の引数と `Date` オブジェクトの日付情報の更新を試みます。例えば、`monthValue` に 15 を指定した場合、年に 1 が加算 (`yearValue + 1`) され、月が 3 になります。

例
-

### setFullYear() の使用

```js
const theBigDay = new Date();
theBigDay.setFullYear(1997);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setfullyear |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCFullYear()`
* `Date.prototype.setUTCFullYear()`
* `Date.prototype.setYear()`


Date.prototype.getUTCMonth() - JavaScript

Date.prototype.getUTCMonth()
============================

**`getUTCMonth()`** メソッドは、協定世界時に基づき、指定された日付の「月」を表す 0 を基点とした値（すなわち 0 が年の最初の月を示す）を返します。

試してみましょう
--------

構文
--

```js
getUTCMonth()
```

### 返値

 数値です。`Date` オブジェクトが有効な日時を表している場合、0 から 11 までの整数値で、指定された日時の月が世界時で何月になるかに対応します。0 は 1 月、1 は 2 月、2 は 3 月、といった具合になります。
 数値です。それ以外の場合は、`Date` オブジェクトが有効な日時を表していなければ `NaN` が返されます。

例
-

### getUTCMonth() の使用

次の例は、現在日時の「月」の部分を変数 `month` に代入します。

```js
const today = new Date();
const month = today.getUTCMonth();
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getutcmonth |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getMonth()`
* `Date.prototype.setUTCMonth()`


Date.prototype.toString() - JavaScript

Date.prototype.toString()
=========================

**`toString()`** メソッドは、指定した `Date` オブジェクトをローカルタイムゾーンで解釈したものを表す文字列を返します。

試してみましょう
--------

構文
--

```js
toString()
```

### 返値

与えられた日付を表す文字列。

解説
--

`Date` オブジェクトは、 `Object` の `toString()` メソッドを上書きします。`Date.prototype.toString()` は、日付と時刻の両方を含む、ローカルタイムゾーンで解釈される Date の文字列表現を返します。これは `toDateString()` と `toTimeString()` で指定した文字列表現を結合し、間に空白を追加したものです。

例: "Thu Jan 01 1970 04:42:04 GMT+0000 (Coordinated Universal Time)"

`toString()` メソッドは、`const today = 'Today is ' + new Date()` のように、日付を文字列に変換する際に自動的に呼び出されます。

`Date.prototype.toString()` は `Date` インスタンスに対して呼び出されなければなりません。もし `this` 値が `Date.prototype` を継承していない場合、 `TypeError` が発生します。

* *日付* の部分を取得したい場合は、 `toDateString()` を使用してください。
* *時刻* の部分を取得したい場合は、 `toTimeString()` を使用してください。
* 日付をローカルタイムゾーンではなく UTC として解釈したい場合は、 `toUTCString()` を使用してください。
* 日付をもっとユーザーが読みやすい形式（例えばローカライズ）で整形したい場合は、 `toLocaleString()` を使用してください。
例
-

### toString() の使用

```js
const x = new Date();
console.log(x.toString()); // Mon Sep 08 1998 14:36:22 GMT-0700 (PDT)
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tostring |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Object.prototype.toString()`
* `Date.prototype.toDateString()`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toTimeString()`


Date.prototype.toJSON() - JavaScript

Date.prototype.toJSON()
=======================

**`toJSON()`** メソッドは、`Date` オブジェクトの文字列表現を返します。

試してみましょう
--------

構文
--

```js
toJSON()
```

### 返値

与えられた日付を表す文字列。

解説
--

`Date` インスタンスは、特定の時点を参照します。`toJSON()` の呼び出しは、`Date` オブジェクトの値を表す文字列 (`toISOString()` を使用) を返します。このメソッドは、既定で、 `Date` オブジェクトを JSON シリアライズ中に有益にシリアライズし、その後、 `Date()` コンストラクター または `Date.parse()` の更新版としての `JSON.parse()` を使用してデシリアライズできるようにすることが一般に意図されています。

例
-

### toJSON() を使う

```js
const jsonDate = new Date().toJSON();
const backToDate = new Date(jsonDate);

console.log(jsonDate); // 2015-10-26T07:46:36.611Z
```

### シリアライズの往復

日付文字列を含む JSON を解釈する場合、 `Date.parse()` を使用して、元の日付オブジェクトに復活させることができます。

```js
const fileData = {
  author: "John",
  title: "Date.prototype.toJSON()",
  createdAt: new Date(2019, 3, 15),
  updatedAt: new Date(2020, 6, 26),
};
const response = JSON.stringify(fileData);

// ネットワーク経由での送信をイメージ

const data = JSON.parse(response, (key, value) => {
  if (key === "createdAt" || key === "updatedAt") {
    return Date.parse(value);
  }
  return value;
});

console.log(data);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.tojson |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toTimeString()`
* `Date.prototype.toUTCString()`


Date.prototype.setUTCDate() - JavaScript

Date.prototype.setUTCDate()
===========================

**`setUTCDate()`** メソッドは、指定された `Date` インスタンスの「日」を UTC 時刻に基づいて変更します。

ローカル時間に基づいて指定された `Date` インスタンスの「日」を変更するには、 `setDate()` メソッドを使用してください。

試してみましょう
--------

構文
--

```js
setUTCDate(dayValue)
```

### 引数

`dayValue`

任意。「日」を表す 1 から 31 までの間の整数値。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日時までの間のミリ秒単位の数値。

解説
--

もし `dayValue` がその月の日付値の範囲外だった場合、 `setDate()` は `Date` オブジェクトをそれに応じて更新します。

例えば、 `dayValue` に 0 が指定された場合、日付は前月の最終日に設定されます。もし `dayValue` に 40 を使用した場合、`Date` オブジェクトに格納されている月が 6 月であれば、日は 10 に変更され、月は 7 月に増加します。

もし `dayValue` に負の数が指定された場合、日付は前月の最終日から逆算して設定されます。 -1 の場合、日付は前月の最終日の 1 日前に設定されます。

例
-

### setUTCDate() の使用

```js
const theBigDay = new Date();
theBigDay.setUTCDate(20);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcdate |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCDate()`
* `Date.prototype.setDate()`


Date.prototype.setHours() - JavaScript

Date.prototype.setHours()
=========================

**`setHours()`** メソッドは、地方時に基づき、指定された日付の「時」を設定し、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された `Date` インスタンスが表す時刻までの間のミリ秒単位の数値を返します。

試してみましょう
--------

構文
--

```js
setHours(hoursValue)
setHours(hoursValue, minutesValue)
setHours(hoursValue, minutesValue, secondsValue)
setHours(hoursValue, minutesValue, secondsValue, msValue)
```

### 引数

`hoursValue`

理想的には、「時」を表す 0 から 23 までの間の整数値です。23 よりも大きな値が指定された場合は、日時は追加の時間数だけ増加します。

`minutesValue`

任意。理想的には、「分」を表す 0 から 59 までの間の整数値です。59 よりも大きな値が指定された場合は、日時は追加の分数だけ増加します。

`secondsValue`

任意。理想的には、「秒」を表す 0 から 59 までの間の整数値です。59 より大きな値が指定された場合は、日時は追加の秒数だけ増加します。`secondsValue` 引数を指定した場合は、`minutesValue` も指定しなければなりません。

`msValue`

任意。理想的には、ミリ秒を表す 0 から 999 までの間の整数値です。999 よりも大きな値が指定された場合は、日時は追加のミリ秒数だけ増加します。`msValue` 引数を指定した場合、`minutesValue` と `secondsValue` も指定しなければなりません。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日時までの間のミリ秒単位の数値。

解説
--

`minutesValue`, `secondsValue` および `msValue` 引数を指定しなかった場合、`getMinutes()` と `getSeconds()`、`getMilliseconds()` メソッドから返される値が使われます。

指定した値が期待される日付の範囲外の場合、それに応じて `setHours()` が他の引数と `Date` オブジェクトの日付情報の更新を試みます。例えば、`secondsValue` に 100 を指定した場合、分に 1 加算 (`minutesValue + 1`) され、秒が 40 になります。

例
-

### setHours() の使用

```js
const theBigDay = new Date();
theBigDay.setHours(7);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.sethours |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getHours()`
* `Date.prototype.setUTCHours()`


Date.prototype[@@toPrimitive] - JavaScript

Date.prototype[@@toPrimitive]
=============================

**`[@@toPrimitive]()`** メソッドは、 `Date` オブジェクトをプリミティブ値に変換します。

試してみましょう
--------

構文
--

```js
Date()[Symbol.toPrimitive](hint)
```

### 返値

与えられた `Date` オブジェクトのプリミティブ値です。引数に応じて、このメソッドは文字列と数値のどちらかを返します。

解説
--

`Date` オブジェクトの `[@@toPrimitive]()` メソッドは、プリミティブ値を返します。これは、数値型または文字列型です。

`hint` が `string` または `default` の場合、`[@@toPrimitive]()` は `toString` メソッドを呼び出そうとします。 `toString` メソッドが存在しなければ、 `valueOf` メソッドを呼び出そうとします。 `valueOf` メソッドも存在しなければ、 `[@@toPrimitive]()` は `TypeError` を発生させます。

`hint` が `number` の場合、 `[@@toPrimitive]()` は初めに `valueOf` メソッドを呼び出そうとします。これが失敗した場合は、 `toString` メソッドを呼び出します。

JavaScript は、 `[@@toPrimitive]()` メソッドを呼び出してオブジェクトをプリミティブ値に変換します。 `[@@toPrimitive]()` メソッドを自分で呼び出す必要はほとんどありません。 JavaScript は、プリミティブ値が期待されるオブジェクトに遭遇した時、自動的にこれを呼び出します。

例
-

### 日付プリミティブの返却

```js
const testDate = new Date(1590757517834);
// "Date Fri May 29 2020 14:05:17 GMT+0100 (British Summer Time)"

testDate[Symbol.toPrimitive]("string");
// "Date Fri May 29 2020 14:05:17 GMT+0100 (British Summer Time)" を返す

testDate[Symbol.toPrimitive]("number");
// "1590757517834" を返す

testDate[Symbol.toPrimitive]("default");
// "Date Fri May 29 2020 14:05:17 GMT+0100 (British Summer Time)" を返す
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype-@@toprimitive |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Symbol.toPrimitive`


Date.parse() - JavaScript

Date.parse()
============

**`Date.parse()`** メソッドは、日時を表す文字列を解釈し、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 からの経過時間を表すミリ秒単位の数値を返します。または、文字列を解釈できなかったり不正な日付（例えば 2015-02-31）が指定されたりした場合は `NaN` を返します。

対応するよう明示的に指定されているのは ISO 8601 形式 (`YYYY-MM-DDTHH:mm:ss.sssZ`) のみです。他の形式は実装で定義されており、すべてのブラウザーで動作するとは限りません。多くの様々な形式に対応するためには、ライブラリーが役に立ちます。

試してみましょう
--------

構文
--

```js
Date.parse(dateString)
```

### 引数

`dateString`

 文字列で、ISO 8601 カレンダー日付拡張形式の簡略化されたものを表します。
 （その他の形式も使用することができますが、結果は実装依存になります。）

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 UTC からの経過時間をミリ秒単位で表す数値。このメソッドに与えられた日付を表す文字列の解釈により取得される日付。引数に正しい値が与えられなかった場合、 `NaN` を返します。

解説
--

`parse()` メソッドは、日時の文字列（例えば `"2011-10-10T14:48:00"`）を取り、協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 からのミリ秒単位の経過時間を表す数値を返します。

この関数は、例えば `setTime()` メソッドと `Date` オブジェクトを組み合わせて使う場合など、文字列値を基にして日時の値を設定するときに便利です。

### 日付と時刻の文字列書式

日時文字列の標準的な文字列表現は、 ISO 8601 のカレンダー日付拡張形式を簡略化したものです。（詳しくは、 ECMAScript 仕様書の Date Time String Format の章を参照してください。）

例えば、 `"2011-10-10"` （*日付のみ*の形式）、`"2011-10-10T14:48:00"` （*日時*形式）、`"2011-10-10T14:48:00.000+09:00"` （*日時*形式にミリ秒とタイムゾーンがついたもの）を渡し、解釈することができます。タイムゾーンのオフセットがない場合は、日付のみの形式では UTC 時刻と解釈され、日時形式では地方時として解釈されます。

タイムゾーン指定子は、日付文字列の解析中に引数を解釈するために使用されますが、返される値は常に、 1970 年 1 月 1 日 00:00:00 UTC と、引数で表される時点との間のミリ秒数または `NaN` です。

`parse()` は `Date` の静的メソッドですので、 `Date` インスタンスのメソッドとしてではなく `Date.parse()` として呼び出されます。

### 実装依存の日付形式へのフォールバック

**メモ:** この節では実装依存の動作を説明しており、実装間で一貫性がない可能性があります。

ECMAScript 仕様書は、文字列が標準の書式に準拠していない場合、この関数は実装固有の検出方法や実装固有の解析アルゴリズムにフォールバックすることがあり、解釈できない文字列や ISO 書式文字列における不正な要素値を含む日付を渡すと、 `Date.parse()` が `NaN` を返すと規定しています。

しかし、 ECMA-262 で定義されている簡略化 ISO 書式として解釈できない日付文字列の無効な値は、ブラウザーや与えられた値に依存して、 `NaN` を返したり返さなかったりすることがあります。次の例を参照してください。

```js
// 不正な値を持つ 非 ISO 文字列
new Date("23/25/2014");
```

これは、 Firefox 30 では、地方時の 2015 年 11 月 25 日として扱われ、 Safari 7 では不正な値として処理されます。

しかし、文字列が ISO 書式の文字列として解釈され、不正な値を含む場合、 ES5 以降の仕様に準拠するすべてのブラウザーが `NaN` を返します。

```js
// 不正な値を持つ ISO 文字列
new Date("2014-25-23").toISOString();
// ES5 準拠のすべてのブラウザーが "RangeError: invalid date" を返す
```

SpiderMonkey の実装特有のヒューリスティックは、`jsdate.cpp` にあります。 `"10 06 2014"` の文字列は、非 ISO 書式の例として挙げられており、このようにカスタム処理にフォールバックされます。この解釈の動作を説明するおよそのアウトライン も参照してください。

```js
new Date("10 06 2014");
```

これは、2014 年 6 月 10 日ではなく、地方時の 2014 年 10 月 6 日 として扱われます。

他の例です。

```js
new Date("foo-bar 2014").toString();
// 返値: "Invalid Date"

Date.parse("foo-bar 2014");
// 返値: NaN
```

### 想定されるタイムゾーンの違い

**メモ:** この節では実装依存の動作を説明しており、実装間で一貫性がない可能性があります。

標準外の日付文字列である `"March 7, 2014"` を渡すと、 `parse()` はタイムゾーンとして地方時を想定しますが、 `"2014-03-07"` のような ISO 書式を与えると UTC をタイムゾーンとして想定します (ES5 および ECMAScript 2015 の仕様)。したがって、これらの文字列を使用して生成される `Date` オブジェクトは、システムが UTC の地方時に設定されていない限り、対応している ECMAScript のバージョンによって異なる時刻を表す可能性があります。つまり、同じように見える 2 つの日付文字列が、変換される文字列の形式によって 2 つの異なる値になる可能性があるということです。

例
-

### Date.parse() の使用

以下の呼び出しはすべて `1546300800000` を返します。最初のものは ES5 によれば UTC 時刻を意味し、それ以外は ISO 日付仕様 (`Z` および `+00:00`) に従って UTC をタイムゾーンを指定しています。

```js
Date.parse("2019-01-01");
Date.parse("2019-01-01T00:00:00.000Z");
Date.parse("2019-01-01T00:00:00.000+00:00");
```

以下の呼び出しではタイムゾーンを指定していないので、システムの地方時で 2019-01-01 の 00:00:00 に設定されます。

```js
Date.parse("2019-01-01T00:00:00");
```

### 標準外の日付文字列

**メモ:** この節では実装依存の動作を説明しており、実装間で一貫性がない可能性があります。

`IPOdate` が既存の `Date` オブジェクトならば、次のようにして、これを 1995 年 8 月 9 日 (地方時) にセットできます:

```js
IPOdate.setTime(Date.parse("Aug 9, 1995"));
```

それ以外の標準外の日付文字列の解釈の例を示します。

```js
Date.parse("Aug 9, 1995");
```

GMT-0300 のタイムゾーンでは `807937200000` を返し、他のタイムゾーンでは他の値を返します。タイムゾーンが指定されておらず ISO 書式でないため、既定で地方時のタイムゾーンが使用されます。

```js
Date.parse("Wed, 09 Aug 1995 00:00:00 GMT");
```

GMT (UTC) が指定されているため、地方時のタイムゾーンに関係なく `807926400000` を返します。

```js
Date.parse("Wed, 09 Aug 1995 00:00:00");
```

GMT-0300 のタイムゾーンでは `807937200000` を返し、他のタイムゾーンでは他の値を返します。引数にタイムゾーンが指定されておらず、 ISO 書式ではないため、地方時として扱われます。

```js
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT");
```

GMT (UTC) のタイムゾーンが指定されているため、地方時のタイムゾーンに関係なく `0` を返します。

```js
Date.parse("Thu, 01 Jan 1970 00:00:00");
```

GMT-0400 のタイムゾーンでは `14400000` を返し、他のタイムゾーンでは他の値を返します。タイムゾーンが指定されておらず、 ISO 書式ではないため、地方時のタイムゾーンが使用されます。

```js
Date.parse("Thu, 01 Jan 1970 00:00:00 GMT-0400");
```

GMT (UTC) のタイムゾーンが指定されているため、地方時のタイムゾーンに関係なく `14400000` を返します。

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.parse |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### 互換性ノート

* Firefox 49 で、2 桁の「年」の解釈が、 Internet Explorer に代わって Google Chrome ブラウザーに準拠するように変更されました。現在、 `50` 以下の 2 桁の「年」は 21 世紀の年として解釈されます。例えば `04/16/17` は、以前は 1917 年 4 月 16 日と解釈されていましたが、 2017 年 4 月 16 日と解釈されるようになりました。相互運用性の問題や年があいまいになることを回避するには、 ISO 8601 書式 (`"2017-04-16"` など) の使用が推奨されます (bug 1265136)。
* Google Chrome は数値の文字列を有効な `dateString` 引数として受け付けます。これは、すなわち、 `!!Date.parse("42")` は Firefox では `false` として評価されるのに対して、 Google Chrome では `true` として評価されます。 "`42`" は 2042 年 1 月 1 日と解釈されるからです。
関連情報
----

* `Date.UTC()`


Date.prototype.setUTCSeconds() - JavaScript

Date.prototype.setUTCSeconds()
==============================

**`setUTCSeconds()`** メソッドは、協定世界時に基づき、指定された日時の「秒」を設定します。

試してみましょう
--------

構文
--

```js
setUTCSeconds(secondsValue)
setUTCSeconds(secondsValue, msValue)
```

### 引数

`secondsValue`

「秒」を表す 0 から 59 までの間の整数値。

`msValue`

任意。ミリ秒を表す 0 から 999 までの間の整数値。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から更新された日時までの間のミリ秒単位の数値。

解説
--

`msValue` 引数を指定しない場合、`getUTCMilliseconds()` メソッドから返される値が使われます。

指定した値が期待される日時の範囲外の場合、それに応じて `setUTCSeconds()` が `Date` オブジェクトの日付情報の更新を試みます。例えば、`secondsValue` に 100 を指定した場合、分に 1 加算され、秒が 40 になります。

例
-

### setUTCSeconds() の使用

```js
const theBigDay = new Date();
theBigDay.setUTCSeconds(20);
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setutcseconds |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCSeconds()`
* `Date.prototype.setSeconds()`


Date.prototype.setDate() - JavaScript

Date.prototype.setDate()
========================

**`setDate()`** メソッドは、現在設定されている月から始まる `Date` オブジェクトの「日」を設定します。

指定された日時の月日を UTC 時間に基づいて変更するには、代わりに `setUTCDate()` メソッドを使用してください。

試してみましょう
--------

構文
--

```js
setDate(dayValue)
```

### 引数

`dayValue`

「日」を表す整数の値です。

### 返値

協定世界時 (UTC) 1970 年 1 月 1 日 00:00:00 から与えられた日付までの間のミリ秒単位の数値（`Date` オブジェクトも適切に変更されます）。

解説
--

`dayValue` がその月の日付の範囲外の値の場合、それに応じて `setDate()` が `Date` オブジェクトを更新します。

例えば、 `dayValue` に 0 が指定された場合、日付は前の月の最終日に設定されます。もし `dayValue` に 40 を使用した場合、 `Date` オブジェクトに格納された月が 6 月であれば、日は 10 に変更され、月は 7 月に増加します。

もし `dayValue` に負の数が指定された場合、前月の最終日から逆算して日付が設定されます。 -1 を指定すると、前月の最終日の 1 日前に日付が設定されます。

例
-

### setDate() の使用

```js
const theBigDay = new Date(1962, 6, 7, 12); // noon of 1962-07-07 (7th of July 1962, month is 0-indexed)
const theBigDay2 = new Date(theBigDay).setDate(24); // 1962-07-24 (24th of July 1962)
const theBigDay3 = new Date(theBigDay).setDate(32); // 1962-08-01 (1st of August 1962)
const theBigDay4 = new Date(theBigDay).setDate(22); // 1962-07-22 (22nd of July 1962)
const theBigDay5 = new Date(theBigDay).setDate(0); // 1962-06-30 (30th of June 1962)
const theBigDay6 = new Date(theBigDay).setDate(98); // 1962-10-06 (6th of October 1962)
const theBigDay7 = new Date(theBigDay).setDate(-50); // 1962-05-11 (11th of May 1962)
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.setdate |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date()`
* `Date.prototype.getDate()`
* `Date.prototype.setUTCDate()`


Date.prototype.toTimeString() - JavaScript

Date.prototype.toTimeString()
=============================

**`toTimeString()`** メソッドは、英語の人間が読める形式で `Date` オブジェクトの「時刻」部を返します。

試してみましょう
--------

構文
--

```js
toTimeString()
```

### 返値

英語の人間が読める形式で、与えられた日付の「時刻」部を表す文字列を返します。

解説
--

`Date` インスタンスは特定の時点を参照します。`toTimeString()` は日付をローカルのタイムゾーンで解釈し、*時刻* の部分を英語の書式にします。これは常に `hh:mm:ss GMT±xxxx (TZ)` の形式を使用します。

| 書式文字列 | 説明 |
| --- | --- |
| `hh` | 時間、2 桁（必要であれば先頭の 0 を含む）。 |
| `mm` | 分、2 桁（必要であれば先頭の 0 を含む）。 |
| `ss` | 秒、2 桁（必要であれば先頭の 0 を含む）。 |
| `±xxxx` | ローカルタイムゾーンのオフセット - 時：2桁、分：2桁 (e.g. `-0500`, `+0800`) |
| `TZ` | ローカルタイムゾーンの名前（`PDT`, `PST` など） |

例: "04:42:04 GMT+0000 (Coordinated Universal Time)".

* *日付* の部分を取得したい場合は、 `toDateString()` を使用してください。
* 日付と時刻の両方を取得したい場合は、 `toString()` を使用してください。
* 日付をローカルタイムゾーンではなく UTC として解釈したい場合は、 `toUTCString()` を使用してください。
* 日付をもっとユーザーが読みやすい形式（例えばローカライズ）で整形したい場合は、 `toLocaleTimeString()` を使用してください。
例
-

### toTimeString() の基本的な使い方

```js
const d = new Date(1993, 6, 28, 14, 39, 7);

console.log(d.toString()); // Wed Jul 28 1993 14:39:07 GMT-0600 (PDT)
console.log(d.toTimeString()); // 14:39:07 GMT-0600 (PDT)
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.totimestring |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.toLocaleTimeString()`
* `Date.prototype.toDateString()`
* `Date.prototype.toString()`


Date.prototype.getMinutes() - JavaScript

Date.prototype.getMinutes()
===========================

**`getMinutes()`** メソッドは、地方時に基づき、指定された日時の「分」を返します。

試してみましょう
--------

構文
--

```js
getMinutes()
```

### 返値

地方時に基づき、与えた日時の「分」を表す 0 から 59 までの間の整数値。

例
-

### getMinutes() の使用

以下の 2 行目の文は、`Date` オブジェクトである `xmas95` の値に基づき、変数 `minutes` に 15 という値を代入します。

```js
const xmas95 = new Date("December 25, 1995 23:15:30");
const minutes = xmas95.getMinutes();

console.log(minutes); // 15
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-date.prototype.getminutes |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Date.prototype.getUTCMinutes()`
* `Date.prototype.setMinutes()`


BigInt64Array() コンストラクター - JavaScript

BigInt64Array() コンストラクター
========================

**`BigInt64Array()`** は型付き配列のコンストラクターで、新しい `BigInt64Array` オブジェクト、すなわち 64 ビット符号付き整数の配列をプラットフォームのバイトオーダーで生成します。バイトオーダーを制御する必要がある場合は、代わりに `DataView` を使用してください。中身は `0n` で初期化されます。生成後は、オブジェクトのメソッドや、標準の配列の添字構文 (すなわち角括弧表記) を用いて配列の要素を参照することができます。

構文
--
```

new BigInt64Array();
new BigInt64Array(length);
new BigInt64Array(typedArray);
new BigInt64Array(object);
new BigInt64Array(buffer [, byteOffset [, length]]);
```

### 引数

`length`

`length` 引数付きで呼び出された場合、 `length` を *`BYTES_PER_ELEMENT` バイトで掛けた大きさ*で、内部の配列バッファーがメモリ内に生成され、内容がゼロになります。

`typedArray`

`typedArray` 引数は任意の型付き配列 (`Int32Array` など) で、 `typedArray` を付けて呼び出された場合、その内容が新しい型付き配列に複写されます。 `typedArray` に含まれるそれぞれの値は、新しい配列にコピーされる前に、このコンストラクターに対応する型に変換されます。新しい型付き配列の長さは、 `typedArray` 引数の長さと同じになります。

`object`

`object` 引数付きで呼び出された場合、新しい型付き配列は `TypedArray.from()` メソッドのようにして生成されます。

`buffer`, `byteOffset`, `length`

`buffer` 引数と、任意で `byteOffset` および `length` 引数をつけて呼び出された場合、新しい型付き配列のビューが作成され、そのビューが指定された `ArrayBuffer` となります。 `byteOffset` および `length` 引数は、型付き配列のビューで公開するメモリの範囲を指定します。両方が省略された場合は、 `buffer` 全体がビューとなり、 `length` のみが省略された場合は、 `buffer` の残りがビューとなります。

例
-

### BigInt64Array を生成するための様々な方法

```js
// From a length
var bigint64 = new BigInt64Array(2);
bigint64[0] = 42n;
console.log(bigint64[0]); // 42n
console.log(bigint64.length); // 2
console.log(bigint64.BYTES\_PER\_ELEMENT); // 8

// From an array
var arr = new BigInt64Array([21n, 31n]);
console.log(arr[1]); // 31n

// From another TypedArray
var x = new BigInt64Array([21n, 31n]);
var y = new BigInt64Array(x);
console.log(y[0]); // 21n

// From an ArrayBuffer
var buffer = new ArrayBuffer(32);
var z = new BigInt64Array(buffer, 0, 4);

// From an iterable
var iterable = (function\* () {
  yield\* [1n, 2n, 3n];
})();
var bigint64 = new BigInt64Array(iterable);
// BigInt64Array[1n, 2n, 3n]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-typedarray-constructors |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* JavaScript typed arrays
* `BigUint64Array`
* `DataView`


RangeError() コンストラクター - JavaScript

RangeError() コンストラクター
=====================

**`RangeError()`** コンストラクターは、値が存在しないか許可された値の範囲にない場合のエラーを生成します。

構文
--
```

new RangeError([message[, fileName[, lineNumber]]])
```

### 引数

`message` 省略可

人間が読むためのエラーの説明です。

`fileName` 省略可

例外が発生したコードを含むファイルの名前です。

`lineNumber` 省略可

例外が発生したコードの行番号です。

例
-

### RangeError の使用 (数値)

```js
function check(n) {
  if (!(n >= -500 && n <= 500)) {
    throw new RangeError("The argument must be between -500 and 500.");
  }
}

try {
  check(2000);
} catch (error) {
  if (error instanceof RangeError) {
    // Handle the error
  }
}
```

### RangeError の使用 (数値以外)

```js
function check(value) {
  if (["apple", "banana", "carrot"].includes(value) === false) {
    throw new RangeError(
      'The argument must be an "apple", "banana", or "carrot".',
    );
  }
}

try {
  check("cabbage");
} catch (error) {
  if (error instanceof RangeError) {
    // Handle the error
  }
}
```

仕様書
---

| Specification |
| --- |
| ECMAScript Language Specification # sec-nativeerror-constructors |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Error`
* `Array`
* `Number.toExponential()`
* `Number.toFixed()`
* `Number.toPrecision()`
* `String.prototype.normalize()`


Intl.NumberFormat - JavaScript

Intl.NumberFormat
=================

**`Intl.NumberFormat`** オブジェクトは、言語に依存した数値書式を可能にするオブジェクトのコンストラクターです。

試してみましょう
--------

コンストラクター
--------

`Intl.NumberFormat()`

新しい `NumberFormat` オブジェクトを生成します。

静的メソッド
------

`Intl.NumberFormat.supportedLocalesOf()`

提供されたロケールのうち、実行時の既定のロケールにフォールバックせずにサポートされるものを配列に納めて返します。

インスタンスメソッド
----------

`Intl.NumberFormat.prototype.format`

ゲッター関数で、ローケルに応じて、この `NumberFormat` オブジェクトのオプションを持つ数値を書式化する関数を返します。

`Intl.NumberFormat.prototype.formatToParts()`

オブジェクトの `Array` を返し、これは専用のロケールを意識した書式で使用することができる部品内の数値文字列を表します。

`Intl.NumberFormat.prototype.resolvedOptions()`

ローケルを反映しているプロパティとオブジェクトの初期化中に計算された照合オプションをもった新しいオブジェクトを返します。

例
-

### 基本的な使用

ローケルを指定しない基本的な使い方では、既定のローケルとオプションで書式化された文字列が返されます。

```js
var number = 3500;

console.log(new Intl.NumberFormat().format(number));
// → '3,500' 英語(U.S.)ロケールの場合
```

### locales の使用

この例では、地域による数値書式の違いをいくつか紹介します。アプリケーションのユーザーインターフェイスで使われた言語書式を得るには、言語 (およびフォールバック言語) を `locales` 引数により指定してください。

```js
var number = 123456.789;

// ドイツではカンマを小数、ピリオドを千単位の区切りに用います
console.log(new Intl.NumberFormat("de-DE").format(number));
// → 123.456,789

// ほとんどのアラビア語圏ではアラビア数字を用います
console.log(new Intl.NumberFormat("ar-EG").format(number));
// → ١٢٣٤٥٦٫٧٨٩

// インドでは thousands/lakh/crore 区切りが用いられます
console.log(new Intl.NumberFormat("en-IN").format(number));
// → 1,23,456.789

// nu 拡張キーにより漢数字などの番号方式が使えます
console.log(new Intl.NumberFormat("zh-Hans-CN-u-nu-hanidec").format(number));
// → 一二三,四五六.七八九

// バリ語のようにサポートされないかもしれない言語を用いる場合は
// フォールバック言語を含めます。次の例ではインドネシア語です。
console.log(new Intl.NumberFormat(["ban", "id"]).format(number));
// → 123.456,789
```

### options の使用

`options`引数を使うと結果をカスタマイズできます。

```js
var number = 123456.789;

// 通貨フォーマットを用います
console.log(
  new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR" }).format(
    number,
  ),
);
// → 123.456,79 €

// 日本円には小数点以下がありません
console.log(
  new Intl.NumberFormat("ja-JP", { style: "currency", currency: "JPY" }).format(
    number,
  ),
);
// → ￥123,457

// 有効数字を3桁に狭めます
console.log(
  new Intl.NumberFormat("en-IN", { maximumSignificantDigits: 3 }).format(
    number,
  ),
);
// → 1,23,000
```

### style と unit の使用

```js
console.log(
  new Intl.NumberFormat("pt-PT", {
    style: "unit",
    unit: "mile-per-hour",
  }).format(50),
);
// → 50 mi/h

console.log(
  (16).toLocaleString("en-GB", {
    style: "unit",
    unit: "liter",
    unitDisplay: "long",
  }),
);
// → 16 litres
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # numberformat-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`


Intl.ListFormat - JavaScript

Intl.ListFormat
===============

**`Intl.ListFormat`** オブジェクトは、言語を考慮したリストの整形ができるようにします。

試してみましょう
--------

コンストラクター
--------

`Intl.ListFormat()`

新しい `Intl.ListFormat` オブジェクトを作成します。

静的メソッド
------

`Intl.ListFormat.supportedLocalesOf()`

指定したロケールのうち、ランタイムの既定のロケールに代替されることなく対応しているものを含む配列を返します。

インスタンスメソッド
----------

`Intl.ListFormat.prototype.format()`

リストの要素を表す、言語を考慮して書式化された文字列を返します。

`Intl.ListFormat.prototype.formatToParts()`

ロケールを考慮した方法で値のリストを書式化するために使用できる、さまざまな部分を表すオブジェクトの配列を返します。

`Intl.ListFormat.prototype.resolvedOptions()`

現在の `Intl.ListFormat` オブジェクトの構築時に計算されたロケールおよびスタイルの書式化オプションを反映したプロパティを持つ、新しいオブジェクトを返します。

例
-

### format の使用

次の例は、英語を使用したリストフォーマッターの作成方法です。

```js
const list = ["Motorcycle", "Bus", "Car"];

console.log(
  new Intl.ListFormat("en-GB", { style: "long", type: "conjunction" }).format(
    list,
  ),
);
// > Motorcycle, Bus and Car

console.log(
  new Intl.ListFormat("en-GB", { style: "short", type: "disjunction" }).format(
    list,
  ),
);
// > Motorcycle, Bus or Car

console.log(
  new Intl.ListFormat("en-GB", { style: "narrow", type: "unit" }).format(list),
);
// > Motorcycle Bus Car
```

### formatToParts の使用

次の例では、整形済みの部分を返すリストフォーマッターを生成する方法を示します。

```js
const list = ["Motorcycle", "Bus", "Car"];
console.log(
  new Intl.ListFormat("en-GB", {
    style: "long",
    type: "conjunction",
  }).formatToParts(list),
);

// [ { "type": "element", "value": "Motorcycle" },
// { "type": "literal", "value": ", " },
// { "type": "element", "value": "Bus" },
// { "type": "literal", "value": ", and " },
// { "type": "element", "value": "Car" } ];
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # listformat-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`
* FormatJS の `Intl.ListFormat` のポリフィル


Intl.DisplayNames - JavaScript

Intl.DisplayNames
=================

**`Intl.DisplayNames`** オブジェクトは、言語、地域、文字体系の表示名の一貫した翻訳を可能にします。

試してみましょう
--------

コンストラクター
--------

`Intl.DisplayNames()`

`Intl.DisplayNames` オブジェクトを作成します。

静的メソッド
------

`Intl.DisplayNames.supportedLocalesOf()`

提供されたロケールのうち、ランタイムの既定のロケールに代替されることなく対応しているロケールを含む配列を返します。

インスタンスメソッド
----------

`Intl.DisplayNames.prototype.of()`

このメソッドは `code` を受け取り、`Intl.DisplayNames` をインスタンス化したときに指定したロケールとオプションに基づく文字列を返します。

`Intl.DisplayNames.prototype.resolvedOptions()`

オブジェクトの初期化時に計算されたロケールや書式設定のオプションを反映したプロパティを持つ新しいオブジェクトを返します。

例
-

### 国 (地域) の表示名

ロケールを指定して `Intl.DisplayNames` を作成し、国 (地域) コードの表示名を取得する方法です。

```js
// 英語の地域名を表示
let regionNames = new Intl.DisplayNames(['en'], {type: 'region'});
regionNames.of('419'); // "Latin America"
regionNames.of('BZ');  // "Belize"
regionNames.of('US');  // "United States"
regionNames.of('BA');  // "Bosnia & Herzegovina"
regionNames.of('MM');  // "Myanmar (Burma)"

// 繁体字中国語での地域名を表示
regionNames = new Intl.DisplayNames(['zh-Hant'], {type: 'region'});
regionNames.of('419'; // "拉丁美洲"
regionNames.of('BZ'); // "貝里斯"
regionNames.of('US'); // "美國"
regionNames.of('BA'); // "波士尼亞與赫塞哥維納"
regionNames.of('MM'); // "緬甸"
```

### 言語の表示名

ロケールを指定して `Intl.DisplayNames` を作成し、言語-文字体系-国 (地域) の一連の表示名を取得する方法です。

```js
// 英語の言語名を表示
let languageNames = new Intl.DisplayNames(["en"], { type: "language" });
languageNames.of("fr"); // "French"
languageNames.of("de"); // "German"
languageNames.of("fr-CA"); // "Canadian French"
languageNames.of("zh-Hant"); // "Traditional Chinese"
languageNames.of("en-US"); // "American English"
languageNames.of("zh-TW"); // "Chinese (Taiwan)"]

// 繁体字中国語での言語名を表示
languageNames = new Intl.DisplayNames(["zh-Hant"], { type: "language" });
languageNames.of("fr"); // "法文"
languageNames.of("zh"); // "中文"
languageNames.of("de"); // "德文"
```

### 文字体系コードの表示名

ロケールを指定して `Intl.DisplayNames` を作成し、文字体系の表示名を取得する方法です。

```js
// 英語の文字体系名を表示
let scriptNames = new Intl.DisplayNames(["en"], { type: "script" });
// Get script names
scriptNames.of("Latn"); // "Latin"
scriptNames.of("Arab"); // "Arabic"
scriptNames.of("Kana"); // "Katakana"

// 繁体字中国語での文字体系名を表示
scriptNames = new Intl.DisplayNames(["zh-Hant"], { type: "script" });
scriptNames.of("Latn"); // "拉丁文"
scriptNames.of("Arab"); // "阿拉伯文"
scriptNames.of("Kana"); // "片假名"
```

### 通貨コードの表示名

ロケールを指定して `Intl.DisplayNames` を作成し、通貨の表示名を取得する方法です。

```js
// 英語の通貨名を表示
let currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });
// Get currency names
currencyNames.of("USD"); // "US Dollar"
currencyNames.of("EUR"); // "Euro"
currencyNames.of("TWD"); // "New Taiwan Dollar"
currencyNames.of("CNY"); // "Chinese Yuan"

// 繁体字中国語の通貨名を表示
currencyNames = new Intl.DisplayNames(["zh-Hant"], { type: "currency" });
currencyNames.of("USD"); // "美元"
currencyNames.of("EUR"); // "歐元"
currencyNames.of("TWD"); // "新台幣"
currencyNames.of("CNY"); // "人民幣"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # intl-displaynames-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`


Intl.getCanonicalLocales() - JavaScript

Intl.getCanonicalLocales()
==========================

**`Intl.getCanonicalLocales()`** メソッドは、正規のロケール名を含む配列を返します。重複は省略され、要素は構造的に有効な言語タグとして検証されます。

試してみましょう
--------

構文
--
```

Intl.getCanonicalLocales(locales)
```

### 引数

`locales`

標準ロケール名を取得するための `String` 値リスト。

### 返値

正規のロケール名を含む配列です。

例
-

### getCanonicalLocales の使用

```js
Intl.getCanonicalLocales("EN-US"); // ["en-US"]
Intl.getCanonicalLocales(["EN-US", "Fr"]); // ["en-US", "fr"]

Intl.getCanonicalLocales("EN\_US");
// RangeError:'EN\_US' is not a structurally valid language tag
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.getcanonicallocales |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.NumberFormat.supportedLocalesOf()`
* `Intl.DateTimeFormat.supportedLocalesOf()`
* `Intl.Collator.supportedLocalesOf()`


Intl.PluralRules - JavaScript

Intl.PluralRules
================

**`Intl.PluralRules`** オブジェクトは、複数形が影響する書式や言語ルールを使用できるようにします。

コンストラクター
--------

`Intl.PluralRules()`

新しい Intl.PluralRules オブジェクトを生成します。

静的メソッド
------

`Intl.PluralRules.supportedLocalesOf()`

指定したロケールのうち、ランタイムの既定のロケールに代替されることなく対応されているものが入った配列を返します。

インスタンスメソッド
----------

`Intl.PluralRules.prototype.resolvedOptions()`

オブジェクトの初期化中に計算されたロケールとコレクションのオプションを反映したプロパティを持った新しいオブジェクトを返します。

`Intl.PluralRules.prototype.select()`

ロケールを考慮した書式化に使用する複数形を示す文字列を返します。

`Intl.PluralRules.prototype.selectRange()`

このメソッドは 2 つの値を受け取り、ロケールを考慮した書式化に使用する複数形を示す文字列を返します。

例
-

### locales の使用

この例では、ローカライズされた複数形ルールのいくつかを表示します。アプリケーションのユーザーインターフェイスで使う言語の書式を取得するには、 `locales` 引数に言語（および必要に応じて代替言語）を指定してください。

```js
// アラビア語は様々な複数形の規則を持っています

new Intl.PluralRules("ar-EG").select(0);
// → 'zero'
new Intl.PluralRules("ar-EG").select(1);
// → 'one'
new Intl.PluralRules("ar-EG").select(2);
// → 'two'
new Intl.PluralRules("ar-EG").select(6);
// → 'few'
new Intl.PluralRules("ar-EG").select(18);
// → 'many'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # pluralrules-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`
* `Intl.PluralRules` の FormatJS におけるポリフィル


Intl.Segmenter - JavaScript

Intl.Segmenter
==============

**`Intl.Segmenter`** オブジェクトは、ロケールに応じたテキストのセグメンテーションを可能にし、文字列から意味のある項目（書記素、単語、文）を取得することができます。

試してみましょう
--------

コンストラクター
--------

`Intl.Segmenter()`

新しい `Intl.Segmenter` オブジェクトを作成します。

静的メソッド
------

`Intl.Segmenter.supportedLocalesOf()`

指定したロケールのうち、ランタイムのデフォルトロケールにフォールバックすることなくサポートされているものを含む配列を返します。

インスタンスメソッド
----------

`Intl.Segmenter.prototype.resolvedOptions()`

この `Intl.Segmenter` オブジェクトの初期化時に計算されたロケールおよび粒度のオプションを反映したプロパティを持つ新しいオブジェクトを返します。

`Intl.Segmenter.prototype.segment()`

この `Intl.Segmenter` のインスタンスのロケールおよび粒度に従って文字列のセグメントを表す、新しい反復可能な `Segments` のインスタンスを返します。

例
-

### 基本的な使い方と String.prototype.split() との相違点

`String.prototype.split(" ")` を使ってテキストを単語に分割する場合、テキストのロケールが単語間の空白を使用しない場合（つまり、日本語、中国語、タイ語、ラオス語、クメール語、ミャンマー語などの場合）、正しい結果を得ることはできません。

```js
const str = "吾輩は猫である。名前はたぬき。";
console.table(str.split(" "));
// ['吾輩は猫である。名前はたぬき。']
// The two sentences are not correctly segmented.
```

```js
const str = "吾輩は猫である。名前はたぬき。";
const segmenterJa = new Intl.Segmenter("ja-JP", { granularity: "word" });

const segments = segmenterJa.segment(str);
console.table(Array.from(segments));
// [{segment: '吾輩', index: 0, input: '吾輩は猫である。名前はたぬき。', isWordLike: true},
// etc.
// ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # segmenter-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.


Intl.RelativeTimeFormat - JavaScript

Intl.RelativeTimeFormat
=======================

**`Intl.RelativeTimeFormat`** オブジェクトは言語に依存の相対時間の書式化を可能にします。

試してみましょう
--------

コンストラクター
--------

`Intl.RelativeTimeFormat.RelativeTimeFormat()`

新しい `Intl.RelativeTimeFormat` オブジェクトを生成します。

静的メソッド
------

`Intl.RelativeTimeFormat.supportedLocalesOf()` (en-US)

指定されたロケールのうち、実行時の既定のロケールにフォールバックせずに対応されるものを配列に収めて返します。

インスタンスメソッド
----------

`Intl.RelativeTimeFormat.prototype.format()`

`value` および `unit` を、指定された `Intl.RelativeTimeFormat` オブジェクトのロケールと書式化オプションに従って書式化します。

`Intl.RelativeTimeFormat.prototype.formatToParts()`

ロケール固有のカスタムフォーマットに使用可能な相対時間のフォーマットを部分的に表現したオブジェクトの `Array` を返します。

`Intl.RelativeTimeFormat.prototype.resolvedOptions()` (en-US)

オブジェクトの初期化中に計算されたロケールやフォーマットのオプションを反映したプロパティを持つ新しいオブジェクトを返します。

例
-

### 基本的な `format` の使用例

以下は英語の相対時間フォーマッターの使い方の例です。

```js
// 明示的に渡された既定値を使って
// ロケールの相対時間を生成します
const rtf = new Intl.RelativeTimeFormat("en", {
  localeMatcher: "best fit", // other values: "lookup"
  numeric: "always", // other values: "auto"
  style: "long", // other values: "short" or "narrow"
});

// 負数の値 (-1) を使った相対時間のフォーマット
rtf.format(-1, "day");
// > "1 day ago"

// 正数の値 (1) を使った相対時間のフォーマット
rtf.format(1, "day");
// > "in 1 day"
```

### formatToParts の使用例

以下はフォーマットされた部品を返す相対時間フォーマッターの生成方法の例です。

```js
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });

// 日単位の相対時間フォーマット
rtf.formatToParts(-1, "day");
// > [{ type: "literal", value: "yesterday"}]

rtf.formatToParts(100, "day");
// > [{ type: "literal", value: "in " },
// > { type: "integer", value: "100", unit: "day" },
// > { type: "literal", value: " days" }]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # relativetimeformat-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* The Intl.RelativeTimeFormat API


Intl.Locale - JavaScript

Intl.Locale
===========

**`Intl.Locale`** オブジェクトは、 Unicode ロケール識別子を表す Intl オブジェクトの標準組み込みプロパティです。

試してみましょう
--------

解説
--

**`Intl.Locale`** オブジェクトは、 Unicode ロケールをより簡単に操作できるようにするために作成されました。 Unicode は、ロケールを*ロケール識別子*と呼ばれる文字列で表します。ロケール識別子は、*言語識別子*と*拡張タグ*から構成されます。言語識別子はロケールの中核となるもので、*言語*、*文字体系*、*地域サブタグ*から構成されます。ロケールに関する追加情報は、オプションの拡張タグに格納されます。*拡張タグ*には、暦の種類や時計の種類、数値表記法の種類などのロケールに関する情報が格納されています。

従来、 Intl API は Unicode と同様に文字列を使用してロケールを表していました。これはシンプルで軽量な解決策であり、うまく機能します。しかし、 Locale クラスを追加することで、言語、文字体系、地域、拡張タグの解析や操作が容易になります。

コンストラクター
--------

`Intl.Locale()`

新しい `Locale` オブジェクトを生成します。

インスタンスプロパティ
-----------

`Intl.Locale.prototype.baseName`

この `Locale` に関する基本的な情報を、完全なデータ文字列の部分文字列の形で返します。

`Intl.Locale.prototype.calendar`

このロケールの暦年を示す `Locale` の部分を返します。

`Intl.Locale.prototype.calendars`

ロケールの規則に従い、利用可能なカレンダー識別子の `Array` を返します。

`Intl.Locale.prototype.caseFirst`

ロケールの照合規則に大文字・小文字を考慮しているかどうかを返します。

`Intl.Locale.prototype.collation`

この `Locale` の照合の種類を返します。これは、ロケールの規則に従って文字列を並べ替えるために使用します。

`Intl.Locale.prototype.hourCycle`

このロケールが使用している時刻保持書式の規則を返します。

`Intl.Locale.prototype.hourCycles`

`Array` で 12 時制 ("h11", "h12") または 24 時制 ("h23", "h24") を示す時周期識別子を返します。

`Intl.Locale.prototype.language`

このロケールに関連づけられた言語を返します。

`Intl.Locale.prototype.numberingSystem`

このロケールが使用している数値表記法を返します。

`Intl.Locale.prototype.numberingSystems`

ロケールの規則に従って利用できる数値表記法の識別子の `Array` を返します。

`Intl.Locale.prototype.numeric`

このロケールが数字に対して特殊な照合順序を持っているかどうかを返します。

`Intl.Locale.prototype.region`

このロケールに関連付けられた世界の地域 (通常は国) を返します。

`Intl.Locale.prototype.script`

このロケールで使われている特定の言語を書く際に使用する文字体系を返します。

`Intl.Locale.prototype.textInfo`

`ltr` （左書き）または `rtl` （右書き）で、文字の並び順を示す部分を返します。

`Intl.Locale.prototype.timeZones`

`Locale` に関連付けられたタイムゾーン識別子の `Array` を返します。

`Intl.Locale.prototype.weekInfo`

ロケールの規則に従い、 UTS 35 の週要素を返します。

インスタンスメソッド
----------

`Intl.Locale.prototype.maximize()`

既存の値に基づいて、ロケールの言語、文字体系、地域の最も可能性の高い値を取得します。

`Intl.Locale.prototype.minimize()`

`Locale.maximize()` を呼び出すことで追加されるロケールに関する情報を削除しようとします。

`Intl.Locale.prototype.toString()`

このロケールの完全なロケール識別子文字列を返します。

例
-

### 基本的な使用

`Intl.Locale` のコンストラクターは、もっとも簡単なものでは、ロケール識別子の文字列を引数に取ります。

```js
let us = new Intl.Locale("en-US");
```

### Locale コンストラクターの options オブジェクト付きでの使用

このコンストラクターは、オプションで構成オブジェクトの引数を取ることができます。たとえば、構成オブジェクトの `hourCycle` プロパティに任意の時間サイクル種別を設定し、それをコンストラクターに渡します。

```js
let us12hour = new Intl.Locale("en-US", { hourCycle: "h12" });
console.log(us12hour.hourCycle); // Prints "h12"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # locale-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`
* Intl.Locale のポリフィル
* Unicode ロケール識別子の仕様書


Intl.Collator - JavaScript

Intl.Collator
=============

**`Intl.Collator`** オブジェクトは、言語を考慮した文字列の比較を可能にします。

試してみましょう
--------

コンストラクター
--------

`Intl.Collator()`

新しい `Collator` オブジェクトを生成します。

静的メソッド
------

`Intl.Collator.supportedLocalesOf()`

指定したロケールのうち、ランタイムの既定のロケールに代替されることなく対応されているものを含む配列を返します。

インスタンスメソッド
----------

`Intl.Collator.prototype.compare`

この `Intl.Collator` オブジェクトのソート順に応じて 2 つの文字列を比較する関数を返します。

`Intl.Collator.prototype.resolvedOptions()`

ローケルを反映しているプロパティとオブジェクトの初期化中に計算された照合オプションをもった新しいオブジェクトを返します。

例
-

### Collator の使用

次の例では、一方の文字列が他方の文字列より前である場合、後である場合、および同じレベルである場合の比較結果を表示します。

```js
console.log(new Intl.Collator().compare("a", "c")); // → 負の値
console.log(new Intl.Collator().compare("c", "a")); // → 正の値
console.log(new Intl.Collator().compare("a", "a")); // → 0
```

上記コードの結果は、ブラウザーやブラウザーのバージョンによって異なる可能性がある点に注意してください。というのも前および後を表す数値については、それぞれ負の数および正の数であることだけが仕様によって定めています。具体的な数値は定められていないため、実装ごとに異なる数値になるかもしれません。

### locales の使用

`Intl/Collator/compare` の結果は言語によって異なります。アプリケーションのユーザーインターフェイスで使用される言語のソート順を取得するには、 `locales` 引数にその言語を（およびフォールバック用の言語も）指定してください。

```js
// in German, ä sorts with a
console.log(new Intl.Collator("de").compare("ä", "z"));
// → 負の値

// in Swedish, ä sorts after z
console.log(new Intl.Collator("sv").compare("ä", "z"));
// → 正の値
```

### options の使用

`Intl/Collator/compare` の結果は `options` 引数でカスタマイズできます。

```js
// in German, ä has a as the base letter
console.log(new Intl.Collator("de", { sensitivity: "base" }).compare("ä", "a"));
// → 0

// in Swedish, ä and a are separate base letters
console.log(new Intl.Collator("sv", { sensitivity: "base" }).compare("ä", "a"));
// → 正の値
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # collator-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`


Intl.DateTimeFormat - JavaScript

Intl.DateTimeFormat
===================

**`Intl.DateTimeFormat`** オブジェクトは、言語に応じた日付と時刻の書式化を可能にします。

試してみましょう
--------

コンストラクター
--------

`Intl.DateTimeFormat()`

新しい `DateTimeFormat` オブジェクトを生成します。

静的メソッド
------

`Intl.DateTimeFormat.supportedLocalesOf()`

指定されたロケールのうち、実行時の既定のロケールにフォールバックせずに対応されるものを配列に収めて返します。

インスタンスメソッド
----------

`Intl.DateTimeFormat.prototype.format()`

ロケールおよびこの `DateTimeFormat` オブジェクトの書式化オプションに則って日付を書式化するゲッター関数です。

`Intl.DateTimeFormat.prototype.formatToParts()`

オブジェクトの `Array` を返し、これは専用のロケールを意識した書式で使用することができる部品内の数値文字列を表します。

`Intl.DateTimeFormat.prototype.resolvedOptions()`

ローケルを反映しているプロパティとオブジェクトの初期化中に計算された照合オプションをもった新しいオブジェクトを返します。

`Intl.DateTimeFormat.prototype.formatRange()`

このメソッドは 2 つの Date を受け取り、 `DateTimeFormat` インスタンスを生成する際に指定されたロケールとオプションに基づいて、最も簡潔な方法で日付の範囲を書式化します。

`Intl.DateTimeFormat.prototype.formatRangeToParts()`

このメソッドは 2 つの Date を受け取り、書式化された日付の範囲の各部分を表すロケール固有のトークンを含むオブジェクトの配列を返します。

例
-

### DateTimeFormat の使用

基本的に、ロケールを指定せずに使用すると、 `DateTimeFormat` は既定のロケールとオプションを使用します。

```js
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// toLocaleString without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(new Intl.DateTimeFormat().format(date));
// → "12/19/2012" if run with en-US locale (language) and time zone America/Los\_Angeles (UTC-0800)
```

### locales の使用

この例では、ローカライズされた日付と時刻の形式のバリエーションの一部示しています。アプリケーションのユーザーインターフェイスで使用される言語のフォーマットを取得するには、 `locales` 引数を使用して、その言語 (およびおそらくいくつかのフォールバック言語) を指定してください。

```js
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// Results below use the time zone of America/Los\_Angeles (UTC-0800, Pacific Standard Time)

// US English uses month-day-year order
console.log(new Intl.DateTimeFormat("en-US").format(date));
// → "12/19/2012"

// British English uses day-month-year order
console.log(new Intl.DateTimeFormat("en-GB").format(date));
// → "19/12/2012"

// Korean uses year-month-day order
console.log(new Intl.DateTimeFormat("ko-KR").format(date));
// → "2012. 12. 19."

// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(new Intl.DateTimeFormat("ar-EG").format(date));
// → "١٩/١٢/٢٠١٢"

// for Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(new Intl.DateTimeFormat("ja-JP-u-ca-japanese").format(date));
// → "24/12/19"

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(new Intl.DateTimeFormat(["ban", "id"]).format(date));
// → "19/12/2012"
```

### options の使用

日付と時刻の書式は `options` 引数を使用してカスタマイズできます。

```js
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0, 200));

// request a weekday along with a long date
var options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(new Intl.DateTimeFormat("de-DE", options).format(date));
// → "Donnerstag, 20. Dezember 2012"

// an application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// → "Thursday, December 20, 2012, GMT"

// sometimes you want to be more precise
options = {
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  timeZone: "Australia/Sydney",
  timeZoneName: "short",
};
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// → "2:00:00 pm AEDT"

// sometimes you want to be very precise
options.fractionalSecondDigits = 3; //number digits for fraction-of-seconds
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// → "2:00:00.200 pm AEDT"

// sometimes even the US needs 24-hour time
options = {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  hour12: false,
  timeZone: "America/Los\_Angeles",
};
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// → "12/19/2012, 19:00:00"

// to specify options but use the browser's default locale, use 'default'
console.log(new Intl.DateTimeFormat("default", options).format(date));
// → "12/19/2012, 19:00:00"

// sometimes it's helpful to include the period of the day
options = { hour: "numeric", dayPeriod: "short" };
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// → 10 at night
```

The used calendar and numbering formats can also be set independently via `options` arguments:

```js
var options = { calendar: "chinese", numberingSystem: "arab" };
var dateFormat = new Intl.DateTimeFormat("default", options);
var usedOptions = dateFormat.resolvedOptions();

console.log(usedOptions.calendar);
// → "chinese"

console.log(usedOptions.numberingSystem);
// → "arab"

console.log(usedOptions.timeZone);
// → "America/New\_York" (the users default timezone)
```

ポリフィル
-----

formatjs Intl.DateTimeFormat polyfill

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # datetimeformat-objects |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl`


Intl.DateTimeFormat.supportedLocalesOf() - JavaScript

Intl.DateTimeFormat.supportedLocalesOf()
========================================

**`Intl.DateTimeFormat.supportedLocalesOf()`** メソッドは、ランタイムの既定のロケールで代替する必要なく日時の書式で対応されているものを含む配列を返します。

試してみましょう
--------

構文
--

```js
Intl.DateTimeFormat.supportedLocalesOf(locales);
Intl.DateTimeFormat.supportedLocalesOf(locales, options);
```

### 引数

`locales`

BCP 47 言語タグを持つ文字列、またはそのような文字列の配列です。 `locales` 引数の一般的な形式については、 Intl のページを参照してください。

`options` 省略可

省略可能です。以下のプロパティを持つことがあるオブジェクトです。

`localeMatcher`

使用するロケールの一致アルゴリズムです。指定可能な値は `lookup` および `best fit` で、既定値は `best fit` です。このオプションの詳細は、 Intl のページを参照してください。

### 返値

指定したロケールタグのサブセットを表す文字列の配列で、ランタイムの既定のロケールで代替する必要なく日時の書式で対応されているものを含みます。

解説
--

`locales` で提供されている言語タグのサブセットを含む配列を返します。返される言語タグは、ランタイムが日時のロケールに対応しているもので、使用しているロケール照合アルゴリズムで一致しているとみなされているものです。

例
-

### supportedLocalesOf() の使用

日時の書式でインドネシア語とドイツ語に対応しており、バリ語に対応していないランタイムを想定すると、 `supportedLocalesOf` はインドネシア語とドイツ語の言語タグを変更せずに返しますが、 pinyin の照合は日時の書式には関係なく、インドネシア語でも使用されません。ここでの `lookup` アルゴリズムの仕様に注意してください — バリ語話者のほとんどはインドネシア語も理解しているので、 `best fit` のマッチャーはインドネシア語がバリ語に適切に一致すると判断し、バリ語の言語タグも返すかもしれません。

```js
const locales = ["ban", "id-u-co-pinyin", "de-ID"];
const options = { localeMatcher: "lookup" };
console.log(
  Intl.DateTimeFormat.supportedLocalesOf(locales, options).join(", "),
);
// → "id-u-co-pinyin, de-ID"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.datetimeformat.supportedlocalesof |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`


Intl.DateTimeFormat.prototype.format() - JavaScript

Intl.DateTimeFormat.prototype.format()
======================================

The **`Intl.DateTimeFormat.prototype.format()`** メソッドは、この `Intl.DateTimeFormat` オブジェクトのロケールと整形オプションに従って日付や時刻を整形します。

試してみましょう
--------

構文
--

```js
format(date);
```

### 引数

`date`

整形する日付です。

解説
--

`format` ゲッター関数は、この `Intl.DateTimeFormat` オブジェクトのロケールと整形オプションに従って日付や時刻を整形し、文字列に格納します。

例
-

### format の使用

`format` ゲッター関数を使用して単一の日付値を整形します。こちらはセルビアの例です。

```js
var options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
var dateTimeFormat = new Intl.DateTimeFormat("sr-RS", options);
console.log(dateTimeFormat.format(new Date()));
// → "недеља, 7. април 2013."
```

### format と map の使用

`format` ゲッター関数を使用して、配列内のすべての日付を整形することができます。なお、この関数は供給元である `Intl.DateTimeFormat` に結び付けられているので、直接 `Array.prototype.map()` に渡すことができます。

```js
var a = [new Date(2012, 08), new Date(2012, 11), new Date(2012, 03)];
var options = { year: "numeric", month: "long" };
var dateTimeFormat = new Intl.DateTimeFormat("pt-BR", options);
var formatted = a.map(dateTimeFormat.format);
console.log(formatted.join("; "));
// → "setembro de 2012; dezembro de 2012; abril de 2012"
```

### 書式化された日付値を固定値と比較することは避ける

ほとんどの場合、 `format()` が返す書式は一貫しています。しかし、これは将来的に変更される可能性があり、すべての言語で保証されているわけではありません — 出力のバリエーションは設計上のものであり、仕様上は許容されています。最も注目すべきは、 IE や Edge ブラウザは日付の周りに双方向の制御文字を挿入するため、他のテキストと連結したときに出力テキストが適切に流れることです。

このことから、 `format()` の結果と固定値を比較することができると期待してはいけません。

```js
let d = new Date("2019-01-01T00:00:00.000000Z");
let formattedDate = Intl.DateTimeFormat(undefined, {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
}).format(d);

"1.1.2019, 01:00:00" === formattedDate;
// true in Firefox and others
// false in IE and Edge
```

**メモ:** この StackOverflow のスレッドに詳細や例があります。

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.datetimeformat.prototype.format |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleTimeString()`


Intl.DateTimeFormat.prototype.formatRange() - JavaScript

Intl.DateTimeFormat.prototype.formatRange()
===========================================

**`Intl.DateTimeFormat.prototype.formatRange()`** は、 `Intl.DateTimeFormat` オブジェクトがインスタンス化されたときに提供された **`locale`** と **`options`** に基づいて、もっとも簡明な方法で日付の範囲を書式化します。

試してみましょう
--------

構文
--

```js
formatRange(startDate, endDate);
```

例
-

### 基本的な formatRange の使用

このメソッドは 2 つの `Date` を受け取り、 `Intl.DateTimeFormat` オブジェクトがインスタンス化されたときに提供された `locale` と `options` に基づいて日付の範囲を書式化します。

```js
let date1 = new Date(Date.UTC(2007, 0, 10, 10, 0, 0));
let date2 = new Date(Date.UTC(2007, 0, 10, 11, 0, 0));
let date3 = new Date(Date.UTC(2007, 0, 20, 10, 0, 0));
// > 'Wed, 10 Jan 2007 10:00:00 GMT'
// > 'Wed, 10 Jan 2007 11:00:00 GMT'
// > 'Sat, 20 Jan 2007 10:00:00 GMT'

let fmt1 = new Intl.DateTimeFormat("en", {
  year: "2-digit",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
});
console.log(fmt1.format(date1));
console.log(fmt1.formatRange(date1, date2));
console.log(fmt1.formatRange(date1, date3));
// > '1/10/07, 10:00 AM'
// > '1/10/07, 10:00 – 11:00 AM'
// > '1/10/07, 10:00 AM – 1/20/07, 10:00 AM'

let fmt2 = new Intl.DateTimeFormat("en", {
  year: "numeric",
  month: "short",
  day: "numeric",
});
console.log(fmt2.format(date1));
console.log(fmt2.formatRange(date1, date2));
console.log(fmt2.formatRange(date1, date3));
// > 'Jan 10, 2007'
// > 'Jan 10, 2007'
// > 'Jan 10 – 20, 2007'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.datetimeformat.prototype.formatRange |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`


Intl.DateTimeFormat.prototype.resolvedOptions() - JavaScript

Intl.DateTimeFormat.prototype.resolvedOptions()
===============================================

**`Intl.DateTimeFormat.prototype.resolvedOptions()`** メソッドは、この `Intl/DateTimeFormat` オブジェクトの初期化時に計算されたロケールや日付と時刻の整形オプションを反映したプロパティを持つ新しいオブジェクトを返します。

試してみましょう
--------

構文
--

```js
resolvedOptions();
```

### 返値

この `Intl/DateTimeFormat` オブジェクトの初期化時に計算されたロケールと照合オプションを反映したプロパティを持つ新しいオブジェクトです。

解説
--

返されるオブジェクトには以下のプロパティがあります。

`locale`

実際に使用したロケールの BCP 47 言語タグ。このロケールにつながる入力 BCP 47 言語タグに Unicode 拡張値が要求された場合、要求されたキーと値のペアのうち、このロケールで対応しているものが `locale` に含まれます。

`calendar`

例: "gregory"

`numberingSystem`

Unicode 拡張キーの `"ca"` および `"nu"` で要求された値、または既定値が入ります。

`timeZone`

`options` 引数の同名のプロパティで要求された値です。提供された値がなければ `undefined` (ランタイムの既定のタイムゾーン) です。警告: アプリケーションは `undefined` が返されることに依存しないでください。将来のバージョンではランタイムの既定のタイムゾーンを識別する `String` 値が返されるようになる可能性があるからです。

`hour12`

`options` 引数の同名のプロパティで要求された値、または既定値が入ります。

`weekday`, `era`, `year`, `month`, `day`, `hour`, `minute`, `second`, `timeZoneName`

`options` 引数の対応するプロパティと、選択したロケールでの日付時刻の書式設定に利用可能な組み合わせや表現との間で、書式のマッチングを行った結果の値。これらのプロパティの中には、対応するコンポーネントが書式化された出力では表現されないものもあります。

例
-

### resolvedOptions メソッドの使用

```js
var germanFakeRegion = new Intl.DateTimeFormat("de-XX", { timeZone: "UTC" });
var usedOptions = germanFakeRegion.resolvedOptions();

usedOptions.locale; // "de"
usedOptions.calendar; // "gregory"
usedOptions.numberingSystem; // "latn"
usedOptions.timeZone; // "UTC"
usedOptions.month; // "numeric"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.datetimeformat.prototype.resolvedoptions |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`


Intl.DateTimeFormat() コンストラクター - JavaScript

Intl.DateTimeFormat() コンストラクター
==============================

**`Intl.DateTimeFormat()`** コンストラクターは、言語に応じた日付と時刻の書式化を可能にする
 `Intl.DateTimeFormat` オブジェクトを生成します。

試してみましょう
--------

構文
--

```js
new Intl.DateTimeFormat();
new Intl.DateTimeFormat(locales);
new Intl.DateTimeFormat(locales, options);
```

### 引数

`locales` 省略可

BCP 47 言語タグの文字列、または、そのような文字列の配列です。ブラウザーの既定のロケールを使用するには、空の配列を渡してください。 Unicode 拡張に対応しています (例えば "`en-US-u-ca-buddhist`" など)。 `locales` 引数の一般的な形式と解釈は、 Intl のページをご覧ください。次の Unicode 拡張キーが利用できます。

`nu`

番号方式。使用できる値は "`arab`", "`arabext`", "`bali`", "`beng`", "`deva`", "`fullwide`", "`gujr`", "`guru`", "`hanidec`", "`khmr`", "`knda`", "`laoo`", "`latn`", "`limb`", "`mlym`", "`mong`", "`mymr`", "`orya`", "`tamldec`", "`telu`", "`thai`", "`tibt`" です。

`ca`

カレンダー。使用できる値は "`buddhist`", "`chinese`", "`coptic`", "`ethiopia`", "`ethiopic`", "`gregory`", "`hebrew`", "`indian`", "`islamic`", "`iso8601`", "`japanese`", "`persian`", "`roc`" です。

`hc`

時制。使用できる値は "`h11`", "`h12`", "`h23`", "`h24`" です。

`options` 省略可

以下のプロパティの一部またはすべてを持つオブジェクトです。

`dateStyle`

`format()` が呼び出された際に使用される日付の書式化スタイルです。利用可能な値は以下のとおりです。

* "`full`"
* "`long`"
* "`medium`"
* "`short`"

**メモ:** `dateStyle` は `timeStyle` と一緒に使用することができますが、他のオプション (`weekday`, `hour`, `month`, など) と一緒に使用することはできません。

`timeStyle`

`format()` が呼び出された際に使用される時刻の書式化スタイルです。利用可能な値は以下のとおりです。

* "`full`"
* "`long`"
* "`medium`"
* "`short`"

**メモ:** `timeStyle` は `dateStyle` と一緒に使用することができますが、他のオプション (`weekday`, `hour`, `month`, など) と一緒に使用することはできません。

`calendar`

暦です。有効な値は、 "`buddhist`", "`chinese`", " `coptic`", "`ethiopia`", "`ethiopic`", "`gregory`", " `hebrew`", "`indian`", "`islamic`", "`iso8601`", " `japanese`", "`persian`", "`roc`" です。

`dayPeriod`

日単位の期間の表現の仕方です。有効な値は、 "`narrow`", "`short`", " `long`" です。

**メモ:**

* このオプションは12時間制を使用したときのみ効果があります。
* 多くのロケールでは幅の指定を無視して同じ文字列を使用します。

`numberingSystem`

命数法です。有効な値は、 "`arab`", "`arabext`", " `bali`", "`beng`", "`deva`", "`fullwide`", " `gujr`", "`guru`", "`hanidec`", "`khmr`", " `knda`", "`laoo`", "`latn`", "`limb`", "`mlym`", " `mong`", "`mymr`", "`orya`", "`tamldec`", " `telu`", "`thai`", "`tibt`" です。

`localeMatcher`

使用するロケール照合アルゴリズム。利用可能な値は "`lookup`" と "`best fit`" です。既定値は "`best fit`" です。このオプションについての詳細は、 Intl のページをご覧ください。

`timeZone`

使用するタイムゾーン。実装が認識しなければならない唯一の値は "`UTC`" です。既定値は、実行時の既定のタイムゾーンです。実装は、 IANA タイムゾーンデータベースのタイムゾーン名、例えば "`Asia/Shanghai`", "`Asia/Kolkata`", "`America/New_York`" なども認識できる場合があります。

`hour12`

(24 時制に対して) 12 時制を使用するかどうか。可能な値は `true` と `false` です。既定ではロケールに依存します。このオプションは `hc` 言語タグや `hourCycle` オプションと一緒に使用された場合、これらを上書きします。

`hourCycle`

使用する時の周期です。利用可能な値は "`h11`", "`h12`", "`h23`", "`h24`" です。このオプションは `hc` 言語タグと一緒に使用された場合はそれを上書きし、両方のオプションが指定されていた場合は `hour12` オプションが優先されます。

`formatMatcher`

使用する書式一致アルゴリズム。可能な値は "`basic`" と "`best fit`" です。既定値は "`best fit`" です。このプロパティの使用方法については、以下の項を参照してください。

以下のプロパティは、書式化の出力や、要求された表現で使用する日付や時刻のコンポーネントです。実装は、少なくとも以下のサブセットに対応することが要求されています。

* `weekday`, `year`, `month`, `day`, `hour`, `minute`, `second`
* `weekday`, `year`, `month`, `day`
* `year`, `month`, `day`
* `year`, `month`
* `month`, `day`
* `hour`, `minute`, `second`
* `hour`, `minute`

実装は他のサブセットに対応することもでき、要求はすべての利用可能な表現の中から最適なものを見つけるために交渉します。 `formatMatcher` プロパティによるこの交渉や選択には2つのアルゴリズムが利用できます。完全に定義された "`basic`" アルゴリズムと、実装に依存した "`best fit`" アルゴリズムです。

`weekday`

曜日の表現です。利用可能な値は以下の通りです。

* "`long`" (例 `Thursday`)
* "`short`" (例 `Thu`)
* "`narrow`" (例 `T`)。ロケールによっては、 narrow 形式が同じ曜日が2つある場合もあります (例 `Tuesday` の narrow 形式も `T` です)。

`era`

時代の表現です。利用可能な値は以下の通りです。

* "`long`" (例 `Anno Domini`, 紀元)
* "`short`" (例 `AD`)
* "`narrow`" (例 `A`)

`year`

年の表現です。利用可能な値は以下の通りです。

* "`numeric`" (例 `2012`)
* "`2-digit`" (例 `12`)

`month`

月の表現です。利用可能な値は以下の通りです。

* "`numeric`" (例 `2`)
* "`2-digit`" (例 `02`)
* "`long`" (例 `March`)
* "`short`" (例 `Mar`)
* "`narrow`" (例 `M`)。ロケールによっては、 narrow 形式が同じ月が2つある場合もあります (例 `May` の narrow 形式も `M` です)。

`day`

日の表現です。利用可能な値は以下の通りです。

* "`numeric`" (例 `1`)
* "`2-digit`" (例 `01`)

`hour`

時の表現です。利用可能な値は "`numeric`", "`2-digit`" です。

`minute`

分の表現です。利用可能な値は "`numeric`", "`2-digit`" です。

`second`

秒の表現です。利用可能な値は "`numeric`", "`2-digit`" です。

`fractionalSecondDigits`

秒の小数点以下を表すために使用される数字の桁数 (その先の桁は切り捨てられます)。利用可能な値は次の通りです。

* `0` (小数点以下は切り捨て)
* `1` (小数点以下は1桁で表される。例えば、 736 は `7` と書式化される。)
* `2` (小数点以下は2桁で表される。例えば、 736 は `73` と書式化される。)
* `3` (小数点以下は2桁で表される。例えば、 736 は `736` と書式化される。)

`timeZoneName`

タイムゾーン名の表現です。利用可能な値は以下の通りです。

* "`long`" ローカライズされた長い形式 (例 `Pacific Standard Time`, `Nordamerikanische Westküsten-Normalzeit`)
* "`short`" ローカライズされた短い形式 (例 `PST`, `GMT-8`)
* "`shortOffset`" ローカライズされた短い GMT 形式 (例 `GMT-8`)
* "`longOffset`" ローカライズされた長い GMT 形式 (例 `GMT-0800`)
* "`shortGeneric`" 一般的な場所を指定しない短い形式 (例 `PT`, `Los Angeles Zeit`).
* "`longGeneric`" 一般的な場所を指定しない長い形式 (例 `Pacific Time`, `Nordamerikanische Westküstenzeit`)

**メモ:** タイムゾーンの表示は、必要な文字列が利用できない場合、別の形式にフォールバックすることがあります。例えば、場所を指定しない形式では、 "Pacific Time" のように特定の国や都市の場所を指定せずにタイムゾーンを表示する必要がありますが、 "Los Angeles Time" のようなタイムゾーンにフォールバックする場合があります。

それぞれの日付や時刻の部分のプロパティの既定値は `undefined` ですが、すべての部分のプロパティが `undefined` であった場合、 `year`, `month`, `day` は "`numeric`" であると想定されます。

例
-

### DateTimeFormat の使用

ロケールを指定しない基本的な使用方法では、 `DateTimeFormat` は既定のロケールとオプションを使用します。

```js
let date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// toLocaleString without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(new Intl.DateTimeFormat().format(date));
// → "12/19/2012" if run with en-US locale (language) and time zone America/Los\_Angeles (UTC-0800)
```

### timeStyle と dateStyle の使用

```js
let o = new Intl.DateTimeFormat("en", {
  timeStyle: "short",
});
console.log(o.format(Date.now())); // "13:31 AM"

let o = new Intl.DateTimeFormat("en", {
  dateStyle: "short",
});
console.log(o.format(Date.now())); // "07/07/20"

let o = new Intl.DateTimeFormat("en", {
  timeStyle: "medium",
  dateStyle: "short",
});
console.log(o.format(Date.now())); // "07/07/20, 13:31:55 AM"
```

### dayPeriod の使用

`dayPeriod` オプションを使用して、1日の時間帯 (「朝」、「夜」、「正午」など) を表す文字列を出力します。なお、これは 12 時間制の書式でのみ有効であり、 (`hourCycle: 'h12'`)、多くのロケールでは `dayPeriod` の値に関係なく同じ文字列が出力されます。

```js
let date = Date.UTC(2012, 11, 17, 4, 0, 42);

console.log(
  new Intl.DateTimeFormat("en-GB", {
    hour: "numeric",
    hourCycle: "h12",
    dayPeriod: "short",
    timeZone: "UTC",
  }).format(date),
);
// > 4 at night" (same formatting in en-GB for all dayPeriod values)

console.log(
  new Intl.DateTimeFormat("fr", {
    hour: "numeric",
    hourCycle: "h12",
    dayPeriod: "narrow",
    timeZone: "UTC",
  }).format(date),
);
// > "4 mat." (same output in French for both narrow/short dayPeriod)

console.log(
  new Intl.DateTimeFormat("fr", {
    hour: "numeric",
    hourCycle: "h12",
    dayPeriod: "long",
    timeZone: "UTC",
  }).format(date),
);
// > "4 du matin"
```

### timeZoneName の使用

`timeZoneName` を使用して、タイムゾーンの文字列 ("GMT", "Pacific Time", など) を出力します。

```js
var date = Date.UTC(2021, 11, 17, 3, 0, 42);
const timezoneNames = [
  "short",
  "long",
  "shortOffset",
  "longOffset",
  "shortGeneric",
  "longGeneric",
];

for (const zoneName of timezoneNames) {
  // Do something with currentValue
  var formatter = new Intl.DateTimeFormat("en-US", {
    timeZone: "America/Los\_Angeles",
    timeZoneName: zoneName,
  });
  console.log(zoneName + ": " + formatter.format(date));
}

// expected output:
// > "short: 12/16/2021, PST"
// > "long: 12/16/2021, Pacific Standard Time"
// > "shortOffset: 12/16/2021, GMT-8"
// > "longOffset: 12/16/2021, GMT-08:00"
// > "shortGeneric: 12/16/2021, PT"
// > "longGeneric: 12/16/2021, Pacific Time"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl-datetimeformat-constructor |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`
* `Intl`


Intl.DateTimeFormat.prototype.formatRangeToParts() - JavaScript

Intl.DateTimeFormat.prototype.formatRangeToParts()
==================================================

**`Intl.DateTimeFormat.prototype.formatRangeToParts()`** メソッドは、 `Intl.DateTimeFormat` フォーマッターで生成される期間の各部品を表すロケール特有のトークンを提供します。

試してみましょう
--------

構文
--

```js
formatRangeToParts(startDate, endDate);
```

例
-

### 基本的な formatRangeToParts の使い方

このメソッドは2つの `Date` を受け取り、期間を書式化する際の各部品を表す*ロケール特有*のトークンを含む `Array` オブジェクトを返します。

**メモ:** 返値は現在のロケールで表示されるので、以下のものとは異なる可能性があります。

```js
let date1 = new Date(Date.UTC(2007, 0, 10, 10, 0, 0));
let date2 = new Date(Date.UTC(2007, 0, 10, 11, 0, 0));
// > 'Wed, 10 Jan 2007 10:00:00 GMT'
// > 'Wed, 10 Jan 2007 11:00:00 GMT'

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

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

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" }
// ]
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-Intl.DateTimeFormat.prototype.formatRangeToParts |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat.prototype.formatRange()`
* `Intl.DateTimeFormat`


Intl.DateTimeFormat.prototype.formatToParts() - JavaScript

Intl.DateTimeFormat.prototype.formatToParts()
=============================================

**`Intl.DateTimeFormat.prototype.formatToParts()`** メソッドは、ロケールを考慮した `Intl.DateTimeFormat` フォーマッターが生成する文字列のロケールを考慮した書式化を可能にします。

試してみましょう
--------

構文
--

```js
formatToParts(date);
```

### 引数

`date` 省略可

書式化する日付。

### 返値

`Array` で、書式化された日付のパーツを含むオブジェクトの配列です。

解説
--

`formatToParts()` メソッドは、日付文字列のフォーマットをカスタマイズするときに役立ちます。これは、ロケール特有の部分を保持しながら、カスタム文字列を構築できるロケール特有のトークンを含むオブジェクトの `Array` を返します。`formatToParts()` メソッドが返却する構造は、このようになります。

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

渡される可能性がある type は以下のとおりです。

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

カレンダーの表現が year ではなくyearNameである場合、関連する4桁のグレゴリオ暦の年に使用される文字列です。例えば "`2019`" です。

second

秒として使用される文字列。たとえば、"`07`" や "`42`"。

timeZoneName

タイムゾーン名として使用される文字列。たとえば、"`UTC`"。

weekday

曜日として使用される文字列。たとえば、"`M`" や "`Monday`"、"`Montag`"。

year

年として使用される文字列。たとえば、"`2012`" や "`96`"。

yearName

関連するコンテキストで yearName に使用される文字列、例えば "`geng-zi`" など。

ポリフィル
-----

この機能のポリフィルは、提案リポジトリーから利用できます。

例
-

`DateTimeFormat` は、直接操作できないローカライズされた透過的でない文字列を出力します。

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

しかし、多くのユーザーインターフェイスでは、この文字列の書式をカスタマイズしたいという要望があります。 `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
var dateString = formatter
  .formatToParts(date)
  .map(({ type, value }) => {
    switch (type) {
      case "dayPeriod":
        return `<b>${value}</b>`;
      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 <b>AM</b>"
```

### 名前付きの年と混合カレンダー

名前付きの年を使用している暦もあります。例えば、中国やチベットの暦では、 60 年周期の干支を使用しています。これらの年は、グレゴリオ暦の年と関連付けて識別されます。このような場合、 `formatToParts()` の結果は、通常は年が存在するはずなのに、年の項目ではなく、 4 桁のグレゴリオ暦の年を含む `relatedYear` の項目を含むことになります。バッグの中の項目を (任意の値で) `year` に設定すると、年と `yearName` グレゴリオ暦の `relatedYear` の両方が得られます。

```js
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` オプションがバッグ内で設定されていない場合 (任意の値に設定されている場合)、結果には `relatedYear` のみが含まれます。

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

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

`year` を出力したい場合は、 `.format()` は一般的にこれらを並べて表示することができます。

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

// 返値
2012壬辰年
```

これにより、ロケールとカレンダーを両方の `format` で混在させることも可能になります。

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

// 返値
2012(ren - chen);
```

および `formatToParts` の場合

```js
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)[
  // 返値
  ({ type: "month", value: "11" },
  { type: "literal", value: "/" },
  { type: "day", value: "4" },
  { type: "literal", value: "/" },
  { type: "relatedYear", value: "2012" })
];
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-Intl.DateTimeFormat.prototype.formatToParts |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.DateTimeFormat`
* `Intl.DateTimeFormat.prototype.format()`
* `Date.prototype.toLocaleString()`
* `Date.prototype.toLocaleDateString()`
* `Date.prototype.toLocaleTimeString()`


Intl.PluralRules.selectRange() - JavaScript

Intl.PluralRules.selectRange()
==============================

**`Intl.PluralRules.prototype.selectRange()`** メソッドは 2 つの値を受け取り、ロケールを考慮した書式設定に使用する複数形ルールを示す文字列を返します。

構文
--

```js
selectRange(startRange, endRange);
```

### 返値

数字の複数形のカテゴリーを表す文字列で、 `zero`, `one`, `two`, `few`, `many`, `other` のいずれかで、 LDML 言語複数ルールで指定されたローカライズのロケールに関連するものです。

解説
--

この関数は、 `Intl.PluralRules` オブジェクトのロケールおよび書式化オプションに従って、複数形カテゴリーを選択するものです。

例
-

### selectRange() の使用

```js
new Intl.PluralRules("sl").selectRange(102, 201);
// → 'few'

new Intl.PluralRules("pt").selectRange(102, 102);
// → 'other'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.pluralrules.prototype.selectrange |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.PluralRules`


Intl.PluralRules.supportedLocalesOf() - JavaScript

Intl.PluralRules.supportedLocalesOf()
=====================================

**`Intl.PluralRules.supportedLocalesOf()`** メソッドは、ランタイムの既定のロケールのうち、代替する必要なく複数形の書式で対応されているものが入った配列を返します。

試してみましょう
--------

構文
--

```js
Intl.PluralRules.supportedLocalesOf(locales);
Intl.PluralRules.supportedLocalesOf(locales, options);
```

### 引数

`locales`

BCP 47 言語タグを持つ文字列、またはそのような文字列の配列です。 `locales` 引数の一般的な形式については、 Intl のページを参照してください。

`options` 省略可

省略可能です。以下のプロパティを持つことがあるオブジェクトです。

`localeMatcher`

使用するロケールの照合アルゴリズムです。指定可能な値は "`lookup`" および "`best fit`" で、既定値は "`best fit`" です。このオプションの詳細は、 Intl のページを参照してください。

### 返値

指定したロケールタグのサブセットを表す文字列の配列で、ランタイムの既定のロケールのうち、代替する必要なく複数形の書式で対応されているものが入ります。

解説
--

`locales` で提供されている言語タグのサブセットを含む配列を返します。返される言語タグは、ランタイムが複数形のロケールに対応しているもので、使用しているロケール照合アルゴリズムで一致しているとみなされているものです。

例
-

### supportedLocalesOf() の使用

複数形の書式でインドネシア語とドイツ語に対応しており、バリ語に対応していないランタイムを想定すると、 `supportedLocalesOf` はインドネシア語とドイツ語の言語タグを変更せずに返しますが、 `pinyin` の照合は複数形の書式には関係なく、インドネシア語でも使用されません。ここでの "`lookup`" アルゴリズムの仕様に注意してください — バリ語話者のほとんどはインドネシア語も理解しているので、 "`best fit`" の照合はインドネシア語がバリ語に適切に一致すると判断し、バリ語の言語タグも返すかもしれません。

```js
const locales = ["ban", "id-u-co-pinyin", "de-ID"];
const options = { localeMatcher: "lookup" };
console.log(Intl.PluralRules.supportedLocalesOf(locales, options).join(", "));
// → "id-u-co-pinyin, de-ID"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.pluralrules.supportedlocalesof |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.PluralRules`


Intl.PluralRules.prototype.resolvedOptions() - JavaScript

Intl.PluralRules.prototype.resolvedOptions()
============================================

**`Intl.PluralRules.prototype.resolvedOptions()`** メソッドは、この `Intl.PluralRules` オブジェクトの初期化時に計算されたロケールと照合オプションを反映したプロパティを持つ新しいオブジェクトを返します。

試してみましょう
--------

構文
--

```js
resolvedOptions();
```

### 返値

この `Intl.PluralRules` オブジェクトの初期化時に計算されたロケールと照合オプションを反映したプロパティを持つ新しいオブジェクトです。

解説
--

返されるオブジェクトには以下のプロパティがあります。

`locale`

実際に使用したロケールの BCP 47 言語タグ。このロケールにつながる入力 BCP 47 言語タグに Unicode 拡張値が要求された場合、要求されたキーと値の組のうち、このロケールで対応しているものが `locale` に含まれます。

`pluralCategories`

指定されたロケールで使用される複数形カテゴリーの `Array` で、 "zero", "one", "two", "few", "many", "other" のリストの中から選択します。

`type`

使用される種類です (`cardinal` または `ordinal`)。

以下の 2 つのプロパティのグループの中では、 1 つだけしか設定できません。

`minimumIntegerDigits`, `minimumFractionDigits`, `maximumFractionDigits`

これらのプロパティには、 `options` 引数で指定された値が入るか、既定値で埋められます。これらのプロパティは `minimumSignificantDigits` と `maximumSignificantDigits` のどちらも `options` 引数で指定されなかった場合のみ存在します。

`minimumSignificantDigits`, `maximumSignificantDigits`

これらのプロパティには、 `options` 引数で指定された値が入るか、既定値で埋められます。これらのプロパティは、少なくとも 1 つのプロパティが `options` 引数で提供された場合にのみ表示されます。

例
-

### resolvedOptions() メソッドの使用

```js
var de = new Intl.PluralRules("de-DE");
var usedOptions = de.resolvedOptions();

usedOptions.locale; // "de-DE"
usedOptions.maximumFractionDigits; // 3
usedOptions.minimumFractionDigits; // 0
usedOptions.minimumIntegerDigits; // 1
usedOptions.pluralCategories; // Array [ "one", "other" ]
usedOptions.type; // "cardinal"
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.pluralrules.prototype.resolvedoptions |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.PluralRules`


Intl.PluralRules.select() - JavaScript

Intl.PluralRules.select()
=========================

**`Intl.PluralRules.prototype.select()`** メソッドは、ロケールを考慮した書式設定に使用する複数形ルールを示す文字列を返します。

試してみましょう
--------

構文
--

```js
select(number);
```

### 引数

`number`

複数のルールを取得するための数値です。

### 返値

数字の複数形のカテゴリーを表す文字列で、 `zero`, `one`, `two`, `few`, `many`, `other` のいずれかになります。

解説
--

この関数は、 `Intl.PluralRules` オブジェクトのロケールや書式オプションに応じて、複数形のカテゴリーを選択します。

例
-

### select() の使用

```js
new Intl.PluralRules("ar-EG").select(0);
// → 'zero'

new Intl.PluralRules("ar-EG").select(1);
// → 'one'

new Intl.PluralRules("ar-EG").select(2);
// → 'two'

new Intl.PluralRules("ar-EG").select(6);
// → 'few'

new Intl.PluralRules("ar-EG").select(18);
// → 'many'
```

仕様書
---

| Specification |
| --- |
| ECMAScript Internationalization API Specification # sec-intl.pluralrules.prototype.select |

ブラウザーの互換性
---------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

関連情報
----

* `Intl.PluralRules`