RU Фигуры SVG

Вики ▸ Справка по API ▸ SVG ▸ Фигуры SVG
English | Русский

SVG содержит некоторое количество встроенных простых фигур, вроде прямоугольников, выровненных по осям координат и окружностей. Для большей гибкости вы можете использовать элемент SVG path в сочетании с генераторами данных D3 для этого элемента (генераторами путей). Если вы хорошо знакомы с Protovis, вы обратите внимание, что генераторы путей D3 очень похожи на метки Protovis.

Генератор фигур, например, возвращаемый функцией d3.svg.arc, является одновременно объектом и функцией. Это значит, что вы можете вызвать фигуру как и любую другую функцию и в тоже время фигура имеет дополнительные методы, изменяющие её поведение. Подобно другим классам в D3, фигуры следуют шаблону цепочечных методов, по которому методы-установщики возвращают саму фигуру, что позволяет выполнять несколько сеттеров в лаконичном выражении.

Элементы SVG

Все SVG-фигуры могут быть трансформированы с помошью атрибута transform. Вы можете применить трансформацию либо непосредственно к фигуре, либо к содержащему её элементу группировки g. Таким образом, когда фигура определяется как «выровненная по осям координат», это всего лишь означает, что она выровнена по осям локальных координат; вы всё ещё можете вращать её и применять другие преобразования. Фигуры могут быть залиты и обведены через использование стилей fill и stroke (так же вы можете использовать атрибуты с теми же самыми именами, но рекомендуются стили, поскольку они совместимы с внешними стилевыми таблицами).

# svg:rect x="0" y="0" width="0" height="0" rx="0" ry="0"

Элемент rect определяет прямоугольник, выровненный по осям координат. Верхний левый угол прямоугольника позиционируется атрибутами x и y, а его размеры определяются с помощью атрибутов width и height. Прямоугольник со скруглёнными углами может быть получен путём использования необязательных атрибутов rx и ry.

# svg:circle cx="0" cy="0" r="0"

Элемент circle определяет окружность по её центру и радиусу. Центр окружности определяется атрибутами cx и cy, а радиус — атрибутом r.

# svg:ellipse cx="0" cy="0" rx="0" ry="0"

Элемент ellipse определяет эллипс выровненный по осям координат по его центру и двум радиусам. Центр эллипса определяется атрибутами cx и cy, а радиусы — атрибутами rx и ry.

# svg:line x1="0" y1="0" x2="0" y2="0"

Элемент line определяет прямой отрезок, который начинается в одной точке и заканчивается в другой. Первая точка определяется атрибутами x1 и y1, а вторая — атрибутами x2 и y2. Элемент line является популярным выбором для рисования направляющих, опорных линий, осей и засечек.

# svg:polyline points=""

Элемент polyline определяет набор соединённых прямых отрезков — ломаную. Обычно элементы polyline определяют открытые фигуры. Точки, образующие ломаную, указываются в атрибуте points. Обратите внимание: как правило, в D3 удобнее и гибче использовать генератор путей d3.svg.line в сочетании с элементом path.

# svg:polygon points=""

Элемент polygon определяет замкнутую фигуру, состоящую из набора соединённых прямых отрезков. Точки, образующие фигуру, указываются в атрибуте points. Обратите внимание: как правило, в D3 удобнее и гибче использовать генератор путей d3.svg.line в сочетании с элементом path. Линия может быть закрыта путём использования команды замкнуть-путь — «Z».

# svg:text x="0" y="0" dx="0" dy="0" text-anchor="start"

Элемент text определяет графический элемент, состоящий из текста. Текстовое содержимое текстового элемента (смотрите оператор text) определяет, какие символы будут отрисованы. Якорная позиция текстового элемента контролируется атрибутами x и y; кроме того, текст может быть сдвинут от якоря атрибутами dx и dy. Это смещение особенно удобно для контроля полей текста и его опорной линии, поскольку вы можете использовать единицы измерения «em», которые зависят от размера шрифта. Горизонтальное выравнивание текста контролируется атрибутом text-anchor. Вот несколько примеров:

