Функция parse и её параметры

Функция parse из библиотеки date-fns предназначена для преобразования строкового представления даты в объект Date на основе заданного шаблона формата.

Сигнатура функции:

parse(dateString, formatString, referenceDate, options)

Пример:

import { parse } from 'date-fns'

const result = parse(
  '21.05.2026',
  'dd.MM.yyyy',
  new Date()
)

console.log(result)

Результат:

2026-05-21T00:00:00.000Z

Общая структура функции

dateString

Строка с датой, которую необходимо разобрать.

'25/12/2026'

formatString

Шаблон, описывающий структуру строки.

'dd/MM/yyyy'

referenceDate

Базовая дата, из которой берутся отсутствующие значения.

new Date()

options

Дополнительные настройки парсинга.

{
  locale: ru
}

Параметр dateString

Разбор строки даты

Первый аргумент — строка, содержащая дату или время.

parse('10-03-2025', 'dd-MM-yyyy', new Date())

Строка должна строго соответствовать формату.

Несоответствие формату

Если структура строки не совпадает с шаблоном, результатом будет Invalid Date.

parse('2025/03/10', 'dd-MM-yyyy', new Date())

Результат:

Invalid Date

Частичный разбор

Можно разбирать только часть даты.

parse('15:30', 'HH:mm', new Date())

В этом случае день, месяц и год будут взяты из referenceDate.

Параметр formatString

Роль шаблона

Шаблон определяет, как интерпретировать строку.

parse('21.05.2026', 'dd.MM.yyyy', new Date())

Каждый токен отвечает за отдельную часть даты.

Основные токены

День месяца

Токен Описание Пример
d День 5
dd День с нулём 05 
parse('05', 'dd', new Date())

Месяц

Токен Описание Пример
M Месяц 8
MM Месяц с нулём 08
MMM Краткое название Aug
MMMM Полное название August 
parse('12', 'MM', new Date())

Год

Токен Описание
yy Двузначный год
yyyy Полный год 
parse('2026', 'yyyy', new Date())

Часы

Токен Описание
H Часы 0–23
HH Часы с ведущим нулём 
parse('23', 'HH', new Date())

Минуты

Токен Описание
m Минуты
mm Минуты с нулём

Секунды

Токен Описание
s Секунды
ss Секунды с нулём

Разделители в шаблоне

Разделители должны совпадать со строкой.

parse('2026/05/21', 'yyyy/MM/dd', new Date())

Если указать другой разделитель:

parse('2026-05-21', 'yyyy/MM/dd', new Date())

результат будет некорректным.

Экранирование текста

Фиксированные символы

Текст в шаблоне можно экранировать одинарными кавычками.

parse(
  'Дата: 21-05-2026',
  "'Дата:' dd-MM-yyyy",
  new Date()
)

Использование кавычек внутри строки

Для вывода самой кавычки используется двойное экранирование.

parse(
  "2026 o'clock",
  "yyyy 'o''clock'",
  new Date()
)

Параметр referenceDate

Назначение базовой даты

referenceDate используется как источник значений, отсутствующих в строке.

const baseDate = new Date(2026, 4, 20)

parse('15:30', 'HH:mm', baseDate)

Результат:

2026-05-20T15:30:00

Разбор только месяца и дня

parse('21-05', 'dd-MM', new Date(2030, 0, 1))

Год будет взят из referenceDate.

Почему referenceDate обязателен

Даже если все данные присутствуют в строке, третий аргумент обязателен.

parse('21.05.2026', 'dd.MM.yyyy', new Date())

Без него функция выбросит ошибку.

Параметр options

Использование локали

Для разбора локализованных названий месяцев используется locale.

import { ru } from 'date-fns/locale'

parse(
  '21 май 2026',
  'dd MMM yyyy',
  new Date(),
  { locale: ru }
)

Английская локаль по умолчанию

Без указания локали библиотека ожидает английские названия.

parse(
  '21 May 2026',
  'dd MMM yyyy',
  new Date()
)

Разбор времени

Часы и минуты

parse(
  '18:45',
  'HH:mm',
  new Date()
)

Полное время

parse(
  '18:45:30',
  'HH:mm:ss',
  new Date()
)

Время с датой

parse(
  '21.05.2026 18:45',
  'dd.MM.yyyy HH:mm',
  new Date()
)

12-часовой формат

Использование hh

Токен Описание
hh Часы 1–12 
parse(
  '11:30 PM',
  'hh:mm a',
  new Date()
)

Токен a

Токен a отвечает за AM/PM.

parse(
  '07:15 AM',
  'hh:mm a',
  new Date()
)

Работа с ISO-строками

Хотя для ISO существует отдельная функция parseISO, parse также может использоваться.

