d3-shape

Визуализации обычно состоят из отдельных графических маркеров, таких как символы, дуги, линии и площади. Хотя прямоугольники столбчатой диаграммы можно достаточно просто сгенерировать напрямую с помощью SVG или Canvas, другие фигуры сложнее, например, скругленные кольцевые секторы и центрально-симметричные сплайны Catmull–Rom. Этот модуль предоставляет различные генераторы фигур для вашего удобства.

Как и в других аспектах D3, эти фигуры управляются данными: каждый генератор фигур предоставляет аксессоры, которые контролируют, как входные данные отображаются в визуальном представлении. Например, вы можете определить генератор линий для временного ряда, масштабируя поля ваших данных для соответствия диаграмме:

const line = d3.line()
    .x(d => x(d.date))
    .y(d => y(d.value));

Этот генератор линий затем может быть использован для вычисления d атрибута элемента SVG пути:

path.datum(data).attr("d", line);

Или вы можете использовать его для визуализации в контексте Canvas 2D:

line.context(context)(data);

Для более подробной информации, прочтите Представление d3-shape.

Установка

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

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

const line = d3.line();

</script>

Ссылка на API

• Дуги
• Секторы
• Линии
• Площади
• Кривые
• Настраиваемые кривые
• Связи
• Символы
• Настраиваемые типы символов
• Стопки

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

Дуги

Генератор дуг создает сектор круга или кольца, как в круговой или кольцевой диаграмме. Если разность между углами начала start и конца end (уголовой размах) больше чем τ, генератор дуг создаст полный круг или кольцо. Если меньше τ, дуги могут иметь скруглённые углы и угловой отступ. Дуги всегда центрированы в ⟨0,0⟩; используйте преобразование (см.: SVG, Canvas) для перемещения дуги в другую позицию.

См. также генератор секторов, который вычисляет необходимые углы для представления массива данных в виде круговой или кольцевой диаграммы; эти углы затем можно передать в генератор дуг.

d3.arc() · Источник

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

arc(arguments…) · Источник

Генерирует дугу для заданных аргументов. Аргументы произвольны; они просто передаются в аксессоры генератора дуг вместе с this объектом. Например, с настройками по умолчанию ожидается объект с радиусами и углами:

const arc = d3.arc();

arc({
  innerRadius: 0,
  outerRadius: 100,
  startAngle: 0,
  endAngle: Math.PI / 2
}); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

Если радиусы и углы определены как константы, вы можете сгенерировать дугу без аргументов:

const arc = d3.arc()
    .innerRadius(0)
    .outerRadius(100)
    .startAngle(0)
    .endAngle(Math.PI / 2);

arc(); // "M0,-100A100,100,0,0,1,100,0L0,0Z"

Если у генератора дуг есть контекст, то дуга визуализируется в этом контексте как последовательность вызовов методов пути, и эта функция возвращает void. В противном случае возвращается строка данных пути.

arc.centroid(arguments…) · Источник

Вычисляет середину [x, y] центральной линии дуги, которая была бы сгенерирована заданными аргументами. Аргументы произвольны; они просто передаются в аксессоры генератора дуг вместе с this объектом. Для согласованности с сгенерированной дугой аксессоры должны быть детерминированными, т.е., возвращать одинаковое значение при одинаковых аргументах. Середина определяется как (startAngle + endAngle) / 2 и (innerRadius + outerRadius) / 2. Например:

Обратите внимание, что это не геометрический центр дуги, который может находиться за пределами дуги; этот метод просто удобен для позиционирования меток.

arc.innerRadius([radius]) · Источник

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

function innerRadius(d) {
  return d.innerRadius;
}

Указание внутреннего радиуса как функции полезно для построения стопки полярных столбцов, часто в сочетании со sqrt масштабом. Чаще используется постоянный внутренний радиус для кольцевой или круговой диаграммы. Если внешний радиус меньше внутреннего, внутренний и внешний радиусы меняются местами. Отрицательное значение обрабатывается как ноль.

arc.outerRadius([radius]) · Источник

Если radius указан, устанавливает внешний радиус в указанную функцию или число и возвращает этот генератор дуг. Если radius не указан, возвращает текущий аксессор внешнего радиуса, который по умолчанию равен:

function outerRadius(d) {
  return d.outerRadius;
}

Указание внешнего радиуса как функции полезно для построения кокскома или полярной столбчатой диаграммы, часто в сочетании со sqrt масштабом. Чаще используется постоянный внешний радиус для круговой или кольцевой диаграммы. Если внешний радиус меньше внутреннего, внутренний и внешний радиусы меняются местами. Отрицательное значение обрабатывается как ноль.

arc.cornerRadius([radius]) · Источник

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

function cornerRadius() {
  return 0;
}

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

Радиус угла не может быть больше чем (outerRadius - innerRadius) / 2. Кроме того, для дуг с угловым размахом меньше π радиус угла может быть уменьшен, так как две смежные скругленные вершины пересекаются. Это происходит чаще с внутренними углами. См. анимацию углов дуги для иллюстрации.

arc.startAngle([angle]) · Источник

Если angle указан, устанавливает начальный угол в указанную функцию или число и возвращает этот генератор дуг. Если angle не указан, возвращает текущий аксессор начального угла, который по умолчанию равен:

function startAngle(d) {
  return d.startAngle;
}

Угол задаётся в радианах, с 0 в -y (12 часов) и положительные углы увеличиваются по часовой стрелке. Если |endAngle - startAngle| ≥ τ, генерируется полный круг или кольцо, а не сектор.

arc.endAngle([angle]) · Источник

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

function endAngle(d) {
  return d.endAngle;
}

Угол задаётся в радианах, с 0 в -y (12 часов) и положительные углы увеличиваются по часовой стрелке. Если |endAngle - startAngle| ≥ τ, генерируется полный круг или кольцо, а не сектор.

arc.padAngle([angle]) · Источник

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

function padAngle() {
  return d && d.padAngle;
}

Угол отступа преобразуется в фиксированное линейное расстояние между смежными дугами, определённое как padRadius * padAngle. Это расстояние вычитается равномерно из начала и конца дуги. Если дуга образует полный круг или кольцо, как при |endAngle - startAngle| ≥ τ, угол отступа игнорируется.

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

Рекомендуемый минимальный внутренний радиус при использовании отступа равен outerRadius * padAngle / sin(θ), где θ — угловой размах наименьшей дуги до применения отступа. Например, если внешний радиус составляет 200 пикселей, а угол отступа — 0,02 радиана, разумное значение θ — 0,04 радиана, и разумный внутренний радиус — 100 пикселей. См. анимацию отступа дуги для иллюстрации.

