d3-time-format

Этот модуль предоставляет приближенную JavaScript-реализацию функций strptime и strftime из стандартной библиотеки C и может использоваться для разбора или форматирования дат в различных локально-зависимых представлениях. Для форматирования даты создайте форматер из спецификатора (строки с желаемыми директивами формата, обозначенными как %); затем передайте дату форматеру, который вернёт строку. Например, для преобразования текущей даты в удобочитаемую строку:

const formatTime = d3.timeFormat("%B %d, %Y");
formatTime(new Date); // "June 30, 2015"

Аналогично, для преобразования строки обратно в дату создайте парсер:

const parseTime = d3.timeParse("%B %d, %Y");
parseTime("June 30, 2015"); // Tue Jun 30 2015 00:00:00 GMT-0700 (PDT)

Вы также можете реализовать более сложные условные форматы времени. Например, вот многомасштабный формат времени с использованием временных интервалов:

const formatMillisecond = d3.timeFormat(".%L"),
    formatSecond = d3.timeFormat(":%S"),
    formatMinute = d3.timeFormat("%I:%M"),
    formatHour = d3.timeFormat("%I %p"),
    formatDay = d3.timeFormat("%a %d"),
    formatWeek = d3.timeFormat("%b %d"),
    formatMonth = d3.timeFormat("%B"),
    formatYear = d3.timeFormat("%Y");

function multiFormat(date) {
  return (d3.timeSecond(date) < date ? formatMillisecond
      : d3.timeMinute(date) < date ? formatSecond
      : d3.timeHour(date) < date ? formatMinute
      : d3.timeDay(date) < date ? formatHour
      : d3.timeMonth(date) < date ? (d3.timeWeek(date) < date ? formatDay : formatWeek)
      : d3.timeYear(date) < date ? formatMonth
      : formatYear)(date);
}

Этот модуль используется D3 временными шкалами для генерации удобочитаемых меток.

Установка

Если вы используете npm, npm install d3-time-format. Вы также можете загрузить последнюю версию на GitHub. Для обычного HTML в современных браузерах импортируйте d3-time-format из Skypack:

<script type="module">

import {timeFormat} from "https://cdn.skypack.dev/d3-time-format@4";

const format = timeFormat("%x");

</script>

Для устаревших сред вы можете загрузить UMD-пакет d3-time-format с CDN на базе npm, например, jsDelivr; экспортируется глобальная переменная d3.

<script src="https://cdn.jsdelivr.net/npm/d3-array@3"></script>
<script src="https://cdn.jsdelivr.net/npm/d3-time@3"></script>
<script src="https://cdn.jsdelivr.net/npm/d3-time-format@4"></script>
<script>

const format = d3.timeFormat("%x");

</script>

Файлы локали публикуются в npm и могут загружаться с помощью d3.json. Например, чтобы установить русский язык в качестве языка по умолчанию:

d3.json("https://cdn.jsdelivr.net/npm/d3-time-format@3/locale/ru-RU.json").then(locale => {
  d3.timeFormatDefaultLocale(locale);

  const format = d3.timeFormat("%c");

  console.log(format(new Date)); // понедельник,  5 декабря 2016 г. 10:31:59
});

Справочник по API

d3.isoFormat · Источник

Полный форматер ISO 8601 UTC времени. Если доступно, этот метод использует Date.toISOString для форматирования.

d3.isoParse · Источник

Полный парсер ISO 8601 UTC времени. Если доступно, этот метод использует конструктор Date для разбора строк. Если вы полагаетесь на строгую проверку входного формата в соответствии с ISO 8601, вы должны построить функцию парсера UTC:

const strictIsoParse = d3.utcParse("%Y-%m-%dT%H:%M:%S.%LZ");

locale.format(specifier) · Источник

Возвращает новый форматировщик для заданного строкового спецификатора. Строка спецификатора может содержать следующие директивы:

%a - сокращённое имя дня недели.*
%A - полное имя дня недели.*
%b - сокращённое имя месяца.*
%B - полное имя месяца.*
%c - дата и время локали, например %x, %X.*
%d - день месяца с ведущими нулями как десятичное число [01,31].
%e - день месяца с пробелами как десятичное число [ 1,31]; эквивалентно %_d.
%f - микросекунды как десятичное число [000000, 999999].
%g - год ISO 8601 по неделе без столетия как десятичное число [00,99].
%G - год ISO 8601 по неделе со столетием как десятичное число.
%H - час (24-часовой формат) как десятичное число [00,23].
%I - час (12-часовой формат) как десятичное число [01,12].
%j - день года как десятичное число [001,366].
%m - месяц как десятичное число [01,12].
%M - минута как десятичное число [00,59].
%L - миллисекунды как десятичное число [000, 999].
%p - либо AM, либо PM.*
%q - квартал года как десятичное число [1,4].
%Q - миллисекунды с начала эпохи UNIX.
%s - секунды с начала эпохи UNIX.
%S - секунда как десятичное число [00,61].
%u - день недели по понедельнику (ISO 8601) как десятичное число [1,7].
%U - неделя года по воскресенью как десятичное число [00,53].
%V - неделя года по ISO 8601 как десятичное число [01, 53].
%w - день недели по воскресенью как десятичное число [0,6].
%W - неделя года по понедельнику как десятичное число [00,53].
%x - дата локали, например %-m/%-d/%Y.*
%X - время локали, например %-I:%M:%S %p.*
%y - год без столетия как десятичное число [00,99].
%Y - год со столетием как десятичное число, например 1999.
%Z - смещение часового пояса, например -0700, -07:00, -07, или Z.
%% - буквальное процента (%).

