API работы со временем

Средства Vega для работы с датой и временем в JavaScript. Эти методы помогают обрабатывать объекты даты и эквивалентные им временные метки Unix. Они доступны через объект верхнего уровня vega, а отдельно — через пакет vega-time. Другие вспомогательные методы описаны в справочнике API утилит.

Справочник API работы со временем

• Единицы времени
• Методы для местного времени
• Методы для времени UTC

Единицы времени

Методы поддерживают заранее определённые единицы времени. Значение отдельной единицы — одна из следующих строк:

• 'year' — год григорианского календаря.
• 'quarter' — квартал: трёхмесячный период, начинающийся в январе, апреле, июле или октябре.
• 'month' — календарный месяц (январь, февраль и т. д.).
• 'date' — день месяца (1 января, 2 января и т. д.).
• 'week' — неделя с началом в воскресенье. Дни до первого воскресенья года относятся к неделе 0; первое воскресенье начинает неделю 1, второе — неделю 2 и т. д.
• 'isoweek' — неделя по стандарту ISO 8601. Неделя начинается в понедельник, а неделя 1 содержит 4 января (или первый четверг года). Поэтому номер недели относится к недельному году её четверга, который может отличаться от календарного года первого или последнего дня недели.
• 'day' — день недели (воскресенье, понедельник и т. д.).
• 'dayofyear' — день года (1, 2, …, 365 и т. д.).
• 'hours' — час суток (00:00, 01:00 и т. д.).
• 'minutes' — минута часа (12:00, 12:01 и т. д.).
• 'seconds' — секунда минуты (12:00:00, 12:00:01 и т. д.).
• 'milliseconds' — миллисекунда секунды.

Массив из нескольких единиц задаёт нужную точность времени. Например, ['year', 'month', 'date'] учитывает год, месяц и день, но не часы, минуты или секунды. Набор ['month', 'date'] учитывает месяц и день без года; это удобно для группировки дат при изучении сезонных закономерностей.

# vega.timeUnits(units) Исходный код

Возвращает стандартизированный и отсортированный набор units. Аргумент должен быть массивом из одной или нескольких допустимых единиц времени. Возвращаемый массив содержит те же единицы в порядке убывания длительности: самая мелкая единица идёт последней, например ['year', 'month', 'date']. Метод выдаёт ошибку, если массив пуст, содержит недопустимую единицу или несовместимые единицы. В частности, 'quarter', 'month' и 'date' нельзя сочетать с 'week', 'isoweek' или 'day'; единицы 'week' и 'isoweek' также несовместимы друг с другом.

# vega.timeUnitSpecifier(units[, specifiers]) Исходный код

Возвращает строку формата времени для указанных units. Необязательный объект specifiers содержит фрагменты строк, которыми можно настроить формат. Его ключами могут быть как отдельные единицы ("year"), так и их последовательности ("year-month-date"). Сначала метод стандартизирует единицы через timeUnits, затем ищет в specifiers самую длинную подходящую последовательность, начиная с начала массива единиц. Найденные фрагменты объединяются, и возвращаемая строка очищается от пробелов по краям.

Если specifiers не задан, используются следующие значения по умолчанию:

{
  "year": "%Y ",
  "year-month": "%Y-%m ",
  "year-month-date": "%Y-%m-%d ",
  "quarter": "Q%q ",
  "month": "%b ",
  "date": "%d ",
  "week": "W%U ",
  "isoweek": "W%V ",
  "year-isoweek": "%G W%V ",
  "day": "%a ",
  "hours": "%H:00",
  "hours-minutes": "%H:%M",
  "minutes": "00:%M",
  "seconds": ":%S",
  "milliseconds": ".%L"
}

Если specifiers задан, его значения объединяются с указанными выше. Для полного управления форматом может потребоваться переопределить составные ключи "year-month", "year-month-date" и "hours-minutes" вместе с ключами отдельных единиц. Значение null в объекте specifiers отключает соответствующее значение по умолчанию.

# vega.timeBin(options) Исходный код

Определяет схему разбиения времени на интервалы, например для гистограммы. Метод перебирает возможные сочетания единиц времени с учётом ограничений, таких как максимальное число интервалов. Он возвращает объект со свойствами units и step, которые затем можно передать методам timeFloor или utcFloor.

Поддерживаются следующие свойства объекта options:

• extent (обязательно): массив из двух элементов [min, max], задающий диапазон дат для интервалов.
• maxbins: максимальное допустимое число интервалов (по умолчанию 40). Фактическое число часто меньше, поскольку границы округляются до удобных значений.

Методы для местного времени

# vega.timeFormat([specifier]) Исходный код

Возвращает функцию, которая принимает дату или временную метку и выдаёт форматированную строку в местном часовом поясе. Если specifier — строка формата, она должна соответствовать синтаксису d3-time-format. В этом случае метод эквивалентен timeFormat из d3-time-format.

