Date.UTC()‎

الدالة Date.UTC()‎ تقبل نفس الوسائط التي يقبلها أطول شكل من أشكال الدالة البانية، وتُعيد كم ملي ثانية مضت منذ January 1, 1970, 00:00:00 في التوقيت العالمي (UTC).

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

Date.UTC(year, month[, day[, hour[, minute[, second[, millisecond]]]]])

year

قيمة عددية صحيحة تُمثِّل السنة بعد عام 1900.

month

قيمة عددية صحيحة تُمثِّل الشهر، وتبدأ من 0 (كانون الثاني/يناير) إلى 11 (كانون الأول/ديسمبر).

day

قيمة اختيارية، وهي عددٌ صحيحٌ يُمثِّل اليوم من الشهر (من 1 إلى 31).

hours

قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل الساعة من اليوم (من 0 حتى 23).

minutes

قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل عدد الدقائق من الوقت (من 0 حتى 59).

seconds

قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل عدد الثواني من الوقت (من 0 حتى 59).

milliseconds

قيمةٌ اختياريةٌ، وهي عددٌ صحيحٌ يُمثِّل عدد الملي ثانية من الوقت (من 0 حتى 999).

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

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

الوصف

الدالة UTC()‎ تقبل وسائط تُمثِّل التاريخ المُحدَّد وتُعيد كم ملي ثانية مضت منذ January 1, 1970, 00:00:00 في التوقيت العالمي (UTC) حتى الوقت الذي حدّدته.

يجب عليك تحديد السنة كاملةً، أي 1998، فهنالك اختلافٌ في طريقة تفسير السنوات المُحدَّدة عبر رقمين.

تختلف الدالة UTC()‎ عن الدالة البانية Date بأمرين:

• الدالة Date.UTC()‎ تستخدم التوقيت العالمي بدلًا من التوقيت المحلي.
• الدالة Date.UTC()‎ تُعيد قيمة الوقت كرقم وليس ككائن Date.

إذا كان الوسيط الذي حدّدت خارج المجال المتوقع، فستُحدِّث الدالة UTC()‎ قيم بقية الوسائط للسماح باستخدام الرقم الذي حددته. فمثلًا لو استخدمتَ القيمة 15 للشهر، فستزداد السنة بمقدار 1 (أي year + 1) وستُستخدَم القيمة 3 للشهر.

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

تمرير أقل من وسيطين إلى الدالة Date.UTC

عند توفير أقل من وسيطين إلى الدالة Date.UTC، فستُعاد القيمة NaN، وهذا السلوك مُعرّف في مواصفة ECMAScript 2017، وجرى تحديث المتصفحات التي لم تكن تدعم هذا السلوك:

Date.UTC();
Date.UTC(1);

// Safari: NaN 
// Chrome/Opera/V8: NaN

// Firefox <54: non-NaN
// Firefox 54+: NaN

// IE: non-NaN
// Edge: NaN

أمثلة

الشيفرة الآتية تُنشِئ كائن من النوع Date باستخدام توقيت UTC بدلًا من التوقيت المحلي:

var utcDate = new Date(Date.UTC(1996, 11, 1, 0, 0, 0));

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

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

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

• مسودة المعيار ECMAScript Latest Draft.
• معيار ECMAScript 2015 (6th Edition)‎.
• معيار ECMAScript 5.1.
• معيار ECMAScript 1st Edition.