1. Web
  2. JavaScript
  3. 參考
  4. 標準內建物件
  5. Date
  6. toLocaleDateString()

Date.prototype.toLocaleDateString()

Baseline 已廣泛支援

此特性已相當成熟，可在許多裝置和瀏覽器版本上使用。自 ⁨2015 年 7 月⁩以來，各瀏覽器均已提供此特性。

toLocaleDateString() 方法是 Date 例項的一個方法，它返回一個字串，該字串是基於本地時區的日期部分的一個語言敏感的表示。在支援 Intl.DateTimeFormat API 的實現中，此方法會委託給 Intl.DateTimeFormat。

每次呼叫 toLocaleDateString 時，都必須在大型本地化字串資料庫中進行搜尋，這可能效率低下。當使用相同的引數多次呼叫該方法時，最好建立一個 Intl.DateTimeFormat 物件並使用其 format() 方法，因為 DateTimeFormat 物件會記住傳遞給它的引數，並可能決定快取資料庫的一部分，以便將來的 format 呼叫可以在一個更受限的上下文中搜索本地化字串。

試一試

const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};

console.log(event.toLocaleDateString("de-DE", options));
// Expected output (varies according to local timezone): Donnerstag, 20. Dezember 2012

console.log(event.toLocaleDateString("ar-EG", options));
// Expected output (varies according to local timezone): الخميس، ٢٠ ديسمبر، ٢٠١٢

console.log(event.toLocaleDateString(undefined, options));
// Expected output (varies according to local timezone and default locale): Thursday, December 20, 2012

語法

js
toLocaleDateString()
toLocaleDateString(locales)
toLocaleDateString(locales, options)

引數

locales 和 options 引數自定義函式行為，並允許應用程式指定應使用的語言的格式約定。

在支援 Intl.DateTimeFormat API 的實現中，這些引數與 Intl.DateTimeFormat() 建構函式的引數完全對應。不支援 Intl.DateTimeFormat 的實現則被要求忽略這兩個引數，使得所使用的區域設定和返回字串的格式完全取決於具體實現。

locales 可選

一個帶有 BCP 47 語言標籤 的字串，或此類字串的陣列。對應於 Intl.DateTimeFormat() 建構函式的 locales 引數。

在不支援 Intl.DateTimeFormat 的實現中，將忽略此引數，通常會使用主機的區域設定。

options 可選

一個調整輸出格式的物件。對應於 Intl.DateTimeFormat() 建構函式的 options 引數。timeStyle 選項必須是 undefined，否則將丟擲 TypeError。如果 weekday、year、month 和 day 都為 undefined，則 year、month 和 day 將被設定為 "numeric"。

在不支援 Intl.DateTimeFormat 的實現中，將忽略此引數。

有關這些引數及其使用方法的詳細資訊，請參閱 Intl.DateTimeFormat() 建構函式。

返回值

一個字串，表示給定日期的日期部分，根據語言特定的約定。

在支援 Intl.DateTimeFormat 的實現中，這等同於 new Intl.DateTimeFormat(locales, options).format(date)，其中 options 已按上述方式規範化。

注意： 大多數情況下，toLocaleDateString() 返回的格式是一致的。然而，在不同實現之間，甚至在同一區域設定下，輸出都可能有所不同——輸出差異是設計使然，並且被規範允許。它也可能不是您期望的。例如，字串可能使用不間斷空格，或者被雙向控制字元包圍。您不應該將 toLocaleDateString() 的結果與硬編碼的常量進行比較。

示例

使用 toLocaleDateString()

不指定 locale 的此方法的簡單用法以預設區域設定和預設選項返回格式化字串。

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

// toLocaleDateString() without arguments depends on the implementation,
// the default locale, and the default time zone
console.log(date.toLocaleDateString());
// "12/11/2012" if run in en-US locale with time zone America/Los_Angeles

檢查對 locales 和 options 引數的支援

locales 和 options 引數可能並非在所有實現中都得到支援，因為國際化 API 的支援是可選的，並且某些系統可能沒有必要的資料。對於不支援國際化的實現，toLocaleDateString() 始終使用系統的區域設定，這可能不是您想要的。因為任何支援 locales 和 options 引數的實現都必須支援 Intl API，所以您可以檢查後者是否存在以判斷支援情況。

js
function toLocaleDateStringSupportsLocales() {
  return (
    typeof Intl === "object" &&
    !!Intl &&
    typeof Intl.DateTimeFormat === "function"
  );
}

使用語言環境

此示例顯示了本地化日期格式的一些變體。為了獲取應用程式使用者介面所用語言的格式，請確保使用 locales 引數指定該語言（以及可能的備用語言）。

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

// formats below assume the local time zone of the locale;
// America/Los_Angeles for the US

// US English uses month-day-year order
console.log(date.toLocaleDateString("en-US"));
// "12/20/2012"

// British English uses day-month-year order
console.log(date.toLocaleDateString("en-GB"));
// "20/12/2012"

// Korean uses year-month-day order
console.log(date.toLocaleDateString("ko-KR"));
// "2012. 12. 20."

// Event for Persian, It's hard to manually convert date to Solar Hijri
console.log(date.toLocaleDateString("fa-IR"));
// "۱۳۹۱/۹/۳۰"

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

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

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

使用選項

toLocaleDateString() 提供的結果可以使用 options 引數進行自定義。

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

// Request a weekday along with a long date
const options = {
  weekday: "long",
  year: "numeric",
  month: "long",
  day: "numeric",
};
console.log(date.toLocaleDateString("de-DE", options));
// "Donnerstag, 20. Dezember 2012"

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

規範

規範
ECMAScript® 2026 語言規範
# sec-date.prototype.tolocaledatestring
ECMAScript® 2026 國際化 API 規範
# sup-date.prototype.tolocaledatestring

瀏覽器相容性

另見

幫助改進 MDN

瞭解如何貢獻

此頁面由 MDN 貢獻者 於 最後修改。

在 GitHub 上檢視此頁面 • 報告此內容的問題
© . Content available under a Creative Commons license.