<svg:text text-anchor="start">выравнивание по левому краю, опорная линия снизу</svg:text>
<svg:text text-anchor="middle">выравнивание по центру, опорная линия снизу</svg:text>
<svg:text text-anchor="end">выравнивание по правому краю, опорная линия снизу</svg:text>
<svg:text dy=".35em" text-anchor="start">выравнивание по левому краю, опорная линия посередине</svg:text>
<svg:text dy=".35em" text-anchor="middle">выравнивание по центру, опорная линия посередине</svg:text>
<svg:text dy=".35em" text-anchor="end">выравнивание по правому краю, опорная линия посередине</svg:text>
<svg:text dy=".71em" text-anchor="start">выравнивание по левому краю, опорная линия сверху</svg:text>
<svg:text dy=".71em" text-anchor="middle">выравнивание по центру, опорная линия сверху</svg:text>
<svg:text dy=".71em" text-anchor="end">выравнивание по правому краю, опорная линия сверху</svg:text>

Вполне возможно, что лучше указывать опорную линию текста используя свойства выравнивания опорной линии SVG, однако они не сильно поддерживаются браузерами. Наконец, цвет шрифта обычно указывается через стиль fill (так же вы можете использовать обводку stroke), а сам шрифт контролируется стилями font, font-family, font-size и прочими сопутствующими. Некоторые браузеры также поддерживают свойства CSS3, например text-shadow.

# svg:path d="" transform=""

Элемент path представляет контур фигуры, который можно заполнить, обвести, использовать как маску отсечения или скомбинировав эти способы. Атрибут d определяет данные пути, которые являются мини-языком команд, таким как встать-сюда (M), провести-линию-сюда (L) и замкнуть-путь (Z). Элемент path является обобщением всех других SVG-фигур и может использоваться для отрисовки практически всего, чего угодно!

Генераторы данных пути

Для упрощения конструирования атрибута d для элементов path, D3 включает в себя несколько вспомогательных класов для генерирования данных пути. Если вы хорошо знакомы с Protovis, вы обнаружите, что эти генераторы путей очень похожи на типы меток Protovis: каждый генератор является функцией от данных. Так, если ваши данные есть не что иное, как последовательность координат xy, вы можете определить функции доступа, которые генераторы путей будут использовать для производства данных пути. Например, вы можете определить генератор линий:

var line = d3.svg.line()
  .x(function(d) { return d.x; })
  .y(function(d) { return d.y; })
  .interpolate("basis");

Затем вы можете использовать полученную функцию для установки атрибута d:

g.append("path")
  .attr("d", line);

Любые данные, привязанные к g (в данном примере), будут переданы в экземпляр генератора line. Таким образом, данные должны быть массивом. Для каждого элемента в массиве вызываются функции доступа x и y для вытаскивания координат управляющей точки.

Генератор пути, например, возвращаемый функцией d3.svg.line, является одновременно объектом и функцией. Это значит, что вы можете вызвать генератор как и любую другую функцию и в тоже время он имеет дополнительные методы, изменяющие его поведение. Подобно другим классам в D3, генераторы путей следуют шаблону цепочечных методов, по которому методы-установщики возвращают сам генератор, что позволяет выполнять несколько сеттеров в лаконичном выражении.

# d3.svg.line()

Конструирует новый генератор линий с функциями доступа к координатам x и y по умолчанию (которые предполагают, что входные данные являются двух-элементным массивом чисел; смотрите ниже для подробностей) и линейной интерполяцией. Возвращённая функция генерирует данные пути для открытой части линейной кривой, или ломаной, как на линейчатой диаграмме:

Путём изменения режима интерполяции вы так же можете генерировать сплайны и шаговую функцию. Также, не бойтесь добавлять дополнительные команды в конец. Например, если вы хотите генерировать замкнутый путь, добавьте команду «замкнуть-путь» (Z):

g.append("path")
  .attr("d", function(d) { return line(d) + "Z"; });

Генератор линий спроектирован для работы в сочетании с генератором областей. Например, при создании диаграммы с областями, вы можете использовать генератор областей со стилем заполнения и генератор линий со стилем обводки для выделения верхней границы области. Поскольку генератор линий используется только для установки атрибута d, вы можете контролировать внешний вид линии, используя стандартные для SVG стили и атрибуты, такие как fill, stroke и stroke-width.

# line(data)

Возвращает строку с описанием пути для указанного массива элементов data или null, если путь пустой.