Часто угол отступа не устанавливается непосредственно на генераторе дуг, а вычисляется генератором секторов (генератор секторов), чтобы обеспечить пропорциональность площади дуг с отступом их значениям; см. сектор.padAngle. Иллюстрация приведена в анимации отступа секторов. Если вы применяете постоянный угол отступа к генератору дуг непосредственно, это приводит к непропорциональному уменьшению меньших дуг, что вносит искажения.

дуга.padRadius([радиус]) · Исходный код

Если радиус указан, устанавливает радиус отступа заданной функцией или числом и возвращает этот генератор дуг. Если радиус не указан, возвращает текущую функцию доступа к радиусу отступа, которая по умолчанию равна null, что означает, что радиус отступа должен вычисляться автоматически как sqrt(innerRadius * innerRadius + outerRadius * outerRadius). Радиус отступа определяет фиксированное линейное расстояние между смежными дугами, определяемое как padRadius * padAngle.

дуга.context([контекст]) · Исходный код

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

Сектора

Генератор секторов не создает форму напрямую, а вместо этого вычисляет необходимые углы для представления табличных данных в виде круговой или кольцевой диаграммы; эти углы затем могут быть переданы генератору дуг (генератор дуг).

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

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

сектор(данные[, аргументы…]) · Исходный код

Генерирует сектор для заданного массива данных, возвращая массив объектов, представляющих углы дуги каждого элемента данных. Любые дополнительные аргументы являются произвольными; они просто передаются в функции доступа к генератору секторов вместе с this объектом. Длина возвращаемого массива совпадает с данными, и каждый элемент i в возвращаемом массиве соответствует элементу i в входных данных. Каждый объект в возвращаемом массиве имеет следующие свойства:

• data - входной элемент данных; соответствующий элемент в массиве входных данных.
• value - числовое значение дуги (значение).
• index - нулевой индекс отсортированной дуги (индекс сортировки).
• startAngle - начальный угол дуги (начальный угол).
• endAngle - конечный угол дуги (конечный угол).
• padAngle - угол отступа дуги (угол отступа).

Эта структура предназначена для работы с функциями доступа по умолчанию генератора дуг startAngle, endAngle и padAngle. Угловые единицы произвольны, но если вы планируете использовать генератор секторов вместе с генератором дуг, вам следует задавать углы в радианах, где 0 соответствует -y (12 часов), а положительные углы — по часовой стрелке.

Для небольшого набора чисел вот как вычислить углы дуг для отображения этих данных в виде круговой диаграммы:

const data = [1, 1, 2, 3, 5, 8, 13, 21];
const arcs = d3.pie()(data);

Первая пара скобок, pie(), создает генератор секторов по умолчанию. Вторая, pie()(data), вызывает этот генератор для набора данных, возвращая массив объектов:

[
  {"data":  1, "value":  1, "index": 6, "startAngle": 6.050474740247008, "endAngle": 6.166830023713296, "padAngle": 0},
  {"data":  1, "value":  1, "index": 7, "startAngle": 6.166830023713296, "endAngle": 6.283185307179584, "padAngle": 0},
  {"data":  2, "value":  2, "index": 5, "startAngle": 5.817764173314431, "endAngle": 6.050474740247008, "padAngle": 0},
  {"data":  3, "value":  3, "index": 4, "startAngle": 5.468698322915565, "endAngle": 5.817764173314431, "padAngle": 0},
  {"data":  5, "value":  5, "index": 3, "startAngle": 4.886921905584122, "endAngle": 5.468698322915565, "padAngle": 0},
  {"data":  8, "value":  8, "index": 2, "startAngle": 3.956079637853813, "endAngle": 4.886921905584122, "padAngle": 0},
  {"data": 13, "value": 13, "index": 1, "startAngle": 2.443460952792061, "endAngle": 3.956079637853813, "padAngle": 0},
  {"data": 21, "value": 21, "index": 0, "startAngle": 0.000000000000000, "endAngle": 2.443460952792061, "padAngle": 0}
]

Обратите внимание, что возвращаемый массив находится в том же порядке, что и данные, даже если эта круговая диаграмма сортируется по убыванию значения, начиная с дуги для последнего элемента данных (значение 21) в 12 часов.

сектор.value([значение]) · Исходный код

Если значение указано, устанавливает функцию доступа к значению заданной функцией или числом и возвращает этот генератор секторов. Если значение не указано, возвращает текущую функцию доступа к значению, которая по умолчанию равна:

function value(d) {
  return d;
}

При генерации сектора функция доступа к значению вызывается для каждого элемента в массиве входных данных, принимая элемент d, индекс i, и массив data в качестве трёх аргументов. По умолчанию функция доступа к значению предполагает, что входные данные являются числами или что они могут быть преобразованы в числа с помощью valueOf. Если ваши данные не являются простыми числами, то следует указать функцию доступа, которая возвращает соответствующее числовое значение для данного элемента данных. Например:

const data = [
  {"number":  4, "name": "Locke"},
  {"number":  8, "name": "Reyes"},
  {"number": 15, "name": "Ford"},
  {"number": 16, "name": "Jarrah"},
  {"number": 23, "name": "Shephard"},
  {"number": 42, "name": "Kwon"}
];

const arcs = d3.pie()
    .value(d => d.number)
    (data);

Это аналогично преобразованию ваших данных в значения до вызова генератора секторов:

const arcs = d3.pie()(data.map(d => d.number));

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

сектор.sort([сравнение]) · Исходный код

Если сравнение указано, устанавливает компаратор данных заданной функцией и возвращает этот генератор секторов. Если сравнение не указано, возвращает текущий компаратор данных, который по умолчанию равен null. Если компаратор данных и компаратор значений равны null, дуги размещаются в исходном порядке входных данных. В противном случае данные сортируются по компаратору данных, а полученный порядок используется. Установка компаратора данных неявно устанавливает компаратор значений (компаратор значений) в null.

Функция сравнение принимает два аргумента a и b, каждый из которых является элементом из массива входных данных. Если дуга для a должна быть перед дугой для b, компаратор должен возвращать число меньше нуля; если дуга для a должна быть после дуги для b, компаратор должен возвращать число больше нуля; возвращение нуля означает, что относительный порядок a и b не определён. Например, для сортировки дуг по связанному имени:

pie.sort((a, b) => a.name.localeCompare(b.name));

Сортировка не влияет на порядок массива сгенерированных дуг (массив сгенерированных дуг), который всегда имеет тот же порядок, что и массив входных данных; она лишь влияет на вычисленные углы каждой дуги. Первая дуга начинается с начального угла, а последняя дуга заканчивается конечным углом.

