Vega Rule Mark 完全指南:用线段绘制轴刻度、网格线与参考线
Vega Rule Mark 完全指南:用线段绘制轴刻度、网格线与参考线
Rule(规则线)是 Vega 可视化语法中用于绘制单个线段的图元(mark)。一条 rule 本质上就是从点 (x, y) 到点 (x2, y2) 的一条直线,它的典型应用场景是绘制坐标轴的刻度(ticks)与网格线(grid lines),也常被用来做参考线、均值线、时间标注线等。读完本文,你将掌握 rule mark 的完整属性体系、编码方式、交互写法,并了解它在 Vega 内部(轴、刻度、网格生成)的真实渲染机制。
Rule Mark 是什么
在 Vega 的 marks 文档 中,rule 被明确定义为"线段,常用于轴刻度和网格线"。与 line(折线,一条线由多个数据点组成)不同,rule 每一条线段只对应一个数据元素,由四个坐标值确定:
- (x, y):线段起点
- (x2, y2):线段终点
这种"一数据一线段"的语义让 rule 特别适合表示离散的参考信息,例如:
- 坐标轴上的刻度短线;
- 图表中的网格线(水平/垂直);
- 均值线、目标线、阈值线等参考线;
- 分面图、雷达图、时间轴中的标注线段。
最小可运行示例
Vega 官方仓库在 docs/docs/marks/rule.vg.json 中提供了一个可直接运行的交互式示例。该规格(spec)定义了四个绑定到滑块的信号(x、y、x2、y2),以及线宽、线帽和虚线样式三个样式信号,因此你可以实时拖动线段端点观察变化:
{
"$schema": "https://vega.github.io/schema/vega/v6.json",
"width": 200,
"height": 200,
"padding": 5,
"signals": [
{ "name": "x", "value": 50,
"bind": {"input": "range", "min": 0, "max": 200, "step": 1} },
{ "name": "y", "value": 50,
"bind": {"input": "range", "min": 0, "max": 200, "step": 1} },
{ "name": "x2", "value": 150,
"bind": {"input": "range", "min": 0, "max": 200, "step": 1} },
{ "name": "y2", "value": 150,
"bind": {"input": "range", "min": 0, "max": 200, "step": 1} },
{ "name": "strokeWidth", "value": 4,
"bind": {"input": "range", "min": 0, "max": 10, "step": 0.5} },
{ "name": "strokeCap", "value": "butt",
"bind": {"input": "select", "options": ["butt", "round", "square"]} },
{ "name": "strokeDash", "value": [1, 0],
"bind": {
"input": "select",
"options": [[1, 0], [8, 8], [8, 4], [4, 4], [4, 2], [2, 1], [1, 1]]
}
}
],
"marks": [
{
"type": "rule",
"encode": {
"enter": {
"stroke": {"value": "#652c90"}
},
"update": {
"x": {"signal": "x"},
"y": {"signal": "y"},
"x2": {"signal": "x2"},
"y2": {"signal": "y2"},
"strokeWidth": {"signal": "strokeWidth"},
"strokeDash": {"signal": "strokeDash"},
"strokeCap": {"signal": "strokeCap"},
"opacity": {"value": 1}
},
"hover": {
"opacity": {"value": 0.5}
}
}
}
]
}
这段规格演示了几个关键点:
- 四个端点坐标都通过
signal引用动态信号,让线段可以随交互实时变化; enter编码集设置颜色(紫色#652c90),保证首次实例化时即生效;update编码集在每次数据/信号更新时重新求值;hover编码集在鼠标悬停时将opacity降为0.5,移开后恢复update的值(Vega 视图需开启.hover()处理,参见 docs/_includes/embed 中view.hover()的调用)。
通用 Mark 属性(rule 可用)
rule 作为 Vega 的 12 种内置图元之一(见 docs/docs/marks.md),支持全部通用 mark 属性。以下是 rule 最常使用的视觉编码通道(完整表格源自 docs/_includes/properties.md):
| 属性 | 类型 | 说明 |
|---|---|---|
| x | Number | 主 x 坐标(像素),线段起点。 |
| x2 | Number | 次 x 坐标(像素),线段终点。 |
| xc | Number | 中心 x 坐标,与 x、x2 互斥。 |
| y | Number | 主 y 坐标(像素),线段起点。 |
| y2 | Number | 次 y 坐标(像素),线段终点。 |
| yc | Number | 中心 y 坐标,与 y、y2 互斥。 |
| opacity | Number | 不透明度,0(透明)到 1(不透明)。 |
| stroke | Color | 描边颜色,rule 的主视觉通道。 |
| strokeOpacity | Number | 描边不透明度,0 到 1。 |
| strokeWidth | Number | 描边宽度(像素)。 |
| strokeCap | String | 线帽样式:butt(默认)、round 或 square。 |
| strokeDash | Number[] | [实线长度, 空格长度] 数组,用于创建虚线/点线。 |
| strokeDashOffset | Number | 虚线数组起始的像素偏移。 |
| strokeJoin | String | 线条连接方式:miter(默认)、round 或 bevel。 |
| strokeMiterLimit | Number | 斜接(miter)转为斜切(bevel)的斜接限制。 |
| blend | String | 混合模式,任意合法的 CSS mix-blend-mode 值(除 "normal");默认 null 在 SVG 下映射为 normal,在 Canvas 下映射为 source-over。 |
| cursor | String | 鼠标悬停时的光标样式,任意合法 CSS cursor 值。 |
| href | URL | 点击后加载的 URL,定义后该 mark 表现为超链接。 |
| tooltip | Any | 悬停提示文本;对象值会逐行展示键值对,数组值以 [v1, v2, ...] 展示,嵌套对象不会递归打印。 |
| zindex | Number | 同级 mark item 的层叠顺序,默认 0,数值越大越靠上;只影响同一 mark 定义内 item 间的渲染顺序。 |
空间属性优先级规则
对支持宽高(如 rect、area)的 mark,水平方向尺寸由 x/x2、x/width、x2/width、xc/width 按优先级依次确定;若 x、x2、width 三者同时给出,width 被忽略。y、y2、yc、height 同理。
对不支持宽高的 mark(如 path、arc,rule 也属于这一类),上述计算依然会执行,但仅用于确定最终的 x / y 位置——width 可能影响最终的 x 位置,但不会被可视化出来。因此 rule 上无需设置 width/height,用四个端点坐标即可。
编码集的约束
同一维度上的多个空间属性(x 与 x2,或 y 与 y2)必须放在同一个编码集内(例如全部放 "enter": {...} 或全部放 "update": {...})。跨编码集拆分(如 x 在 enter、x2 在 update)会导致不可预期的行为。这也是官方示例把 x/y/x2/y2 统一写在 update 中的原因。
无障碍属性(Vega 5.11+)
| 属性 | 类型 | 说明 |
|---|---|---|
| aria | Boolean | 默认 true,是否在 SVG 输出中包含 ARIA 属性;设为 false 时输出元素会被加上 aria-hidden,从无障碍树中移除。 |
| description | String | mark item 的文字描述(仅 SVG 输出),设置后决定输出元素的 aria-label 属性。 |
这些属性在编码集中逐 item 生效,而每个 mark 定义整体层的 ARIA 行为由 mark 级无障碍属性(aria、description)控制。
数值范围与默认值速查
结合官方示例与源码约束,rule 常用属性的取值范围归纳如下:
- 坐标:
x、x2、y、y2、xc、yc均为像素值,可为任意数值或信号; - strokeWidth:任意非负数值,示例中的滑块范围是 0~10(步长 0.5);
- strokeCap:
butt|round|square,默认butt; - strokeDash:形如
[1, 0](实线)、[8, 8](等长虚线)、[4, 2](短虚线)等;[1, 0]即默认实线; - opacity / strokeOpacity / fillOpacity:0~1;
- zindex:整数,默认 0。
源码视角:rule 如何被渲染
rule mark 在 Vega 中有一套完整的实现链,可以从三个层面印证文档描述:
1. 场景图绘制层——packages/vega-scenegraph/src/marks/rule.js 是 rule 的核心渲染实现:
tag: 'line':SVG 输出时 rule 直接渲染为<line>元素;attr:向 SVG 元素输出x2、y2属性,且做了归一化——x2输出的是item.x2 - (item.x || 0),即相对于起点的相对位移;bound:用boundStroke计算包围盒,起点缺失时以(0, 0)兜底(x1 = item.x || 0),终点缺失时退化为起点(item.x2 != null ? item.x2 : x1),因此只写x不写x2会渲染成零长度线段;path/draw:Canvas 渲染时执行moveTo(x1, y1)→lineTo(x2, y2)→stroke();hit:基于isPointInStroke做命中检测,配合intersectRule支持线段求交。
2. 解析层——packages/vega-parser/src/parsers/encode/rule.js 实现编码通道中的"生产规则"(production rule)解析:按顺序拼接 test ? value : ... 三元链,若无 else 分支则以 null 结尾(见注释 #1366),这对应文档中"无 else 时属性默认 null"的约定。
3. 类型系统——packages/vega-typings/types/spec/mark.d.ts 第 84 行定义了 RuleMark 接口(type: 'rule'),与 GroupMark、RectMark 等并列;packages/vega-parser/src/parsers/marks/marktypes.js 中则导出了 RuleMark = 'rule' 常量供各解析器引用。
轴刻度、网格线与参考线的官方实现
规则线是坐标轴刻度的"官方组件"。在 Vega 解析器中,坐标轴的三个组成元素全部由 RuleMark 生成(见 packages/vega-parser/src/parsers/guides 目录):
- 刻度线:axis-ticks.js 第 51 行以
type: RuleMark生成刻度,x/x2(或y/y2)分别绑定刻度位置与刻度长度(tickSize),水平轴时x取zero/tickPos、x2取tickSize,垂直轴则互换; - 网格线:axis-grid.js 第 61 行同样以
type: RuleMark生成贯穿绘图区的网格线; - 轴线:axis-domain.js 第 39 行以
type: RuleMark生成坐标轴主体线段。
也就是说,"grid": true 的坐标轴、每个刻度短线,本质上都是 Vega 内部自动生成的 rule mark 实例。理解 rule 的编码规则,就等于理解了坐标轴的自定义基础。
实战参考线示例
从官方示例 docs/examples/budget-forecasts.vg.json 第 237 行可以看到一条典型的"当前年份参考线"写法——它把 x 固定为 0,x2 通过尺度映射到 currentYear 信号,从而让竖线随信号移动:
{
"type": "rule",
"encode": {
"enter": {
"y": {"scale": "y", "value": 0},
"stroke": {"value": "#000"},
"strokeWidth": {"value": 1}
},
"update": {
"x": {"value": 0},
"x2": {"scale": "x", "signal": "currentYear"}
}
}
}
这里的模式非常典型:把某个端点固定为常量({"value": 0}),另一端点用尺度或信号驱动,即可实现从边到边或数据驱动的参考线。该示例还同时用 symbol mark(三角形 handle)叠加在参考线端点上,形成可拖拽的时间游标。
仓库中还有大量 rule 实战用法可参考:quantile-dot-plot.vg.json(分位点参考线)、radar-chart.vg.json(雷达图轴线)、stock-index-chart.vg.json(多条水平参考线)、table-scrollbar.vg.json(表格滚动条刻度)、watch.vg.json(表盘刻度)等。
与其他 mark 的对比与选型
| 场景 | 推荐 mark | 理由 |
|---|---|---|
| 单个线段/刻度/网格线 | rule |
一数据一线段,语义清晰,渲染开销小 |
| 多段连续折线(时间序列) | line |
多个数据点构成一条连续轨迹 |
| 可随数据改变粗细的连线 | trail |
线宽随数据编码变化 |
| 填充区域 | area / rect |
需要面状图形时使用 |
需要强调:rule 不支持 width/height 的可视化(与 rect、area 不同),设置后仅可能影响最终位置计算。当需要"线段加粗"效果时,应使用 strokeWidth。
小结
Rule mark 是 Vega 中最轻量、用途最聚焦的图元之一:一条从 (x, y) 到 (x2, y2) 的线段,覆盖了坐标轴刻度、网格线、参考线等高频可视化需求。掌握它的四个端点坐标、stroke* 系列描边通道、编码集约束(同维属性必须在同一编码集)以及 hover 交互写法,即可在 Vega 规格中自由绘制各类线段;而理解源码中"轴刻度/网格/轴线均由 RuleMark 生成"的实现事实,则能帮助你在自定义坐标轴与复杂参考线时更有把握。