---
title: String.prototype.localeCompare()
slug: Web/JavaScript/Reference/Global_Objects/String/localeCompare
tags:
  - Internationalization
  - JavaScript
  - String.prototype.localeCompare()
  - 原型
  - 参考
  - 字符串
  - 方法
translation_of: Web/JavaScript/Reference/Global_Objects/String/localeCompare
---
<div>{{JSRef}}</div>

<p><strong><code>localeCompare()</code></strong> 方法返回一个数字来指示一个参考字符串是否在排序顺序前面或之后或与给定字符串相同。</p>

<p><code>新的 locales 、</code> <code>options</code> 参数能让应用程序定制函数的行为即指定用来排序的语言。  <code>locales</code> 和 <code>options</code> 参数是依赖于具体实现的，在旧的实现中这两个参数是完全被忽略的。</p>

<h2 id="语法">语法</h2>

<pre class="syntaxbox notranslate"><code><var>referenceStr</var>.localeCompare(<var>compareString</var>[, <var>locales</var>[, <var>options</var>]])</code></pre>

<h3 id="参数">参数</h3>

<p>查阅<a href="#浏览器支持">浏览器支持</a>部分来确定哪些浏览器支持 <code>locales</code> 参数和 <code>options</code> 参数， <a href="检查浏览器对扩展参数的支持">在功能检测中检查对 <code>locales</code> 、<code>options </code>参数的支持</a>。</p>

