Date.prototype.toLocaleString()

背景

由於咱們開發的項目在多個國家和地區使用，不一樣國家和地區對於日期的顯示習慣是不一樣的。例如：咱們習慣使用 年-月-日 的方式顯示日期，而英國習慣使用 日-月-年 的方式顯示日期。所以在這裏介紹一下日期本地化函數 toLocaleString。

簡介

toLocaleString() 方法返回日期對象的字符串，該字符串因語言環境、配置的選項不一樣而不一樣。新增的參數 locales 和 options 使程序可以指定語言環境、選項。在舊版瀏覽器中， locales 和 options 參數被忽略。

let event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// 英國使用 日-月-年 的順序，24小時制，不帶 AM/PM
event.toLocaleString('en-GB', { timeZone: 'UTC' }); // 20/12/2012, 03:00:00

// 韓國使用 年-月-日 的順序，12小時制 + AM/PM
event.toLocaleString('ko-KR', { timeZone: 'UTC' }); // 2012. 12. 20. 오전 3:00:00

複製代碼

語法

dateObj.toLocaleString([locales [, options]])
複製代碼

查看 瀏覽器兼容性，看下哪些瀏覽器支持 locales 和 options 參數，還能夠參看 例子：檢測 locales 和 options 參數支持狀況。

參數

• locales：

  可選，值是遵循 BCP47 規範的語言標記字符串或此類字符串數組，若是想使用瀏覽器默認的語言環境，忽略這個參數或者傳 undefined 便可。

  支持 Unicode 擴展。例如：'en-US-u-ca-buddhist'，其中 'en-US' 是 BCP47 語言標記，表示美國使用的英語；'u' 表明 Unicode，表示其後是 Unicode 擴展；'ca' 表明 Calendar，'buddhist' 是 ca 的值。容許使用如下 Unicode 擴展密鑰：

  • nu

    Numbering system. Possible values include: 'arab', 'arabext', 'bali', 'beng', 'deva', 'fullwide', 'gujr', 'guru', 'hanidec', 'khmr', 'knda', 'laoo', 'latn', 'limb', 'mlym', 'mong', 'mymr', 'orya', 'tamldec', 'telu', 'thai', 'tibt'

  • ca

    Calendar. Possible values include: 'buddhist', 'chinese', 'coptic', 'ethiopia', 'ethiopic', 'gregory', 'hebrew', 'indian', 'islamic', 'islamic', 'iso8601', 'japanese', 'persian', 'roc'.

  • hc

    Hour cycle. Possible values include: 'h11', 'h12', 'h23', 'h24'.

  const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
  event.toLocaleString('en-US', { timeZone: 'UTC' }); // '12/20/2012, 3:00:00 AM'
  event.toLocaleString('en-US-u-ca-buddhist', { timeZone: 'UTC' }); // '12/20/2555, 3:00:00 AM'
  複製代碼

  更多信息請參考 Intl page。

• options: 可選，對象，有如下屬性：

  • dateStyle：可選值：'full', 'long', 'medium', 'short'。

    const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
    event.toLocaleString('en-GB', { timeZone: 'UTC' }); // '20/12/2012, 03:00:00'
    event.toLocaleString('en-GB', { timeZone: 'UTC', dateStyle: 'full' }); // 'Thursday, 20 December 2012'
    event.toLocaleString('en-GB', { timeZone: 'UTC', dateStyle: 'long' }); // '20 December 2012'
    event.toLocaleString('en-GB', { timeZone: 'UTC', dateStyle: 'medium' }); // '20 Dec 2012'
    event.toLocaleString('en-GB', { timeZone: 'UTC', dateStyle: 'short' }); // '20/12/2012'
    複製代碼

  • timeStyle：可選值：'full', 'long', 'medium', 'short'。

    const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
    event.toLocaleString('en-GB', { timeZone: 'UTC' }); // '20/12/2012, 03:00:00'
    event.toLocaleString('en-GB', { timeZone: 'UTC', timeStyle: 'full' }); // '03:00:00 Coordinated Universal Time'
    event.toLocaleString('en-GB', { timeZone: 'UTC', timeStyle: 'long' }); // '03:00:00 UTC'
    event.toLocaleString('en-GB', { timeZone: 'UTC', timeStyle: 'medium' }); // '03:00:00'
    event.toLocaleString('en-GB', { timeZone: 'UTC', timeStyle: 'short' }); // '03:00'
    複製代碼

  • localeMatcher：locale 匹配策略；可選值是：'lookup', 'best fit'；默認值是 'best fit'。更多信息請參考 Intl page.

  • timeZone: 指定時區；可選值是：'UTC'；默認值是當前瀏覽器的默認時區。瀏覽器也能識別出 IANA 時區數據庫 的時區名稱，例如：'Asia/Shanghai', 'Asia Kolkata', 'America/New_York'。

  • hour12: 是否使用12小時制時間（對應的是 24小時制）；可選值：true, false。默認值和 locale 有關，它比 locales 中 Unicode 擴展標記中的 hc 和 hourCycle 優先級都高。

  • hourCycle: 要使用的小時循環。可選值：'h11', 'h12', 'h23', 'h24'。它比 locales 中 Unicode 擴展標記中的 hc 優先級高，比 hour12 優先級低。

  • formatMatcher: 格式化匹配策略；可選值是 'lookup', 'best fit'；默認值是 'best fit'。

  • weekday：星期的表示，可選值以下：

    • 'long' (e.g. Thursday)
    • 'short' (e.g. Thu)
    • 'narrow' (e.g. T) 注意一些地區的簡寫多是相同的，好比：Thursday & Thursday。

  • era：時代的表示，可選值以下：

    • 'long' (e.g. Anno Domini) 公元
    • 'short' (e.g. AD)
    • 'narrow' (e.g. A)

  • year：年的表示，可選值以下：

    • 'numeric' (e.g. 2012)
    • '2-digit' (e.g. 12)

  • month：月的表示，可選值以下：

    • 'numeric' (e.g. 2)
    • '2-digit' (e.g. 02)
    • 'long' (e.g. March)
    • 'short' (e.g. Mar)
    • 'narrow' (e.g. M) 注意一些地區的月的 'narrow' 簡寫多是相同的，好比：March & May。

  • day：日的表示，可選值以下：

    • 'numeric' (e.g. 1)
    • '2-digit' (e.g. 01)

  • hour：小時的表示，可選值是：'numeric' & '2-digit'

  • minute：分鐘的表示，可選值是：'numeric' & '2-digit'

  • second：秒的表示，可選值是：'numeric' & '2-digit'

  • timeZoneName：時區名的表示，可選值以下：

    • 'long' (e.g. British Summer Time)
    • 'short' (e.g. GMT+1)