сектор.sortValues([сравнение]) · Исходный код

Если сравнение указано, устанавливает компаратор значений заданной функцией и возвращает этот генератор секторов. Если сравнение не указано, возвращает текущий компаратор значений, который по умолчанию сортируется по убыванию значения. По умолчанию компаратор значений реализован как:

function compare(a, b) {
  return b - a;
}

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

Компаратор значений похож на компаратор данных (компаратор данных), за исключением того, что два аргумента a и b — это значения, полученные из массива входных данных с помощью функции доступа к значению (value accessor), а не сами элементы данных. Если дуга для a должна быть перед дугой для b, компаратор должен возвращать число меньше нуля; если дуга для a должна быть после дуги для b, компаратор должен возвращать число больше нуля; возвращение нуля означает, что относительный порядок a и b не определён. Например, чтобы отсортировать дуги по возрастанию значения:

pie.sortValues((a, b) => a - b);

Сортировка не влияет на порядок массива сгенерированных дуг, который всегда соответствует порядку входных данных; она только влияет на вычисленные углы каждой дуги. Первая дуга начинается с начального угла, а последняя дуга заканчивается конечным углом.

сектор.startAngle([угол]) · Исходный код

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

function startAngle() {
  return 0;
}

Здесь начальный угол означает общий начальный угол сектора, т.е., начальный угол первой дуги. Функция доступа к начальному углу вызывается один раз, принимая те же аргументы и this контекст, что и генератор секторов (генератор секторов). Единицы угла произвольны, но если вы планируете использовать генератор секторов вместе с генератором дуг, следует задавать угол в радианах, где 0 соответствует -y (12 часов), а положительные углы — по часовой стрелке.

сектор.endAngle([угол]) · Исходный код

Если угол указан, устанавливает общий конечный угол сектора заданной функцией или числом и возвращает этот генератор секторов. Если угол не указан, возвращает текущую функцию доступа к конечному углу, которая по умолчанию равна:

function endAngle() {
  return 2 * Math.PI;
}

Здесь конечный угол означает общий конечный угол сектора, т.е., конечный угол последней дуги. Функция доступа к конечному углу вызывается один раз, принимая те же аргументы и this контекст, что и генератор секторов (генератор секторов). Единицы угла произвольны, но если вы планируете использовать генератор секторов вместе с генератором дуг, следует задавать угол в радианах, где 0 соответствует -y (12 часов), а положительные углы — по часовой стрелке.

Значение конечного угла ограничено начальным углом ± τ, таким образом |endAngle - startAngle| ≤ τ.

сектор.padAngle([угол]) · Исходный код

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

function padAngle() {
  return 0;
}

Здесь угол отступа означает угловое расстояние между каждой смежной дугой. Общий объём отступа равен заданному углу, умноженному на количество элементов в массиве входных данных, и не более |endAngle - startAngle|; оставшееся пространство затем делится пропорционально на значение таким образом, чтобы относительная площадь каждой дуги сохранялась. См. анимацию отступа круговой диаграммы для иллюстрации. Обработчик угла отступа вызывается один раз, получая те же аргументы и this контекст, что и генератор круговой диаграммы. Единицы измерения угла произвольны, но если вы планируете использовать генератор круговой диаграммы в сочетании с генератором дуги, вы должны указать угол в радианах.

Линии

Генератор линий создаёт сплайн или ломаную линию, как в диаграмме с линиями. Линии также встречаются во многих других типах визуализации, таких как связи в иерархическом связывании рёбер.

d3.line([x][, y]) · Исходный код, Примеры

Создаёт новый генератор линий с настройками по умолчанию. Если x или y указаны, устанавливает соответствующие обработчики до указанной функции или числа и возвращает этот генератор линий.

line(data) · Исходный код, Примеры

Генерирует линию для данного массива data. В зависимости от связанной с этим генератором линий кривой, заданные входные данные могут потребовать сортировки по значению x перед передачей в генератор линий. Если у генератора линий есть контекст, то линия отрисовывается в этом контексте как последовательность вызовов методов пути, и эта функция возвращает void. В противном случае возвращается строка данных пути.

line.x([x]) · Исходный код, Примеры

Если x указан, устанавливает обработчик x до указанной функции или числа и возвращает этот генератор линий. Если x не указан, возвращает текущий обработчик x, который по умолчанию:

function x(d) {
  return d[0];
}

Когда генерируется линия, обработчик x вызывается для каждого определённого элемента в массиве входных данных, получая элемент d, индекс i, и массив data в качестве трёх аргументов. Обработчик x по умолчанию предполагает, что входные данные — это массивы из двух чисел. Если ваши данные имеют другой формат или если вы хотите преобразовать данные перед отрисовкой, вам следует указать пользовательский обработчик. Например, если x является шкалой времени, а y — линейной шкалой:

const data = [
  {date: new Date(2007, 3, 24), value: 93.24},
  {date: new Date(2007, 3, 25), value: 95.35},
  {date: new Date(2007, 3, 26), value: 98.84},
  {date: new Date(2007, 3, 27), value: 99.92},
  {date: new Date(2007, 3, 30), value: 99.80},
  {date: new Date(2007, 4,  1), value: 99.47},
  …
];

const line = d3.line()
    .x(d => x(d.date))
    .y(d => y(d.value));

line.y([y]) · Исходный код, Примеры

Если y указан, устанавливает обработчик y до указанной функции или числа и возвращает этот генератор линий. Если y не указан, возвращает текущий обработчик y, который по умолчанию:

function y(d) {
  return d[1];
}

При генерации линии обработчик y вызывается для каждого определённого элемента в массиве входных данных, получая элемент d, индекс i, и массив data в качестве трёх аргументов. Обработчик y по умолчанию предполагает, что входные данные — это массивы из двух чисел. См. line.x для получения дополнительной информации.

line.defined([defined]) · Исходный код, Примеры

Если defined указан, устанавливает обработчик определения до указанной функции или булевого значения и возвращает этот генератор линий. Если defined не указан, возвращает текущий обработчик определения, который по умолчанию:

function defined() {
  return true;
}

Таким образом, обработчик по умолчанию предполагает, что входные данные всегда определены. Когда генерируется линия, обработчик определения вызывается для каждого элемента в массиве входных данных, получая элемент d, индекс i, и массив data в качестве трёх аргументов. Если данный элемент определён (то есть, если обработчик определения возвращает истинное значение для этого элемента), обработчики x и y будут впоследствии вычислены, и точка будет добавлена к текущему отрезку линии. В противном случае элемент будет пропущен, текущий отрезок линии завершится, и для следующей определённой точки будет сгенерирован новый отрезок линии. В результате сгенерированная линия может иметь несколько отдельных отрезков. Например:

