.toLocaleString()

toLocaleString()メソッドは、その日時を言語に沿った表現にして文字列を返します。 新しいlocalesoptionsの引数は、 使用されるべきフォーマットの形式の言語をアプリケーションに特定させることで、 関数の動作をカスタマイズ出来るようにしてくれます。 localesoptionsの引数を無視する古い実装では、 完全に実装依存となり、そのロケールと文字列の形式が返されます。(翻訳に自信なし)

文法

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

ブラウザ互換性のセクションと、機能検知のための「例:localesとoptions引数のサポートの確認」を参照して、 localesoptions引数がブラウザでサポートされているかを確認してください。

引数 説明
locales

BCP 47言語タグを使用した文字列、またはそれらの文字列の配列を指定します。 この一般的な形式とlocales引数を判定するために、 Intlのページを参照してください。 下記のユニコードの拡張キーが許可されています。

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ページを参照してください。
timeZone
使用するタイムゾーンを指定します。 実装に認識しなければいけない唯一の値は"UTC"で、デフォルトはランタイムのデフォルトのタイムゾーンです。 実装はまた、"Asia/Shanghai"、"Asia/Kolkata"、"America/New_York"のような、 IANAタイムゾーンデータベースのタイムゾーン名を認識出来るかもしれません。
hour12
12-hour時間(24-hour時間に対するものとして)を使用するか否かを指定します。 指定可能な値はtrueとfalseで、デフォルトはロケールに依存します。
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

実装は他のサブセットをサポートする可能性があり、リクエストはベストマッチするものを見つけるために、 全ての利用可能なサブセット表現に対して交渉が行われます。 この交渉のために2つのアルゴリズムが利用され、formatMatcherプロパティによって選択されます。 その2つとは完全指定の"basic"アルゴリズムと、実装に依存する"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)ですが、 もしweekdayyearmonthdayhourminutesecondが全て未定義の場合、 yearmonthdayhourminutesecondは"numeric"とみなされます。

説明

toLocaleStringの使用例

ロケール指定無しの基本的な使用時では、デフォルトロケール、デフォルトオプションでフォーマットされた文字列が返されます。

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

// 引数無しでデフォルトロケールとデフォルトタイムゾーンに依存
date.toLocaleString();
// → "12/11/2012, 7:00:00 PM" 実行環境がen-USロケールでAmerica/Los_Angelesが使用された場合

例: localesoptions引数のサポートの確認

localesoptions引数はまだ全てのブラウザでサポートされているわけではありません。 RangeError例外を利用して、不正な言語タグを拒絶する必要条件を指定することで、 これらのサポートが既に実装されているかを確認することが可能です。

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

localesの使用例

この例は日付と時間のフォーマットのローカライズの幾つかのバリエーションを示したものです。 アプリケーションのユーザーインターフェースで使用される言語のフォーマットを取得するには、 locales引数を使用して、その言語指定(可能であればフォールバック用の幾つの言語も)を確定するようにしてください。

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

// 以降はロケールのローカルタイムゾーンがUSの
// America/Los_Angelesとします。

// US英語は、月-日-年の順で使用します。
alert(date.toLocaleString("en-US"));
// → "12/19/2012, 7:00:00 PM"

// イギリス英語は、日-月-年の順で使用します。
alert(date.toLocaleString("en-GB"));
// → "20/12/2012 03:00:00"

// 韓国語は、年-月-日の順で使用します。
alert(date.toLocaleString("ko-KR"));
// → "2012. 12. 20. 오후 12:00:00"

// アラビア語(アラビア語を話すほとんどの国)は、アラビア数字を使用します。
alert(date.toLocaleString("ar-EG"));
// → "٢٠‏/١٢‏/٢٠١٢ ٥:٠٠:٠٠ ص"

// 日本語のためにアプリケーションは日本のカレンダーを使用して、
// 2012年を平成の年号にすることも可能です。
alert(date.toLocaleString("ja-JP-u-ca-japanese"));
// → "24/12/20 12:00:00"

// Balineseのようにリクエストした言語がサポートされていない可能性がある場合、
// このケースでのインドネシア語のようなフォールバック用の言語を含めてください。
alert(date.toLocaleString(["ban", "id"]));
// → "20/12/2012 11.00.00"

optionsの使用例

toLocaleStringに提供される結果は、options引数を使用してカスタマイズ可能です。

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

// weekdayにlongを指定して曜日をリクエスト
var options = {weekday: "long", year: "numeric", month: "long", day: "numeric"};
alert(date.toLocaleString("de-DE", options));
// → "Donnerstag, 20. Dezember 2012"
// (Donnerstagはドイツ語で木曜日)

// UTCを使用して、それを見えるようにすることも可能です。
options.timeZone = "UTC";
options.timeZoneName = "short";
alert(date.toLocaleString("en-US", options));
// → "Thursday, December 20, 2012, GMT"

// アメリカであっても24時間表記が必要なこともあるでしょう。
alert(date.toLocaleString("en-US", {hour12: false}));
// → "12/19/2012, 19:00:00"

日付の大きい数値をフォーマットする場合、Intl.DateTimeFormatオブジェクトを作成し、 そのフォーマットプロパティによって提供される関数を使用するのが望ましいでしょう。

パフォーマンス

仕様

デスクトップ
機能 Chrome Firefox
(Gecko)
IE Opera Safari
基本
localesとoptions
引数
24 29 (29) 11 15 ×
モバイル
機能 Android Chrome for
Android
Firefox
Mobile
IE
Mobile
Opera
Mobile
Safari
Mobile
基本
localesとoptions
引数
× 26 × × × ×

ブラウザ互換性

 Back to top

© 2017 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.

このページは、ページトップのURL先のMozilla Developer Network(以下、MDN)のコンテンツを翻訳した内容を基に構成されています。 構成について異なる点も含まれますので、下記の項目を確認し、必要に応じて元のコンテンツをご確認ください。 もし、誤訳などの間違いを見つけましたら、 @tomofまで教えていただければ幸いです。

  • 特定のブラウザに特化しすぎている情報やあまりにも古い情報、 または試験的に導入されているようなAPIや機能については、省略していることがあります。
  • 例やデモについて、実際にページ内で動作させる関係で一部ソースコードを変更している場合や、 その例で使用しているコンテンツの単語や文章などを日本人向けに変更しいてる場合があります。
  • MDNの更新頻度が高いため、元のコンテンツと比べ情報が古くなっている可能性があります。
  • "訳注:"などの断わりを入れた上で、日本人向けの情報の追記を行っている事があります。