JavaScript/Date/parse

الدالة Date.parse()‎ تُفسِّر سلسلةً نصيّةً تحتوي على تمثيلٍ للتاريخ، وتعيد كم ملي ثانية مضت منذ ‎1 January 1970 00:00:00 UTC؛ أو القيمة NaN إذا لم يمكن التعرف على السلسلة النصية أو في بعض الحالات إذا احتوت على قيم تاريخ غير صحيحة (مثلًا: 2015‎-02-31‎).

من غير المستحسن استخدام الدالة Date.parse لأنَّه قبل معيار ES5 كان تفسير السلاسل النصية يختلف من متصفح لآخر؛ وما تزال هنالك اختلافات في كيفية تفسير بعض أنواع السلاسل النصية، لذا من الأفضل تفسير السلاسل النصية يدويًا (ربما تستعين بمكتبةٍ ما).

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

استدعاء مباشر:

Date.parse(dateString)

استدعاء ضمني:

new Date(dateString)

dateString

سلسلة نصية تُمثِّل تاريخًا بصيغة RFC 2822، أو أحد صيغ ISO 8601 (يمكن استخدام صيغ أخرى لكن النتائج قد لا تكون متوقعة).

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

قيمة عددية من النوع Number تُمثِّل كم ملي ثانية مضت منذ بدء توقيت يونكس (UNIX epoch) إلى التاريخ الذي حصلنا عليه من تفسير السلسلة النصية المُمرَّرة إلى الدالة. إذا لم تمثِّل السلسلة النصية تاريخًا صحيحًا فستُعاد القيمة NaN.

الوصف

الدالة parse()‎ تأخذ سلسلةً نصيةً تُمثِّل تاريخًا (مثل "Dec 25, 1995") وتُعيد كم ملي ثانية مضت منذ January 1, 1970, 00:00:00 UTC. هذه الدالة مفيدة لضبط قيم التاريخ بناءً على قيم نصية، فمثلًا يمكننا استخدامها مع الدالة setTime()‎‎ ومع الكائن Date.

إذا كانت لدينا سلسلة نصية تُمثِّل الوقت، فإنَّ الدالة parse()‎ ستُعيد قيمة ذاك الوقت، وهي تقبل صيغة RFC 2822 (انظر القسم 3.3 من معيار RFC 2822)، مثلًا "Mon, 21 May 1995 13:30:00 GMT"، ويمكن استخدام إزاحة للمنطقة الزمنية، مثلًا: "Mon, 21 May 1995 13:30:00 +0430"، أي 4 ساعات و 30 دقيقة شرق خط غرينتش.

يُعدّ UTC و GMT متكافئين، وسيستخدم التوقيت المحلي لتفسير الوسائط بصيغة RFC 2822 (القسم 3.3) التي لا تحتوي على معلومات عن المنطقة الزمنية.

بسبب الاختلافات في تفسير السلاسل النصية التي تُمثِّل التاريخ، فمن المستحسن دومًا تفسير السلاسل النصية يدويًا، ذلك لأنَّ النتائج غير موحدّة، وخصوصًا بين المتصفحات التي تُطبِّق إصدارات مختلفة من معيار ECMAScript، ففيها قد تُفسَّر السلسلة النصية ‎"2015-10-12 12:00:00"‎ إلى NaN أو إلى توقيت UTC أو إلى المنطقة الزمنية المحلية.

دعم معيار ECMAScript 5.1 لصيغة ISO-8601

يمكن أن تكون السلسلة النصية بصيغة ISO 8601 المبسطة، فمثلًا، ‎"2011-10-10"‎ (تاريخ فقط) أو ‎"2011-10-10T14:48:00"‎ (تاريخ مع وقت).

إذا كانت السلسلة النصية التي بصيغة ISO 8601 فيها تاريخ فقط، فستُستخدَم المنطقة الزمنية UTC لتفسيرها، أما إذا كانت السلسلة النصية تُمثِّل التاريخ والوقت بصيغة ISO 8601 فستُعامل على أنها في المنطقة الزمنية المحلية.

لمّا كانت الدالة parse()‎ دالةً ساكنة (static method) تابعةً للكائن Date، فيجب استخدامها دومًا بالشكل Date.parse()‎.

الاختلافات في تفسير المنطقة الزمنية

لتكن لدينا السلسلة النصية التي تحمل التاريخ "March 7, 2014"، ستعدّها الدالة parse()‎ على أنها في المنطقة الزمنية المحليّة، لكن إذا كان التاريخ معطى بصيغة ISO مثل ‎"2014-03-07"‎ فستُعدّ المنطقة الزمنية هي UTC (في ES5 و ECMAScript 2015)، وبالتالي قد تُمثِّل كائنات Date التي تُنشَأ من السلسلتين النصيتين السابقتين لحظات زمنية مختلفة اعتمادًا على نسخة ECMAScript المدعومة، ما لم تكن المنطقة الزمنية للنظام هي UTC. وهذا يعني أنَّ سلسلتين نصيتين يشيران إلى التاريخ نفسه قد تُفسران إلى قيمتين مختلفتين اعتمادًا على الصيغة التي كُتِبَ فيها التاريخ.