Demos

不帶參數

沒有指定語言環境（locales）時，返回一個使用默認語言環境和格式設置（options）的格式化字符串。

// toLocaleString 不包含參數的返回值取決於當前瀏覽器的默認語言環境(locales)和默認時區(time zone)，我機器的語言環境是簡體中文（cn-ZH），時區是東八區
const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
event.toLocaleString(); // '2012/12/20 上午11:00:00'

// 若是是在 en-US 語言環境和 America/Los_Angeles 時區運行返回值爲 '12/19/2012, 7:00:00 PM'
event.toLocaleString('en-US', { timeZone: 'America/Los_Angeles' }); // '12/19/2012, 7:00:00 PM'
複製代碼

locales 和 options 參數不是全部的瀏覽器都支持。爲了檢測瀏覽器是否支持它們，可使用不合法的語言標籤，若是實現環境支持該參數，則會拋出一個 RangeError 異常，反之會忽略參數。

function toLocaleStringSupportsLocales() {
    try {
        new Date().toLocaleString('i');
    } catch (e) {
        return e.name === 'RangeError';
    }
    return false;
}
複製代碼

使用 locales 參數

下例展現了使用 locales 參數指定語言環境後，輸出的日期字符串。

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

// en-US 使用 month-day-year 的順序展現年月日
date.toLocaleString('en-US', { timeZone: 'America/Los_Angeles' }); // '12/19/2012, 7:00:00 PM'

// en-GB 使用 day-month-year 順序展現年月日
date.toLocaleString('en-GB', { timeZone: 'UTC' }); // // '20/12/2012 03:00:00'

// 韓語使用 year-month-day 順序展現年月日
date.toLocaleString('ko-KR', { timeZone: 'Asia/Seoul' }); // '2012. 12. 20. 오후 12:00:00'

// 在日本，程序可能想指定使用日本日曆,
// 2012是平成24年（平成是日本天皇明仁的年號, 由1989年1月8日起開始計算直至如今）
date.toLocaleString('ja-JP-u-ca-japanese', { timeZone: 'Asia/Tokyo' }); // '24/12/20 12:00:00'

// 當請求一個語言可能不支持，如巴釐(ban)，如有備用的語言印尼語(id)，那麼將使用印尼語(id)
date.toLocaleString(['ban', 'id']); // '20/12/2012 11.00.00'
複製代碼

使用 options 參數

可使用 options 參數來自定義 toLocaleString 方法返回的字符串。

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

// options 包含參數 weekday，而且該參數的值爲 long
const options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
date.toLocaleString('en-US', options); // 'Thursday, December 20, 2012'

// 指定 timeZone 爲 'UTC'
options.timeZone = 'UTC';
// 不指定 timeZoneName 仍然顯示的是世界標準時間，可是 UTC 三個字母不會顯示
options.timeZoneName = 'short';
date.toLocaleString('en-US', options); // 'Thursday, December 20, 2012, UTC'

// 使用24小時制
date.toLocaleString('en-US', { hour12: false }); // '12/19/2012, 19:00:00'
複製代碼

其餘文章連接

TypeScript 踩坑之旅

[譯文]一步步構建發佈一個 TypeScript NPM 包

npm install package-lock.json 的更新策略

[譯]瀏覽器語言首選項

Date.prototype.toLocaleString()