Vega Rule Mark 完全指南:用线段绘制轴刻度、网格线与参考线

原创2026-09-22 12:53:391,644 阅读
文章标签:数据可视化

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 生成"的实现事实,则能帮助你在自定义坐标轴与复杂参考线时更有把握。

登录后查看全文
vega