صيغ التاريخ الخاصة بالمتصفحات

يقول معيار ECMAScript: إذا لم تكن السلسلة النصية مُطابِقة لما ورد في صيغة المعيار، فقد تستخدم هذه الدالة أيّة خوارزميات تفسير تابعة للمتصفح، والسلاسل النصية التي لم يكن بالإمكان التعرف عليها أو التواريخ التي تحتوي عناصر غير مسموحة في صيغة ISO ستؤدي إلى إعادة القيمة NaN.

لكن القيم غير الصحيحة الموجودة في السلاسل النصية التي لا تُعدّ من صيغة ISO المُبسّطة المدعومة من ECMAScript قد تعيد القيمة NaN وقد لا تُعيدها، وذلك اعتمادًا على المتصفح. مثلًا، السلسلة النصية:

// سلسلة نصية غير معيارية فيها قيم غير صحيحة
new Date('23/25/2014');

ستُفسّر على أنها التاريخ المحلي ‎25 November, 2015 في متصفح Firefox 30، وعلى أنها تاريخٌ غير صحيح في متصفح Safari 7. لكن إذا كان التاريخ بصيغة ISO لكن احتوى على قيم غير صحيحة، فستُعاد القيمة NaN في جميع المتصفحات التي تدعم مواصفة ES5 وما بعدها:

// صيغة معيارية لكن فيها قيم غير صالحة
new Date('2014-25-23').toISOString(); // RangeError: invalid date

مثال آخر عن صيغة غير معيارية:

new Date('foo-bar 2014').toString();
// "Invalid Date"

Date.parse('foo-bar 2014');
// NaN

ملاحظات التوافقية

إصدار Firefox 49 غيّر طريقة تفسير السنة المُمثّلة برقمين لكي يتوافق مع متصفح Chrome بدلًا من Internet Explorer؛ إذ أصبحت السنوات المؤلفة من رقمين والأقل من 50 ستُفسّر على أنها من القرن الحادي والعشري، فمثلًا التاريخ 04/16/17 كان يُفسَّر فيما قد سلف على أنه April 16, 1917، لكنه أصبح الآن April 16, 2017. لتفادي المشاكل في التفسير فمن المستحسن استخدام صيغة ISO 8601 كما في السلسلة النصية ‎"2017-04-16"‎.

أمثلة

إذا كان الكائن IP0date هو كائن Date مُهيّئ مسبقًا، فيمكننا ضبطه (setTime) إلى التاريخ August 9, 1995 (بالتوقيت المحلي) كما يلي:

IPOdate.setTime(Date.parse('Aug 9, 1995'));

بعض الأمثلة عن تفسير السلاسل النصية غير القياسية:

Date.parse('Aug 9, 1995');

ستُعيد القيمة 807937200000 في المنطقة الزمنية GMT-0300 وقيم أخرى في مناطق زمنية أخرى، ولمّا كانت السلسلة النصية غير معيارية ولا تُحدِّد منطقةً زمنيةً وليست بصيغة ISO، فستُعدّ المنطقة الزمنية هي المنطقة الزمنية المحلية.

Date.parse('Wed, 09 Aug 1995 00:00:00 GMT');

ستُعيد القيمة 807926400000 بغض النظر عن المنطقة الزمنية المحليّة، لأنَّنا حدننا المنطقة الزمنية فيها (GMT أو UTC).

Date.parse('Wed, 09 Aug 1995 00:00:00');

ستُعيد القيمة 807937200000 في المنطقة الزمنية GMT-0300 وقيم أخرى في مناطق زمنية أخرى، ولمّا كانت السلسلة النصية غير معيارية ولا تُحدِّد منطقةً زمنيةً وليست بصيغة ISO، فستُعدّ المنطقة الزمنية هي المنطقة الزمنية المحلية.

Date.parse('Thu, 01 Jan 1970 00:00:00 GMT');

ستُعيد القيمة 0 بغض النظر عن المنطقة الزمنية المحليّة، لأنَّنا حدننا المنطقة الزمنية فيها (GMT أو UTC).

Date.parse('Thu, 01 Jan 1970 00:00:00');

ستُعيد القيمة 14400000 في المنطقة الزمنية GMT-0400 وقيم أخرى في مناطق زمنية أخرى، ولمّا كانت السلسلة النصية غير معيارية ولا تُحدِّد منطقةً زمنيةً وليست بصيغة ISO، فستُعدّ المنطقة الزمنية هي المنطقة الزمنية المحلية.

Date.parse('Thu, 01 Jan 1970 00:00:00 GMT-0400');

ستُعيد القيمة 14400000 بغض النظر عن المنطقة الزمنية المحليّة، لأنَّنا حدننا المنطقة الزمنية فيها (GMT أو UTC).

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

الميزة	Chrome	Firefox	Internet Explorer	Opera	Safari
الدعم الأساسي	نعم	نعم	نعم	نعم	نعم

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

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.
• معيار ECMAScript 5.1. إضافة صيغة ISO 8601 المُبسّطة.
• معيار ECMAScript 1st Edition.