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()`