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

Вики ▸ Справка по API ▸ Работа со временем ▸ Форматирование времени
English | Русский

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

# d3.time.format(specifier)

Конструирует новую функцию форматирования местного времени, используя указанный строковый спецификатор формата specifier (эквивалентна locale.timeFormat для локали по умолчанию — «U.S. English»). Строка спецификатора может содержать следующие директивы:

• «%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, для которой он равен _.

Возвращаемый объект format является одновременно объектом и функцией. Например:

var format = d3.time.format("%Y-%m-%d");
format.parse("2011-01-01"); // вернёт объект Date
format(new Date(2011, 0, 1)); // вернёт строку

# format(date)

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

var monthNameFormat = d3.time.format("%B");
var dayNameFormat = d3.time.format("%A");
monthNameFormat(new Date(2014, 4, 1));  // возвращает строку "May" (помните, что в JavaScript месяцы нумеруются с нуля, так что 4 = May)
dayNameFormat(new Date(2014, 4, 1));  // возвращает строку "Thursday"

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

time = +date; // преобразует объект Date во время в миллисекундах
date = new Date(time); // преобразует время в миллисекундах в объект Date

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

# format.parse(string)

Разбирает указанную строку string, возвращая соответствующий объект Date. Если разбор не удался, возвращает 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(formats)

Возвращает новую функцию форматирования времени с несколькими временн́ыми разрешениями по указанному массиву форматов formats. Каждый формат — это двух-элементный массив, состоящий из строки спецификатора формата (такой же, какая передаётся в конструктор 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(specifier)

Конструирует новую функцию форматирования времени UTC, используя указанный спецификатор specifier (эквивалентна locale.timeFormat.utc для локали по умолчанию — «U.S. English»). Спецификатор может содержать теже самые директивы, что и функция 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");