d3-axis

Компонент оси отображает читаемые человеком метки отсчёта для шкал. Это облегчает одну из более трудоемких задач при визуализации данных.

Установка

Если вы используете npm, npm install d3-axis. Вы также можете скачать последнюю версию на GitHub. Для обычного HTML в современных браузерах импортируйте d3-axis из Skypack:

<script type="module">

import {axisLeft} from "https://cdn.skypack.dev/d3-axis@3";

const axis = axisLeft(scale);

</script>

Для устаревших сред вы можете загрузить UMD-пакет d3-axis с CDN на основе npm, такого как jsDelivr; экспортируется глобальная переменная d3:

<script src="https://cdn.jsdelivr.net/npm/d3-axis@3"></script>
<script>

const axis = d3.axisLeft(scale);

</script>

Попробуйте d3-axis в своём браузере.

Ссылка на API

Независимо от ориентации, оси всегда отображаются в начале координат. Чтобы изменить положение оси относительно диаграммы, укажите атрибут transform на содержащем элементе. Например:

d3.select("body").append("svg")
    .attr("width", 1440)
    .attr("height", 30)
  .append("g")
    .attr("transform", "translate(0,30)")
    .call(axis);

Элементы, созданные осью, считаются частью её публичного API. Вы можете применять внешние таблицы стилей или изменять сгенерированные элементы оси, чтобы настроить внешний вид оси.

Ось состоит из элемента path класса “domain”, представляющего область значений шкалы, за которым следуют преобразованные элементы g класса “tick”, представляющие каждый из делений шкалы. Каждое деление содержит элемент line для рисования линии деления и элемент text для метки деления. Например, вот типичная ось направленная вниз:

<g fill="none" font-size="10" font-family="sans-serif" text-anchor="middle">
  <path class="domain" stroke="currentColor" d="M0.5,6V0.5H880.5V6"></path>
  <g class="tick" opacity="1" transform="translate(0.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.0</text>
  </g>
  <g class="tick" opacity="1" transform="translate(176.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.2</text>
  </g>
  <g class="tick" opacity="1" transform="translate(352.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.4</text>
  </g>
  <g class="tick" opacity="1" transform="translate(528.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.6</text>
  </g>
  <g class="tick" opacity="1" transform="translate(704.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">0.8</text>
  </g>
  <g class="tick" opacity="1" transform="translate(880.5,0)">
    <line stroke="currentColor" y2="6"></line>
    <text fill="currentColor" y="9" dy="0.71em">1.0</text>
  </g>
</g>

Ориентация оси фиксирована; чтобы изменить ориентацию, удалите старую ось и создайте новую.

d3.axisTop(scale) · Source

Создаёт новый генератор оси, направленный вверх, для заданной шкалы, с пустым аргументом делений, размером деления 6 и отступом 3. В этой ориентации деления рисуются над горизонтальным элементом области значений.

d3.axisRight(scale) · Source

Создаёт новый генератор оси, направленный вправо, для заданной шкалы, с пустым аргументом делений, размером деления 6 и отступом 3. В этой ориентации деления рисуются справа от вертикального элемента области значений.

d3.axisBottom(scale) · Source

Создаёт новый генератор оси, направленный вниз, для заданной шкалы, с пустым аргументом делений, размером деления 6 и отступом 3. В этой ориентации деления рисуются под горизонтальным элементом области значений.

d3.axisLeft(scale) · Source

Создаёт новый генератор оси, направленный влево, для заданной шкалы, с пустым аргументом делений, размером деления 6 и отступом 3. В этой ориентации деления рисуются слева от вертикального элемента области значений.

axis(context) · Source

Отображает ось в заданном контексте, который может быть либо выбором контейнеров SVG (элементов SVG или G), либо соответствующим переходом.

axis.scale([scale]) · Source

Если scale указан, устанавливает шкалу и возвращает ось. Если scale не указан, возвращает текущую шкалу.

axis.ticks(arguments…) · Source
axis.ticks([count[, specifier]])
axis.ticks([interval[, specifier]])

Устанавливает аргументы, которые будут переданы в scale.ticks и scale.tickFormat при отображении оси, и возвращает генератор оси. Значение аргументов зависит от типа шкалы оси: чаще всего, аргументы представляют собой предполагаемое количество делений (или интервал времени для шкалы времени) и необязательный спецификатор формата для настройки форматирования значений делений.

Этот метод не имеет эффекта, если шкала не реализует scale.ticks, как в случае с полосными и точечными шкалами. Чтобы явно задать значения делений, используйте axis.tickValues. Чтобы явно задать форматирование делений, используйте axis.tickFormat.

Например, чтобы сгенерировать двадцать делений с форматированием с использованием префиксов СИ для линейной шкалы, скажите:

