Графические примитивы

В разделе «Кодирование» мы рассмотрели, как метод Chart.encode сопоставляет столбцы с визуальными свойствами диаграммы. Свойство mark определяет, как именно эти свойства представлены на диаграмме.

Altair поддерживает следующие базовые примитивы:

Примитив	Метод	Описание
Arc	`Chart.mark_arc`	Круговая диаграмма.
Area	`Chart.mark_area`	Диаграмма с заполненной областью.
Bar	`Chart.mark_bar`	Столбчатая диаграмма.
Circle	`Chart.mark_circle`	Диаграмма рассеяния с заполненными кругами.
Geoshape	`Chart.mark_geoshape`	Визуализация пространственных данных.
Image	`Chart.mark_image`	Диаграмма рассеяния с маркерами-изображениями.
Line	`Chart.mark_line`	Линейная диаграмма.
Point	`Chart.mark_point`	Диаграмма рассеяния с настраиваемой формой точек.
Rect	`Chart.mark_rect`	Заполненный прямоугольник, используемый для тепловых карт.
Rule	`Chart.mark_rule`	Вертикальная или горизонтальная линия на всю ось.
Square	`Chart.mark_square`	Диаграмма рассеяния с заполненными квадратами.
Text	`Chart.mark_text`	Диаграмма, в которой точки представлены текстом.
Tick	`Chart.mark_tick`	Короткая вертикальная или горизонтальная черта.
Trail	`Chart.mark_trail`	Линия с переменной толщиной.

Кроме того, есть составные примитивы:

Примитив	Метод	Описание	Пример
Boxplot	`Chart.mark_boxplot`	Диаграмма размаха.	Диаграмма размаха
Errorband	`Chart.mark_errorband`	Непрерывная полоса вокруг линии.	Линия с доверительным интервалом
Errorbar	`Chart.mark_errorbar`	Интервал погрешности вокруг точки.	Интервалы погрешностей

Удобнее всего задавать примитивы методами mark_* объекта Chart, например mark_bar. Они принимают необязательные именованные аргументы для настройки внешнего вида.

Свойства примитивов

Ниже перечислены стандартные свойства базовых примитивов. У некоторых есть дополнительные специальные свойства, описанные на их страницах.

Общие свойства

Нажмите, чтобы показать таблицу

Свойство	Тип	Описание
`aria`	anyOf(`boolean`, `ExprRef`)	Добавлять ли атрибуты ARIA для доступности; только для SVG. При `false` выходной SVG-элемент получает `aria-hidden`, и примитив исключается из дерева доступности ARIA.
`description`	anyOf(`string`, `ExprRef`)	Текстовое описание примитива для доступности ARIA; только для SVG. Если задано, определяет атрибут `aria-label`.
`style`	anyOf(`string`, array(`string`))	Строка или массив строк с именами пользовательских стилей. Стиль — именованный набор стандартных свойств примитива из конфигурации стилей. В массиве поздние стили переопределяют ранние. Свойства, явно заданные в `encoding`, переопределяют значения стиля. По умолчанию: имя примитива, например `"bar"`. Указанный стиль дополняет стандартный: `"style": "foo"` у bar использует `config.style.bar` и `config.style.foo`, причём `foo` имеет больший приоритет.
`tooltip`	anyOf(`number`, `string`, `boolean`, `TooltipContent`, `ExprRef`, `null`)	Строка подсказки при наведении или объект, определяющий её поля. При `true` или `{"content": "encoding"}` используются все поля `encoding`; при `{"content": "data"}` — все поля наведённой точки данных. При `null` или `false` подсказка отсутствует. Подробнее см. подсказки Vega-Lite. По умолчанию: `null`.
`clip`	anyOf(`boolean`, `ExprRef`)	Обрезать ли примитив по ширине и высоте содержащей его группы.
`invalid`	anyOf(`MarkInvalidDataMode`, `null`)	Режим обработки некорректных данных: `null` и `NaN` на непрерывных шкалах без заданного результата для таких значений. `"filter"` исключает некорректные значения из примитивов и шкал. Линии, области и trail соединяют допустимые точки, словно некорректных строк нет. `"break-paths-filter-domains"` разрывает пути в некорректных точках. Для примитивов без пути эквивалентен `"filter"`. Все диапазоны шкал исключают отфильтрованные точки. `"break-paths-show-domains"` разрывает пути и скрывает некорректные точки остальных примитивов. Диапазоны всех шкал включают эти точки. `"show"` или `null` показывает все точки в примитивах и диапазонах шкал. Шкала использует результат из `config.scale.invalid`; если он не задан, некорректные значения отображаются как ноль, когда он входит в шкалу, или как минимум шкалы, когда ноль не входит. `"break-paths-show-path-domains"`, используемый по умолчанию, эквивалентен `"break-paths-show-domains"` для line/area/trail и `"filter"` для остальных примитивов. Если для шкалы канала задан результат некорректных значений в `config.scale.invalid`, все её значения считаются допустимыми. Поля такого канала не фильтруются и не вызывают разрывов пути.
`order`	[null, boolean]	Для line и trail значение `null` или `false` сохраняет исходный порядок данных при построении линии.

Положение и смещение