Обратите внимание, что если отрезок линии состоит только из одной точки, он может быть невидимым, если не отрисовать его с округленными или квадратными концами линий. Кроме того, некоторые кривые, такие как curveCardinalOpen, отображают видимый отрезок только в том случае, если он содержит несколько точек.

line.curve([curve]) · Исходный код, Примеры

Если curve указан, устанавливает фабрику кривых и возвращает этот генератор линий. Если curve не указан, возвращает текущую фабрику кривых, которая по умолчанию curveLinear.

line.context([context]) · Исходный код, Примеры

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

d3.lineRadial() · Исходный код, Примеры

Создаёт новый генератор радиальных линий с настройками по умолчанию. Генератор радиальных линий эквивалентен стандартному декартову генератору линий, за исключением того, что обработчики x и y заменены обработчиками angle и radius. Радиальные линии всегда позиционируются относительно ⟨0,0⟩; используйте преобразование (см.: SVG, Canvas), чтобы изменить начало отсчёта.

lineRadial(data) · Исходный код, Примеры

Эквивалентно line.

lineRadial.angle([angle]) · Исходный код, Примеры

Эквивалентно line.x, за исключением того, что обработчик возвращает угол в радианах, где 0 соответствует -y (12 часов).

lineRadial.radius([radius]) · Исходный код, Примеры

Эквивалентно line.y, за исключением того, что обработчик возвращает радиус: расстояние от начала координат ⟨0,0⟩.

lineRadial.defined([defined])

Эквивалентно line.defined.

lineRadial.curve([curve]) · Исходный код, Примеры

Эквивалентно line.curve. Обратите внимание, что curveMonotoneX или curveMonotoneY не рекомендуются для радиальных линий, поскольку они предполагают, что данные монотонны по x или y, что обычно неверно для радиальных линий.

lineRadial.context([context])

Эквивалентно line.context.

Площади

Генератор областей создаёт область, как, например, в диаграмме области. Область определяется двумя ограничивающими линиями, либо сплайнами, либо ломаными. Обычно две линии имеют одинаковые значения x (x0 = x1), отличаясь только значением y (y0 и y1); чаще всего y0 задаётся как константа, представляющая ноль. Первая линия (верхняя линия) определяется x1 и y1 и отображается первой; вторая линия (нижняя линия) определяется x0 и y0 и отображается второй, с точками в обратном порядке. При линейной кривой кривой, это создаёт многоугольник по часовой стрелке.

d3.area([x][, y0][, y1]) · Исходный код

Создаёт новый генератор областей с настройками по умолчанию. Если указаны x, y0 или y1, устанавливает соответствующие функции или числа в качестве аксессоров и возвращает этот генератор областей.

area(data) · Исходный код

Генерирует область для данного массива данных. В зависимости от связанной с этим генератором областей кривой, входные данные data могут потребовать сортировки по значению x перед передачей в генератор областей. Если у генератора областей есть контекст, то область отображается в этом контексте как последовательность вызовов методов пути, и эта функция возвращает void. В противном случае возвращается строка данных пути.

area.x([x]) · Исходный код

Если x указан, устанавливает x0 на x и x1 на null и возвращает этот генератор областей. Если x не указан, возвращает текущий аксессор x0.

area.x0([x]) · Исходный код

Если x указан, устанавливает аксессор x0 на указанную функцию или число и возвращает этот генератор областей. Если x не указан, возвращает текущий аксессор x0, который по умолчанию:

function x(d) {
  return d[0];
}

Когда область генерируется, аксессор x0 вызывается для каждого определённого элемента в массиве входных данных, принимая элемент d, индекс i, и массив data в качестве трёх аргументов. По умолчанию аксессор x0 предполагает, что входные данные являются массивами из двух элементов — чисел. Если ваши данные имеют другой формат, или если вы хотите преобразовать данные перед отрисовкой, то вам следует указать пользовательский аксессор. Например, если x является шкалой времени, а y является линейной шкалой:

const data = [
  {date: new Date(2007, 3, 24), value: 93.24},
  {date: new Date(2007, 3, 25), value: 95.35},
  {date: new Date(2007, 3, 26), value: 98.84},
  {date: new Date(2007, 3, 27), value: 99.92},
  {date: new Date(2007, 3, 30), value: 99.80},
  {date: new Date(2007, 4,  1), value: 99.47},
  …
];

const area = d3.area()
    .x(d => x(d.date))
    .y1(d => y(d.value))
    .y0(y(0));

area.x1([x]) · Исходный код

Если x указан, устанавливает аксессор x1 на указанную функцию или число и возвращает этот генератор областей. Если x не указан, возвращает текущий аксессор x1, который по умолчанию равен null, что указывает на то, что ранее вычисленное значение x0 должно быть повторно использовано для значения x1.

Когда область генерируется, аксессор x1 вызывается для каждого определённого элемента в массиве входных данных, принимая элемент d, индекс i, и массив data в качестве трёх аргументов. См. area.x0 для получения дополнительной информации.

area.y([y]) · Исходный код

Если y указан, устанавливает y0 на y и y1 на null и возвращает этот генератор областей. Если y не указан, возвращает текущий аксессор y0.

area.y0([y]) · Исходный код

Если y указан, устанавливает аксессор y0 на указанную функцию или число и возвращает этот генератор областей. Если y не указан, возвращает текущий аксессор y0, который по умолчанию:

function y() {
  return 0;
}

Когда область генерируется, аксессор y0 вызывается для каждого определённого элемента в массиве входных данных, принимая элемент d, индекс i, и массив data в качестве трёх аргументов. См. area.x0 для получения дополнительной информации.

area.y1([y]) · Исходный код

Если y указан, устанавливает аксессор y1 на указанную функцию или число и возвращает этот генератор областей. Если y не указан, возвращает текущий аксессор y1, который по умолчанию:

function y(d) {
  return d[1];
}

Также разрешён аксессор null, что указывает на то, что ранее вычисленное значение y0 должно быть повторно использовано для значения y1. Когда область генерируется, аксессор y1 вызывается для каждого определённого элемента в массиве входных данных, принимая элемент d, индекс i, и массив data в качестве трёх аргументов. См. area.x0 для получения дополнительной информации.

area.defined([defined]) · Исходный код

Если defined указан, устанавливает аксессор defined на указанную функцию или boolean и возвращает этот генератор областей. Если defined не указан, возвращает текущий аксессор defined, который по умолчанию:

function defined() {
  return true;
}

