عرض مصدر JavaScript/Date/toLocaleString

<noinclude>{{DISPLAYTITLE:<code>Date.prototype.toLocaleString()‎</code>}}</noinclude>
الدالة <code>Date.prototype.toLocaleString()‎</code> تعيد سلسلةً نصيةً صيغتها تتبع لمحليّة النظام (system locale) التي تُمثِّل الكائن <code>[[JavaScript/Date|Date]]</code>.

تسمح الوسائط <code>locales</code> و <code>options</code> الجديدة للتطبيقات بتحديد اللغة التي يجب استخدام قواعد التنسيق الخاصة بها، وتسمح بتخصيص سلوك هذه الدالة؛ لكن في الإصدارات القديمة من هذه الدالة، التي كانت تتجاهل قيمة الوسيطين <code>locales</code> و <code>options</code>، كانت ستُستخدَم المحليّة (locale) في النظام ويكون شكل السلسلة النصية المُعادة تابعًا للمتصفح ونظام التشغيل.

== البنية العامة ==
<syntaxhighlight lang="javascript">
dateObj.toLocaleString([locales[, options]])

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

=== <code>locales</code> ===
وسيطٌ اختياريٌ، وهو سلسلة نصيةٌ تحتوي على رمز اللغة وفقًا لمعيار [https://tools.ietf.org/html/bcp47 BCP 47]، أو مصفوفة من تلك الرموز. يمكن استخدام مفاتيح يونيكود الآتية مع رمز اللغة:

==== <code>nu</code> ====
النظام العددي، والقيم الممكنة هي <code>"arab"</code> و <code>"arabext"</code> و <code>"bali"</code> و <code>"beng"</code> و <code>"deva"</code> و <code>"fullwide"</code> و <code>"gujr"</code> و <code>"guru"</code> و <code>"hanidec"</code> و <code>"khmr"</code> و <code>"knda"</code> و <code>"laoo"</code> و <code>"latn"</code> و <code>"limb"</code> و <code>"mlym"</code> و <code>"mong"</code> و <code>"mymr"</code> و <code>"orya"</code> و <code>"tamldec"</code> و <code>"telu"</code> و <code>"thai"</code> و <code>"tibt"</code>.

==== <code>ca</code> ====
التقويم. القيم الممكنة تتضمن: <code>"buddhist"</code> و <code>"chinese"</code> و <code>"coptic"</code> و <code>"ethioaa"</code> و <code>"ethiopic"</code> و <code>"gregory"</code> و <code>"hebrew"</code> و <code>"indian"</code> و <code>"islamic"</code> و <code>"islamicc"</code> و <code>"iso8601"</code> و <code>"japanese"</code> و <code>"persian"</code> و <code>"roc"</code>.

==== <code>hc</code> ====
نظام الساعات (hour cycle). القيم الممكنة هي <code>"h11"</code> و <code>"h12"</code> و <code>"h23"</code> و <code>"h24"</code>.

=== <code>options</code> ===
وسيطٌ اختياريٌ، وهو كائنٌ له بعض (أو كل) الخاصيات الآتية:

==== <code>localeMatcher</code> ====
تحديد خوارزمية مُطابقة المحليّة (locale) التي ستُستخدَم. القيم الممكنة هي <code>"lookup"</code> و <code>"best fit"</code>؛ والقيمة الافتراضية هي <code>"best fit"</code>.

==== <code>timeZone</code> ====
المنطقة الزمنية التي ستُستعمَل. القيمة الوحيدة التي يجب أن يتعرف عليها المتصفح هي <code>"UTC"</code>، ويمكن أن تدعم المتصفحات أسماء المناطق من [https://www.iana.org/time-zones قاعدة بيانات IANA للمناطق الزمنية]، مثل <code>"Asia/Shanghai"</code> و <code>"Asia/Kolkata"</code> و <code>"America/New_York"</code>.

==== <code>hour12</code> ====
تحديد إذا كان سيُستخدَم نظام 12 ساعة (مقابل استخدام نظام 24 ساعة). القيم الممكنة هي <code>true</code> و <code>false</code>، والقيمة الافتراضية تعتمد على ضبط المحليّة. وقيمة هذا الخيار ستتجاوز القيمة المضبوطة في وسم <code>hc</code> أو الخيار <code>hourCycle</code> في حال كانا مضبوطين.

==== <code>hourCycle</code> ====
نظام الساعات المستخدم. القيم الممكنة هي <code>"h11"</code> و <code>"h12"</code> و <code>"h23"</code> و <code>"h24"</code>. هذا الخيار يتجاوز قيمة الوسم <code>hc</code>، لكن للخيار <code>hour12</code> الأولوية عليه.

==== <code>formatMatcher</code> ====
خوارزمية المُطابَقة المستخدمة. والقيمة الممكنة هي <code>"basic"</code> و <code>"best fit"</code>؛ القيمة الافتراضية هي <code>"best fit"</code>. راجع الفقرات التالية لمعلومات حول استخدام هذه الخاصية.

الخاصيات الآتية تصف مكونات الوقت والتاريخ المستخدمة لتنسيق المخرجات، يجب أن تدعم المتصفحات أحد الصيغ الآتية على الأقل:
* <code>weekday</code>, <code>year</code>, <code>month</code>, <code>day</code>, <code>hour</code>, <code>minute</code>, <code>second</code>
* <code>weekday</code>, <code>year</code>, <code>month</code>, <code>day</code>
* <code>year</code>, <code>month</code>, <code>day</code>
* <code>year</code>, <code>month</code>
* <code>month</code>, <code>day</code>
* <code>hour</code>, <code>minute</code>, <code>second</code>
* <code>hour</code>, <code>minute</code>

==== <code>weekday</code> ====
تمثيل اليوم في الأسبوع. القيم الممكنة هي <code>"narrow"</code> و <code>"short"</code> و <code>"long"</code>.

==== <code>era</code> ====
تمثيل العصر (era). القيم الممكنة هي <code>"narrow"</code> و <code>"short"</code> و <code>"long"</code>.

==== <code>year</code> ====
تمثيل السنة. القيم الممكنة هي <code>"numeric"</code> و <code>"‎2-digit"</code>.

==== <code>month</code> ====
تمثيل الشهر. القيم الممكنة هي <code>"numeric"</code> و <code>"‎2-digit"</code> و <code>"narrow"</code> و <code>"short"</code> و <code>"long"</code>.

==== <code>day</code> ====
تمثيل اليوم. القيم الممكنة هي <code>"numeric"</code> و <code>"‎2-digit"</code>.

==== <code>hour</code> ====
تمثيل الساعة. القيم الممكنة هي <code>"numeric"</code> و <code>"‎2-digit"</code>.

==== <code>minute</code> ====
تمثيل الدقيقة. القيم الممكنة هي <code>"numeric"</code> و <code>"‎2-digit"</code>.

==== <code>second</code> ====
تمثيل الثانية. القيم الممكنة هي <code>"numeric"</code> و <code>"‎2-digit"</code>.

==== <code>timeZoneName</code> ====
تمثيل الثانية. القيم الممكنة هي <code>"short"</code> و <code>"‎long"</code>.

القيمة الافتراضية لكل خاصية من خاصيات الوقت والتاريخ هي <code>[[JavaScript/undefined|undefined]]</code>، لكن إذا كانت قيمة الخاصيات <code>weekday</code> و <code>year</code> و <code>month</code> و <code>day</code> هي <code>[[JavaScript/undefined|undefined]]</code> فستُعدّ قيم <code>year</code> و <code>month</code> و <code>day</code> على أنها <code>"numeric"</code>.

=== القيمة المعادة ===
سلسلة نصية تُمثِّل التاريخ اعتمادًا على تنسيق التحويل الخاص باللغة.

== أمثلة ==

=== استخدام الدالة <code>toLocaleString()‎</code> ===
في حال استخدام الدالة <code>toLocaleString()‎</code> دون تحديد المحليّة (locale)، فستُعاد سلسلة نصية مُنسّقة وفق المحلية الافتراضية:<syntaxhighlight lang="javascript">
var date = new Date(Date.UTC(2012, 11, 12, 3, 0, 0));

console.log(date.toLocaleString());
// "12/11/2012, 7:00:00 PM" in en-US locale

</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 toLocaleStringSupportsLocales() {
  try {
    new Date().toLocaleString('i');
  } catch (e) {
    return e instanceof RangeError;
  }
  return false;
}
</syntaxhighlight>

=== استخدام الوسيط <code>locales</code> ===
المثال الآتي يُظهِر بعض صيغ التاريخ عبر تحديد المحليّة. الصيغ الآتية ستفترض أنَّ المنطقة الزمنية للمحليّة هي <code>America/Los_Angeles</code>:<syntaxhighlight lang="javascript">
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

</syntaxhighlight>المحلية en-US (أي US English) تستخدم الترتيب month-day-year ونظام 12 ساعة مع AM/PM:<syntaxhighlight lang="javascript">
console.log(date.toLocaleString('en-US'));
// "12/19/2012, 7:00:00 PM"

</syntaxhighlight>المحلية en-GB (أي British English) تستخدم الترتيب day-month-year ونظام 24 ساعة دون AM/PM:<syntaxhighlight lang="javascript">
console.log(date.toLocaleString('en-GB'));
// "20/12/2012 03:00:00"

</syntaxhighlight>المحلية ko-KR (التابعة لكوريا) تستخدم الترتيب year-month-day ونظام 12 ساعة مع AM/PM:<syntaxhighlight lang="javascript">
console.log(date.toLocaleString('ko-KR'));
// "2012. 12. 20. 오후 12:00:00"

</syntaxhighlight>المحلية ar-EG (اللغة العربية - مصر) تستخدم الأرقام العربية المشرقية:<syntaxhighlight lang="javascript">
console.log(date.toLocaleString('ar-EG'));
// "٢٠‏/١٢‏/٢٠١٢ ٥:٠٠:٠٠ ص"

</syntaxhighlight>أما في اليابان، فيمكن أن تستخدم التطبيقات التقويم الياباني، والذي يكون العام 2012 فيه مساويًا للعام 24 في [https://ar.wikipedia.org/wiki/%D9%81%D8%AA%D8%B1%D8%A9_%D9%87%D9%8A%D8%B3%D9%8A فترة هيسي] ([[wikipedia:Heisei_period|Heisei era]])، لاحظ استخدام  مفاتيح يونيكود (بعد المحرف <code>u</code>):<syntaxhighlight lang="javascript">
console.log(date.toLocaleString('ja-JP-u-ca-japanese'));
// "24/12/20 12:00:00"

</syntaxhighlight>عند طلب عرض التاريخ في لغة قد لا تكون مدعومةً، مثل [https://ar.wikipedia.org/wiki/%D9%84%D8%BA%D8%A9_%D8%A8%D8%A7%D9%84%D9%8A%D8%A9 اللغة البالية] فيمكن تضمين لغة أخرى لتُستخدَم عوضًا عنها، وفي هذه الحالة سنستخدم [https://ar.wikipedia.org/wiki/%D9%84%D8%BA%D8%A9_%D8%A5%D9%86%D8%AF%D9%88%D9%86%D9%8A%D8%B3%D9%8A%D8%A9 اللغة الإندونيسية]:<syntaxhighlight lang="javascript">
console.log(date.toLocaleString(['ban', 'id']));
// "20/12/2012 11.00.00"

</syntaxhighlight>

=== استخدام الوسيط <code>options</code> ===
يمكن تخصيص النتائج التي توفِّرها الدالة <code>toLocaleString()‎</code> باستخدام الوسيط <code>options</code>:<syntaxhighlight lang="javascript">
var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

// طلب إظهار اليوم من الأسبوع إضافةً إلى التاريخ الطويل
var options = { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' };
// المحليّة هي الألمانية
console.log(date.toLocaleString('de-DE', options));
// "Donnerstag, 20. Dezember 2012"

// قد يستخدم التطبيق التوقيت العالمي ويُظهِر ذلك
options.timeZone = 'UTC';
options.timeZoneName = 'short';
console.log(date.toLocaleString('en-US', options)); // المحلية هي الإنكليزية - أميركا
// "Thursday, December 20, 2012, GMT"

// أحيانًا نحتاج إلى نظام 24 ساعة حتى لو كانت المحليّة هي الإنكليزية - أميركا
console.log(date.toLocaleString('en-US', { hour12: false }));
// "12/19/2012, 19:00:00"
</syntaxhighlight>

== دعم المتصفحات ==
{| class="wikitable"
!الميزة
!|Chrome
!Firefox
!Internet Explorer
!Opera
!Safari
|-
! الدعم الأساسي
|نعم
|نعم
|نعم
|نعم
|نعم
|-
!locales و options
|24
|29
|11
|15
|10
|}
== مصادر ومواصفات ==
* مسودة المعيار [http://tc39.github.io/ecma402/#sec-Date.prototype.toLocaleString ECMAScript Internationalization API 4.0].
* معيار [http://www.ecma-international.org/ecma-402/2.0/#sec-13.3.1 ECMAScript Internationalization API 2.0].
* معيار [http://www.ecma-international.org/ecma-402/1.0/#sec-13.3.1 ECMAScript Internationalization API 1.0]. عرّف هذا المعيار الوسيطين <code>locales</code> و <code>options</code>.
* مسودة المعيار [https://tc39.github.io/ecma262/#sec-date.prototype.tolocalestring ECMAScript Latest Draft].
* معيار [http://www.ecma-international.org/ecma-262/6.0/#sec-date.prototype.tolocalestring ECMAScript 2015 (6th Edition)]‎.
* معيار [http://www.ecma-international.org/ecma-262/5.1/#sec-15.9.5.5 ECMAScript 5.1].
* معيار [http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%201st%20edition,%20June%201997.pdf ECMAScript 1st Edition]. 
[[تصنيف:JavaScript]]
[[تصنيف:JavaScript Global Objects]]
[[تصنيف:JavaScript Date]]