Date.prototype.toLocaleDateString()

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

The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.

構文

dateObj.toLocaleDateString([locales [, options]])

引数

locales 引数と options 引数をサポートしているブラウザーは、ブラウザーの実装状況 セクションを確認してください。機能が使用できるかどうかは、locales 引数と options 引数がサポートされているか確認するで確認してください。

各日時コンポーネントのプロパティのデフォルト値は、undefinedです。ただし、weekday および year、month、day プロパティがすべて undefined のときは、year、month、day は "numeric" とみなされます。

戻り値

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

例

toLocaleDateString() を使う

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

var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

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

locales 引数と options 引数がサポートされているか確認する

locales 引数と options 引数は、まだすべてのブラウザーでサポートされていません。これらが実装されているかどうかは、不適切な言語タグを与えて RangeError 例外でリジェクトされることで確かめられます:

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

locales を使う

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

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

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

// 米国英語は月-日-年の順
console.log(date.toLocaleDateString('en-US'));
// → "12/19/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 引数でカスタマイズできます:

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

// 曜日を加えて月とともに長い書式で表す
var 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, GMT"

パフォーマンス

数多くの日付の書式を処理したいときは、Intl.DateTimeFormat オブジェクトを作成し、その format プロパティが提供する関数を用いるのがよいでしょう。

仕様

ブラウザー実装状況

The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.

関連情報

• Intl.DateTimeFormat
• Date.prototype.toLocaleString()
• Date.prototype.toLocaleTimeString()
• Date.prototype.toString()