По умолчанию аксессор предполагает, что входные данные всегда определены. Когда область генерируется, аксессор defined вызывается для каждого элемента в массиве входных данных, принимая элемент d, индекс i, и массив data в качестве трёх аргументов. Если данный элемент определён (т.е., если аксессор defined возвращает истинное значение для этого элемента), аксессоры x0, x1, y0 и y1 будут затем оценены, и точка будет добавлена к текущему сегменту области. В противном случае элемент будет пропущен, текущий сегмент области будет завершён, и новый сегмент области будет сгенерирован для следующей определённой точки. В результате сгенерированная область может иметь несколько отдельных сегментов. Например:

Обратите внимание, что если сегмент области состоит только из одной точки, он может быть невидим, если не отрисовывается с закруглёнными или квадратными концами линий. Кроме того, некоторые кривые, такие как curveCardinalOpen, отображают видимый сегмент только в том случае, если он содержит несколько точек.

area.curve([curve]) · Исходный код

Если curve указан, устанавливает функцию кривой и возвращает этот генератор областей. Если curve не указан, возвращает текущую функцию кривой, которая по умолчанию равна curveLinear.

area.context([context]) · Исходный код

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

area.lineX0() · Исходный код
area.lineY0() · Исходный код

Возвращает новый генератор линий, который имеет текущий аксессор определения, кривой и контекста этого генератора областей. Аксессор x линии — это аксессор x0 области, а аксессор y линии — это аксессор y0 области.

area.lineX1() · Исходный код

Возвращает новый генератор линий, который имеет текущий аксессор определения, кривой и контекста этого генератора областей. Аксессор x линии — это аксессор x1 области, а аксессор y линии — это аксессор y0 области.

area.lineY1() · Исходный код

Возвращает новый генератор линий, который имеет текущий аксессор определения, кривой и контекста этого генератора областей. Аксессор x линии — это аксессор x0 области, а аксессор y линии — это аксессор y1 области.

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

Создаёт новый генератор радиальных областей с настройками по умолчанию. Генератор радиальных областей эквивалентен стандартному декартову генератору областей, за исключением того, что аксессоры x и y заменены аксессорами угла и радиуса. Радиальные области всегда позиционируются относительно ⟨0,0⟩; используйте преобразование (см.: SVG, Canvas), чтобы изменить начало координат.

areaRadial(data)

Эквивалентно area.

areaRadial.angle([angle]) · Исходный код

Эквивалентно area.x, за исключением того, что функция-аксессор возвращает угол в радианах, где 0 соответствует -y (12 часов).

areaRadial.startAngle([angle]) · Исходный код

Эквивалентно area.x0, за исключением того, что функция-аксессор возвращает угол в радианах, где 0 соответствует -y (12 часов). Примечание: обычно используется angle вместо задания отдельных начального и конечного углов.

areaRadial.endAngle([angle]) · Исходный код

Эквивалентно area.x1, за исключением того, что функция-аксессор возвращает угол в радианах, где 0 соответствует -y (12 часов). Примечание: обычно используется angle вместо задания отдельных начального и конечного углов.

areaRadial.radius([radius]) · Исходный код

Эквивалентно area.y, за исключением того, что функция-аксессор возвращает радиус: расстояние от начала координат ⟨0,0⟩.

areaRadial.innerRadius([radius]) · Исходный код

Эквивалентно area.y0, за исключением того, что функция-аксессор возвращает радиус: расстояние от начала координат ⟨0,0⟩.

areaRadial.outerRadius([radius]) · Исходный код

Эквивалентно area.y1, за исключением того, что функция-аксессор возвращает радиус: расстояние от начала координат ⟨0,0⟩.

areaRadial.defined([defined])

Эквивалентно area.defined.

areaRadial.curve([curve]) · Исходный код

Эквивалентно area.curve. Обратите внимание, что curveMonotoneX или curveMonotoneY не рекомендуются для радиальных областей, так как предполагают, что данные монотонны по x или y, что обычно неверно для радиальных областей.

areaRadial.context([context])

Эквивалентно line.context.

areaRadial.lineStartAngle() · Исходный код
areaRadial.lineInnerRadius() · Исходный код

Возвращает новый генератор радиальной линии d3.lineRadial, который использует текущие значения функции-аксессора defined, кривой curve и контекста context данного генератора радиальной области. Функция-аксессор угла линии — это функция-аксессор начального угла области, а функция-аксессор радиуса линии — это функция-аксессор внутреннего радиуса области.

areaRadial.lineEndAngle() · Исходный код

Возвращает новый генератор радиальной линии d3.lineRadial, который использует текущие значения функции-аксессора defined, кривой curve и контекста context данного генератора радиальной области. Функция-аксессор угла линии — это функция-аксессор конечного угла области, а функция-аксессор радиуса линии — это функция-аксессор внутреннего радиуса области.

areaRadial.lineOuterRadius() · Исходный код

Возвращает новый генератор радиальной линии d3.lineRadial, который использует текущие значения функции-аксессора defined, кривой curve и контекста context данного генератора радиальной области. Функция-аксессор угла линии — это функция-аксессор начального угла области, а функция-аксессор радиуса линии — это функция-аксессор внешнего радиуса области.

Кривые

Хотя линии определяются как последовательность двумерных точек [x, y], а области аналогично определяются верхней и нижней линиями, остается задача преобразования этого дискретного представления в непрерывную форму: т.е., как интерполировать между точками. Для этой цели предоставляется множество кривых.

Кривые обычно не создаются и не используются напрямую, а передаются в line.curve и area.curve. Например:

const line = d3.line(d => d.date, d => d.value)
    .curve(d3.curveCatmullRom.alpha(0.5));

d3.curveBasis(context) · Исходный код

Создаёт кубическую базисную сплайн-кривую с использованием указанных контрольных точек. Первая и последняя точки утроены, таким образом, сплайн начинается в первой точке и заканчивается в последней точке, и является касательной к линии между первой и второй точками, и к линии между предпоследней и последней точками.

d3.curveBasisClosed(context) · Исходный код

Создаёт замкнутую кубическую базисную сплайн-кривую с использованием указанных контрольных точек. Когда сегмент линии заканчивается, первые три контрольных точки повторяются, создавая замкнутую петлю с непрерывностью C2.

d3.curveBasisOpen(context) · Исходный код

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

d3.curveBumpX(context) · Исходный код

Создаёт кривую Безье между каждой парой точек с горизонтальными касательными в каждой точке.

d3.curveBumpY(context) · Исходный код

Создаёт кривую Безье между каждой парой точек с вертикальными касательными в каждой точке.

d3.curveBundle(context) · Исходный код

