Масштабы времени

Справочник API ▸ Время ▸ Масштабы времени

Масштаб времени D3 — это расширение d3.scale.linear, использующее объекты JavaScript Date для представления области. Таким образом, в отличие от обычного линейного масштаба, значения области приводятся к датам, а не к числам; аналогично, функция invert возвращает дату. Самое удобное, что масштаб времени также предоставляет подходящие разметки, основанные на интервалах времени, устраняя необходимость в генерации осей для практически любой области, связанной со временем.

Объект масштаба, такой как тот, что возвращается d3.time.scale, является одновременно объектом и функцией. То есть: вы можете вызвать масштаб как любую другую функцию, и масштаб имеет дополнительные методы, которые изменяют его поведение. Как и другие классы в D3, масштабы следуют шаблону цепочки вызовов методов, где методы-сеттеры возвращают сам масштаб, что позволяет вызывать несколько сеттеров в одном компактном операторе.

d3.time.scale()

Создаёт новый масштаб времени с заданными по умолчанию областью и диапазоном; разметки и формат разметки настроены для местного времени.

d3.time.scale.utc()

Создаёт новый масштаб времени с заданными по умолчанию областью и диапазоном; разметки и формат разметки настроены для времени UTC.

scale(x)

Принимая дату x из области ввода, возвращает соответствующее значение в выходном диапазоне.

scale.invert(y)

Возвращает дату в области ввода x для соответствующего значения в выходном диапазоне y. Это представляет обратное отображение от диапазона к области. Для допустимого значения y в выходном диапазоне, scale(scale.invert(y)) равно y; аналогично, для допустимой даты x в области ввода, scale.invert(scale(x)) равно x. Оператор invert особенно полезен для взаимодействия, например, для определения даты в области ввода, соответствующей местоположению пикселя под курсором мыши.

scale.domain([dates])

Если dates указаны, задаёт область ввода масштаба заданным массивом дат. Массив должен содержать две или более даты. Если элементы в заданном массиве не являются датами, они будут приведены к датам; это приведение происходит аналогично при вызове масштаба. Если dates не указаны, возвращает текущую область ввода масштаба. Хотя масштабы времени обычно содержат только две даты в своей области, вы можете указать более двух дат для полилинейного масштаба. В этом случае должно быть эквивалентное количество значений в выходном диапазоне.

scale.nice([interval[, step]])
scale.nice([count])

Расширяет область, чтобы она начиналась и заканчивалась на удобных значениях, определяемых указанным интервалом interval и необязательным количеством step. В качестве альтернативы указанию явного интервала времени, можно указать числовое count, и интервал времени будет выбран автоматически, в соответствии с scale.ticks. Если count не указан, он по умолчанию равен 10.

Этот метод обычно расширяет область масштаба, и может только расширять границы до ближайшего удобного значения. Удобная область полезна, если область вычисляется из данных и может быть нерегулярной. Например, для области [2009-07-13T00:02, 2009-07-13T23:48] удобная область — [2009-07-13, 2009-07-14]. Если область содержит более двух значений, приведение к удобной области влияет только на первое и последнее значение.

scale.range([values])

Если values указаны, задаёт выходной диапазон масштаба заданным массивом значений. Массив должен содержать две или более значений, соответствуя количеству элементов в области ввода. Элементы в заданном массиве не должны быть числами; любое значение, поддерживаемое базовым интерполятором, будет работать. Однако числовые диапазоны необходимы для оператора invert.

Если values не указаны, возвращает текущий выходной диапазон масштаба.

scale.rangeRound([values])

Задает выходной диапазон масштаба заданным массивом значений, одновременно устанавливая интерполятор масштаба в d3.interpolateRound. Это удобная процедура, когда значения, выводимые масштабом, должны быть точными целыми числами, например, для предотвращения артефактов размытия. Также можно округлять выходные значения вручную после применения масштаба.

scale.interpolate([factory])

Если factory указан, устанавливает интерполятор масштаба, используя указанный factory. По умолчанию интерполятор-фабрика — d3.interpolate, и используется для сопоставления нормированного параметра области t в [0,1] с соответствующим значением в выходном диапазоне. Фабрика интерполятора будет использоваться для построения интерполяторов для каждой пары смежных значений из выходного диапазона. Если factory не указан, возвращает фабрику интерполятора масштаба.

scale.clamp([boolean])

Если boolean указан, включить или выключить привязку соответственно. По умолчанию привязка отключена, так что если значение, выходящее за пределы области ввода, передается в масштаб, масштаб может вернуть значение, выходящее за пределы выходного диапазона, через линейную экстраполяцию. Например, с областью и диапазоном по умолчанию [0,1], входное значение 2 вернёт выходное значение 2. При включении привязки нормированный параметр области t привязывается к диапазону [0,1], так что возвращаемое значение масштаба всегда находится в выходном диапазоне масштаба. Если boolean не указан, возвращает, включена или выключена привязка значений к выходному диапазону.

scale.ticks([interval[, step]])
scale.ticks([count])

Возвращает представительные даты из области ввода масштаба. Возвращаемые метки — даты с равномерным распределением (модуль нерегулярных интервалов времени, таких как месяцы и високосные годы), имеют удобочитаемые значения (такие как полночь) и гарантированно находятся в пределах области ввода. Разметки часто используются для отображения справочных линий или отметок в сочетании с визуализируемыми данными.

Если count — число, то будет возвращено приблизительно count меток. Если count не указан, он по умолчанию равен 10. Указанное count — только подсказка; масштаб может вернуть больше или меньше значений в зависимости от области ввода. Если указан интервал interval, то будет использована функция диапазона интервала времени range, которой передаётся необязательный аргумент step, если таковой имеется. Например, для создания десяти меток по умолчанию, можно сказать:

scale.ticks(10);

А для создания меток с интервалом в 15 минут, можно сказать:

scale.ticks(d3.time.minute, 15);

Примечание: для масштабов UTC необходимо использовать соответствующий метод диапазона UTC (например, d3.time.minute.utc).

Для автоматического выбора меток рассматриваются следующие интервалы времени:

• 1, 5, 15 и 30 секунд.
• 1, 5, 15 и 30 минут.
• 1, 3, 6 и 12 часов.
• 1 и 2 дня.
• 1 неделя.
• 1 и 3 месяца.
• 1 год.

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

scale.tickFormat()

Возвращает функцию формата времени, подходящую для отображения значения метки. Вы не обязаны использовать встроенный формат разметки масштаба, но он автоматически вычисляет подходящий формат отображения на основе даты.

Рассматриваются следующие форматы времени:

• %Y — для границ года, например, "2011".
• %B — для границ месяца, например, "Февраль".
• %b %d — для границ недели, например, "Фев 06".
• %a %d — для границ дня, например, "Пн 07".
• %I %p — для границ часа, например, "01 AM".
• %I:%M — для границ минуты, например, "01:23".
• :%S — для границ секунды, например, ":45".
• .%L — миллисекунды для всех остальных моментов времени, например, ".012".

Используя многомасштабные форматы времени, стандартный формат разметки предоставляет как локальный, так и глобальный контекст для каждого интервала времени. Например, показав последовательность [23:00, Пн 07, 01:00], форматировщик меток показывает информацию об часах, датах и дне одновременно — а не только о часах. Если вам нужен одномасштабный формат времени, вы всегда можете использовать свой собственный d3.time.format. Вы также можете разработать свой собственный специальный многомасштабный формат времени.

scale.copy()

Возвращает точную копию этого масштаба времени. Изменения в этом масштабе не повлияют на возвращённый масштаб, и наоборот.