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

Date.prototype.toLocaleTimeString()

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

構文

dateObj.toLocaleTimeString([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です。ただし、hour および minutesecond プロパティがすべて undefined のときは、hourminutesecond"numeric" とみなされます。

戻り値

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

toLocaleTimeString() を使う

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

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

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

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

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

function toLocaleTimeStringSupportsLocales() {
  try {
    new Date().toLocaleTimeString('i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}

locales を使う

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

var 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 引数でカスタマイズできます:

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

// アプリケーションで UTC を用いてそれを示したい場合
var 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"

性能

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

仕様

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

ブラウザの実装状況

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

関連情報

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

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