Date.parse()

Метод Date.parse() розбирає рядкове представлення дати та повертає кількість мілісекунд від 1 січня 1970 року, 00:00:00 за UTC, або NaN, якщо рядок неможливо розібрати чи, в окремих випадках, він містить недозволені значення (наприклад, 2015-02-31).

Не рекомендується використовувати Date.parse, оскільки у версіях до ES5 розбір був повністю залежним від реалізації. Досі існують багато відмінностей у тому, як різні хости розбирають рядки з датами, тому вони мають розбиратися вручну (можна скористатись бібліотекою, якщо очікується багато різних форматів).

Синтаксис

Прямий виклик:

Date.parse(dateString)

Неявний виклик:

new Date(dateString)

Параметри

dateString
Рядок, що відображає спрощену версію розширеного календарного формату дати ISO 8601. (Можна використовувати й інші формати, але результат залежитиме від реалізації.)

Повертає

Число, що відображає кількість мілісекунд від 1 січня 1970 року, 00:00:00 за UTC, і дату, отриману розбором наданого рядкового представлення дати. Якщо аргумент не відображає дозволене значення дати, повертається NaN.

Опис

Метод parse() приймає рядок з датою (наприклад, "2011-10-10T14:48:00") та повертає число мілісекунд від 1 січня 1970 року, 00:00:00 за UTC.

Ця функція корисна для присвоєння дати на основі рядкових значень, наприклад, у поєднанні з методом setTime() та об'єктом Date.

Рядковий формат дати та часу

Стандартне рядкове представлення дати та часу є спрощенням розширеного календарного формату дати ISO 8601. (Дивіться більше подробиць у розділі Date Time String Format специфікації ECMAScript.)

Наприклад, "2011-10-10" (лише дата), "2011-10-10T14:48:00" (дата та час) або "2011-10-10T14:48:00.000+09:00" (дата та час з мілісекундами та часовим поясом) можуть бути та будуть розібрані. Коли зсув часового поясу відсутній, форми, що містять лише дату, інтерпретуються як час UTC, а форми з датою та часом інтерпретуються як місцевий час.

Хоча специфікатори часового поясу використовуються під час розбору рядків для інтерпретації аргументу, значення, що повертається, завжди буде кількістю мілісекунд між 1 січня 1970 року 00:00:00 за UTC та точкою у часі, відображеною аргументом, або ж NaN.

Оскіьки parse() - статичний метод Date, він викликається як Date.parse(), а не як метод екземпляра Date.

Використання специфічних реалізацій форматів дати

Цей розділ містить специфічно реалізовану поведінку, яка може не співпадати між різними реалізаціями.

Специфікація ECMAScript зазначає: Якщо рядок не відповідає стандартному формату, функція може застосовувати будь-яку специфічно реалізовану евристику чи специфічно реалізований алгоритм розбору. Рядки, які неможливо розібрати, чи дати, що містять недозволені значення елементів у рядках формату ISO, змусять метод Date.parse() повернути NaN.

Однак, недозволені значення у рядках дат, які не розпізнаються в якості спрощеного формату ISO, визначеного у ECMA-262, можуть повернути або не повернути NaN, в залежності від переглядача, наданих значень і т.д.:

// Рядок не формату ISO з недозволеними значеннями у даті
new Date('23/25/2014');

це буде сприйнято як локальна дата 25 листопада 2015 у Firefox 30 та як неправильна дата у Safari 7.

Однак, якщо рядок розпізнається як рядок формату ISO та містить недозволені значення, він поверне NaN в усіх переглядачах, сумісних з ES5 та пізнішими версіями:

// Рядок ISO з недозволеними значеннями
new Date('2014-25-23').toISOString();
// викидає "RangeError: invalid date" в усіх переглядачах, сумісних з ES5

Специфічну реалізацію SpiderMonkey можна знайти у jsdate.cpp. Рядок "10 06 2014" є прикладом невідповідності формату ISO, і тому використовується особливий алгоритм. Дивіться також цей короткий опис того, як працює розбір.

new Date('10 06 2014');

це буде сприйматись як локальна дата 6 жовтня 2014, а не як 10 червня 2014.

Інші приклади:

new Date('foo-bar 2014').toString();
// повертає: "Invalid Date"

Date.parse('foo-bar 2014');
// повертає: NaN

Відмінності у отриманому часовому поясі

Цей розділ містить специфічно реалізовану поведінку, яка може не співпадати між різними реалізаціями.

Отримавши нестандартний рядок дати "March 7, 2014", parse() припускає, що він відноситься до місцевого часового поясу, але отримавши рядок у спрощеній версії розширеного календарного формату ISO 8601, наприклад, "2014-03-07", він припускає часовий пояс UTC (ES5 та ECMAScript 2015). Таким чином, об'єкти Date, отримані за допомогою цих рядків, можуть відображати різні моменти часу, в залежності від версії ECMAScript, яка підтримується, якщо тільки у системі не встановлений місцевий часовий пояс UTC. Це означає, що два рядки дат, що виглядають еквівалентними, можуть повернути два різних значення, в залежності від формату рядка, який перетворюється.

Приклади

Використання Date.parse()

Усі наступні виклики повертають 1546300800000. Перший, у відповідності до ES5, застосує час UTC, а інші вказують часовий пояс UTC через специфікацію дати ISO (Z та +00:00)

Date.parse("2019-01-01")
Date.parse("2019-01-01T00:00:00.000Z")
Date.parse("2019-01-01T00:00:00.000+00:00")

Наступний виклик, який не вказує часовий пояс, поверне 2019-01-01 о 00:00:00 у локальному часовому поясі системи.

Date.parse("2019-01-01T00:00:00")

Нестандартні рядки дат

Цей розділ містить специфічно реалізовану поведінку, яка може не співпадати між різними реалізаціями.

Якщо IPOdate є існуючим об'єктом Date, йому можна призначити дату 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).

Специфікації

Специфікація
ECMAScript (ECMA-262)
The definition of 'Date.parse' in that specification.

Сумісність з веб-переглядачами

BCD tables only load in the browser

Примітки щодо сумісності

  • Firefox 49 змінив розбір 2-значних значень року для співпадіння з переглядачем Google Chrome замість Internet Explorer. Тепер 2-значні значення року, менші за 50, розбираються як роки 21-го сторіччя. Наприклад, 04/16/17, що раніше інтерпретувалось як 16 квітня 1917 року тепер буде 16 квітня 2017 року. Щоб запобігти будь-яких проблем сумісності чи невизначеності, рекомендується використовувати формат ISO 8601, наприклад, "2017-04-16" (помилка 1265136).
  • Google Chrome прийме числовий рядок як дозволений параметр dateString. Це означає, що, наприклад, в той час, як команда !!Date.parse("42") повертає false у Firefox, вона поверне true у Google Chrome, оскільки "42" інтерпретується як 1 січня 2042 року.

Див. також