Intl.DateTimeFormat() コンストラクター

Intl.DateTimeFormat() コンストラクターは、言語に応じた日付と時刻の書式化を可能にするオブジェクトのためのものです。

構文

new Intl.DateTimeFormat([locales[, options]])

引数

locales Optional

BCP47 言語タグの文字列、または、そのような文字列の配列です。ブラウザーの既定のロケールを使用するには、空の配列を渡してください。。 Unicode 拡張に対応しています (例えば "en-US-u-ca-buddhist" など)。 locales 引数の一般的な形式と解釈は、 Intl のページをご覧ください。次の 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", "ethiopia", "ethiopic", "gregory", "hebrew", "indian", "islamic", "iso8601", "japanese", "persian", "roc"
hc
時制。使用できる値は次の通りです。 "h11", "h12", "h23", "h24".
options Optional

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

dateStyle
format() が呼び出された際に使用される日付の書式化スタイルです。利用可能な値は以下のとおりです。
  • "full"
  • "long"
  • "medium"
  • "short"

dateStyletimeStyle と一緒に使用することができますが、他のオプションと一緒に使用することができません (例えば weekday, hour, month, など)。

timeStyle
format() が呼び出された際に使用される時刻の書式化スタイルです。利用可能な値は以下のとおりです。
  • "full"
  • "long"
  • "medium"
  • "short"

timeStyledateStyle と一緒に使用することができますが、他のオプションと一緒に使用することができません (例えば weekday, hour, month, など)。

calendar
暦です。有効な値は、 "buddhist", "chinese", " coptic", "ethiopia", "ethiopic", "gregory", " hebrew", "indian", "islamic", "iso8601", " japanese", "persian", "roc" です。
dayPeriod
日単位の期間の表現の仕方です。有効な値は、 "narrow", "short", " long" です。
numberingSystem
命数法です。有効な値は、 "arab", "arabext", " bali", "beng", "deva", "fullwide", " gujr", "guru", "hanidec", "khmr", " knda", "laoo", "latn", "limb", "mlym", " mong", "mymr", "orya", "tamldec", " telu", "thai", "tibt" です。
localeMatcher
使用するロケール一致アルゴリズム。利用可能な値は "lookup" と "best fit" です。既定値は "best fit" です。このオプションについての詳細は、 Intl のページをご覧ください。
timeZone
使用するタイムゾーン。実装が認識しなければならない唯一の値は "UTC" です。既定値は、実行時の既定のタイムゾーンです。実装は、 IANA タイムゾーンデータベースのタイムゾーン名、例えば "Asia/Shanghai", "Asia/Kolkata", "America/New_York" なども認識できる場合があります。
hour12
12時制を使用するかどうか (24時制に対して)。可能な値は truefalse です。既定ではロケールに依存します。このオプションは hc 言語タグや hourCycle オプションと一緒に使用された場合、これらを上書きします。
hourCycle
使用する時の周期です。利用可能な値は "h11", "h12", "h23", "h24" です。このオプションは hc 言語タグと一緒に使用された場合はそれを上書きし、両方のオプションが指定されていた場合は hour12 オプションが優先されます。
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 プロパティによるこの交渉や選択には2つのアルゴリズムが利用できます。完全に定義された "basic" アルゴリズムと、実装に依存した"best fit" アルゴリズムです。

weekday
曜日の表現です。利用可能な値は以下の通りです。
  • "long" (例 Thursday)
  • "short" (例 Thu)
  • "narrow" (例 T)。ロケールによっては、 narrow 形式が同じ曜日が2つある場合もあります (例 Tuesday の narrow 形式も T です)。
era
時代の表現です。利用可能な値は以下の通りです。
  • "long" (例 Anno Domini, 紀元)
  • "short" (例 AD)
  • "narrow" (例 A)
year
年の表現です。利用可能な値は以下の通りです。
  • "numeric" (例 2012)
  • "2-digit" (例 12)
month
月の表現です。利用可能な値は以下の通りです。
  • "numeric" (例 2)
  • "2-digit" (例 02)
  • "long" (例 March)
  • "short" (例 Mar)
  • "narrow" (例 M)。ロケールによっては、 narrow 形式が同じ月が2つある場合もあります (例 May の narrow 形式も M です)。
day
日の表現です。利用可能な値は以下の通りです。
  • "numeric" (例 1)
  • "2-digit" (例 01)
hour
時の表現です。利用可能な値は "numeric", "2-digit" です。
minute
分の表現です。利用可能な値は "numeric", "2-digit" です。
second
秒の表現です。利用可能な値は "numeric", "2-digit" です。
fractionalSecondDigits

Firefox 84, Chrome 84, などで追加されました。詳しくは互換性一覧表を参照してください。

秒の小数点以下を表すために使用される数字の桁数 (その先の桁は切り捨てられます)。利用可能な値は次の通りです。
  • 0 (小数点以下は切り捨て)
  • 1 (小数点以下は1桁で表される。例えば、 736 は 7 と書式化される。)
  • 2 (小数点以下は2桁で表される。例えば、 736 は 73 と書式化される。)
  • 3 (小数点以下は2桁で表される。例えば、 736 は 736 と書式化される。)
timeZoneName
タイムゾーン名の表現です。利用可能な値は以下の通りです。
  • "long" (例 British Summer Time)
  • "short" (例 GMT+1)

日付・時間コンポーネントプロパティの既定値は undefined ですが、すべてのコンポーネントプロパティが undefined であった場合、 year, month, day は "numeric" であると仮定されます。

DateTimeFormat の使用

ロケールを指定しない基本的な使用方法では、 DateTimeFormat は既定のロケールとオプションを使用します。

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

// toLocaleString without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(new Intl.DateTimeFormat().format(date));
// → "12/19/2012" if run with en-US locale (language) and time zone America/Los_Angeles (UTC-0800)

timeStyle と dateStyle の使用

let o = new Intl.DateTimeFormat("en" , {
  timeStyle: "short"
});
console.log(o.format(Date.now())); // "13:31 AM"

let o = new Intl.DateTimeFormat("en" , {
  dateStyle: "short"
});
console.log(o.format(Date.now())); // "07/07/20"

let o = new Intl.DateTimeFormat("en" , {
  timeStyle: "medium",
  dateStyle: "short"
});
console.log(o.format(Date.now())); // "07/07/20, 13:31:55 AM"

仕様書

ブラウザーの互換性

BCD tables only load in the browser

以下の表は、クロスブラウザーの安定性にまだ達していない新機能の日々の実装状況を示しています。このデータは、 JavaScript の標準テストスイートである Test262 で関連する機能テストをナイトリービルド、または各ブラウザの JavaScript エンジンの最新リリースで実行することで生成されます。

関連情報