# line.x([x])

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

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

Обычно стоит указывать функцию доступа к координате x, поскольку входные данные приходят в другом формате или потому что вы хотите применить шкалу. Например, если ваши данные определены не кортежом, а как объекты с атрибутами x и y, вы можете одновременно достать эти атрибуты и применить к ним шкалу:

var x = d3.scale.linear().range([0, w]),
    y = d3.scale.linear().range([h, 0]);

var line = d3.svg.line()
  .x(function(d) { return x(d.x); })
  .y(function(d) { return y(d.y); });

Функция доступа к координате x вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция line; однако, в общем случае, когда генератор линий передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). В данном контексте индекс — это индекс в массиве контрольных точек, а не индекс текущего элемента в выборке. Функция доступа к координате x вызывается один раз для каждой привязки к данным, в порядке, определяемом массивом данных. Таким образом, возможно определить недетерминированную функцию доступа, например, генератор случайных чисел. Так же возможно определить функцию доступа к координате x как константу, а не функцию, в этом случае все точки будут иметь одинаковую координату x.

# line.y([y])

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

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

Пример определения функции доступа к координате y пожно посмотреть в описании функции доступа к координате x — действия аналогичные. Обратите внимание, что, как и многие графические библиотеки, SVG использует верхний левый угол в качестве начала координат и, таким образом, б́ольшие значения координаты y разполагаются ниже на экране. При визуализации нам чаще всего нужно, чтобы начало координат находилось в нижнем левом углу; простой способ добиться этого — инвертировать диапазон шкалы y используя range([h, 0]) вместо range([0, h]).

# line.interpolate([interpolate])

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

• linear — кусочки отрезков, как в ломаной.
• linear-closed — замкнутые прямые отрезки, образующие многоугольник.
• step — чередующиеся горизонтальные и вертикальные отрезки, как в функции step.
• step-before — чередующиеся вертикальные и горизонтальные отрезки, как в функции step.
• step-after — чередующиеся горизонтальные и вертикальные отрезки, как в функции step.
• basis — B-сплайн, с продублированными на концах контрольными точками.
• basis-open — открытый B-сплайн; может не пересекать начальную или конечную точки.
• basis-closed — закрытый B-сплайн, образует петлю.
• bundle — эквивалентен режиму basis, за исключением того, что используется параметр натяжения tension для спрямления кривой.
• cardinal — фундаментальный сплайн, с продублированными на концах контрольными точками.
• cardinal-open — открытый фундаментальный сплайн; может не пересекать начальную или конечную точки, но будет пересекать другие контрольные точки.
• cardinal-closed — закрытый фундаментальный сплайн, образует петлю.
• monotone — кубическая интерполяция сохраняющая монотонность по координате y.

Поведение некоторых режимов интерполяции может быть в дальнейшем настроено параметром натяжения.

Если параметр interpolate является функцией, то эта функция будет вызываться для преобразования массива точек в форме [​[x0, y0], [x1, y1], …] в строку данных элемента path SVG, который будет использован для отображения линии. Символ «M» в начале строки будет неявно добавлен к возвращаемой строке и не должен возвращаться. К примеру, линейнай интерполяция реализована следующим способом:

function interpolateLinear(points) {
  return points.join("L");
}

Это эквивалентно следующему коду (и эффективнее его):

function interpolateLinear(points) {
  var path = "";
  for (var i = 0; i < points.length; i++) {
    if (i) path += "L";
    path += points[i][0] + "," + points[i][1];
  }
  return path;
}

Смотрите bl.ocks.org/3310323 для других примеров пользовательской интерполяции линий.

# line.tension([tension])

Если указан параметр tension, устанавливает натяжение интерполяции фундаментального сплайна в указанное число в диапазоне [0, 1]. Если параметр tension не указан, возвращает текущее натяжение. Натяжение применяется только к режимам интерполяции фундаментальными сплайнами: cardinal, cardinal-open и cardinal-closed. Натяжение по умолчанию равно 0.7. В некотором смысле оно может быть истолковано, как длина касательной; 1 даст нулевые касательные, а 0 даст сплайн Катмулла-Рома.

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