Создаёт выпрямленную кубическую базисную сплайн-кривую с использованием указанных контрольных точек, с выпрямлением сплайна в соответствии с beta кривой, по умолчанию равным 0,85. Эта кривая обычно используется в иерархическом связывании рёбер для разграничения соединений, как предложил Danny Holten в Hierarchical Edge Bundles: Visualization of Adjacency Relations in Hierarchical Data. Эта кривая не реализует curve.areaStart и curve.areaEnd; она предназначена для работы с d3.line, а не с d3.area.

bundle.beta(beta) · Исходный код

Возвращает кривую связывания со значением beta в диапазоне [0, 1], представляющим силу связывания. Если beta равно нулю, возвращается прямая линия между первой и последней точкой; если beta равно единице, возвращается стандартная кривая basis. Например:

const line = d3.line().curve(d3.curveBundle.beta(0.5));

d3.curveCardinal(context) · Исходный код

Создаёт кубическую кардинальную сплайн-кривую с использованием указанных контрольных точек, используя односторонние разности для первого и последнего сегмента. Значение по умолчанию для tension — 0.

d3.curveCardinalClosed(context) · Исходный код

Создаёт замкнутую кубическую кардинальную сплайн-кривую с использованием указанных контрольных точек. Когда сегмент линии заканчивается, первые три контрольных точки повторяются, создавая замкнутую петлю. Значение по умолчанию для tension — 0.

d3.curveCardinalOpen(context) · Исходный код

Создаёт кубическую кардинальную сплайн-кривую с использованием указанных контрольных точек. В отличие от curveCardinal, односторонние разности не используются для первого и последнего сегмента, и, следовательно, кривая начинается со второй точки и заканчивается в предпоследней точке. Значение по умолчанию для tension — 0.

cardinal.tension(tension) · Исходный код

Возвращает кривую кардинального типа с заданной натянутостью в диапазоне [0, 1]. Натянутость определяет длину касательных: натянутость равна единице, что приводит к нулевым касательным, эквивалентно curveLinear; натянутость равна нулю, что приводит к равномерной кривой Catmull–Rom. Например:

const line = d3.line().curve(d3.curveCardinal.tension(0.5));

d3.curveCatmullRom(context) · Source

Создаёт кубическую кривую Catmull–Rom, используя заданные контрольные точки и параметр альфа, по умолчанию равный 0,5, как предложено Yuksel и др. в On the Parameterization of Catmull–Rom Curves, с односторонними разностными значениями для первого и последнего отрезка.

d3.curveCatmullRomClosed(context) · Source

Создаёт замкнутую кубическую кривую Catmull–Rom, используя заданные контрольные точки и параметр альфа, по умолчанию равный 0,5, как предложено Yuksel и др. При завершении отрезка линия, первая тройка контрольных точек повторяется, образуя замкнутый контур.

d3.curveCatmullRomOpen(context) · Source

Создаёт кубическую кривую Catmull–Rom, используя заданные контрольные точки и параметр альфа, по умолчанию равный 0,5, как предложено Yuksel и др. В отличие от curveCatmullRom, односторонние разностные значения не используются для первого и последнего отрезка, и, следовательно, кривая начинается со второй точки и заканчивается на предпоследней.

catmullRom.alpha(alpha) · Source

Возвращает кубическую кривую Catmull–Rom с заданным значением альфа в диапазоне [0, 1]. Если альфа равна нулю, то создаёт равномерную кривую, эквивалентную curveCardinal с натянутостью ноль; если альфа равна единице, то создаёт хордовую кривую; если альфа равна 0,5, то создаёт центростремительную кривую. Центростремительные кривые рекомендуется использовать для предотвращения самопересечений и перехлёстов. Например:

const line = d3.line().curve(d3.curveCatmullRom.alpha(0.5));

d3.curveLinear(context) · Source

Создаёт ломаную линию, проходящую через указанные точки.

d3.curveLinearClosed(context) · Source

Создаёт замкнутую ломаную линию, проходящую через указанные точки, повторяя первую точку при окончании отрезка.

d3.curveMonotoneX(context) · Source

Создаёт кубическую кривую, которая сохраняет монотонность по y, предполагая монотонность по x, как предложено Steffene в A simple method for monotonic interpolation in one dimension: «гладкая кривая с непрерывными производными первого порядка, проходящая через любые заданные точки данных без ложных колебаний. Локальные экстремумы могут появляться только в точках сетки, заданных данными, но не между двумя смежными точками сетки.»

d3.curveMonotoneY(context) · Source

Создаёт кубическую кривую, которая сохраняет монотонность по x, предполагая монотонность по y, как предложено Steffene в A simple method for monotonic interpolation in one dimension: «гладкая кривая с непрерывными производными первого порядка, проходящая через любые заданные точки данных без ложных колебаний. Локальные экстремумы могут появляться только в точках сетки, заданных данными, но не между двумя смежными точками сетки.»

d3.curveNatural(context) · Source

Создаёт естественную кубическую сплайн-кривую с производной второго порядка сплайна, равной нулю в конечных точках.

d3.curveStep(context) · Source

Создаёт кусково-постоянную функцию (функцию со ступенчатым графиком), состоящую из чередующихся горизонтальных и вертикальных линий. Значение y изменяется в середине каждой пары смежных значений x.

d3.curveStepAfter(context) · Source

Создаёт кусково-постоянную функцию (функцию со ступенчатым графиком), состоящую из чередующихся горизонтальных и вертикальных линий. Значение y изменяется после значения x.

d3.curveStepBefore(context) · Source

Создаёт кусково-постоянную функцию (функцию со ступенчатым графиком), состоящую из чередующихся горизонтальных и вертикальных линий. Значение y изменяется до значения x.

Настраиваемые кривые

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

curve.areaStart() · Source

Указывает начало нового сегмента области. Каждый сегмент области состоит ровно из двух отрезков линии: верхнего отрезка и нижнего отрезка, причём точки нижнего отрезка перечислены в обратном порядке.

curve.areaEnd() · Source

Указывает конец текущего сегмента области.

curve.lineStart() · Source

Указывает начало нового отрезка линии. За ним могут следовать ноль или более точек.

curve.lineEnd() · Source

Указывает конец текущего отрезка линии.

curve.point(x, y) · Source

Указывает новую точку в текущем отрезке линии с заданными значениями x и y.

Ссылки

Форма связи генерирует плавную кубическую кривую Безье от точки источника к точке назначения. Касательные кривой в начале и конце являются либо вертикальными, либо горизонтальными, либо радиальными.

d3.linkVertical() · Source

