عرض مصدر JavaScript/String/localeCompare

<noinclude>{{DISPLAYTITLE:<code>String.prototype.localeCompare()‎</code>}}</noinclude>
الدالة <code>String.prototype.localeCompare()‎</code> تُعيد رقمًا يُشير إذا ما كانت السلسلة النصية المُشار إليها تأتي قبل أو بعد أو بنفس ترتيب السلسلة النصية المُعطاة في ترتيبٍ معيّن.

الوسيطان الجديدان <code>locales</code> و <code>options</code> يسمحان للتطبيقات بتحديد اللغة التي سيُستخدَم الترتيب الخاص بها وتخصيص سلوك هذه الدالة؛ أما الإصدارات القيمة من هذه الدالة فستتجاهل الوسيطين <code>locales</code> و <code>options</code> وسيكون المحليّة (locale) والترتيب (sort) معتمدين تمامًا على المتصفح ونظام التشغيل.
==البنية العامة==
<syntaxhighlight lang="javascript">
referenceStr.localeCompare(compareString[, locales[, options]])

</syntaxhighlight>انظر إلى قسم [[#دعم المتصفحات|دعم المتصفحات]] لتعرف ما هي المتصفحات التي تدعم الوسيطين <code>locales</code> و <code>options</code>.

=== <code>compareString</code> ===
السلاسل النصية التي نريد البحث مقارنتها مع السلسلة النصية المرجعية.
===<code>locales</code>===
وسيطٌ اختياريٌ، وهو سلسلة نصيةٌ تحتوي على رمز اللغة وفقًا لمعيار [https://tools.ietf.org/html/bcp47 BCP 47]، أو مصفوفة من تلك الرموز. يمكن استخدام مفاتيح يونيكود الآتية مع رمز اللغة:
====<code>co</code>====
القيم الممكنة هي <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>usage</code> في الوسيط <code>options</code> بدلًا منها (انظر أدناه).
====<code>kn</code>====
تحديد هل سيُستخدم الترتيب الرقمي، أي أنَّ ‎"1" < "2" < "10"‎، القيم الممكنة هي <code>"true"</code> و <code>"false"</code>، ويمكن ضبط هذا الخيار عبر الخاصية <code>options</code> أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية <code>options</code> بالحسبان.
====<code>kf</code>====
تحديد إذا كانت ستأتي الحروف ذات الحالة الكبيرة أولًا أم الصغيرة أولًا، والقيم الممكنة هي <code>"upper"</code> أو <code>"lower"</code> أو <code>"false"</code> (أي استخدام القيمة الافتراضية). يمكن ضبط هذا الخيار عبر الخاصية <code>options</code> أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية <code>options</code> بالحسبان.
===<code>options</code>===
وسيطٌ اختياريٌ، وهو كائنٌ له بعض (أو كل) الخاصيات الآتية:
====<code>localeMatcher</code>====
تحديد خوارزمية مُطابقة المحليّة (locale) التي ستُستخدَم. القيم الممكنة هي <code>"lookup"</code> و <code>"best fit"</code>؛ والقيمة الافتراضية هي <code>"best fit"</code>.
====<code>usage</code>====
تحديد إذا كانت المقارنة ستُستخدَم للترتيب أو للبحث عن مطابقات لسلاسل نصية. القيم الممكنة هي <code>"sort"</code> و <code>"search"</code> والقيمة الافتراضية هي <code>"sort"</code>.
====<code>sensitivity</code>====
ما هي الاختلافات بين السلسلتين النصيتين التي ستؤدي إلى قيم غير صفرية، القيم الممكنة هي:
*<code>"base"</code>: ستختلف السلاسل النصية في أساس الحرف فقط، مثلًا: a ≠ b, a = á, a = A.
*<code>"accent"</code>: ستختلف السلاسل النصية إذا اختلف أساس الحرف والحركات، مثلًا: a ≠ b, a ≠ á, a = A.
*<code>"case"</code>: ستختلف السلاسل النصية إذا اختلف أساس الحرف وحالته. مثلًا: a ≠ b, a = á, a ≠ A.
*<code>"variant"</code>: ستختلف السلاسل النصية إذا اختلف أساس الحرف وحالته والحركة. مثلًا: a ≠ b, a ≠ á, a ≠ A.
القيمة الافتراضية هي <code>"variant"</code> إذا كان الاستخدام (<code>usage</code>) هو <code>"sort"</code>، وستعتمد على ضبط المحليّة (locale) إذا كان الاستخدام هو <code>"search"</code>.

====<code>ignorePunctuation</code>====
تحديد إذا كان سيتم تجاهل علامات الترقيم، والقيم الممكنة هي <code>true</code> و <code>false</code>، والقيمة الافتراضية هي <code>false</code>.
====<code>numeric</code>====
تحديد هل سيُستخدم الترتيب الرقمي، أي أنَّ ‎"1" < "2" < "10"‎، القيم الممكنة هي <code>"true"</code> و <code>"false"</code>، ويمكن ضبط هذا الخيار عبر الخاصية <code>options</code> أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية <code>options</code> بالحسبان.
====<code>caseFirst</code>====
تحديد إذا كانت ستأتي الحروف ذات الحالة الكبيرة أولًا أم الصغيرة أولًا، والقيم الممكنة هي <code>"upper"</code> أو <code>"lower"</code> أو <code>"false"</code> (أي استخدام القيمة الافتراضية). يمكن ضبط هذا الخيار عبر الخاصية <code>options</code> أو عبر مفتاح يونيكود، وإذا وّفرنا قيمةً لكليهما، فستؤخذ قيمة الخاصية <code>options</code> بالحسبان.
=== القيمة المعادة ===
عدد سالب إذا كانت السلسلة النصية المرجعية تقع قبل السلسلة النصية التي تجري المقارنة معها، وعددٌ موجب إذا كانت تقع السلسلة النصية المرجعية بعد السلسلة النصية التي تجري المقارنة معها، و 0 إذا كانتا متساويتين.

== الوصف ==
تُعيد هذه الدالة عددًا صحيحًا يُشير إذا ما كانت السلسلة النصية <code>referenceStr</code> تأتي قبل أو بعد أو تكافئ السلسلة النصية <code>compareStr</code>.
* عدد سالب عندما تأتي <code>referenceStr</code> قبل <code>compareStr</code>
* عدد موجب عندما تأتي <code>referenceStr</code> بعد <code>compareStr</code>
* 0 عندما تكون السلاستان النصيتان متكافئتين.
لا تعتمد على القيم -1 و 1، فالقيم الموجبة والسالبة المُعادة من هذه الدالة تختلف بين المتصفحات (وحتى بين إصدارات المتصفح نفسه)، ذلك لأنَّ مواصفة W3C قالت أنَّ القيمة يجب أن تكون سالبة أو موجبة، ولم تُحدِّد القيمة الدقيقة لها، لذا قد تُعيد بعض المتصفحات القيمة -2 أو 2 أو غيرها.

== أمثلة ==

=== استخدام <code>localeCompare()‎</code> ===
الحرف "a" يقع قبل الحرف "c"، لذا ستنتج قيمة سالبة (-2 أو -1 أو قيمة سالبة أخرى):<syntaxhighlight lang="javascript">
'a'.localeCompare('c'); // -1

</syntaxhighlight>الكلمة "check" تقع -هجائيًا- بعد الكلمة "against" مما يُنتِج عددًا موجبًا:<syntaxhighlight lang="javascript">
'check'.localeCompare('against'); // 1
</syntaxhighlight>الحرف "a" يكافئ الحرف "a"، مما يُنتِج القيمة 0:<syntaxhighlight lang="javascript">
'a'.localeCompare('a'); // 0
</syntaxhighlight>

=== ترتيب مصفوفة ===
تسمح الدالة <code>localeCompare</code> بترتيب المصفوفات دون أخذ حالة الأحرف بالحسبان. راجع صفحة الدالة <code>[[JavaScript/Array/sort|sort]]</code> [[JavaScript/Arrow Functions|والدوال السهمية]] لمزيدٍ من المعلومات:<syntaxhighlight lang="javascript">
var items = ['réservé', 'premier', 'cliché', 'communiqué', 'café', 'adieu'];
items.sort((a, b) => a.localeCompare(b)); // ['adieu', 'café', 'cliché', 'communiqué', 'premier', 'réservé']

</syntaxhighlight>
===التحقق من دعم الوسيطين <code>locales</code> و <code>options</code>===
الوسيطان <code>locales</code> و <code>options</code> أصبحا مدعومين حديثًا؛ وللتحقق إن كان المتصفح يدعمها فيمكننا استخدام كتلة <code>[[JavaScript/try...catch|try...catch]]</code>، إذ إنَّ رموز اللغات غير الصالحة ستُرفضَ من هذه الدالة وستؤدي إلى رمي الاستثناء <code>[[JavaScript/RangeError|RangeError]]</code>:<syntaxhighlight lang="javascript">
function localeCompareSupportsLocales() {
  try {
    'foo'.localeCompare('bar', 'i');
  } catch (e) {
    return e.name === 'RangeError';
  }
  return false;
}

</syntaxhighlight>

=== استخدام الوسيط <code>locales</code> ===
النتائج التي توفِّرها الدالة <code>localeCompare</code> تختلف بين اللغات، ولضمان استخدام اللغة التي نشاء، فاحرص على تحديد تلك اللغة باستخدام الوسيط <code>locales</code>:<syntaxhighlight lang="javascript">
console.log('ä'.localeCompare('z', 'de')); // قيمة سالبة في الألمانية
console.log('ä'.localeCompare('z', 'sv')); // قيمة موجبة في السويدية

</syntaxhighlight>

=== استخدام الوسيط <code>options</code> ===
يمكن تخصيص النتائج التي توفِّرها الدالة <code>localeCompare</code> باستخدام الوسيط <code>options</code>. مثلًا، المحرفان a و ä لهما نفس الأساس في الألمانية، بينما يكونان منفصلين تمامًا في السويدية:<syntaxhighlight lang="javascript">
// الألمانية
console.log('ä'.localeCompare('a', 'de', { sensitivity: 'base' })); // 0

// السويدية
console.log('ä'.localeCompare('a', 'sv', { sensitivity: 'base' })); // قيمة موجبة
</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|نعم
|نعم
|نعم
|نعم
|نعم
|}
== مصادر ومواصفات ==
* مسودة [http://tc39.github.io/ecma402/#sec-String.prototype.localeCompare ECMAScript Internationalization API 4.0].
* معيار [http://www.ecma-international.org/ecma-402/2.0/#sec-13.1.1 ECMAScript Internationalization API 2.0].
* معيار [http://www.ecma-international.org/ecma-402/1.0/#sec-13.1.1 ECMAScript Internationalization API 1.0]. عرّف هذا المعيار الوسيطين <code>locales</code> و <code>options</code>.
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-string.prototype.localecompare ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-string.prototype.localecompare ECMAScript 2015 (6th Edition)]‎.
* معيار [http://www.ecma-international.org/ecma-262/5.1/#sec-15.5.4.9 ECMAScript 5.1].
* معيار [http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf ECMAScript 3rd Edition] . 
[[تصنيف:JavaScript|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript Global Objects|{{SUBPAGENAME}}]]
[[تصنيف:JavaScript String|{{SUBPAGENAME}}]]