`Date.prototype.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.

`Date.prototype.toLocaleString()‎`

محتويات

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

`locales`

`nu`

`ca`

`hc`

`options`

`localeMatcher`

`timeZone`

`hour12`

`hourCycle`

`formatMatcher`

`weekday`

`era`

`year`

`month`

`day`

`hour`

`minute`

`second`

`timeZoneName`

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

أمثلة

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

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

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

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

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

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

قائمة التصفح

بحث

Date.prototype.toLocaleString()‎

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

locales

nu

ca

hc

options

localeMatcher

timeZone

hour12

hourCycle

formatMatcher

weekday

era

year

month

day

hour

minute

second

timeZoneName

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

أمثلة

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

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

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

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

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

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

قائمة التصفح

بحث

`Date.prototype.toLocaleString()‎`

`locales`

`nu`

`ca`

`hc`

`options`

`localeMatcher`

`timeZone`

`hour12`

`hourCycle`

`formatMatcher`

`weekday`

`era`

`year`

`month`

`day`

`hour`

`minute`

`second`

`timeZoneName`

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

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

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

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