Возвращает новый генератор связи с вертикальными касательными. Например, для визуализации связей в диаграмме дерева, укоренённой на верхнем краю экрана, можно использовать:

const link = d3.linkVertical()
    .x(d => d.x)
    .y(d => d.y);

d3.linkHorizontal() · Source

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

const link = d3.linkHorizontal()
    .x(d => d.y)
    .y(d => d.x);

link(arguments…) · Source

Генерирует ссылку для заданных аргументов. Аргументы являются произвольными; они просто передаются функциям доступа к генератору связи вместе с this объектом. Например, с настройками по умолчанию ожидается объект:

link({
  source: [100, 100],
  target: [300, 300]
});

link.source([source]) · Source

Если source задан, устанавливает функцию доступа к источнику и возвращает этот генератор связи. Если source не задан, возвращает текущую функцию доступа к источнику, которая по умолчанию:

function source(d) {
  return d.source;
}

link.target([target]) · Source

Если target задан, устанавливает функцию доступа к цели и возвращает этот генератор связи. Если target не задан, возвращает текущую функцию доступа к цели, которая по умолчанию:

function target(d) {
  return d.target;
}

link.x([x]) · Source

Если x задан, устанавливает функцию доступа по оси x или числовое значение и возвращает этот генератор связи. Если x не задан, возвращает текущую функцию доступа по оси x, которая по умолчанию:

function x(d) {
  return d[0];
}

link.y([y]) · Source

Если y указано, устанавливает y-аксессор в указанную функцию или число и возвращает этот генератор ссылок. Если y не указано, возвращает текущий y-аксессор, который по умолчанию:

function y(d) {
  return d[1];
}

ссылка.context([контекст]) · Исходный код

Если контекст указан, устанавливает контекст и возвращает этот генератор ссылок. Если контекст не указан, возвращает текущий контекст, который по умолчанию равен null. Если контекст не null, то сгенерированная ссылка отображается в этом контексте как последовательность вызовов методов методов пути. В противном случае возвращается строка данных пути, представляющая сгенерированную ссылку. См. также d3-path.

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

Возвращает новый генератор ссылок с радиальными касательными. Например, для визуализации ссылок в диаграмме дерева, укоренённой в центре отображения, можно сделать так:

const link = d3.linkRadial()
    .angle(d => d.x)
    .radius(d => d.y);

linkRadial.angle([угол]) · Исходный код

Эквивалентно link.x, за исключением того, что аксессор возвращает угол в радианах, где 0 находится в точке -y (12 часов).

linkRadial.radius([радиус]) · Исходный код

Эквивалентно link.y, за исключением того, что аксессор возвращает радиус: расстояние от начала координат ⟨0,0⟩.

Символы

Символы обеспечивают категориальное кодирование формы, как это обычно используется в точечных диаграммах. Символы всегда центрированы в точке ⟨0,0⟩; используйте преобразование (см.: SVG, Canvas), чтобы переместить символ в другое положение.

d3.symbol([тип][, размер]) · Исходный код, Примеры

Создаёт новый генератор символов заданного типа и размера. Если не указано, тип по умолчанию устанавливается в круг, а размер — в 64.

символ(аргументы…) · Исходный код, Примеры

Генерирует символ для заданных аргументов. Аргументы произвольные; они просто передаются в функции-акссесоры генератора символов вместе с объектом this. Например, с настройками по умолчанию, для создания круга с площадью 64 квадратных пикселя, аргументы не нужны. Если у генератора символов есть контекст, то символ отображается в этом контексте как последовательность вызовов методов методов пути, и эта функция возвращает void. В противном случае возвращается строка данных пути.

символ.type([тип]) · Исходный код, Примеры

Если тип указан, устанавливает тип символа в указанную функцию или тип символа и возвращает этот генератор символов. Если тип является функцией, аргументы генератора символов и this передаются через неё. (См. selection.attr, если вы используете d3-selection.) Если тип не указан, возвращает текущий аксессор типа символа, который по умолчанию:

function type() {
  return circle;
}

См. символы для набора встроенных типов символов. Для реализации пользовательского типа символа передайте объект, который реализует symbolType.draw.

символ.size([размер]) · Исходный код, Примеры

Если размер указан, устанавливает размер в указанную функцию или число и возвращает этот генератор символов. Если размер является функцией, аргументы генератора символов и this передаются через неё. (См. selection.attr, если вы используете d3-selection.) Если размер не указан, возвращает текущий аксессор размера, который по умолчанию:

function size() {
  return 64;
}

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

символ.context([контекст]) · Исходный код

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

d3.symbols · Исходный код, Примеры

Массив, содержащий набор всех встроенных типов символов: круг, крест, ромб, квадрат, звезда, треугольник и Y. Полезно для построения области порядковой шкалы, если вы хотите использовать кодирование формы для категориальных данных.

d3.symbolCircle · Исходный код, Примеры

Тип символа — круг.

d3.symbolCross · Исходный код, Примеры

Тип символа — греческий крест с равными по длине ветвями.

d3.symbolDiamond · Исходный код, Примеры

Тип символа — ромб.

d3.symbolSquare · Исходный код, Примеры

Тип символа — квадрат.

d3.symbolStar · Исходный код, Примеры

Тип символа — пятиконечная звезда (пентаграмма).

d3.symbolTriangle · Исходный код, Примеры

Тип символа — треугольник.

d3.symbolWye · Исходный код, Примеры

Тип символа — Y-образный.

d3.pointRadial(угол, радиус) · Исходный код, Примеры

Возвращает точку [x, y] для заданного угла в радианах, где 0 находится в точке -y (12 часов), а положительные углы идут по часовой стрелке, и заданного радиуса.

Пользовательские типы символов

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

symbolType.draw(контекст, размер)

Отображает этот тип символа в указанный контекст с указанным размером в квадратных пикселях. Контекст реализует интерфейс CanvasPathMethods. (Обратите внимание, что это подмножество интерфейса CanvasRenderingContext2D!)

Стопки

Некоторые типы форм можно накладывать друг на друга, располагая одну форму рядом с другой. Например, столбчатая диаграмма ежемесячных продаж может быть разбита на многорядную столбчатую диаграмму по категориям продукции, накладывая столбцы друг на друга по вертикали. Это эквивалентно разделению столбчатой диаграммы по порядковой размерности (например, по категории продукции) и применению цветового кодирования.

Столбчатые диаграммы могут одновременно показывать общую величину и величину по категориям; однако, как правило, сложнее сравнивать категории, так как только нижний слой стека выровнен. Поэтому тщательно выбирайте порядок стека и рассмотрите streamgraph. (См. также группированные диаграммы.)

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

