Date.prototype.toLocaleString()
toLocaleString() 方法是 Date 例項的一個方法，它返回一個字串，該字串表示此日期在本地時區中的、符合語言習慣的表示形式。在支援 Intl.DateTimeFormat API 的實現中，此方法會代理到 Intl.DateTimeFormat。
每次呼叫 toLocaleString 時，它都必須在一個龐大的本地化字串資料庫中進行搜尋，這可能會效率低下。當該方法以相同的引數多次呼叫時，最好建立一個 Intl.DateTimeFormat 物件並使用其 format() 方法，因為 DateTimeFormat 物件會記住傳遞給它的引數，並可能決定快取資料庫的一部分，因此未來的 format 呼叫可以在更受限制的上下文中搜索本地化字串。
試一試
const event = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(event.toLocaleString("en-GB", { timeZone: "UTC" }));
// Expected output: "20/12/2012, 03:00:00"
// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(event.toLocaleString("ko-KR", { timeZone: "UTC" }));
// Expected output: "2012. 12. 20. 오전 3:00:00"
語法
toLocaleString()
toLocaleString(locales)
toLocaleString(locales, options)
引數
locales 和 options 引數自定義函式行為，並允許應用程式指定應使用的語言的格式約定。
在支援 Intl.DateTimeFormat API 的實現中，這些引數與 Intl.DateTimeFormat() 建構函式的引數完全對應。不支援 Intl.DateTimeFormat 的實現則被要求忽略這兩個引數，使得所使用的區域設定和返回字串的格式完全取決於具體實現。
locales可選-
一個帶有 BCP 47 語言標籤 的字串，或此類字串的陣列。對應於
Intl.DateTimeFormat()建構函式的locales引數。在不支援
Intl.DateTimeFormat的實現中，將忽略此引數，通常會使用主機的區域設定。 options可選-
一個調整輸出格式的物件。對應於
Intl.DateTimeFormat()建構函式的options引數。如果weekday、year、month、day、dayPeriod、hour、minute、second和fractionalSecondDigits都未定義，則year、month、day、hour、minute、second將被設定為"numeric"。在不支援
Intl.DateTimeFormat的實現中，將忽略此引數。
有關這些引數及其使用方法的詳細資訊，請參閱 Intl.DateTimeFormat() 建構函式。
返回值
一個根據語言特定約定表示給定日期的字串。
在支援 Intl.DateTimeFormat 的實現中，這等同於 new Intl.DateTimeFormat(locales, options).format(date)。
注意： 大多數情況下，toLocaleString() 返回的格式是一致的。然而，輸出在不同實現之間可能會有所不同，即使在相同的區域設定中也是如此——輸出差異是設計使然，並受規範允許。它也可能不符合您的預期。例如，字串可能使用不間斷空格或被雙向控制字元包圍。您不應將 toLocaleString() 的結果與硬編碼常量進行比較。
示例
使用 toLocaleString()
此方法的基本用法——不指定 locale 或 options——取決於具體實現，並返回一個基於預設語言環境和時區的字串，使用預設選項進行格式化。
const date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));
console.log(date.toLocaleString());
// "12/11/2012, 7:00:00 PM" if run in en-US locale with time zone America/Los_Angeles
檢查對 locales 和 options 引數的支援
locales 和 options 引數可能並非在所有實現中都得到支援，因為對國際化 API 的支援是可選的，並且某些系統可能沒有必要的資料。對於不支援國際化的實現，toLocaleString() 始終使用系統的語言環境，這可能不是您想要的。由於任何支援 locales 和 options 引數的實現都必須支援 Intl API，因此您可以檢查後者是否存在來判斷是否支援。
function toLocaleStringSupportsLocales() {
return (
typeof Intl === "object" &&
!!Intl &&
typeof Intl.DateTimeFormat === "function"
);
}
使用語言環境
此示例展示了本地化日期和時間格式的一些變化。為了獲得應用程式使用者介面所使用的語言的格式，請確保使用 locales 引數指定該語言（以及可能的備用語言）。
const date = new Date(Date.UTC(2012, 1, 2, 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 and 12-hour time with AM/PM
console.log(date.toLocaleString("en-US"));
// "2/1/2012, 7:00:00 PM" (UTC-8 is the previous day)
// British English uses day-month-year order and 24-hour time without AM/PM
console.log(date.toLocaleString("en-GB"));
// "02/02/2012, 03:00:00" (UTC+0 or UTC+1 depending on time of the year)
// Korean uses year-month-day order and 12-hour time with AM/PM
console.log(date.toLocaleString("ko-KR"));
// "2012. 2. 2. 오후 12:00:00"
// Arabic in most Arabic-speaking countries uses Eastern Arabic numerals
console.log(date.toLocaleString("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.toLocaleString("ja-JP-u-ca-japanese"));
// "H24/2/2 12:00:00"
// When requesting a language that may not be supported, such as
// Balinese, include a fallback language (in this case, Indonesian)
console.log(date.toLocaleString(["ban", "id"]));
// "2/2/2012 11.00.00"
使用選項
toLocaleString() 提供的結果可以使用 options 引數進行自定義。
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.toLocaleString("de-DE", options));
// Example output: "Donnerstag, 20. Dezember 2012"
// The exact date may shift depending on your local time zone.
// An application may want to use UTC and make that visible
options.timeZone = "UTC";
options.timeZoneName = "short";
console.log(date.toLocaleString("en-US", options));
// Example output: "Thursday, December 20, 2012 at UTC"
// Sometimes even the US needs 24-hour time
console.log(date.toLocaleString("en-US", { hour12: false }));
// Example output: "12/19/2012, 19:00:00"
// The exact date and time may shift depending on your local time zone.
規範
| 規範 |
|---|
| ECMAScript® 2026 語言規範 # sec-date.prototype.tolocalestring |
| ECMAScript® 2026 國際化 API 規範 # sup-date.prototype.tolocalestring |
瀏覽器相容性
載入中…