axis.ticks(20, "s");

Чтобы сгенерировать деления через каждые пятнадцать минут со шкалой времени, скажите:

axis.ticks(d3.timeMinute.every(15));

Этот метод также является удобной функцией для axis.tickArguments. Например, это:

axis.ticks(10);

Эквивалентно:

axis.tickArguments([10]);

Чтобы сгенерировать значения делений напрямую, используйте scale.ticks.

axis.tickArguments([arguments]) · Source

Если arguments указан, устанавливает аргументы, которые будут переданы в scale.ticks и scale.tickFormat при отображении оси, и возвращает генератор оси. Значение аргументов зависит от типа шкалы оси: чаще всего, аргументы представляют собой предполагаемое количество делений (или интервал времени для шкалы времени) и необязательный спецификатор формата для настройки форматирования значений делений.

Если arguments указан, этот метод не имеет эффекта, если шкала не реализует scale.ticks, как в случае с полосными и точечными шкалами. Чтобы явно задать значения делений, используйте axis.tickValues. Чтобы явно задать форматирование делений, используйте axis.tickFormat.

Если arguments не указан, возвращает текущие аргументы делений, по умолчанию пустой массив.

Например, чтобы сгенерировать двадцать делений с форматированием с использованием префиксов СИ для линейной шкалы, скажите:

axis.tickArguments([20, "s"]);

Чтобы сгенерировать деления через каждые пятнадцать минут со шкалой времени, скажите:

axis.tickArguments([d3.timeMinute.every(15)]);

См. также axis.ticks.

axis.tickValues([values]) · Source

Если указана итерируемая последовательность values, указанные значения используются для делений вместо автоматического генератора делений шкалы. Если values равно null, очищаются все ранее заданные явные значения делений и возвращается к генератору делений шкалы. Если values не указано, возвращает текущие значения делений, по умолчанию null. Например, чтобы сгенерировать деления в определённых значениях:

var xAxis = d3.axisBottom(x)
    .tickValues([1, 2, 3, 5, 8, 13, 21]);

Явные значения делений имеют приоритет над аргументами делений, заданными axis.tickArguments. Однако любые аргументы делений всё ещё будут переданы в функцию tickFormat шкалы, если формат делений не установлен.

axis.tickFormat([format]) · Source

Если format указан, устанавливает функцию форматирования делений и возвращает ось. Если format не указан, возвращает текущую функцию форматирования, по умолчанию null. Нулевой формат указывает, что должен использоваться стандартный форматировщик шкалы, который генерируется вызовом scale.tickFormat. В этом случае аргументы, указанные axis.tickArguments, также передаются в scale.tickFormat.

См. d3-format и d3-time-format для создания форматировщиков. Например, чтобы отображать целые числа с группировкой разрядов тысяч:

axis.tickFormat(d3.format(",.0f"));

Чаще всего, спецификатор формата передаётся в axis.ticks:

axis.ticks(10, ",f");

Это имеет преимущество в том, что точность формата автоматически устанавливается на основе интервала делений.

axis.tickSize([size]) · Source

Если size указан, устанавливает внутренний и внешний размер делений на указанное значение и возвращает ось. Если size не указан, возвращает текущий внутренний размер делений, по умолчанию 6.

axis.tickSizeInner([size]) · Source

Если size указан, устанавливает внутренний размер делений на указанное значение и возвращает ось. Если size не указан, возвращает текущий внутренний размер делений, по умолчанию 6. Внутренний размер делений определяет длину линий делений, смещённых от естественного положения оси.

axis.tickSizeOuter([size]) · Source

Если задано size, устанавливает размер внешних делений до заданного значения и возвращает ось. Если size не задано, возвращает текущий размер внешних делений, который по умолчанию равен 6. Размер внешних делений управляет длиной квадратных концов пути области, смещенных от собственного положения оси. Таким образом, «внешние деления» на самом деле не являются делениями, а частью пути области, и их положение определяется диапазоном соответствующей шкалы. Таким образом, внешние деления могут перекрываться с первым или последним внутренним делением. Размер внешних делений 0 подавляет квадратные концы пути области, вместо этого создавая прямую линию.

axis.tickPadding([padding]) · Source

Если задано padding, устанавливает отступ до указанного значения в пикселях и возвращает ось. Если padding не задано, возвращает текущий отступ, который по умолчанию равен 3 пикселям.

axis.offset([offset]) · Source

Если задано offset, устанавливает смещение до указанного значения в пикселях и возвращает ось. Если offset не задано, возвращает текущее смещение, которое по умолчанию равно 0 на устройствах с devicePixelRatio больше 1, и 0,5 пикселя в противном случае. Этот отступ по умолчанию обеспечивает четкие края на устройствах с низким разрешением.