Форматирование времени

Справочник API ▸ Время ▸ Форматирование времени

D3 включает вспомогательный модуль для парсинга и форматирования дат, моделирующий известные стандарты strptime и strftime C-библиотеки. Эти функции также доступны в модуле времени Python time.

d3.time.format(спецификатор)

Создает новый локальный форматировщик времени, используя заданный спецификатор. (Эквивалентно locale.timeFormat для локального языка по умолчанию — английский США.) Строка спецификатора может содержать следующие директивы.

• %a — сокращённое имя дня недели.
• %A — полное имя дня недели.
• %b — сокращённое имя месяца.
• %B — полное имя месяца.
• %c — дата и время, как "%a %b %e %H:%M:%S %Y".
• %d — день месяца с нулевым дополнением в виде десятичной цифры [01,31].
• %e — день месяца с пробельным дополнением в виде десятичной цифры [ 1,31]; эквивалентно %_d.
• %H — час (24-часовой формат) в виде десятичной цифры [00,23].
• %I — час (12-часовой формат) в виде десятичной цифры [01,12].
• %j — день года в виде десятичной цифры [001,366].
• %m — месяц в виде десятичной цифры [01,12].
• %M — минута в виде десятичной цифры [00,59].
• %L — миллисекунды в виде десятичной цифры [000, 999].
• %p — либо AM, либо PM.
• %S — секунда в виде десятичной цифры [00,61].
• %U — номер недели в году (воскресенье — первый день недели) в виде десятичной цифры [00,53].
• %w — день недели в виде десятичной цифры [0(воскресенье),6].
• %W — номер недели в году (понедельник — первый день недели) в виде десятичной цифры [00,53].
• %x — дата, как "%m/%d/%Y".
• %X — время, как "%H:%M:%S".
• %y — год без столетия в виде десятичной цифры [00,99].
• %Y — год со столетием в виде десятичной цифры.
• %Z — смещение часового пояса, например "-0700".
• %% — литеральный символ "%".

Для %U все дни в новом году, предшествующие первому воскресенью, считаются неделей 0. Для %W все дни в новом году, предшествующие первому понедельнику, считаются неделей 0. В некоторых реализациях strftime и strptime (как в Python) директива может включать необязательную ширину поля или точность; эта функция пока не реализована в D3, но может быть добавлена в будущем.

Для форматировщиков дат и времени, специфичных для языка, см. locale.timeFormat.

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

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

Если модификатор заполнения не указан, по умолчанию используется 0 для всех директив, за исключением %e, для которого по умолчанию используется _).

Возвращаемый формат — это и объект, и функция. Например:

var format = d3.time.format("%Y-%m-%d");
format.parse("2011-01-01"); // returns a Date
format(new Date(2011, 0, 1)); // returns a string

format(дата)

Форматирует указанную дату, возвращая соответствующую строку. Дата должна быть объектом JavaScript Date.

var monthNameFormat = d3.time.format("%B");
var dayNameFormat = d3.time.format("%A");
monthNameFormat(new Date(2014, 4, 1));  //returns string "May" (remember javascript months are zero-indexed, thus 4 = May)
dayNameFormat(new Date(2014, 4, 1));  //returns string "Thursday"

Обратите внимание, что при использовании дат вместе с количественными шкалами даты неявно приводятся к числам, представляющим количество миллисекунд с момента эпохи Unix. Для преобразования между числами и датами можно использовать следующий код:

time = +date; // convert a Date object to time in milliseconds
date = new Date(time); // convert a time in milliseconds to a Date object

Если вы предпочитаете быть явным, вы также можете использовать метод getTime объекта даты, но оператор + короче и, возможно, быстрее.

format.parse(строка)

Парсит указанную строку, возвращая соответствующий объект даты. В случае неудачи парсинга возвращает null. В отличие от парсеров дат «натурального языка» (включая встроенный парсер JavaScript parse), этот метод строгий: если указанная строка не точно соответствует связанному спецификатору формата, этот метод возвращает null. Например, если связанный формат — полная строка ISO 8601 "%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, несмотря на то, что являются допустимыми датами 8601. (Обратите внимание, что жёстко заданный «Z» здесь отличается от %Z, смещения часового пояса.) При желании вы можете использовать несколько форматов, чтобы последовательно попробовать несколько спецификаторов формата.

Спецификаторы формата %d и %e считаются эквивалентными для парсинга.

d3.time.format.multi(форматы)

Возвращает новый многоуровневый формат времени, заданный указанным массивом предикатных форматов. Каждый формат — это массив из двух элементов: строка спецификатора формата (такая, что передается в конструктор d3.time.format) и функция предиката. Для любой даты, передаваемой в возвращаемый формат времени, первая функция предиката, возвращающая true, определит, как отформатирована указанная дата. Например, формат времени по умолчанию, используемый d3.time.scale, реализован как:

var format = d3.time.format.multi([
  [".%L", function(d) { return d.getMilliseconds(); }],
  [":%S", function(d) { return d.getSeconds(); }],
  ["%I:%M", function(d) { return d.getMinutes(); }],
  ["%I %p", function(d) { return d.getHours(); }],
  ["%a %d", function(d) { return d.getDay() && d.getDate() != 1; }],
  ["%b %d", function(d) { return d.getDate() != 1; }],
  ["%B", function(d) { return d.getMonth(); }],
  ["%Y", function() { return true; }]
]);

Таким образом, если указанная дата не является целой секундой, используется формат миллисекунд (".%L"); в противном случае, если указанная дата не является целой минутой, используется формат секунд (":%S") и так далее. См. bl.ocks.org/4149176 для примера.

Метод multi доступен для любого конструктора d3.time.format. Например, d3.time.format.utc.multi возвращает многоуровневый формат UTC времени, а locale.timeFormat.multi возвращает многоуровневый формат времени для указанного языка.

d3.time.format.utc(спецификатор)

Создает новый форматировщик UTC времени, используя заданный спецификатор. (Эквивалентно locale.timeFormat.utc для локального языка по умолчанию — английский США.) Спецификатор может содержать те же директивы, что и локальный формат времени format. Внутренне этот форматировщик времени реализован с использованием методов UTC для объекта Date, таких как getUTCDate и setUTCDate вместо getDate и setDate.

d3.time.format.iso

Полный формат UTC времени ISO 8601: "%Y-%m-%dT%H:%M:%S.%LZ". Там, где доступно, этот метод будет использовать Date.toISOString для форматирования и конструктор объекта Date для парсинга строк. Если вы полагаетесь на строгую валидацию входного формата согласно ISO 8601, вы должны явно сконструировать формат времени вместо этого:

var iso = d3.time.format.utc("%Y-%m-%dT%H:%M:%S.%LZ");