<dl>
 <dt><code>compareString</code></dt>
 <dd>用来比较的字符串</dd>
 <dt><strong><code><font face="consolas, Liberation Mono, courier, monospace"><span style="background-color: #eeeeee;">locales</span></font></code></strong></dt>
 <dd>可选。 用来表示一种或多种语言或区域的一个符合 <a href="https://tools.ietf.org/html/rfc5646">BCP 47</a> 标准的字符串或一个字符串数组。 <code>locales</code>参数的一般形式与解释， 详情请参考 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation">Intl page</a>。 下列的 Unicode 扩展关键词是允许的：</dd>
 <dd><code><strong>co</strong></code></dd>
 <dd>为了某些地域多样的排序规则。可能的值包括： <code>"big5han"</code>, <code>"dict"</code>, <code>"direct"</code>, <code>"ducet"</code>, <code>"gb2312"</code>, <code>"phonebk"</code>, <code>"phonetic"</code>, <code>"pinyin"</code>, <code>"reformed"</code>, <code>"searchjl"</code>, <code>"stroke"</code>, <code>"trad"</code>, <code>"unihan"</code>。 <code>"standard"</code> 和<code>"search"</code> 这两个值是被忽略的; 它们被 <code>options</code> 的属性 <code>usage</code> 代替(往下看)。</dd>
 <dd><strong><code>kn</code></strong></dd>
 <dd>指定数值排序是否应该被使用， 像是这样 "1" &lt; "2" &lt; "10"。 可能的值是 <code>"true"</code> 和 <code>"false"</code>。 这个选项能被通过<code>options</code> 属性设置或通过 Unicode 扩展。 假如两个都被设置了， 则 <code>options</code> 优先。（<em>"<em>language</em>-<em>region</em>-u-kn-true|false"）</em></dd>
 <dd><strong><code>kf</code></strong></dd>
 <dd>指定是否优先对大写字母或小写字母排序。 可能的值有 <code>"upper"</code>, <code>"lower"</code>, 或 <code>"false"</code> (use the locale's default)。这个选项能被通过<code>options</code> 属性设置或通过 Unicode 扩展。假如两个都被设置了， 则 <code>options</code> 优先。<em>（"<em>language</em>-<em>region</em>-u-kf-upper|lower|false"）</em></dd>
 <dt><code>options</code></dt>
 <dd>
 <p>可选。 支持下列的一些或全部属性的一个对象:</p>

 <dl>
  <dt><code>localeMatcher</code></dt>
  <dd>地域匹配算法的使用. 可能的值是 <code>"lookup"</code> 和 <code>"best fit"</code>; 默认的值是 <code>"best fit"</code>。更多相关的资料, 请参考 <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_negotiation" title="The Intl object is the namespace for the ECMAScript Internationalization API, which provides language sensitive string comparison, number formatting, and date and time formatting. The constructors for Collator, NumberFormat, and DateTimeFormat objects are properties of the Intl object. This page documents these properties as well as functionality common to the internationalization constructors and other language sensitive functions.">Intl page</a>.</dd>
  <dt><code>usage</code></dt>
  <dd>指定比较的目标是排序或者是搜索. 可能的值是 <code>"sort"</code> 和 <code>"search"</code>; 默认是 <code>"sort"</code>.</dd>
  <dt><code>sensitivity</code></dt>
  <dd>
  <p>指定排序程序的敏感度（Which differences in the strings should lead to non-zero result values.） 可能的有:</p>

  <ul>
   <li><code>"base"</code>: 只有不同的字母字符串比较是不相等的. 举个例子: <code>a ≠ b</code>, <code>a = á</code>, <code>a = A</code>.</li>
   <li><code>"accent"</code>: 只有不同的字母或读音比较是不相等的. 举个例子: <code>a ≠ b</code>, <code>a ≠ á</code>, <code>a = A</code>.</li>
   <li><code>"case"</code>: 只有不同的字母或大小写比较是不相等的. 举个例子: <code>a ≠ b</code>, <code>a = á</code>, <code>a ≠ A</code>.</li>
   <li><code>"variant"</code>: 不同的字母或读音及其它有区别的标志或大小写都是不相等的， 还有其它的差异可能也会考虑到. 举个例子: <code>a ≠ b</code>, <code>a ≠ á</code>, <code>a ≠ A</code>.</li>
  </ul>

  <p>The default is <code>"variant"</code> for usage <code>"sort"</code>; it's locale dependent for usage <code>"search"</code>.</p>
  </dd>
  <dt><code>ignorePunctuation</code></dt>
  <dd>指定是否忽略标点. 可能的值是 <code>true</code> and <code>false</code>; 默认为 <code>false</code>.</dd>
  <dt><code>numeric</code></dt>
  <dd>是否指定使用数字排序, 像这样 "1" &lt; "2" &lt; "10". 可能的值是 <code>true</code> 和 <code>false</code>; 默认为 <code>false</code>. 这个选项能被通过<code>options</code> 属性设置或通过 Unicode 扩展。假如两个都被设置了， 则 <code>options</code> 优先。 实现不用必须支持这个属性.</dd>
  <dt><code>caseFirst</code></dt>
  <dd>指定大小写有限排序. 可能的值有 <code>"upper"</code>, <code>"lower"</code>, or <code>"false"</code> (use the locale's default); 默认为 <code>"false"</code>. 这个选项能被通过<code>options</code> 属性设置或通过 Unicode 扩展。假如两个都被设置了， 则 <code>options</code> 优先。 实现不用必须支持这个属性.</dd>
 </dl>
 </dd>
 <dd>
 <h3 id="返回值"><strong>返回值</strong></h3>

 <p>如果引用字符存在于比较字符之前则为<strong>负数</strong>; 如果引用字符存在于比较字符之后则为<strong>正数</strong>; 相等的时候返回 <strong>0</strong> .</p>
 </dd>
 <dd>page('/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Collator', 'Parameters')}}</dd>
</dl>

<h2 id="描述">描述</h2>

<p>返回一个数字表示是否 <strong>引用字符串</strong> 在排序中位于 <strong>比较字符串</strong> 的前面，后面，或者二者相同。</p>

<ul>
 <li>当 <strong>引用字符串 </strong>在 <strong>比较字符串 </strong>前面时返回 -1</li>
 <li>当 <strong>引用字符串</strong> 在 <strong>比较字符串 </strong>后面时返回 1</li>
 <li>相同位置时返回 0</li>
</ul>

