标记#

我们在编码中了解到，encode() 方法用于将列映射到图的视觉属性。mark 属性则指定这些属性应如何在图上精确表示。

Altair 支持以下基本标记类型

标记

方法

描述

弧形

mark_arc()

饼图。

面积

mark_area()

填充面积图。

条形图

mark_bar()

条形图。

圆形

mark_circle()

带有填充圆形的散点图。

地理形状

mark_geoshape()

包含空间数据的可视化

图像

mark_image()

带有图像标记的散点图。

折线

mark_line()

折线图。

点

mark_point()

带有可配置点形状的散点图。

矩形

mark_rect()

填充矩形，用于热力图

规则线

mark_rule()

跨轴的垂直或水平线。

正方形

mark_square()

带有填充正方形的散点图。

文本

mark_text()

点由文本表示的散点图。

刻度线

mark_tick()

垂直或水平刻度线。

轨迹线

mark_trail()

宽度可变的折线。

此外，Altair 还提供以下复合标记

标记名称

方法

描述

示例

箱线图

mark_boxplot()

箱线图。

带最小/最大须线的箱线图

误差带

mark_errorband()

线周围的连续带。

带置信区间带的折线图

误差条

mark_errorbar()

点周围的误差条。

带置信区间的误差条

在 Altair 中，最方便指定标记的方法是使用 Chart 对象的 mark_* 方法（例如 mark_bar），这些方法接受可选的关键字参数来配置标记的外观。

标记属性#

本节列出了基本标记类型的标准标记属性。此外，某些标记可能具有特殊的标记属性（在其文档页面中列出）。

通用标记属性#

点击显示表格

属性

类型

描述

aria

anyOf(boolean, ExprRef)

一个布尔标志，指示是否应包含 ARIA 属性 <https://mdn.org.cn/en-US/docs/Web/Accessibility/ARIA>__（仅限 SVG 输出）。如果为 false，则会在输出 SVG 元素上设置“aria-hidden”属性，从而将标记项从 ARIA 可访问性树中移除。

description

anyOf(string, ExprRef)

标记项的文本描述，用于 ARIA 可访问性 <https://mdn.org.cn/en-US/docs/Web/Accessibility/ARIA>__（仅限 SVG 输出）。如果指定，此属性将决定 "aria-label" 属性 <https://mdn.org.cn/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute>__。

style

anyOf(string, array(string))

一个字符串或字符串数组，指示要应用于标记的自定义样式的名称。样式是在 style configuration <https://vega.github.io/vega-lite/docs/mark.html#style-config>__ 中定义的标记属性默认值的命名集合。如果 style 是一个数组，后面的样式将覆盖前面的样式。在 encoding 中明确定义的任何 mark properties <https://vega.github.io/vega-lite/docs/encoding.html#mark-prop>__ 将覆盖样式默认值。

默认值：标记的名称。例如，条形标记默认具有样式 "bar"。注意：任何指定的样式都会增强默认样式。例如，带有 "style": "foo" 的条形标记将同时应用 config.style.bar 和 config.style.foo 中的设置（指定的样式 "foo" 具有更高的优先级）。

tooltip

anyOf(number, string, boolean, TooltipContent, ExprRef, null)

鼠标悬停时显示的工具提示文本字符串，或定义工具提示应从哪些字段派生的对象。

  • 如果 tooltip 为 true 或 {"content": "encoding"}，则将使用 encoding 中的所有字段。

  • 如果 tooltip 为 {"content": "data"}，则将使用突出显示的数据点中出现的所有字段。

  • 如果设置为 null 或 false，则不会使用工具提示。

有关 Vega-Lite 中工具提示的详细讨论，请参阅 tooltip <https://vega.github.io/vega-lite/docs/tooltip.html>__ 文档。

默认值： null

clip

anyOf(boolean, ExprRef)

标记是否应被剪裁到包含组的宽度和高度。

invalid

anyOf(MarkInvalidDataMode, null)