svg.selectAll("path")
    .data([0, 0.2, 0.4, 0.6, 0.8, 1])
  .enter().append("path")
    .attr("d", function(d) { return line.tension(d)(data); });

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

# line.defined([defined])

Возвращает / устанавливает функцию доступа, определяющую, где линия определена. Если указан параметр defined, устанавливает новую функцию доступа и возвращает линию. Если параметр defined не указан, возвращает текущую функцию доступа, равную по умолчанию функции function() { return true; }. Функция доступа defined может использоваться для указания того, в каких точках линия определена, а в каких нет, обычно это полезно, когда у вас недостаёт данных; сгенерированные по данным пути автоматически разобъются на несколько отдельных подпутей, пропускающих неопределённые данные. Например, если вы хотите игнорировать значения y, не являющиеся числами (или неопределённые), вы можете написать:

line.defined(function(d) { return !isNaN(d[1]); });

# d3.svg.line.radial()

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

# line(data[, index])

Возвращает строку с описанием пути для указанного массива элементов data. Может быть указан необязательный параметр index, который будет передан в функции доступа генератора.

# line.radius([radius])

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

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

Этот метод является преобразованным декартовым методом line.x.

# line.angle([angle])

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

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

Этот метод является преобразованным декартовым методом line.y.

# d3.svg.area()

Конструирует новый генератор областей с функциями доступа по умолчанию к координатам x, y0 и y1 (которые предполагают, что входные данные являются двух-элементным массивом чисел; смотрите ниже для подробностей) и линейной интерполяцией. Возвращённая функция генерирует данные пути для открытой части линейной кривой, или ломаной, как в диаграмме с областями:

Концептуально, многоугольник формируется из двух линий: верхняя линия формируется с использованием функций доступа к координатам x и y1 и тянется слева направо; нижняя линия добавляется к этой линии с использованием функций доступа к координатам x и y0 и тянется справа налево. Путём установки атрибута transform для поворота элемента path на 90 градусов, вы так же можете генерировать вертикальные области. Путём смены режима интерполяции вы так же можете генерировать сплайны и шаговые функции.

Генератор областей спроектирован для работы в сочетании с генератором линий. Например, при создании диаграммы с областями, вы можете использовать генератор областей со стилем заполнения и генератор линий со стилем обводки для выделения верхней границы области. Поскольку генератор областей используется только для установки атрибута d, вы можете контролировать внешний вид области, используя стандартные для SVG стили и атрибуты, такие как fill.

Для создания потоковых графиков (диаграмм с областями, уложенными в стек), используйте стековую компоновку. Эта компоновка устанавливает атрибут y0 для каждого значения в сериях, который может использоваться из функций доступа к координатам y0 и y1. Обратите внимание, что серии должны иметь одинаковое количество значений и соответствующие значения в сериях должны иметь одинаковые координаты x; если у вас недостаёт данных или координаты x по сериям не совпадают, вы должны перераспределить и проинтерполировать ваши данные перед вычислением стековой компоновки.

# area(data[, index])

Возвращает строку с описанием пути для указанного массива элементов data или null, если путь пустой. Может быть указан необязательный параметр index, который будет передан в функции доступа генератора.

# area.x([x])

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

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

Обычно стоит указывать функцию доступа к координате x, поскольку входные данные приходят в другом формате или потому что вы хотите применить шкалу. Например, если ваши данные определены не кортежом, а как объекты с атрибутами x и y, вы можете одновременно достать эти атрибуты и применить к ним шкалу:

var x = d3.scale.linear().range([0, w]),
    y = d3.scale.linear().range([h, 0]);

var area = d3.svg.area()
  .x(function(d) { return x(d.x); })
  .y0(h)
  .y1(function(d) { return y(d.y); });

Функция доступа к координате x вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция area; однако, в общем случае, когда генератор областей передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). В данном контексте индекс — это индекс в массиве контрольных точек, а не индекс текущего элемента в выборке. Функция доступа к координате x вызывается один раз для каждой привязки к данным, в порядке, определяемом массивом данных. Таким образом, возможно определить недетерминированную функцию доступа, например, генератор случайных чисел. Так же возможно определить функцию доступа к координате x как константу, а не функцию, в этом случае все точки будут иметь одинаковую координату x.

# area.x0([x0])

…

# area.x1([x1])

…

