JavaScript/Date/toLocaleString

الدالة Date.prototype.toLocaleString()‎ تعيد سلسلةً نصيةً صيغتها تتبع لمحليّة النظام (system locale) التي تُمثِّل الكائن Date.

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

البنية العامة

dateObj.toLocaleString([locales[, options]])

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

locales

وسيطٌ اختياريٌ، وهو سلسلة نصيةٌ تحتوي على رمز اللغة وفقًا لمعيار BCP 47، أو مصفوفة من تلك الرموز. يمكن استخدام مفاتيح يونيكود الآتية مع رمز اللغة:

nu

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

ca

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

hc

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

options

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

localeMatcher

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

timeZone

المنطقة الزمنية التي ستُستعمَل. القيمة الوحيدة التي يجب أن يتعرف عليها المتصفح هي "UTC"، ويمكن أن تدعم المتصفحات أسماء المناطق من قاعدة بيانات IANA للمناطق الزمنية، مثل "Asia/Shanghai" و "Asia/Kolkata" و "America/New_York".

hour12

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

hourCycle

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

formatMatcher

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

الخاصيات الآتية تصف مكونات الوقت والتاريخ المستخدمة لتنسيق المخرجات، يجب أن تدعم المتصفحات أحد الصيغ الآتية على الأقل:

• weekday, year, month, day, hour, minute, second
• weekday, year, month, day
• year, month, day
• year, month
• month, day
• hour, minute, second
• hour, minute

weekday

تمثيل اليوم في الأسبوع. القيم الممكنة هي "narrow" و "short" و "long".

era

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

year

تمثيل السنة. القيم الممكنة هي "numeric" و "‎2-digit".

month

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

day

تمثيل اليوم. القيم الممكنة هي "numeric" و "‎2-digit".

hour

تمثيل الساعة. القيم الممكنة هي "numeric" و "‎2-digit".

minute

تمثيل الدقيقة. القيم الممكنة هي "numeric" و "‎2-digit".

second

تمثيل الثانية. القيم الممكنة هي "numeric" و "‎2-digit".

timeZoneName

تمثيل الثانية. القيم الممكنة هي "short" و "‎long".

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

القيمة المعادة

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

أمثلة

استخدام الدالة toLocaleString()‎

في حال استخدام الدالة toLocaleString()‎ دون تحديد المحليّة (locale)، فستُعاد سلسلة نصية مُنسّقة وفق المحلية الافتراضية:

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

التحقق من دعم الوسيطين locales و options

الوسيطان locales و options أصبحا مدعومين حديثًا؛ وللتحقق إن كان المتصفح يدعمها فيمكننا استخدام كتلة try...catch، إذ إنَّ رموز اللغات غير الصالحة ستُرفضَ من هذه الدالة وستؤدي إلى رمي الاستثناء RangeError:

function toLocaleStringSupportsLocales() {
  try {
    new Date().toLocaleString('i');
  } catch (e) {
    return e instanceof RangeError;
  }
  return false;
}

استخدام الوسيط locales

المثال الآتي يُظهِر بعض صيغ التاريخ عبر تحديد المحليّة. الصيغ الآتية ستفترض أنَّ المنطقة الزمنية للمحليّة هي America/Los_Angeles:

var date = new Date(Date.UTC(2012, 11, 20, 3, 0, 0));

المحلية en-US (أي US English) تستخدم الترتيب month-day-year ونظام 12 ساعة مع AM/PM:

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

المحلية en-GB (أي British English) تستخدم الترتيب day-month-year ونظام 24 ساعة دون AM/PM:

console.log(date.toLocaleString('en-GB'));
// "20/12/2012 03:00:00"

المحلية ko-KR (التابعة لكوريا) تستخدم الترتيب year-month-day ونظام 12 ساعة مع AM/PM:

console.log(date.toLocaleString('ko-KR'));
// "2012. 12. 20. 오후 12:00:00"

المحلية ar-EG (اللغة العربية - مصر) تستخدم الأرقام العربية المشرقية:

console.log(date.toLocaleString('ar-EG'));
// "٢٠‏/١٢‏/٢٠١٢ ٥:٠٠:٠٠ ص"

أما في اليابان، فيمكن أن تستخدم التطبيقات التقويم الياباني، والذي يكون العام 2012 فيه مساويًا للعام 24 في فترة هيسي (Heisei era)، لاحظ استخدام مفاتيح يونيكود (بعد المحرف u):

console.log(date.toLocaleString('ja-JP-u-ca-japanese'));
// "24/12/20 12:00:00"

عند طلب عرض التاريخ في لغة قد لا تكون مدعومةً، مثل اللغة البالية فيمكن تضمين لغة أخرى لتُستخدَم عوضًا عنها، وفي هذه الحالة سنستخدم اللغة الإندونيسية:

console.log(date.toLocaleString(['ban', 'id']));
// "20/12/2012 11.00.00"

استخدام الوسيط options

يمكن تخصيص النتائج التي توفِّرها الدالة toLocaleString()‎ باستخدام الوسيط options:

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"

دعم المتصفحات

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	نعم	نعم
locales و options	24	29	11	15	10

مصادر ومواصفات

• مسودة المعيار ECMAScript Internationalization API 4.0.
• معيار ECMAScript Internationalization API 2.0.
• معيار ECMAScript Internationalization API 1.0. عرّف هذا المعيار الوسيطين locales و options.
• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.
• معيار ECMAScript 5.1.
• معيار ECMAScript 1st Edition.