String.prototype.localeCompare()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2017.

localeCompare() 回傳一個數字，用來表示其與被比較的字串的先後順序。

如果環境中有支援Intl.Collator API，這個方法實際上是調用 Intl.Collator API。

嘗試一下

語法

localeCompare(compareString)
localeCompare(compareString, locales)
localeCompare(compareString, locales, options)

參數

locales 和 options 參數可以調整函數的回傳結果，並且能指定要依照哪種語言來進行比較。

在實現 Intl.Collator API的環境中，這些參數與 Intl.Collator() 的參數互相對應；若環境沒有實現 Intl.Collator ，則這兩個參數就會被忽略，其回傳結果完全看該環境如何實作，唯一的要求是（對於同樣的字串）比較結果必須始終一致。

compareString

要和referenceStr進行比較的字串

locales 選擇性

「BCP 47 語言標籤」的字串或是陣列。相當於Intl.Collator()的locales 參數。

如果使用的環境並未實現 Intl.Collator，此參數會被忽略，並且視同採用當前主機的語言環境

options 選擇性

一個處理輸出格式的物件。相當於Intl.Collator()的 options參數。

如果使用的環境並未實現Intl.Collator ，此參數會被忽略。

關於locales和options參數以及其使用的資訊，可參閱Intl.Collator() constructor。

回傳值

如果referenceStr在compareString以先，會回傳負數；若referenceStr在compareString以後，則為正數; 0表示兩者相等。

如果所使用的環境有實現 Intl.Collator，相當於回傳 new Intl.Collator(locales, options).compare(referenceStr, compareString)。

說明

回傳 referenceStr 和 compareString的先後順序

若回傳負數，表示 referenceStr在 compareString以先
若為正數，表示 referenceStr在compareString以後
若回傳0，表示兩者相等

警告： 不要依靠特定的回傳值，例如 -1 或是 1！

正數或是負數的回傳值在不同的瀏覽器(也包誇同一瀏覽器但不同版本）之間有可能會有所不同。因為 W3C 規範僅要求值得正負而已。也因此，某些瀏覽器可能會回傳 -2 、 2 甚至其他值。

// "a" 在 "c" 之前，所以會回傳負數
"a".localeCompare("c"); // -2、-1 或是其他負數值
// 按字母順序，「check」的順序在「against」之後，所以回傳正數
"check".localeCompare("against"); // 2、1 或其他正數值
// "a" 和 "a" 相同，所以回傳 0
"a".localeCompare("a"); // 0

陣列排序

localeCompare() 用來進行「不分大小寫」的排序

let items = ["réservé", "Premier", "Cliché", "communiqué", "café", "Adieu"];
items.sort((a, b) => a.localeCompare(b, "fr", { ignorePunctuation: true }));
// ['Adieu', 'café', 'Cliché', 'communiqué', 'Premier', 'réservé']

檢查瀏覽器對額外參數的支援度

並不是所有瀏覽器都支援 locales 和 options 參數。

要檢查是否支援，可以使用 "i" 參數（正常情況下，非正常的語言標籤會回報錯誤）並檢查是否有 RangeError exception：

function localeCompareSupportsLocales() {
  try {
    "foo".localeCompare("bar", "i");
  } catch (e) {
    return e.name === "RangeError";
  }
  return false;
}

使用 `locales`

localeCompare()回傳的結果會因為語言而有所不同。

為了讓回傳結果依照特定語言來排序，請確保使用 locales 參數指定該語言（可能還要再加上其他後備語言）：

console.log("ä".localeCompare("z", "de")); // 回傳負數：在德文, ä 的順序在 z 之前
console.log("ä".localeCompare("z", "sv")); // 回傳正數：在瑞典文， ä 的順序在 z 之後

使用 `options`

localeCompare() 可以藉由 options 參數來調整：

// 在德文， ä 和 a 是相同字母
console.log("ä".localeCompare("a", "de", { sensitivity: "base" })); // 0
// 在瑞典文， ä 和 a 是各自獨立的字母
console.log("ä".localeCompare("a", "sv", { sensitivity: "base" })); // 回傳正數

數字排序

// 默認情況下, "2" > "10"
console.log("2".localeCompare("10")); // 1
// 使用 option 讓其視為數字進行比較
console.log("2".localeCompare("10", undefined, { numeric: true })); // -1
// 使用locales標籤
console.log("2".localeCompare("10", "en-u-kn-true")); // -1

規範

Specification
ECMAScript Language Specification # sec-string.prototype.localecompare
ECMAScript Internationalization API Specification # sup-String.prototype.localeCompare

瀏覽器相容性

BCD tables only load in the browser

參見

Intl.Collator