Директивы, помеченные звёздочкой (*), могут зависеть от определения локали.

Для %U, все дни в новом году, предшествующие первому воскресенью, считаются неделей 0. Для %W, все дни в новом году, предшествующие первому понедельнику, считаются неделей 0. Номера недель вычисляются с помощью interval.count. Например, 2015-52 и 2016-00 представляют понедельник, 28 декабря 2015 года, а 2015-53 и 2016-01 представляют понедельник, 4 января 2016 года. Это отличается от спецификации даты ISO по неделе (%V), которая использует более сложное определение!

Для %V,%g и %G, согласно странице руководства strftime:

В этой системе недели начинаются с понедельника и нумеруются с 01 для первой недели до 52 или 53 для последней недели. Неделя 1 - это первая неделя, в которой четыре или более дней приходятся на новый год (или, синонимично, неделя 01: первая неделя года, содержащая четверг; или неделя, которая содержит 4 января). Если номер ISO-недели принадлежит предыдущему или следующему году, используется этот год вместо него.

Символ %, указывающий на директиву, может быть сразу же после модификатора выравнивания:

0 - нулевое выравнивание
_ - пробельное выравнивание
- - отключение выравнивания

Если модификатор выравнивания не указан, по умолчанию используется 0 для всех директив, кроме %e, для которой по умолчанию используется _. (В некоторых реализациях strftime и strptime директива может включать необязательную ширину поля или точность; эта функция пока не реализована.)

Возвращаемая функция форматирует указанную дату, возвращая соответствующую строку.

const formatMonth = d3.timeFormat("%B"),
    formatDay = d3.timeFormat("%A"),
    date = new Date(2014, 4, 1); // Thu May 01 2014 00:00:00 GMT-0700 (PDT)

formatMonth(date); // "May"
formatDay(date); // "Thursday"

locale.parse(specifier) · Источник

Возвращает новый парсер для заданного строкового спецификатора. Строка спецификатора может содержать те же директивы, что и locale.format. Директивы %d и %e считаются эквивалентными при разборе.

Возвращаемая функция анализирует заданную строку, возвращая соответствующую дату или null, если строка не может быть обработана в соответствии со спецификатором формата. Разбор строгий: если заданная строка не точно соответствует ассоциированному спецификатору, этот метод возвращает null. Например, если связанный спецификатор %Y-%m-%dT%H:%M:%SZ, то строка "2011-07-01T19:15:28Z" будет обработана как ожидалось, но "2011-07-01T19:15:28", "2011-07-01 19:15:28" и "2011-07-01" вернут null. (Обратите внимание, что буквальное Z здесь отличается от директивы смещения часового пояса %Z.) Если требуется более гибкий парсер, попробуйте несколько форматов последовательно, пока один из них не вернёт не null.

locale.utcFormat(specifier) · Источник

Эквивалентно locale.format, за исключением того, что все директивы интерпретируются как координированное универсальное время (UTC), а не местное время.

locale.utcParse(specifier) · Источник

Эквивалентно locale.parse, за исключением того, что все директивы интерпретируются как координированное универсальное время (UTC), а не местное время.

Локали

d3.timeFormatLocale(definition) · Источник

Возвращает объект locale для указанного definition с методами locale.format, locale.parse, locale.utcFormat, locale.utcParse. definition должен включать следующие свойства:

dateTime - спецификатор формата даты и времени (%c) (например, "%a %b %e %X %Y").
date - спецификатор формата даты (%x) (например, "%m/%d/%Y").
time - спецификатор формата времени (%X) (например, "%H:%M:%S").
periods - эквиваленты AM и PM (например, ["AM", "PM"]).
days - полные имена дней недели, начиная с воскресенья.
shortDays - сокращённые имена дней недели, начиная с воскресенья.
months - полные имена месяцев (начиная с января).
shortMonths - сокращённые имена месяцев (начиная с января).

Пример см. Локализованная ось времени II.

d3.timeFormatDefaultLocale(definition) · Источник

Эквивалентно d3.timeFormatLocale, но также переопределяет d3.timeFormat, d3.timeParse, d3.utcFormat и d3.utcParse на новые локальные locale.format, locale.parse, locale.utcFormat и locale.utcParse. Если не задана локаль по умолчанию, используется американская английская локаль.

Пример см. Локализованная ось времени.