parse(
  '2026-05-21',
  'yyyy-MM-dd',
  new Date()
)

Разбор названий месяцев

Краткие названия

parse(
  '21 Feb 2026',
  'dd MMM yyyy',
  new Date()
)

Полные названия

parse(
  '21 February 2026',
  'dd MMMM yyyy',
  new Date()
)

Разбор дня недели

Использование токена EEEE

parse(
  'Monday, 21-05-2026',
  'EEEE, dd-MM-yyyy',
  new Date()
)

День недели не влияет на итоговую дату

Если день недели не совпадает с реальной датой, библиотека ориентируется на числовые значения.

parse(
  'Sunday, 21-05-2026',
  'EEEE, dd-MM-yyyy',
  new Date()
)

Ошибки и Invalid Date

Проверка результата

Для проверки используется функция isValid.

import { parse, isValid } from 'date-fns'

const result = parse(
  '99.99.2026',
  'dd.MM.yyyy',
  new Date()
)

console.log(isValid(result))

Причины появления Invalid Date

Неверный формат

parse('2026-05', 'dd.MM.yyyy', new Date())

Некорректные значения

parse('31.02.2026', 'dd.MM.yyyy', new Date())

Ошибка в токенах

parse('21-05-2026', 'DD-MM-YYYY', new Date())

Отличие yyyy и YYYY

Правильный токен года

В date-fns используется:

yyyy

а не:

YYYY

Причина

YYYY относится к week-numbering year и может давать неожиданные результаты около начала года.

Правильно:

parse('2026', 'yyyy', new Date())

Отличие dd и DD

День месяца

dd

День года

DD

Использование неправильного токена приводит к ошибкам.

Строгость парсинга

Полное совпадение строки

Функция требует точного соответствия.

parse(
  '2026-05-21abc',
  'yyyy-MM-dd',
  new Date()
)

Результат:

Invalid Date

Комбинирование токенов

Сложный шаблон

parse(
  'Thursday, 21 May 2026 18:45:10',
  'EEEE, dd MMMM yyyy HH:mm:ss',
  new Date()
)

Практические примеры

Разбор даты из формы

const userInput = '24.12.2026'

const date = parse(
  userInput,
  'dd.MM.yyyy',
  new Date()
)

Разбор серверной строки

const apiDate = '2026-05-21 14:30:00'

const result = parse(
  apiDate,
  'yyyy-MM-dd HH:mm:ss',
  new Date()
)

Работа с логами

parse(
  '2026/05/21 18:45:30',
  'yyyy/MM/dd HH:mm:ss',
  new Date()
)

Часто используемые шаблоны

Формат Шаблон
21.05.2026 dd.MM.yyyy
2026-05-21 yyyy-MM-dd
21/05/2026 dd/MM/yyyy
18:30 HH:mm
18:30:15 HH:mm:ss
21 May 2026 dd MMM yyyy
Thursday, 21 May EEEE, dd MMMM

Рекомендации по использованию

Использование parseISO для ISO

Для ISO-дат предпочтительнее:

parseISO('2026-05-21')

Проверка валидности

После парсинга рекомендуется всегда проверять результат.

if (isValid(date)) {
  console.log('Дата корректна')
}

Единый формат на проекте

Использование одного стандарта формата снижает количество ошибок:

yyyy-MM-dd

Совместное использование с format

Обратное преобразование

import { parse, format } from 'date-fns'

const date = parse(
  '21.05.2026',
  'dd.MM.yyyy',
  new Date()
)

const result = format(
  date,
  'yyyy-MM-dd'
)

console.log(result)

Внутренний принцип работы parse

Функция проходит по шаблону слева направо:

  1. Анализирует токены
  2. Считывает соответствующие части строки
  3. Преобразует значения в компоненты даты
  4. Формирует объект Date
  5. Проверяет корректность результата

Особенности работы с часовыми поясами

parse создаёт объект Date в локальном часовом поясе среды выполнения.

parse(
  '2026-05-21 10:00',
  'yyyy-MM-dd HH:mm',
  new Date()
)

Результат может отличаться в разных часовых поясах.

Типичные ошибки

Использование Moment.js токенов

Неправильно:

DD.MM.YYYY

Правильно:

dd.MM.yyyy

Отсутствие локали

parse(
  '21 Май 2026',
  'dd MMM yyyy',
  new Date()
)

Без locale: ru результат будет неверным.

Смешивание 12-часового и 24-часового форматов

Неправильно:

HH:mm a

Правильно:

hh:mm a

Сравнение parse и new Date

new Date

new Date('2026-05-21')

Зависит от реализации движка и формата строки.

parse

parse(
  '21.05.2026',
  'dd.MM.yyyy',
  new Date()
)

Даёт предсказуемый результат благодаря явному шаблону.

Оглавление