# area.y([y])

…

# area.y0([y0])

Если указан параметр y0, устанавливает функцию доступа к координате y0 в указанную функцию или константу. Если параметр y0 не указан, возвращает текущую функцию доступа к координате y0. Функция доступа вызывается для каждого элемента в массиве данных, переданного в генератор областей. Функция доступа по умолчанию равна константе ноль, таким образом, используется фиксированная опорная линия в точках, где y = 0. Пример определения функции доступа к координате y0 пожно посмотреть в описании функции доступа к координате x — действия аналогичные.

# area.y1([y1])

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

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

Пример определения функции доступа к координате y1 пожно посмотреть в описании функции доступа к координате x — действия аналогичные. Обратите внимание, что, как и многие графические библиотеки, SVG использует верхний левый угол в качестве начала координат и, таким образом, б́ольшие значения координаты y разполагаются ниже на экране. При визуализации нам чаще всего нужно, чтобы начало координат находилось в нижнем левом углу; простой способ добиться этого — инвертировать диапазон шкалы y используя range([h, 0]) вместо range([0, h]).

# area.interpolate([interpolate])

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

• linear — кусочки отрезков, как в ломаной.
• step — чередующиеся горизонтальные и вертикальные отрезки, как в функции step.
• step-before — чередующиеся вертикальные и горизонтальные отрезки, как в функции step.
• step-after — чередующиеся горизонтальные и вертикальные отрезки, как в функции step.
• basis — B-сплайн, с продублированными на концах контрольными точками.
• basis-open — открытый B-сплайн; может не пересекать начальную или конечную точки.
• cardinal — фундаментальный сплайн, с продублированными на концах контрольными точками.
• cardinal-open — открытый фундаментальный сплайн; может не пересекать начальную или конечную точки, но будет пересекать другие контрольные точки.
• monotone — кубическая интерполяция сохраняющая монотонность по координате y.

Поведение некоторых режимов интерполяции может быть в дальнейшем настроено параметром натяжения. Технически, режимы интерполяции basis-closed и cardinal-closed также поддерживаются, но они имеют смысл при применении к генерированию линий, а не областей.

Если параметр interpolate является функцией, то эта функция будет вызываться для преобразования массива точек в форме [​[x0, y0], [x1, y1], …] в строку данных элемента path SVG, который будет использован для отображения области. Символ «M» в начале строки будет неявно добавлен к возвращаемой строке и не должен возвращаться. К примеру, линейнай интерполяция реализована следующим способом:

function interpolateLinear(points) {
  return points.join("L");
}

Это эквивалентно следующему коду (и эффективнее его):

function interpolateLinear(points) {
  var path = "";
  for (var i = 0; i < points.length; i++) {
    if (i) path += "L";
    path += points[i][0] + "," + points[i][1];
  }
  return path;
}

Смотрите bl.ocks.org/3310323 для других примеров пользовательской интерполяции.

# area.tension([tension])

Если указан параметр tension, устанавливает натяжение интерполяции фундаментального сплайна в указанное число в диапазоне [0, 1]. Если параметр tension не указан, возвращает текущее натяжение. Натяжение применяется только к режимам интерполяции фундаментальными сплайнами: cardinal, cardinal-open и cardinal-closed. Натяжение по умолчанию равно 0.7. В некотором смысле оно может быть истолковано, как длина касательной; 1 даст нулевые касательные, а 0 даст сплайн Катмулла-Рома. Обратите внимание, что натяжение должно быть константой, а не функцией, так как оно постоянно для всей области.

# area.defined([defined])

Возвращает / устанавливает функцию доступа, определяющую, где область определена. Если указан параметр defined, устанавливает новую функцию доступа и возвращает область. Если параметр defined не указан, возвращает текущую функцию доступа, равную по умолчанию функции function() { return true; }. Функция доступа defined может использоваться для указания того, в каких точках область определена, а в каких нет, обычно это полезно, когда у вас недостаёт данных; сгенерированные по данным пути автоматически разобъются на несколько отдельных подпутей, пропускающих неопределённые данные. Например, если вы хотите игнорировать значения y, не являющиеся числами (или неопределённые), вы можете написать:

area.defined(function(d) { return !isNaN(d[1]); });

# d3.svg.area.radial()

