9. Intl.RelativeTimeFormat

#Intl.RelativeTimeFormat

多くの日付ライブラリは、「昨日」、「5 分前」、「2 か月前」などの相対時間の表示をサポートしています。言語ごとに日付の表示形式や関連する単語が異なるため、これらのライブラリのサイズは非常に大きくなります。

現在、ブラウザーには組み込みの Intl.RelativeTimeFormat API が提供されており、これらのライブラリを使用せずに相対時間を直接表示できます。

基本的な使い方

Intl.RelativeTimeFormat() は、言語コードをパラメーターとして受け取り、相対時間インスタンスオブジェクトを返すコンストラクターです。パラメータを省略した場合、デフォルトで現在のランタイムの言語コードが渡されます。

const rtf = new Intl.RelativeTimeFormat('en');

rtf.format(3.14, '秒') // "3.14秒以内"
rtf.format(-15, '分') // "15 分前"
rtf.format(8, 'hour') // "8時間後"
rtf.format(-2, 'day') // "2日前"
rtf.format(3, 'week') // "3週間以内"
rtf.format(-5, 'month') // "5 か月前"
rtf.format(2, 'quarter') // "2 四半期で"
rtf.format(-42, '年') // "42年前"

上記のコードは、相対時間を英語で表示することを指定しています。

以下はスペイン語で相対時間を表示する例です。

const rtf = new Intl.RelativeTimeFormat('es');

rtf.format(3.14, 'second') // "3,14 セグンドスのデントロ"
rtf.format(-15, '分') // "残り 15 分"
rtf.format(8, 'hour') // "8 時間のデントロ"
rtf.format(-2, 'day') // "あと 2 日"
rtf.format(3, 'week') // "3 セマナスのデントロ"
rtf.format(-5, 'month') // "hace 5 meses"
rtf.format(2, 'quarter') // "2 学期のデントロ"
rtf.format(-42, '年') // "hace 42 años"

Intl.RelativeTimeFormat() は、相対時間インスタンスの動作を正確に指定するために、構成オブジェクトを 2 番目のパラメーターとして受け入れることもできます。構成オブジェクトは次のプロパティを共有します。

options.style: 返される文字列のスタイルを示します。指定可能な値には、「long」（「1 か月以内」などのデフォルト値）、「short」（「1 か月以内」など）、「narrow」が含まれます。 ` (「1 か月以内」など)。一部の言語では、「狭い」スタイルは「短い」スタイルに似ています。
options.localeMatcher: 言語パラメータを照合するためのアルゴリズムを表します。可能な値は「最適値」(デフォルト値) と「検索」です。
options.numeric: 返された文字列を数値で表示するかテキストで表示するかを示します。指定可能な値には、「always」 (デフォルト値、常にテキスト表示) および「auto」 (自動変換) が含まれます。

//以下の設定オブジェクトはデフォルト値で渡されます。
const rtf = new Intl.RelativeTimeFormat('en', {
  localeMatcher: 'best fit', // その他の値: 'lookup'
  style: 'long', // その他の値: 'short' または 'narrow'
  数値: 'always', // その他の値: 'auto'
});

// それでは、いくつかの特殊なケースを試してみましょう。

rtf.format(-1, 'day') // "1 日前"
rtf.format(0, 'day') // "0日後"
rtf.format(1, 'day') // "1日以内"
rtf.format(-1, 'week') // "1週間前"
rtf.format(0, 'week') // "0 週間後"
rtf.format(1, 'week') // "1週間以内"

上記のコードでは、「昨日」の代わりに「1 日前」が表示され、「今週」の代わりに「0 週間後」が表示されます。これは、デフォルトでは相対時間がテキスト形式ではなく数値形式で表示されるためです。

この動作を変更するには、構成オブジェクトの numeric 属性を auto に変更します。

const rtf = new Intl.RelativeTimeFormat('en', { 数値: 'auto' });

rtf.format(-1, 'day') // "昨日"
rtf.format(0, 'day') // "今日"
rtf.format(1, 'day') // "明日"
rtf.format(-1, 'week') // "先週"
rtf.format(0, 'week') // "今週"
rtf.format(1, 'week') // "来週"

Intl.RelativeTimeFormat.prototype.format()

相対時間インスタンスオブジェクトの format メソッドは、時間間隔の値と単位である 2 つのパラメータを受け入れます。「unit」は、次の 8 つの値を受け入れることができる文字列です。

年
四半期
月
週
日
時間
分
2番

let rtf = new Intl.RelativeTimeFormat('en');
rtf.format(-1, "日") // "昨日"
rtf.format(2.15, "day") // "2.15 日後

Intl.RelativeTimeFormat.prototype.formatToParts()

相対時間インスタンスオブジェクトの formatToParts() メソッドのパラメータは format() メソッドと同じですが、相対時間の各部分を正確に制御するために配列を返します。

const rtf = new Intl.RelativeTimeFormat('en', { 数値: 'auto' });

rtf.format(-1, '日')
// "昨日"
rtf.formatToParts(-1, '日');
// [{ タイプ: "リテラル"、値: "昨日" }]

rtf.format(3, '週');
// 「3週間後」
rtf.formatToParts(3, '週');
//[
// { タイプ: 'リテラル'、値: 'in ' },
// { タイプ: '整数'、値: '3'、単位: '週' },
// { タイプ: 'リテラル'、値: '週間' }
//]

返される配列の各メンバーは、2 つのプロパティを持つオブジェクトです。

type: 出力値のタイプを示す文字列。
値: 出力内容を示す文字列。
単位: 出力コンテンツが数値を表す場合 (つまり、type 属性が literal ではない)、値の単位を示す unit 属性も存在します。

参考リンク

Intl.RelativeTimeFormat API、Mathias Bynens
Intl.RelativeTimeFormat API 仕様、TC39