Нажмите, чтобы показать таблицу

Свойство	Тип	Описание
`x`	anyOf(`number`, `string`, `ExprRef`)	Координата x примитива или ширина горизонтальных bar и area, если не заданы `x2` или `width`. Значение может быть числом или строкой `"width"`, обозначающей ширину диаграммы.
`x2`	anyOf(`number`, `string`, `ExprRef`)	Вторая координата x для area, bar, rect и rule с диапазоном. Значение может быть числом или строкой `"width"`, обозначающей ширину диаграммы.
`width`	anyOf(`number`, `ExprRef`, `RelativeBandSize`)	Ширина примитива: фиксированное число пикселей либо относительная доля полосы. Например, `{band: 0.5}` означает половину полосы.
`height`	anyOf(`number`, `ExprRef`, `RelativeBandSize`)	Высота примитива: фиксированное число пикселей либо относительная доля полосы. Например, `{band: 0.5}` означает половину полосы.
`y`	anyOf(`number`, `string`, `ExprRef`)	Координата y примитива или высота вертикальных bar и area, если не заданы `y2` или `height`. Значение может быть числом или строкой `"height"`, обозначающей высоту диаграммы.
`y2`	anyOf(`number`, `string`, `ExprRef`)	Вторая координата y для area, bar, rect и rule с диапазоном. Значение может быть числом или строкой `"height"`, обозначающей высоту диаграммы.
`xOffset`	anyOf(`number`, `ExprRef`)	Смещение позиции x.
`x2Offset`	anyOf(`number`, `ExprRef`)	Смещение позиции x2.
`yOffset`	anyOf(`number`, `ExprRef`)	Смещение позиции y.
`y2Offset`	anyOf(`number`, `ExprRef`)	Смещение позиции y2.

Цвет

Нажмите, чтобы показать таблицу

Свойство	Тип	Описание
`filled`	`boolean`	Использовать ли цвет примитива для заливки вместо обводки. По умолчанию: `false` для point, line, rule и geoshape с источником graticule; для остальных — `true`. Нельзя задавать в конфигурации стилей.
`color`	anyOf(`Color`, `Gradient`, `ExprRef`)	Стандартный цвет. По умолчанию: ■ `"#4682b4"`. Нельзя задавать в конфигурации стилей. Свойства `fill` и `stroke` имеют больший приоритет и переопределяют `color`.
`fill`	anyOf(`Color`, `Gradient`, `null`, `ExprRef`)	Стандартный цвет заливки; имеет больший приоритет, чем `config.color`. Значение `null` убирает заливку. По умолчанию: отсутствует.
`stroke`	anyOf(`Color`, `Gradient`, `null`, `ExprRef`)	Стандартный цвет обводки; имеет больший приоритет, чем `config.color`. Значение `null` убирает обводку. По умолчанию: отсутствует.
`blend`	anyOf(`Blend`, `ExprRef`)	Режим смешивания цвета примитива с текущим фоном. Допускается любое значение CSS `mix-blend-mode`. По умолчанию: `"source-over"`.
`opacity`	anyOf(`number`, `ExprRef`)	Общая непрозрачность в диапазоне `[0,1]`. По умолчанию: `0.7` для неагрегированных диаграмм с point, tick, circle, square или столбчатых диаграмм со слоями; иначе `1`.
`fillOpacity`	anyOf(`number`, `ExprRef`)	Непрозрачность заливки в диапазоне `[0,1]`. По умолчанию: `1`.
`strokeOpacity`	anyOf(`number`, `ExprRef`)	Непрозрачность обводки в диапазоне `[0,1]`. По умолчанию: `1`.

Стиль обводки

Нажмите, чтобы показать таблицу

Свойство	Тип	Описание
`strokeCap`	anyOf(`StrokeCap`, `ExprRef`)	Форма концов линии: `"butt"`, `"round"` или `"square"`. По умолчанию: `"butt"`.
`strokeDash`	anyOf(array(`number`), `ExprRef`)	Массив чередующихся длин штриха и промежутка для пунктирных и штриховых линий.
`strokeDashOffset`	anyOf(`number`, `ExprRef`)	Смещение в пикселях, с которого начинается рисунок штриховой линии.
`strokeJoin`	anyOf(`StrokeJoin`, `ExprRef`)	Способ соединения сегментов обводки: `"miter"`, `"round"` или `"bevel"`. По умолчанию: `"miter"`.
`strokeMiterLimit`	anyOf(`number`, `ExprRef`)	Предел острого соединения, при превышении которого оно срезается.
`strokeWidth`	anyOf(`number`, `ExprRef`)	Толщина обводки в пикселях.

Гиперссылки

Примитив может быть гиперссылкой, если задано свойство href или соответствующий канал кодирования. При заданном href свойство cursor по умолчанию равно "pointer", чтобы обозначить возможность перехода.

Нажмите, чтобы показать таблицу

Свойство	Тип	Описание
`href`	anyOf(`URI`, `ExprRef`)	URL для перехода при щелчке мышью. При заданном значении примитив действует как гиперссылка.
`cursor`	anyOf(`Cursor`, `ExprRef`)	Указатель мыши при наведении на примитив. Допускается любой тип указателя CSS.