<p><strong>切勿依赖于 -1 或 1 这样特定的返回值。</strong>不同浏览器之间（以及不同浏览器版本之间）<strong> </strong>返回的正负数的值各有不同，因为W3C规范中只要求返回值是正值和负值，而没有规定具体的值。一些浏览器可能返回-2或2或其他一些负的、正的值。</p>

<h2 id="示例">示例</h2>

<h3 id="使用_localeCompare">使用 <code>localeCompare()</code></h3>

<pre class="brush: js notranslate">// The letter "a" is before "c" yielding a negative value
'a'.localeCompare('c');
// -2 or -1 (or some other negative value)

// Alphabetically the word "check" comes after "against" yielding a positive value
'check'.localeCompare('against');
// 2 or 1 (or some other positive value)

// "a" and "a" are equivalent yielding a neutral value of zero
'a'.localeCompare('a');
// 0
</pre>

<h3 id="检查浏览器对扩展参数的支持">检查浏览器对扩展参数的支持</h3>

<p><code>locales</code> 和 <code>options</code> 参数还没有被所有浏览器所支持。检查是否被支持， 使用 "i" 参数 (a requirement that illegal language tags are rejected) 判断是否有异常 {{jsxref("RangeError")}}抛出:</p>

<pre class="brush: js notranslate">function localeCompareSupportsLocales() {
  try {
    'foo'.localeCompare​('bar', 'i');
  } catch (e) {
    return e​.name === 'RangeError';
  }
  return false;
}
</pre>

<h3 id="使用_locales_参数">使用 <code>locales 参数</code></h3>

<p>在不同的语言下 <code>localeCompare()</code> 所提供的结果是不一致的。 为了能让用户得到正确的比较值， 通过使用 <code>locales</code> 参数来提供要比较的语言 (and possibly some fallback languages) :</p>

<pre class="brush: js notranslate">console.log('ä'.localeCompare('z', 'de')); // a negative value: in German, ä sorts with a
console.log('ä'.localeCompare('z', 'sv')); // a positive value: in Swedish, ä sorts after z
</pre>

<h3 id="使用_options_参数">使用 <code>options 参数</code></h3>

<p><code>localeCompare()</code> 所提供的结果可以通过 <code>options</code> 参数来制定:</p>

<pre class="brush: js notranslate">// in German, ä has a as the base letter
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// in Swedish, ä and a are separate base letters
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // a positive value
</pre>

<h2 id="性能相关">性能相关</h2>

<p>当比较大量字符串时， 比如比较大量数组时， 最好创建一个{{jsxref("Global_Objects/Collator", "Intl.Collator")}} 对象并使用{{jsxref("Collator.prototype.compare", "compare")}} 属性所提供的函数。</p>

<h2 id="规范">规范</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">规范</th>
   <th scope="col">状态</th>
   <th scope="col">备注</th>
  </tr>
  <tr>
   <td>{{SpecName('ES3')}}</td>
   <td>{{Spec2('ES3')}}</td>
   <td>Initial definition. Implemented in JavaScript 1.2.</td>
  </tr>
  <tr>
   <td>{{SpecName('ES5.1', '#sec-15.5.4.9', 'String.prototype.localeCompare')}}</td>
   <td>{{Spec2('ES5.1')}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName('ES6', '#sec-string.prototype.localecompare', 'String.prototype.localeCompare')}}</td>
   <td>{{Spec2('ES6')}}</td>
   <td></td>
  </tr>
  <tr>
   <td>{{SpecName('ES Int 1.0', '#sec-13.1.1', 'String.prototype.localeCompare')}}</td>
   <td>{{Spec2('ES Int 1.0')}}</td>
   <td><code>locale</code> and <code>option</code> parameter definitions.</td>
  </tr>
 </tbody>
</table>

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<p>{{Compat("javascript.builtins.String.localeCompare")}}</p>

<h2 id="相关链接">相关链接</h2>

<ul>
 <li>{{jsxref("Global_Objects/Collator", "Intl.Collator")}}</li>
</ul>