d3-time-format

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

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

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

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

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

var 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. В противном случае, скачайте последнюю версию. Вы также можете загрузить его напрямую с d3js.org, как отдельную библиотеку или как часть D3. Поддерживаются AMD, CommonJS и обычные среды. В обычных средах экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-time.v2.min.js"></script>
<script src="https://d3js.org/d3-time-format.v3.min.js"></script>
<script>

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

</script>

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

d3.json("https://cdn.jsdelivr.net/npm/d3-time-format@3/locale/ru-RU.json", function(error, locale) {
  if (error) throw error;

  d3.timeFormatDefaultLocale(locale);

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

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

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

d3.timeFormat(specifier) · Источник

Псевдоним для locale.format по умолчанию локализаций.

d3.timeParse(specifier) · Источник

Псевдоним для locale.parse по умолчанию локализаций.

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

Псевдоним для locale.utcFormat по умолчанию локализаций.

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

Псевдоним для locale.utcParse по умолчанию локализаций.

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

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

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

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

var 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 week date (%V), которая использует более сложное определение!

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

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

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

• 0 - заполнение нулями
• _ - заполнение пробелами
• - - отключение заполнения

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

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

var 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. Если вы не зададите локаль по умолчанию, она будет по умолчанию на английском языке (США).

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