d3.stack() · Source

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

stack(data[, arguments…]) · Source

Генерирует стек для данного массива data, возвращая массив, представляющий каждую серию. Любые дополнительные arguments произвольны; они просто передаются в аксессоры вместе с объектом this.

Серии определяются аксессором ключей; каждая серия i в возвращаемом массиве соответствует i-му ключу. Каждая серия — это массив точек, где каждая точка j соответствует j-му элементу в входных data. Наконец, каждая точка представлена как массив [y0, y1], где y0 — меньшее значение (базовая линия), а y1 — большее значение (верхняя линия); разница между y0 и y1 соответствует вычисленному значению для этой точки. Ключ для каждой серии доступен как series.key, а индекс — как series.index. Элемент входных данных для каждой точки доступен как point.data.

Например, рассмотрим следующую таблицу, представляющую ежемесячные продажи фруктов:

Это можно представить в JavaScript как массив объектов:

const data = [
  {month: new Date(2015, 0, 1), apples: 3840, bananas: 1920, cherries: 960, dates: 400},
  {month: new Date(2015, 1, 1), apples: 1600, bananas: 1440, cherries: 960, dates: 400},
  {month: new Date(2015, 2, 1), apples:  640, bananas:  960, cherries: 640, dates: 400},
  {month: new Date(2015, 3, 1), apples:  320, bananas:  480, cherries: 640, dates: 400}
];

Чтобы создать стек для этих данных:

const stack = d3.stack()
    .keys(["apples", "bananas", "cherries", "dates"])
    .order(d3.stackOrderNone)
    .offset(d3.stackOffsetNone);

const series = stack(data);

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

[
  [[   0, 3840], [   0, 1600], [   0,  640], [   0,  320]], // apples
  [[3840, 5760], [1600, 3040], [ 640, 1600], [ 320,  800]], // bananas
  [[5760, 6720], [3040, 4000], [1600, 2240], [ 800, 1440]], // cherries
  [[6720, 7120], [4000, 4400], [2240, 2640], [1440, 1840]], // dates
]

Затем каждая серия обычно передаётся в генератор областей для отрисовки диаграммы областей или используется для построения прямоугольников для столбчатой диаграммы.

stack.keys([keys]) · Source

Если keys задано, устанавливает аксессор ключей в указанную функцию или массив и возвращает этот генератор стека. Если keys не задано, возвращает текущий аксессор ключей, который по умолчанию равен пустому массиву. Для каждого ключа генерируется серия (слой). Ключи обычно являются строками, но могут быть произвольными значениями. Ключ серии передаётся аксессору значения вместе с каждой точкой данных для вычисления значения точки.

stack.value([value]) · Source

Если value задано, устанавливает аксессор значения в указанную функцию или число и возвращает этот генератор стека. Если value не задано, возвращает текущий аксессор значения, который по умолчанию:

function value(d, key) {
  return d[key];
}

Таким образом, по умолчанию генератор стека предполагает, что входные данные — это массив объектов, где каждый объект раскрывает именованные свойства с числовыми значениями; см. stack для примера.

stack.order([order]) · Source

Если order задано, устанавливает аксессор порядка в указанную функцию или массив и возвращает этот генератор стека. Если order не задано, возвращает текущий аксессор порядка, который по умолчанию равен stackOrderNone; это использует порядок, заданный аксессором ключа. Смотрите порядки стеков для встроенных порядков.

Если order является функцией, она получает массив сгенерированных серий и должна возвратить массив числовых индексов, представляющих порядок стека. Например, порядок по умолчанию определяется как:

function orderNone(series) {
  let n = series.length;
  const o = new Array(n);
  while (--n >= 0) o[n] = n;
  return o;
}

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

stack.offset([offset]) · Source

Если offset задано, устанавливает аксессор смещения в указанную функцию и возвращает этот генератор стека. Если offset не задано, возвращает текущий аксессор смещения, который по умолчанию равен stackOffsetNone; это использует нулевую базовую линию. Смотрите смещения стеков для встроенных смещений.

Функция смещения получает массив сгенерированных серий и массив индексов порядка; затем она отвечает за обновление нижних и верхних значений в массиве серий. Например, смещение по умолчанию определяется как:

function offsetNone(series, order) {
  if (!((n = series.length) > 1)) return;
  for (let i = 1, s0, s1 = series[order[0]], n, m = s1.length; i < n; ++i) {
    s0 = s1, s1 = series[order[i]];
    for (let j = 0; j < m; ++j) {
      s1[j][1] += s1[j][0] = s0[j][1];
    }
  }
}

Порядки стека

Порядки стека обычно не используются напрямую, но вместо этого передаются в stack.order.

d3.stackOrderAppearance(series) · Source

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

d3.stackOrderAscending(series) · Source

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

d3.stackOrderDescending(series) · Source

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

d3.stackOrderInsideOut(series) · Source

Возвращает порядок серии таким образом, что самые ранние серии (согласно максимальному значению) находятся внутри, а более поздние — снаружи. Этот порядок рекомендуется для потоковых диаграмм в сочетании со смещением волнистости. См. Stacked Graphs—Geometry & Aesthetics Брайона и Ваттенберга для получения дополнительной информации.

d3.stackOrderNone(series) · Source

Возвращает заданный порядок серии [0, 1, … n - 1], где n — количество элементов в series. Таким образом, порядок стека определяется аксессором ключа.

d3.stackOrderReverse(series) · Source

Возвращает обратный заданный порядок серии [n - 1, n - 2, … 0], где n — количество элементов в series. Таким образом, порядок стека определяется обратным аксессором ключа.

Смещения стека

Смещения стека обычно не используются напрямую, но вместо этого передаются в stack.offset.

d3.stackOffsetExpand(series, order) · Source

Применяет нулевую базовую линию и нормализует значения для каждой точки таким образом, что верхняя линия всегда равна единице.

d3.stackOffsetDiverging(series, order) · Source

Положительные значения накладываются над нулём, отрицательные значения накладываются под нулём, а нулевые значения накладываются на ноль.

d3.stackOffsetNone(series, order) · Source

Применяет нулевую базовую линию.

d3.stackOffsetSilhouette(series, order) · Source

Смещает базовую линию вниз таким образом, что центр потоковой диаграммы всегда находится на нуле.

d3.stackOffsetWiggle(series, order) · Source

Смещает базовую линию так, чтобы минимизировать взвешенную волнистость слоёв. Это смещение рекомендуется для потоковых диаграмм в сочетании с порядком внутреннего-внешнего. См. Stacked Graphs—Geometry & Aesthetics Брайона и Ваттенберга для получения дополнительной информации.