d3-axis

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

Установка

Если вы используете NPM, npm install d3-axis. В противном случае, скачайте последнюю версию. Вы также можете загрузить напрямую с d3js.org, как самостоятельную библиотеку standalone library или в составе D3. (Для удобства использования вам также потребуется использовать d3-scale и d3-selection, но эти зависимости необязательны.) Поддерживаются среды AMD, CommonJS и vanilla. В vanilla среде экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-axis.v2.min.js"></script>
<script>

var 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) · Исходный код

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

d3.axisRight(scale) · Исходный код

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

d3.axisBottom(scale) · Исходный код

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

d3.axisLeft(scale) · Исходный код

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

axis(context) · Исходный код

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

axis.scale([scale]) · Исходный код

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

axis.ticks(arguments…) · Исходный код
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]) · Исходный код

Если 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]) · Исходный код

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

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

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

axis.tickFormat([format]) · Исходный код

Если format указан, устанавливает функцию форматирования делений и возвращает ось. Если format не указан, возвращает текущую функцию форматирования, которая по умолчанию равна null. Значение 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]) · Исходный код

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

axis.tickSizeInner([size]) · Исходный код

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

axis.tickSizeOuter([size]) · Исходный код

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

axis.tickPadding([padding]) · Source

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

axis.offset([offset]) · Source

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