الكائن Date في JavaScript
الدالة البانية Date تُنشِئ كائنًا من النوع Date الذي يُمثِّل لحظة زمنية معيّنة. القيمة الزمنية الموجودة في كائنات Date هي كم ملي ثانية مضى منذ تاريخ 1 كانون الثاني (يناير) 1970 بتوقيت UTC.
البنية العامة
new Date();
new Date(value);
new Date(dateString);
new Date(year, month, day, hours, minutes, seconds, milliseconds);
ملاحظة: كائنات Date في JavaScript يمكن تهيئتها باستخدام Date كدالة بانية فقط، أي استدعاؤها كدالة عادية (دون المعامل new) وسيُعيد ذلك سلسلةً نصيةً بدلًا من الكائن Date، وعلى النقيض من بقية أنواع كائنات JavaScript، لا توجد صيغة مختصرة (literal syntax) لكائنات Date.
ملاحظة: الوسيط month يبدأ من الصفر، وهذا يعني أنَّ January = 0 و December = 11.
ملاحظة: عند استدعاء الدالة البانية Date مع أكثر من وسيط، وكانت القيم أكبر من مجالها المنطقي (مثلًا: استخدمنا 13 مكان الشهر أو 70 مكان الدقائق) فستُعدّل قيمة التاريخ بما يوافق ذلك. أي أنَّ new Date(2013, 13, 1) يكافئ new Date(2014, 1, 1) وكلا الدالتين يُنشِئ التاريخ 2014-02-01 (تذكر أنَّ عدّ الأشهر يبدأ من الصفر). مثالٌ آخر عن الدقائق: new Date(2013, 2, 1, 0, 70) يكافئ new Date(2013, 2, 1, 1, 10) وكلاهما يشير إلى 2013-03-01T01:10:00.
ملاحظة: عند استدعاء الدالة البانية Date مع أكثر من وسيط، فإنَّ الوسائط المُمرَّرة ستكون في التوقيت المحلي، إذا أردتَ أن يكون التوقيت UTC فاستخدام new Date(Date.UTC(...)) مع الوسائط نفسها.
value
قيمةٌ عدديةٌ صحيحةٌ تُمثِّل كم ملي ثانية قد مضى منذ تاريخ 1 January 1970 00:00:00 UTC، مع إهمال الثواني الكبيسة (leap seconds)، أي كأنها بصمة وقت يونكس (Unix time stamp، لكن ضع في ذهنك أنَّ أغلبية الدوال التي تتعامل مع بصمات الوقت تستخدم الثواني بدلًا من الملي ثانية).
dateString
سلسلة نصية تُمثِّل تاريخًا، وهذه السلسلة يجب أن تكون بصيغة تتعرف عليها الدالة Data.parse() (وهي بصمات الوقت التي تتوافق مع معيار RFC 2822 ونسخة من ISO8601).
ملاحظة: تفسير السلاسل النصية التي تحتوي على التاريخ باستخدام الدالة البانية Date (أو الدالة Date.parse، فهما متكافئتان هنا) هو أمرٌ غير مستحسن بسبب الاختلافات بين المتصفحات، فدعم صيغة RFC 2822 شكليٌ تقريبًا، أما دعم صيغة ISO 8601 فيختلف في أنَّ السلاسل النصية التي فيها تواريخ فقط (مثل "1970-01-01") ستُفسَّر على أنها في توقيت UTC، وليس في المنطقة الزمنية المحلية.
year
قيمة عددية صحيحة تُمثِّل السنة. والقيم من 0 إلى 99 تُمثِّل السنوات 1900 إلى 1999. راجع قسم الأمثلة أدناه.
month
قيمة عددية صحيحة تُمثِّل الشهر، وتبدأ من 0 (كانون الثاني/يناير) إلى 11 (كانون الأول/ديسمبر).
day
قيمة اختيارية، وهي عددٌ صحيحٌ يُمثِّل اليوم من الشهر.
hours
قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل الساعة من اليوم.
minutes
قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل عدد الدقائق من الوقت.
seconds
قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل عدد الثواني من الوقت.
milliseconds
قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل قسم الملي ثانية من الوقت.
الوصف
- إذا لم يُوفَّر وسيط إلى الدالة، فستُنشِئ الدالة البانية الكائن
Dateللوقت والتاريخ الحاليين تبعًا لإعدادات النظام. - إذا وُفِّرَ وسيطان على الأقل، فالوسائط الناقصة ستُعد على أنها 1 (إذا لم يُحدَّد اليوم
day) أو 0 لجميع القيمة الأخرى. - الكائن
Dateفي JavaScript مبنيٌ على المقدار الذي مضى بدلًا من منتصف ليلة 01 January, 1970 UTC بالملي ثانية. وكل يوم فيه 86,400,000 ملي ثانية؛ ومجال الكائنDateفي JavaScript هو من -100,000,000 إلى 100,000,000 نسبةً إلى تاريخ 01 January, 1970 UTC. - الكائن
Dateيوفِّر سلوكًا موحدًا في جميع المنصات، ويمكن تمرير قيمة الوقت بين مختلف الأنظمة لإنشاء كائنDateيُمثِّل اللحظة الزمنية نفسها. - الكائن Date يوفِّر عددًا من دوال UTC، إضافةً إلى عدد من الدوال التي تتعامل مع المنطقة الزمنية المحلي. توقيت UTC (أي Universal Time Coordinated ويُعرَف أيضًا بتوقيت غرينتش Greenwich Mean Time اختصارًا GMT) يُشير إلى الوقت العالمي، أما الوقت المحلي فهو الوقت المعروف إلى الحاسوب عند تنفيذ شيفرة JavaScript.
- استدعاء الدالة
Dateكدالة عادية (أي دون المعاملnew) سيؤدي إلى إعادة سلسلة نصية تُمثِّل الوقت والتاريخ الحاليين.
الخاصيات
Date.prototype
تسمح هذه الخاصية بإضافة خاصيات متاحة لجميع الكائنات التي نوعها هو Date.
Date.length
قيمة الخاصية Date.length هي 7، وهو عدد الوسائط التي يمكن أن تُعالِجها الدالة البانية.
الدوال
Date.now()
إعادة القيمة العددية التي تُشير إلى الوقت الحالي، أي كم ملي ثانية قد مضت بدءًا من 1 January 1970 00:00:00 UTC مع إهمال الثواني الكبيسة.
Date.parse()
تفسير سلسلة نصية تُمثِّل تاريخًا وإعادة كم ملي ثانية قد مضت بدءًا من 1 January 1970 00:00:00 UTC مع إهمال الثواني الكبيسة.
Date.UTC()
تقبل هذه الدالة نفس الوسائط التي يقبلها الشكل الطويل من الدالة البانية (أي من 2 إلى 7 وسائط)، وتُعيد كم ملي ثانية قد مضت بدءًا من 1 January 1970 00:00:00 UTC مع إهمال الثواني الكبيسة.
الدوال التابعة للكائن Date.prototype
النسخ المُنشَأة من الدالة البانية Date ترث الدوال والخاصيات من كائن Date.prototype؛ وكما في جميع الدوال البانية، يمكنك إجراء تغييرات إلى كائن prototype في الدالة البانية لكي تنعكس تلك التعديلات إلى جميع نسخ الكائن Date.
دوال الحصول على قيم
Date.prototype.getDate()
إعادة اليوم من الشهر (1-31) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getDay()
إعادة اليوم من الأسبوع (0-6) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getFullYear()
إعادة السنة (أربعة أرقام) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getHours()
إعادة الساعة (0-23) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getMilliseconds()
إعادة أجزاء الثواني (بالملي ثانية، 0-999) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getMinutes()
إعادة الدقائق (0-59) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getMonth()
إعادة الشهر (0-11) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getSeconds()
إعادة الثواني (0-59) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.getTime()
إعادة قيمة رقمية للتاريخ المُحدَّد تُمثِّل كم ملي ثانية مضت منذ January 1, 1970, 00:00:00 UTC.
Date.prototype.getTimezoneOffset()
إعادة إزاحة المنطقة الزمنية للمحليّة (locale) عن UTC.
Date.prototype.getUTCDate()
إعادة اليوم من الشهر (1-31) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCDay()
إعادة اليوم من الأسبوع (0-6) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCFullYear()
إعادة السنة (أربعة أرقام) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCHours()
إعادة الساعة (0-23) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCMilliseconds()
إعادة أجزاء الثواني (بالملي ثانية، 0-999) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCMinutes()
إعادة الدقائق (0-59) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCMonth()
إعادة الشهر (0-11) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getUTCSeconds()
إعادة الثواني (0-59) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.getYear()
إعادة السنة (2-3 أرقام عادةً) للتاريخ المُحدَّد وفقًا للتوقيت المحلي. لا تستخدم هذه الدالة واستخدم الدالة getFullYear() بدلًا منها.
دوال ضبط القيم
Date.prototype.setDate()
ضبط اليوم من الشهر (1-31) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setFullYear()
ضبط السنة (أربعة أرقام) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setHours()
ضبط الساعة (0-23) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setMilliseconds()
ضبط أجزاء الثواني (بالملي ثانية، 0-999) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setMinutes()
ضبط الدقائق (0-59) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setMonth()
ضبط الشهر (0-11) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setSeconds()
ضبط الثواني (0-59) للتاريخ المُحدَّد وفقًا للتوقيت المحلي.
Date.prototype.setTime()
ضبط قيمة رقمية للتاريخ المُحدَّد تُمثِّل كم ملي ثانية مضت منذ January 1, 1970, 00:00:00 UTC.
Date.prototype.setUTCDate()
ضبط اليوم من الشهر (1-31) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setUTCFullYear()
ضبط السنة (أربعة أرقام) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setUTCHours()
ضبط الساعة (0-23) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setUTCMilliseconds()
ضبط أجزاء الثواني (بالملي ثانية، 0-999) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setUTCMinutes()
ضبط الدقائق (0-59) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setUTCMonth()
ضبط الشهر (0-11) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setUTCSeconds()
ضبط الثواني (0-59) للتاريخ المُحدَّد وفقًا للتوقيت العالمي.
Date.prototype.setYear()
ضبط السنة (2-3 أرقام عادةً) للتاريخ المُحدَّد وفقًا للتوقيت المحلي. لا تستخدم هذه الدالة واستخدم الدالة setFullYear() بدلًا منها.
دوال التحويل
Date.prototype.toDateString()
إعادة قسم التاريخ من كائن Date كسلسلة نصية سهلة القراءة من البشر.
Date.prototype.toISOString()
تحويل التاريخ إلى سلسلة نصية تتبع صيغة ISO 8601 الموسّعة.
Date.prototype.toJSON()
إعادة سلسة نصية تُمثِّل كائن Date باستخدام toISOString()، والغرض منها هو استعمالها من قبل الدالة JSON.stringify().
Date.prototype.toGMTString()
إعادة سلسة نصية تُمثِّل كائن Date اعتمادًا على توقيت غرينتش (GMT). هذه الدالة مهملة ويجب استخدام الدالة toUTCString() بدلًا منها.
Date.prototype.toLocaleDateString()
إعادة سلسة نصية تُمثِّل قسم التاريخ اعتمادًا على إعدادات محليّة (locale) النظام.
Date.prototype.toLocaleString()
إعادة سلسة نصية تُمثِّل التاريخ والوقت اعتمادًا على إعدادات محليّة (locale) النظام.
Date.prototype.toLocaleTimeString()
إعادة سلسة نصية تُمثِّل الوقت اعتمادًا على إعدادات محليّة (locale) النظام.
Date.prototype.toString()
إعادة سلسة نصية تُمثِّل الكائن Date. وهي إعادة تعريف للدالة Object.prototype.toString.
Date.prototype.toTimeString()
إعادة قسم الوقت من كائن Date كسلسلة نصية سهلة القراءة من البشر.
Date.prototype.toUTCString()
تحويل التاريخ إلى سلسلة نصية تستخدم المنطقة الزمنية UTC.
Date.prototype.valueOf()
إعادة القيمة الأولية (primitive value) للكائن المُحدَّد. وهي إعادة تعريف للدالة Object.prototype.valueOf.
أمثلة
عدّة طرائق لإنشاء كائن Date
المثال الآتي يبيّن عدّة طرائق لإنشاء كائنات Date في JavaScript.
ملاحظة: نُكرِّر أنَّ من غير المستحسن تفسير السلاسل النصية التي تحتوي على تواريخ باستخدام الدالة البانية Date (أو الدالة Date.parse، فهما سواء)، ذلك بسبب الاختلافات بين طرائق التفسير بين المتصفحات.
var today = new Date();
var birthday = new Date('May 21, 1995 03:24:00');
var birthday = new Date('1995-5-21T03:24:00');
var birthday = new Date(1995, 4, 21);
var birthday = new Date(1995, 4, 21, 3, 24, 0);
السنوات بين 1900 و 1999
لضبط والحصول على التواريخ بين العامين 0 و 99، فاستخدم الدالتين Date.prototype.setFullYear() و Date.prototype.getFullYear()؛ لاحظ أنَّه من غير المستحسن استخدام الدالتين Date.prototype.setYear() و Date.prototype.getYear() لأنها تعدان الأرقام بين 0 و 99 على أنهما 1900 و 1999:
var date = new Date(98, 1); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setYear(98); // Sun Feb 01 1998 00:00:00 GMT+0000 (GMT)
date.setFullYear(98); // Sat Feb 01 0098 00:00:00 GMT+0000 (BST)
حساب الزمن المنقضي
الأمثلة الآتية يبيّن كيفية حساب الزمن المنقضي بين تاريخين في JavaScript بالملي ثانية.
استخدام كائنّي Date:
var start = Date.now();
doSomethingForALongTime(); // العملية التي نريد حساب مدة تنفيذها
var end = Date.now();
var elapsed = end - start; // الزمن المنقضي بالملي ثانية
استخدام دوال الكائن Date:
var start = new Date();
doSomethingForALongTime(); // العملية التي نريد حساب مدة تنفيذها
var end = new Date();
var elapsed = end.getTime() - start.getTime(); // الزمن المنقضي بالملي ثانية
اختبار دالة ما وحساب زمن تنفيذها:
function printElapsedTime(fTest) {
var nStartTime = Date.now(),
vReturn = fTest(),
nEndTime = Date.now();
console.log('Elapsed time: ' + String(nEndTime - nStartTime) + ' milliseconds');
return vReturn;
}
var yourFunctionReturn = printElapsedTime(yourFunction);
دعم المتصفحات
| الميزة | Chrome | Firefox | Internet Explorer | Opera | Safari |
|---|---|---|---|---|---|
| الدعم الأساسي | نعم | نعم | نعم | نعم | نعم |
انظر إلى صفحة كل خاصية ودالة تابعة للكائن Date لتفاصيل عن دعم المتصفحات لها.
مصادر ومواصفات
- مسودة المعيار ECMAScript Latest Draft.
- معيار ECMAScript 2015 (6th Edition).
- معيار ECMAScript 5.1.
- معيار ECMAScript 1st Edition.