Intl.DateTimeFormat

Baseline 已廣泛支援

此功能已成熟,可跨多種裝置和瀏覽器版本使用。自 2017 年 9 月以來,它已在瀏覽器中提供。

Intl.DateTimeFormat 物件支援進行語言敏感的日期和時間格式化。

試一試

const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738));
// Results below assume UTC timezone - your results may vary

// Specify default date formatting for language (locale)
console.log(new Intl.DateTimeFormat("en-US").format(date));
// Expected output: "12/20/2020"

// Specify default date formatting for language with a fallback language (in this case Indonesian)
console.log(new Intl.DateTimeFormat(["ban", "id"]).format(date));
// Expected output: "20/12/2020"

// Specify date and time format using "style" options (i.e. full, long, medium, short)
console.log(
  new Intl.DateTimeFormat("en-GB", {
    dateStyle: "full",
    timeStyle: "long",
    timeZone: "Australia/Sydney",
  }).format(date),
);
// Expected output: "Sunday, 20 December 2020 at 14:23:16 GMT+11"

建構函式

Intl.DateTimeFormat()

建立一個新的 Intl.DateTimeFormat 物件。

靜態方法

Intl.DateTimeFormat.supportedLocalesOf()

返回一個數組,其中包含提供的區域設定中受支援的那些區域設定,而無需回退到執行時預設區域設定。

例項屬性

這些屬性定義在 Intl.DateTimeFormat.prototype 上,並被所有 Intl.DateTimeFormat 例項共享。

Intl.DateTimeFormat.prototype.constructor

建立例項物件的建構函式。對於 Intl.DateTimeFormat 例項,初始值是 Intl.DateTimeFormat 建構函式。

Intl.DateTimeFormat.prototype[Symbol.toStringTag]

[Symbol.toStringTag] 屬性的初始值是字串 "Intl.DateTimeFormat"。此屬性用於 Object.prototype.toString()

例項方法

Intl.DateTimeFormat.prototype.format()

用於根據此 DateTimeFormat 物件的語言環境和格式選項格式化日期的 getter 函式。

Intl.DateTimeFormat.prototype.formatRange()

此方法接收兩個 Date 物件,並根據例項化 DateTimeFormat 時提供的語言環境和選項,以最簡潔的方式格式化日期範圍。

Intl.DateTimeFormat.prototype.formatRangeToParts()

此方法接收兩個 Date 物件,並返回一個物件陣列,其中包含表示格式化日期範圍的每個部分的特定於語言環境的標記。

Intl.DateTimeFormat.prototype.formatToParts()

返回一個物件 Array,其中包含表示日期字串的各個部分,可用於自定義的、符合語言環境的格式化。

Intl.DateTimeFormat.prototype.resolvedOptions()

返回一個新物件,其屬性反映在物件初始化過程中計算出的語言環境和格式化選項。

示例

使用 DateTimeFormat

在不指定語言環境的基本用法中,DateTimeFormat 使用預設語言環境和預設選項。

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

// toLocaleString without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(new Intl.DateTimeFormat().format(date));
// "12/19/2012" if run with en-US locale (language) and time zone America/Los_Angeles (UTC-0800)

使用語言環境

本示例展示了本地化日期和時間格式的一些變化。為了獲得應用程式使用者介面中所用語言的格式,請確保使用 locales 引數指定該語言(以及可能的某些備用語言)。

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

// Results below use the time zone of America/Los_Angeles (UTC-0800, Pacific Standard Time)

// US English uses month-day-year order
console.log(new Intl.DateTimeFormat("en-US").format(date));
// "12/19/2012"

// British English uses day-month-year order
console.log(new Intl.DateTimeFormat("en-GB").format(date));
// "19/12/2012"

// Korean uses year-month-day order
console.log(new Intl.DateTimeFormat("ko-KR").format(date));
// "2012. 12. 19."

// Arabic in most Arabic speaking countries uses real Arabic digits
console.log(new Intl.DateTimeFormat("ar-EG").format(date));
// "١٩‏/١٢‏/٢٠١٢"

// for Japanese, applications may want to use the Japanese calendar,
// where 2012 was the year 24 of the Heisei era
console.log(new Intl.DateTimeFormat("ja-JP-u-ca-japanese").format(date));
// "24/12/19"

// when requesting a language that may not be supported, such as
// Balinese, include a fallback language, in this case Indonesian
console.log(new Intl.DateTimeFormat(["ban", "id"]).format(date));
// "19/12/2012"

使用選項

日期和時間格式可以使用 options 引數進行自定義。

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

// request a weekday along with a long date
let options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(new Intl.DateTimeFormat("de-DE", options).format(date));
// "Donnerstag, 20. Dezember 2012"

// an application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// "Thursday, December 20, 2012, GMT"

// sometimes you want to be more precise
options = {
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  timeZone: "Australia/Sydney",
  timeZoneName: "short",
};
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// "2:00:00 pm AEDT"

// sometimes you want to be very precise
options.fractionalSecondDigits = 3; // number digits for fraction-of-seconds
console.log(new Intl.DateTimeFormat("en-AU", options).format(date));
// "2:00:00.200 pm AEDT"

// sometimes even the US needs 24-hour time
options = {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  hour12: false,
  timeZone: "America/Los_Angeles",
};
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// "12/19/2012, 19:00:00"

// to specify options but use the browser's default locale, use undefined
console.log(new Intl.DateTimeFormat(undefined, options).format(date));
// "12/19/2012, 19:00:00"

// sometimes it's helpful to include the period of the day
options = { hour: "numeric", dayPeriod: "short" };
console.log(new Intl.DateTimeFormat("en-US", options).format(date));
// 10 at night

使用的日曆和數字格式也可以透過 options 引數獨立設定。

js
const options = { calendar: "chinese", numberingSystem: "arab" };
const dateFormat = new Intl.DateTimeFormat(undefined, options);
const usedOptions = dateFormat.resolvedOptions();

console.log(usedOptions.calendar);
// "chinese"

console.log(usedOptions.numberingSystem);
// "arab"

console.log(usedOptions.timeZone);
// "America/New_York" (the users default timezone)

規範

規範
ECMAScript® 2026 國際化 API 規範
# datetimeformat-objects

瀏覽器相容性

另見