DateTimeFormat.prototype.formatToParts()

Intl.DateTimeFormat.prototype.formatToParts() メソッドは、DateTimeFormat フォーマットによって生成されるロケール対応書式を設定可能にします

構文

Intl.DateTimeFormat.prototype.formatToParts(date)

パラメーター

date Optional

フォーマットする日付。

戻り値

フォーマットされた日付のパーツを含むオブジェクトの Array。

説明

formatToParts() メソッドは、日付文字列のフォーマットをカスタマイズするときに役立ちます。これは、ロケール特有の部分を保持しながら、カスタム文字列を構築できるロケール特有のトークンを含むオブジェクトの Array を返します。formatToParts() メソッドが返却する構造は、このようになります：

[
  { type: "day", value: "17" },
  { type: "weekday", value "Monday" }
]

可能な type 以下のとおりです。

day

日付として使用される文字列。たとえば、 "17"。

dayPeriod

日付期間として使用される文字列。たとえば、"AM" や "PM"（現在は、"dayperiod" として実装されています。バグ 1260858) を見てください）。

era

時代として使用される文字列。たとえば、"BC" や "AD"。

hour

時刻として使用される文字列。たとえば、"3" や "03"。

minute

分として使用される文字列。たとえば、"00"。

month

月として使用される文字列。たとえば、"12"。

second

秒として使用される文字列。たとえば、"07" や "42"。

separator

日付や時刻の区切りとして使用される文字列。たとえば、" : , / " のいずれか。（"separator" は "literal" に変更されるでしょう。バグ 1260858 を見てください）。

timeZoneName

タイムゾーン名として使用される文字列。たとえば、"UTC"。

weekday

曜日として使用される文字列。たとえば、"M" や "Monday"、"Montag"。

year

年として使用される文字列。たとえば、"2012" や "96"。

例

DateTimeFormat は、ローカライズされた、不透過で直接操作できない文字列を出力します：

var date = Date.UTC(2012, 11, 17, 3, 0, 42);

var formatter = new Intl.DateTimeFormat("en-us", {
  weekday: 'long',
  year: 'numeric',
  month: 'numeric',
  day: 'numeric',
  hour: 'numeric',
  minute: 'numeric',
  second: 'numeric',
  hour12: true,
  timeZone: "UTC"
});

formatter.format(date);
// "Monday, 12/17/2012, 3:00:42 AM"

しかし、多くのユーザーインターフェースにおいて、この文字列フォーマットをカスタマイズしたいという要望があります。formatToParts メソッドは、文字列のパーツを提供することで、DateTimeFormat フォーマットによって生成されるロケール対応書式を設定可能にします：

formatter.formatToParts(date);

// 戻り値： 
[ 
  { type: 'weekday',   value: 'Monday' }, 
  { type: 'separator', value: ', '     }, 
  { type: 'month',     value: '12'     }, 
  { type: 'separator', value: '/'      }, 
  { type: 'day',       value: '17'     }, 
  { type: 'separator', value: '/'      }, 
  { type: 'year',      value: '2012'   }, 
  { type: 'separator', value: ', '     }, 
  { type: 'hour',      value: '3'      }, 
  { type: 'separator', value: ':'      }, 
  { type: 'minute',    value: '00'     }, 
  { type: 'separator', value: ':'      }, 
  { type: 'second',    value: '42'     }, 
  { type: 'separator', value: ' '      }, 
  { type: 'dayperiod', value: 'AM'     } 
]

情報を個別に利用してフォーマットし、独自の方法で再結合できます。たとえば、Array.prototype.map() や アロー関数、switch ステートメント、template strings、Array.prototype.reduce() で使用できます。

var dateString = formatter.formatToParts(date).map(({type, value}) => { 
  switch (type) {
    case 'dayperiod': return `<strong>${value}</strong>`; 
    default : return value; 
  } 
}).reduce((string, part) => string + part);

formatToParts() メソッドを使用した場合、日付期間を太字にします。

console.log(formatter.format(date));
// "Monday, 12/17/2012, 3:00:42 AM"

console.log(dateString);
// "Monday, 12/17/2012, 3:00:42 <strong>AM</strong>"

仕様

ブラウザ実装状況

[1] 現在、このメソッドは、B2G システムアプリにのみ公開されています（バグ 1216150 を見てください）。

関連項目

• Intl.DateTimeFormat
• Intl.DateTimeFormat.prototype.format
• Date.prototype.toLocaleString()
• Date.prototype.toLocaleDateString()
• Date.prototype.toLocaleTimeString()