# Intl.RelativeTimeFormat
很多日期庫支持顯示相對時間，比如“昨天”、“五分鐘前”、“兩個月之前”等等。由于不同的語言，日期顯示的格式和相關詞語都不同，造成這些庫的體積非常大。
現在，瀏覽器提供內置的 Intl.RelativeTimeFormat API，可以不使用這些庫，直接顯示相對時間。
## 基本用法
`Intl.RelativeTimeFormat()`是一個構造函數，接受一個語言代碼作為參數，返回一個相對時間的實例對象。如果省略參數，則默認傳入當前運行時的語言代碼。
```javascript
const rtf = new Intl.RelativeTimeFormat('en');
rtf.format(3.14, 'second') // "in 3.14 seconds"
rtf.format(-15, 'minute') // "15 minutes ago"
rtf.format(8, 'hour') // "in 8 hours"
rtf.format(-2, 'day') // "2 days ago"
rtf.format(3, 'week') // "in 3 weeks"
rtf.format(-5, 'month') // "5 months ago"
rtf.format(2, 'quarter') // "in 2 quarters"
rtf.format(-42, 'year') // "42 years ago"
```
上面代碼指定使用英語顯示相對時間。
下面是使用西班牙語顯示相對時間的例子。
```javascript
const rtf = new Intl.RelativeTimeFormat('es');
rtf.format(3.14, 'second') // "dentro de 3,14 segundos"
rtf.format(-15, 'minute') // "hace 15 minutos"
rtf.format(8, 'hour') // "dentro de 8 horas"
rtf.format(-2, 'day') // "hace 2 días"
rtf.format(3, 'week') // "dentro de 3 semanas"
rtf.format(-5, 'month') // "hace 5 meses"
rtf.format(2, 'quarter') // "dentro de 2 trimestres"
rtf.format(-42, 'year') // "hace 42 a?os"
```
`Intl.RelativeTimeFormat()`還可以接受一個配置對象，作為第二個參數，用來精確指定相對時間實例的行為。配置對象共有下面這些屬性。
- options.style：表示返回字符串的風格，可能的值有`long`（默認值，比如“in 1 month”）、`short`（比如“in 1 mo.”）、`narrow`（比如“in 1 mo.”）。對于一部分語言來說，`narrow`風格和`short`風格是類似的。
- options.localeMatcher：表示匹配語言參數的算法，可能的值有`best fit`（默認值）和`lookup`。
- options.numeric：表示返回字符串是數字顯示，還是文字顯示，可能的值有`always`（默認值，總是文字顯示）和`auto`（自動轉換）。
```javascript
// 下面的配置對象，傳入的都是默認值
const rtf = new Intl.RelativeTimeFormat('en', {
localeMatcher: 'best fit', // 其他值：'lookup'
style: 'long', // 其他值：'short' or 'narrow'
numeric: 'always', // 其他值：'auto'
});
// Now, let’s try some special cases!
rtf.format(-1, 'day') // "1 day ago"
rtf.format(0, 'day') // "in 0 days"
rtf.format(1, 'day') // "in 1 day"
rtf.format(-1, 'week') // "1 week ago"
rtf.format(0, 'week') // "in 0 weeks"
rtf.format(1, 'week') // "in 1 week"
```
上面代碼中，顯示的是“1 day ago”，而不是“yesterday”；顯示的是“in 0 weeks”，而不是“this week”。這是因為默認情況下，相對時間顯示的是數值形式，而不是文字形式。
改變這個行為，可以把配置對象的`numeric`屬性改成`auto`。
```javascript
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
rtf.format(-1, 'day') // "yesterday"
rtf.format(0, 'day') // "today"
rtf.format(1, 'day') // "tomorrow"
rtf.format(-1, 'week') // "last week"
rtf.format(0, 'week') // "this week"
rtf.format(1, 'week') // "next week"
```
## Intl.RelativeTimeFormat.prototype.format()
相對時間實例對象的`format`方法，接受兩個參數，依次為時間間隔的數值和單位。其中，“單位”是一個字符串，可以接受以下八個值。
- year
- quarter
- month
- week
- day
- hour
- minute
- second
```javascript
let rtf = new Intl.RelativeTimeFormat('en');
rtf.format(-1, "day") // "yesterday"
rtf.format(2.15, "day") // "in 2.15 days
```
## Intl.RelativeTimeFormat.prototype.formatToParts()
相對時間實例對象的`formatToParts()`方法的參數跟`format()`方法一樣，但是返回的是一個數組，用來精確控制相對時間的每個部分。
```javascript
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
rtf.format(-1, 'day')
// "yesterday"
rtf.formatToParts(-1, 'day');
// [{ type: "literal", value: "yesterday" }]
rtf.format(3, 'week');
// "in 3 weeks"
rtf.formatToParts(3, 'week');
// [
// { type: 'literal', value: 'in ' },
// { type: 'integer', value: '3', unit: 'week' },
// { type: 'literal', value: ' weeks' }
// ]
```
返回數組的每個成員都是一個對象，擁有兩個屬性。
- type：字符串，表示輸出值的類型。
- value：字符串，表示輸出的內容。
- unit：如果輸出內容表示一個數值（即`type`屬性不是`literal`），那么還會有`unit`屬性，表示數值的單位。
## 參考鏈接
- [The Intl.RelativeTimeFormat API](https://developers.google.com/web/updates/2018/10/intl-relativetimeformat), Mathias Bynens
- [Intl.RelativeTimeFormat API Specification](https://github.com/tc39/proposal-intl-relative-time#api), TC39