Если specifier — объект, создаётся функция с несколькими форматами. Она выбирает формат по точности входной даты: значения на границе года, месяца, дня и других единиц можно выводить по-разному. Ключами объекта должны быть допустимые строки единиц времени. Если specifier не задан, возвращается функция с форматами по умолчанию, эквивалентная следующему объекту:

{
  "year": "%Y",
  "quarter": "%B",
  "month": "%B",
  "week": "%b %d",
  "date": "%a %d",
  "hours": "%I %p",
  "minutes": "%I:%M",
  "seconds": ":%S",
  "milliseconds": ".%L"
}

Если в объекте specifier нет одного из ключей, используется его значение по умолчанию. Для этого метода единицы "date" и "day" взаимозаменяемы; если указаны обе, приоритет имеет "date".

# vega.timeFloor(units[, step]) Исходный код

Возвращает функцию, которая округляет входные даты вниз до указанных units в местном часовом поясе. Аргумент units должен быть массивом допустимых единиц времени, например ['year', 'month'] или ['week', 'date']. Необязательный step (по умолчанию 1) задаёт шаг по самой мелкой из указанных единиц. Например, timeFloor(['quarter']) эквивалентен timeFloor(['month'], 3).

# vega.timeInterval(unit) Исходный код

Возвращает интервал d3-time для заданной единицы unit в местном часовом поясе.

# vega.timeOffset(unit, date[, step]) Исходный код

Возвращает новый объект Date, полученный сдвигом date на указанную единицу unit в местном часовом поясе. Необязательный step задаёт число шагов сдвига (по умолчанию 1).

# vega.timeSequence(unit, start, stop[, step]) Исходный код

Возвращает массив объектов Date от start включительно до stop не включительно. Соседние элементы разделены единицей unit в местном часовом поясе. Необязательный step задаёт число единиц между элементами (по умолчанию 1).

# vega.dayofyear(date) Исходный код

Возвращает номер дня года для date, начиная с 1. Аргумент должен быть объектом Date или временной меткой.

# vega.week(date) Исходный код

Возвращает номер недели года для date, заданной объектом Date или временной меткой. Неделя начинается в воскресенье. Дни до первого воскресенья года относятся к неделе 0; первое воскресенье начинает неделю 1, второе — неделю 2 и т. д.

# vega.isoweek(date) Исходный код

Возвращает номер недели по ISO 8601 для date, заданной объектом Date или временной меткой. Неделя начинается в понедельник, а неделя 1 содержит 4 января. Результат находится между 1 и 53 и относится к недельному, а не обязательно к календарному году.

Методы для времени UTC

# vega.utcFormat([specifier]) Исходный код

Возвращает функцию, которая принимает дату или временную метку и выдаёт форматированную строку по всемирному координированному времени (UTC). Если specifier — строка формата, она должна соответствовать синтаксису d3-time-format. В этом случае метод эквивалентен utcFormat из d3-time-format.

Метод также принимает объект specifier для создания функции с несколькими форматами. Без аргументов возвращается такая функция с настройками по умолчанию. Подробности см. в описании метода timeFormat.

# vega.utcFloor(units[, step]) Исходный код

Возвращает функцию, которая округляет входные даты вниз до указанных units по времени UTC. Аргумент units должен быть массивом допустимых единиц времени, например ['year', 'month'] или ['week', 'date']. Необязательный step (по умолчанию 1) задаёт шаг по самой мелкой из указанных единиц. Например, utcFloor(['quarter']) эквивалентен utcFloor(['month'], 3).

# vega.utcInterval(unit) Исходный код

Возвращает интервал d3-time для заданной единицы unit по времени UTC.

# vega.utcOffset(unit, date[, step]) Исходный код

Возвращает новый объект Date, полученный сдвигом date на указанную единицу unit по времени UTC. Необязательный step задаёт число шагов сдвига (по умолчанию 1).

# vega.utcSequence(unit, start, stop[, step]) Исходный код

Возвращает массив объектов Date от start включительно до stop не включительно. Соседние элементы разделены единицей unit по времени UTC. Необязательный step задаёт число единиц между элементами (по умолчанию 1).

# vega.utcweek(date) Исходный код

Возвращает номер недели года по времени UTC для date, заданной объектом Date или временной меткой. Неделя начинается в воскресенье. Дни до первого воскресенья года относятся к неделе 0; первое воскресенье начинает неделю 1, второе — неделю 2 и т. д.

# vega.utcisoweek(date) Исходный код

Возвращает номер недели по ISO 8601 и времени UTC для date, заданной объектом Date или временной меткой. Неделя начинается в понедельник, а неделя 1 содержит 4 января. Результат находится между 1 и 53 и относится к недельному, а не обязательно к календарному году.