无效数据模式，定义标记和相应的比例尺应如何表示无效值（连续比例尺中没有定义无效值输出的 null 和 NaN）。

  • "filter" — 从可视化效果的标记和比例尺中排除所有无效值。对于路径标记（折线、面积、轨迹），此选项将创建连接有效点的路径，就好像具有无效值的数据行不存在一样。

  • "break-paths-filter-domains" — 在无效值处断开路径标记（折线、面积、轨迹）。对于非路径标记，这等同于 "filter"。所有比例尺域将排除这些过滤后的数据点。

  • "break-paths-show-domains" — 在无效值处断开路径（折线、面积、轨迹）。对非路径标记隐藏无效值。所有比例尺域都将包含这些过滤后的数据点（包括路径和非路径标记）。

  • "show" 或 null — 显示标记和比例尺域中的所有数据点。每个比例尺将使用 config.scale.invalid 中定义的无效值输出，如果未指定，则默认情况下无效值将产生与零（如果比例尺包含零）或最小值（如果比例尺不包含零）相同的视觉值。

  • "break-paths-show-path-domains"（默认）— 对于基于路径的标记（折线/面积/轨迹），这等同于 "break-paths-show-domains"，对于非路径标记，则等同于 "filter"。

注意：如果任何通道的比例尺在 config.scale.invalid 中定义了无效值的输出，则比例尺的所有值都将被视为“有效”，因为它们可以为比例尺产生合理的输出。因此，这些通道的字段不会被过滤，也不会导致路径断开。

order

[null, boolean]

对于折线和轨迹标记，此 order 属性可以设置为 null 或 false，使线条使用数据源中的原始顺序。

位置和偏移属性#

点击显示表格

属性

类型

描述

x

anyOf(number, string, ExprRef)

标记的 X 坐标，或未指定 x2 或 width 的水平 "bar" 和 "area" 的宽度。

此通道的 value 可以是一个数字或字符串 "width"，用于表示图的宽度。

x2

anyOf(number, string, ExprRef)

用于范围型 "area"、"bar"、"rect" 和 "rule" 的 X2 坐标。

此通道的 value 可以是一个数字或字符串 "width"，用于表示图的宽度。

width

anyOf(number, ExprRef, RelativeBandSize)

标记的宽度。以下之一：

  • 表示固定像素宽度的数字。

  • 相对带大小定义。例如，{band: 0.5} 表示带的一半。

height

anyOf(number, ExprRef, RelativeBandSize)

标记的高度。以下之一：

  • 表示固定像素高度的数字。

  • 相对带大小定义。例如，{band: 0.5} 表示带的一半

y

anyOf(number, string, ExprRef)

标记的 Y 坐标，或未指定 y2 或 height 的垂直 "bar" 和 "area" 的高度。

此通道的 value 可以是一个数字或字符串 "height"，用于表示图的高度。

y2

anyOf(number, string, ExprRef)

用于范围型 "area"、"bar"、"rect" 和 "rule" 的 Y2 坐标。

此通道的 value 可以是一个数字或字符串 "height"，用于表示图的高度。

xOffset

anyOf(number, ExprRef)

x 位置的偏移。

x2Offset

anyOf(number, ExprRef)

x2 位置的偏移。

yOffset

anyOf(number, ExprRef)

y 位置的偏移。

y2Offset

anyOf(number, ExprRef)

y2 位置的偏移。

颜色属性#

点击显示表格

属性

类型

描述

filled

boolean

标记的颜色是用作填充色还是描边色。

默认值：对于所有 point、line 和 rule 标记以及 graticule <https://vega.github.io/vega-lite/docs/data.html#graticule>__ 数据源的 geoshape 标记，为 false；否则为 true。

注意：此属性不能在 style config <https://vega.github.io/vega-lite/docs/mark.html#style-config>__ 中使用。

color

anyOf(Color, Gradient, ExprRef)

默认颜色。

默认值：:raw-html:<span style="color: #4682b4;"> ■ :raw-html:</span> "#4682b4"

注意

  • 此属性不能在 style config <https://vega.github.io/vega-lite/docs/mark.html#style-config>__ 中使用。

  • fill 和 stroke 属性的优先级高于 color，并将覆盖 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 <https://mdn.org.cn/en-US/docs/Web/CSS/mix-blend-mode>__ 值。

默认值： "source-over"

opacity

anyOf(number, ExprRef)

整体不透明度（值介于 [0,1] 之间）。

默认值：对于带有 point、tick、circle 或 square 标记的非聚合图或分层 bar 图表，为 0.7；否则为 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)

描边宽度，以像素为单位。