…

# area(data[, index])

Возвращает строку с описанием пути для указанного массива элементов data. Может быть указан необязательный параметр index, который будет передан в функции доступа генератора.

# area.radius([radius])

…

# area.innerRadius([radius])

…

# area.innerRadius([radius])

…

# area.angle([angle])

…

# area.startAngle([angle])

…

# area.endAngle([angle])

…

# d3.svg.arc()

Конструирует новый генератор колец с функциями доступа по умолчанию к внутреннему радиусу innerRadius, внешнему радиусу outerRadius, начальному углу startAngle и конечному углу endAngle (которые предполагают, что входные данные являются объектом с атрибутами с соответствующими именами; смотрите ниже для подробностей). Хотя функции доступа по умолчанию предполагают, что размеры кольца будут динамическими, очень часто требуется установить одно или более измерений в константное значение, например, внутренний радиус в ноль для круговой диаграммы. Возвращённая функция генерирует данные пути для замкнутого сплошного кольца, как в круговой или кольцевой диаграмме:

На самом деле возможны четыре формы: круг (когда внутренний радиус равен нулю, а угол раскрытия больше или равен 2π), [сектор круга](http://ru.wikipedia.org/wiki/Сектор_(геометрия\)) (когда внутренний радиус равен нулю, а угол раскрытия меньше 2π), [кольцо](http://ru.wikipedia.org/wiki/Кольцо_(геометрия\)) (когда внутренний радиус больше нуля и угол раскрытия больше или равен 2π) и сектор кольца (когда внутренний радиус больше нуля, а угол раскрытия меньше 2π).

# arc(datum[, index])

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

# arc.innerRadius([radius])

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

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

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

Функция доступа к внутреннему радиусу вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция arc; однако, в общем случае, когда генератор колец передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к внутреннему радиусу как константу, а не функцию.

# arc.outerRadius([radius])

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

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

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

Функция доступа к внешнему радиусу вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к внешнему радиусу как константу, а не функцию.

# arc.startAngle([angle])

Если указан параметр angle, устанавливает функцию доступа к начальному углу в указанную функцию или константу. Если параметр angle не указан, возвращает текущую функцию доступа. Углы указываются в радианах, хотя в SVG обычно используются градусы. Угол 0 соответствует 12 часам (отрицательная ось y) и увеличивается по часовой стрелке, повторяясь через каждые 2π радиан. Функция доступа вызывается для аргумента, переданного в генератор колец. Функция доступа по умолчанию предполагает, что входные данные являются объектом с соответствующими названиями атрибутов:

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

Для построения круговой или кольцевой диаграммы, вам нужно вычислять начальный угол каждого сектора как конечный угол предыдущего сектора. Это очень легко сделать с использованием круговой компоновки, которая очень похожа на стековую компоновку; по указанному набору входных данных круговая компоновка конструирует объекты колец с такими атрибутами startAngle и endAngle, которые вы сможете использовать с функциями доступа генератора колец по умолчанию.

Функция доступа к начальному углу вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к начальному углу как константу, а не функцию.

# arc.endAngle([angle])

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

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

Для построения круговой или кольцевой диаграммы, вам нужно вычислять конечный угол каждого сектора как смещение от начального угла. Это очень легко сделать с использованием круговой компоновки, которая очень похожа на стековую компоновку; по указанному набору входных данных круговая компоновка конструирует объекты колец с такими атрибутами startAngle и endAngle, которые вы сможете использовать с функциями доступа генератора колец по умолчанию.

Функция доступа к конечному углу вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к конечному углу как константу, а не функцию.

# arc.centroid(arguments…)

Вычисляет центр масс кольца, которое будет сгенерировано из указанных входных агрументов arguments; обычно аргументами являются текущая привязка к данным (d) и необязательный текущий индекс (i). Центр масс определяется как средняя точка в полярных координатах между внутренним и внешним радиусом и начальным и конечным углами. Функция предоставляет удобное местополжение для подписи к кольцу. Например:

arcs.append("text")
  .attr("transform", function(d) { return "translate(" + arc.centroid(d) + ")"; })
  .attr("dy", ".35em")
  .attr("text-anchor", "middle")
  .text(function(d) { return d.value; });

Кроме того, вы можете использовать атрибут transform SVG для поворота текста сообразно его позиции, хотя вам может потребоваться перевести радианы в градусы. Ещё одна возможность состоит в использовании элемента textPath для искривления подписи вдоль кольца!

# d3.svg.symbol()

Конструирует новый генератор символов с функциями доступа по умолчанию к типу type и размеру size (который не делает предположений относительно входных данных и производит окружности размером 64 квадратных пикселя; смотрите ниже для подробностей). Хотя функции доступа по умолчанию генерируют статические символы, очень часто требуется установить одну или более функций доступа в функции, например, для установки размера пропорционально количеству данных для диаграммы рассеяния. Возвращённая функция генерирует данные пути для различных символов, как в точечной диаграмме:

Обратите внимание, что символы не включают функции доступа к координатам x и y. Вместо этого вы можете использовать атрибут transform элемента path для позиционирования символов:

vis.selectAll("path")
    .data(data)
  .enter().append("path")
    .attr("transform", function(d) { return "translate(" + x(d.x) + "," + y(d.y) + ")"; })
    .attr("d", d3.svg.symbol());

В будущем, мы может быть добавим функции доятупа к координатам x и y для единообразия с генераторами линий и областей. Символ будет отцентрован по центру координат (0, 0) локальной системы координат. Также вы можете использовать встроенные в SVG базовые фигуры для производства множества из данных типов символов, хотя генератор символов D3 более полезен в сочетании с элементом path, поскольку вы можете легко изменять тип символа и его размер в зависимости от данных.

# symbol(datum[, index])

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

# symbol.type([type])

Если указан параметр type, устанавливает функцию доступа к типу символа в указанную функцию или константу. Если параметр type не указан, возвращает текущую функцию доступа. Функция доступа по умолчанию является константой «circle», а поддерживаются следующие типы:

• circle — кружок.
• cross — греческий крест или знак «плюс».
• diamond — ромб.
• square — квадрат, выровненный по осям координат.
• triangle-down — равносторонний треугольник, направленный вниз.
• triangle-up — равносторонний треугольник, направленный вверх.

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

Функция доступа к типу символа вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция symbol; однако, в общем случае, когда генератор колец передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к типу символа как константу, а не функцию.

# symbol.size([size])

Если указан параметр size, устанавливает функцию доступа к размеру символа в указанную функцию или константу. Если параметр size не указан, возвращает текущую функцию доступа. Функция доступа по умолчанию является константой 64. Функция доступа вызывается для аргумента, переданного в генератор символов. Функция доступа к размеру символа обычно задаётся функцией, если вы хотите использовать размер символа для кодирования количества данных, или константой, если вы просто хотите сделать все точки больше или меньше. Если вы хотите определять радиус вместо размера, вы должны делать это косвенно, например, используя степенную шкалу с экспонентой 2.

# d3.svg.symbolTypes

Массив поддерживаемых типов символов.

# d3.svg.chord()

Конструирует новый генератор хорд с функциями доступа по умолчанию (которые предполагают, что входные данные являются объектом с атрибутами с соответствующими именами; смотрите ниже для подробностей). Хотя функции доступа по умолчанию предполагают, что размеры хорд будут динамическими, очень часто требуется установить одно или более измерений в константное значение, например, радиус. Возвращённая функция генерирует данные пути для замкнутой фигуры, соединяющей две дуги квадратичной кривой Безье, как в хордовой диаграмме:

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

# chord(datum[, index])

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

# chord.source([source])

Если указан параметр source, устанавливает функцию доступа к источнику в указанную функцию или константу. Если параметр source не указан, возвращает текущую функцию доступа. Задачей функции доступа к источнику является вернуть объект, описывающий начальную дугу хорды. Впоследствии возвращённый объект передаётся в функции доступа radius, startAngle и endAngle. Таким образом, эти функции доступа могут использоваться как с описанием дуги-источника, так и с описанием дуги-назначения. Функция доступа по умолчанию предполагает, что входные данные являются объектом с соответствующими названиями атрибутов:

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

Функция доступа к источнику вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция chord; однако, в общем случае, когда генератор хорд передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к источнику как константу, а не функцию.

# chord.target([target])

Если указан параметр target, устанавливает функцию доступа к назначению в указанную функцию или константу. Если параметр target не указан, возвращает текущую функцию доступа. Задачей функции доступа к назначению является вернуть объект, описывающий конечную дугу хорды. Впоследствии возвращённый объект передаётся в функции доступа radius, startAngle и endAngle. Таким образом, эти функции доступа могут использоваться как с описанием дуги-источника, так и с описанием дуги-назначения. Функция доступа по умолчанию предполагает, что входные данные являются объектом с соответствующими названиями атрибутов:

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

Функция доступа к назначению вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция chord; однако, в общем случае, когда генератор хорд передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к назначению как константу, а не функцию.

# chord.radius([radius])

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

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

Функция доступа к радиусу вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущее описание источника или назначения (зависящее от текущей привязке к данным, d) и текущий индекс (i). Так же возможно определить функцию доступа к радиусу как константу, а не функцию.

# chord.startAngle([angle])

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

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

Функция доступа к начальному углу вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущее описание источника или назначения (зависящее от текущей привязке к данным, d) и текущий индекс (i). Так же возможно определить функцию доступа к начальному углу как константу, а не функцию.

# chord.endAngle([angle])

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

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

Функция доступа к конечному углу вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущее описание источника или назначения (зависящее от текущей привязке к данным, d) и текущий индекс (i). Так же возможно определить функцию доступа к конечному углу как константу, а не функцию.

# d3.svg.diagonal()

Конструирует новый генератор диагоналей с функциями доступа по умолчанию (которые предполагают, что входные данные являются объектом с атрибутами, имена которых соответствуют функциям доступа; смотрите ниже для подробностей). Возвращённая функция генерирует данные пути для кубической кривой Безье, соединяющей точки источника и назначения; касательные указываются таким образом, чтобы плавно входить и выходить из соединяемых узлов, как в диаграмме связей узлов:

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

# diagonal(datum[, index])

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

# diagonal.source([source])

Если указан параметр source, устанавливает функцию доступа к источнику в указанную функцию или константу. Если параметр source не указан, возвращает текущую функцию доступа. Задачей функции доступа к источнику является вернуть объект, описывающий начальную точку диагонали. Впоследствии возвращённый объект передаётся в функцию доступа projection. Функция доступа по умолчанию предполагает, что входные данные являются объектом с соответствующими названиями атрибутов:

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

Функция доступа к источнику вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция diagonal; однако, в общем случае, когда генератор диагоналей передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к источнику как константу, а не функцию.

# diagonal.target([target])

Если указан параметр target, устанавливает функцию доступа к назначению в указанную функцию или константу. Если параметр target не указан, возвращает текущую функцию доступа. Задачей функции доступа к назначению является вернуть объект, описывающий конечную точку диагонали. Впоследствии возвращённый объект передаётся в функцию доступа projection. Функция доступа по умолчанию предполагает, что входные данные являются объектом с соответствующими названиями атрибутов:

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

Функция доступа к назначению вызывается таким же способом, как и другие функции значения в D3. Контекст this функции привязан к текущему элементу в выборке (технически, это тот же самый контекст this, с которым вызывается функция diagonal; однако, в общем случае, когда генератор диагоналей передаётся в оператор attr, контекст this будет привязан к элементу DOM). Функция принимает два аргумента: текущую привязку к данным (d) и текущий индекс (i). Так же возможно определить функцию доступа к назначению как константу, а не функцию.

# diagonal.projection([projection])

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

function projection(d) {
  return [d.x, d.y];
}

Таким образом, функция доступа по умолчанию совместима с различными компоновками узлов D3, включая древовидную компоновку, компоновку с разделением и кластерную компоновку. Например, для создания радиальный диагоналей, при условии, что атрибут y определяет радиус в пикселях, а атрибут x — угол в градусах:

function projection(d) {
  var r = d.y, a = (d.x - 90) / 180 * Math.PI;
  return [r * Math.cos(a), r * Math.sin(a)];
}

Функция проецирования вызывается таким же способом, как и другие функции значения в D3. Функция принимает два аргумента: текущее описание точки источника или назначения (зависящее от текущих данных, d) и текущий индекс (i).

# d3.svg.diagonal.radial()

…

# diagonal(datum[, index])

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