MDN’s new design is in Beta! A sneak peek: https://blog.mozilla.org/opendesign/mdns-new-design-beta/

Date.prototype.toLocaleDateString()

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

構文

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

引数

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

locales

任意。BCP47 言語タグの文字列、または、そのような文字列の配列。locales 引数の一般的な形式と解釈は、Intl page をご覧ください。次の 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", "ethioaa", "ethiopic", "gregory", "hebrew", "indian", "islamic", "islamicc", "iso8601", "japanese", "persian", "roc"
options

任意。以下のプロパティの一部またはすべてを持つオブジェクト:

localeMatcher
使用するロケールマッチングアルゴリズム。可能な値は "lookup""best fit" です。デフォルトは "best fit" です。このオプションについての詳細は、Intl page をご覧ください。
timeZone
使用するタイムゾーン。実装が認識しなければならない唯一の値は "UTC" です。デフォルトは、実行時のデフォルトのタイムゾーンです。実装は、また、"Asia/Shanghai", "Asia/Kolkata", "America/New_York" のような IANA time zone database のタイムゾーン名を認識できます。
hour12
12 時間表示を使用するかどうか (反対は 24 時間表示)。可能な値は truefalse です。デフォルトはロケール依存です。
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 プロパティによって選択されます: fully specified "basic" algorithm"best fit" アルゴリズムに依存した実装。

weekday
平日の表現。可能な値は、"narrow", "short", "long" です。
era
時代の表現。可能な値は "narrow", "short", "long" です。
year
今年の表現。可能な値は "numeric", "2-digit" です。
month
月の表現。可能な値は "numeric", "2-digit", "narrow", "short", "long" です。
day
日の表現。可能な値は "numeric", "2-digit" です。
hour
時間の表現。可能な値は "numeric", "2-digit" です。
minute
分の表現。可能な値は "numeric", "2-digit" です。
second
秒の表現。可能な値は "numeric", "2-digit" です。
timeZoneName
タイムゾーン名の表現。可能な値は "short", "long" です。

各日時コンポーネントのプロパティのデフォルト値は、undefinedです。ただし、weekday および yearmonthday プロパティがすべて undefined のときは、yearmonthday"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."

// 多くのアラビア語圏ではアラビア数字
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 プロパティが提供する関数を用いるのがよいでしょう。

仕様

仕様書 策定状況 備考
ECMAScript 3rd Edition (ECMA-262) 標準 初期定義。JavaScript 1.0 で実装。
ECMAScript 5.1 (ECMA-262)
Date.prototype.toLocaleDateString の定義
標準
ECMAScript 2015 (6th Edition, ECMA-262)
Date.prototype.toLocaleDateString の定義
標準
ECMAScript 2017 Draft (ECMA-262)
Date.prototype.toLocaleDateString の定義
ドラフト
ECMAScript Internationalization API 1.0 (ECMA-402)
Date.prototype.toLocaleDateString の定義
標準 locales および options 引数を定義。
ECMAScript Internationalization API 2.0 (ECMA-402)
Date.prototype.toLocaleDateString の定義
標準
ECMAScript Internationalization API 4.0 (ECMA-402)
Date.prototype.toLocaleDateString の定義
ドラフト

ブラウザの実装状況

機能 Chrome Firefox (Gecko) Internet Explorer Opera Safari
基本サポート (有) (有) (有) (有) (有)
locales および options 引数 24 [1] 29 (29) 11 15 Nightly build[2]
機能 Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
基本サポート (有) (有) (有) (有) (有) (有)
locales および options 引数 未サポート 26 未サポート 未サポート 未サポート 未サポート

[1] Chrome 24 では、UTC のほかに timeZones を渡すこともできます。

[2] WebKit のバグ 147612 を参照。

関連情報

ドキュメントのタグと貢献者

 このページの貢献者: Marsf, FumioNonaka, x2357, shide55
 最終更新者: Marsf,