# Intl API
>`Intl` 物件是 ECMAScript 國際化 API 的一個命名空間，它提供精確的字串對比、數字格式化與日期時間格式化。

原來JS內建這麼好用的東西，會對翻譯、排序與時間等格式化有很便捷的使用，如果使用得當，覺得會是對程式與專案上有更好的優化。

## Intl.Collator 字串比對與排序

//比較
const c = new Intl.Collator( 'en' );      //'zh' 可替換成別的語系 如：en、de 等
console.log( c.compare( "好", "好" ) );    // 回傳0 表示兩者相同
console.log( c.compare( "n好", "好" ) );    // 回傳-1 表示不同
console.log( c.compare( "好s", "好" ) );    // 回傳1 表示不同

//排序
const list = [ '5', '1', '12', '4' ]
const c = new Intl.Collator( "en", { numeric: true } );
console.log( list.sort( c.compare ) );    // 回傳 [ '1', '12', '4', '5' ]

* numeric : 是否按照數值比較排序
## Intl.ListFormat 陣列格式化

const arr = [ 'Mary', 'Ban', 'Tom', 'Mom' ];

const list = new Intl.ListFormat( 'zh-TW', {
style: 'long',                    
type: 'conjunction' } );      

console.log( list.format( arr ) );  //Mary, Ban, Tom, 和 Mom 

* style
-
* long
* narrow
* short
* type
-
* conjunction : and 和
* disjunction : or 或
* unit : 間距空格

## Intl.NumberFormat 數字格式化

const num = 12345;

//僅需百位符號
const n1 = new Intl.NumberFormat( 'zh-TW');
console.log( n1.format( num ) ); // 12,345


//貨幣的文字
const n2 = new Intl.NumberFormat( 'zh-TW', {
    style: 'currency',
    currency: 'NTD',
    maximumFractionDigits: 0,
} );
console.log( n2.format( num ) ); // NTD 12,345

//單位
const n3 = new Intl.NumberFormat( 'zh-TW', {
    style: 'unit',
    unit: 'kilometer',
    unitDisplay: 'short',
} );
console.log( n3.format( num ) ); // 12,345 公里

//符號更換
const n3 = new Intl.NumberFormat( 'zh-TW', {
    notation: 'compact'
} );
console.log( n3.format( num ) ); // 1.2萬

* 語言環境
-
* zh-Hans-CN-u-nu-hanidec ： 中文文字的轉換
* ar-EG ： 阿拉伯數字的轉換
* ...
* useGrouping
-
百分位符號，預設：true。
* style
-
* currency : 貨幣，需搭配 currency
* unit ： 單位，需搭配 unit

* currency
-
* NTD : 台幣
* JPY : 日幣
* USD : 美金
* ...只要是貨幣簡寫都行
* currencyDisplay ，可搭配currency
-
* symbol ： 符號 (default)
* code ： ISO貨幣代碼
* name ： 文字轉換

* unit ，可搭配unitDisplay
-
* kilometer ： 公里
* centimeter ：公分
* liter ： 升
* kilometer-per-hour ： 一小時幾公里

* unitDisplay，沒有使用，unit預設為short
-
* long ： 全稱
* short ： 簡寫
* narrow ： 簡寫，去掉與數字間的空格

* maximumFractionDigits
-
最大小數點數，判斷的值為1到21，默認值為1。
* maximumSignificantDigits
-
比如殺價時，都會問問老闆能不能去掉尾數；有效值為1到15，默認值為15。
* minimumIntegerDigits
-
補零。
* notation
-
* standard : 百位符號（預設）
* compact : 簡寫符號
* engineering : 工程符號
* scientific : 科學符號

## Intl.DateTimeFormat 日期時間格式化

const today = new Date();
const b1 = new Intl.DateTimeFormat( 'zh-TW', {
    dateStyle: 'full',
    timeStyle: 'short'
} );
console.log( b1.format( today ) );  // 2023年6月20日 星期二 下午1:35 


const b = new Intl.DateTimeFormat( 'zh-TW', {
    dayPeriod: 'short'
} );
console.log( b.format( today ) );  // 下午

const c = new Intl.DateTimeFormat( 'fr-CA', {
    year: "numeric", 
    month: "2-digit", 
    day: "2-digit"
} );
console.log( c.format( today ) ); //2023-06-20

* dateStyle、timeStyle
-
* full
* long
* medium
* short (default)

* year、month、day、hour
-
* numeric
* 2-digit

* dayPeriod (不可與timeStyle、dateStyle搭配使用)
-
* long
* narrow
* short

## Intl.RelativeTimeFormat 相對時間格式化

const today = new Date();
const f = new Intl.RelativeTimeFormat( 'en', {
    style: 'short',
    numeric: 'auto',
} );
console.log( f.format( 0, 'days' ) );  // today
console.log( f.format( 0, 'year' ) );  // this yr.
console.log( f.format( 4, 'year' ) );  // in 4 yr.
console.log( f.format( 3, 'month' ) ); // in 3 mo.

const today = new Date();
const f = new Intl.RelativeTimeFormat( 'zh-tw', {
    style: 'short',
    numeric: 'auto',
} );
console.log( f.format( 0, 'days' ) );  // 今天
console.log( f.format( 0, 'year' ) );  // 今年
console.log( f.format( 4, 'month' ) ); // 4 年後
console.log( f.format( 3, 'month' ) ); // 3 個月後

* style
-
* long
* narrow
* short
* numeric
-
* auto
* always (default)

## Intl.DisplayNames

const d = new Intl.DisplayNames( 'zh-TW', {
    type: 'language',
    style: 'short',  // default 'long'   
} );

// type: 'language',
console.log( d.of( 'Hant' ) ); // hant

// type: 'script',
console.log( d.of( 'Hant' ) ); // 繁體

* 語言環境
-
* zh-Hant ： 繁體
* zh-TW
* ...
* type
-
* language : 語言名稱
* region : 地區名稱
* script : : script 名稱
* currency : 幣別名稱
* calendar : 日曆（找不到對應參數）
* dateTimeField : 日期時間名稱
* style (外國語系比較有感)
-
* long (default)
* narrow
* short

## 注意
Intl的函數有些參數目前只有瀏覽器有實作，在 server 使用是須留意相容性或需透過 Babel 處理，相關的相容性在MDN都可以找到參考。

## 參考
[Intl-MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
[Intl.RelativeTimeFormat Is A Game Changer In JavaScript](https://www.youtube.com/watch?v=Nn-5dTtVqqk)
[How To Easily Format Currencies In JavaScript](https://www.youtube.com/watch?v=H-FeuIKvHS4&ab_channel=WebDevSimplified)
[How To Easily Format Dates In JavaScript](https://www.youtube.com/watch?v=jZUHZDXmQ_A&ab_channel=WebDevSimplified)
[[WebAPIs] Intl API](https://pjchender.dev/webapis/webapis-intl/)
[JS Intl对象完整简介及在中文中的应用](https://www.zhangxinxu.com/wordpress/2019/09/js-intl-zh/)