文档开发者中心
我的

鸿蒙 Canvas 渲染管线中的 save-transform-...

浏览6W+发布于2026-06-30 15:36河南
本文章最后由 在人间耕耘 于 2026-07-02 05:19 编辑

矢量图形引擎:Shape 模型 + 矩阵变换 + 包围盒——在鸿蒙上从零搭建画板的核心三件套

本文基于矢量图形编辑器项目,拆解其图形引擎的底层设计:Shape 抽象基类、2D 仿射变换矩阵、轴对齐包围盒,以及连接它们的坐标系统和渲染管线。全文约 400 行,配 3 张架构图。

引言

做矢量图形编辑器,第一步不是画界面,而是把"图形"这件事想清楚。

一个矩形、一条线、一个流程图节点——它们看起来完全不同,但在引擎眼里都是同一个东西:一个带着变换矩阵和样式的几何体。引擎要做的就是三件事——算出它在哪(矩阵变换)、算出它多大(包围盒)、把它画出来(Canvas 渲染)。

这就是 Shape + Matrix + BoundingBox 三件套的由来。

收起
自动换行
深色代码主题
复制
矢量图形引擎的三根支柱:
Shape   →  它是什么(几何 + 样式)
Matrix  →  它在哪(位置 + 旋转 + 缩放)
BBox    →  它多大(选中框 + 碰撞检测)

本文拆解的是一个纯 TypeScript 实现——没有 OpenGL、没有 Skia、没有外部依赖,全部逻辑加起来不到 800 行,却能支撑一个完整的矢量编辑器。

矢量图形引擎三件套:Shape + Matrix + BoundingBox

一、Shape 基类:所有图形的公约数

Shape 是所有图形的抽象基类。它的设计哲学是"把共性提到基类,把差异留给子类":

收起
自动换行
深色代码主题
复制
export abstract class Shape {
  id: string = '';
  kind: ShapeKind = ShapeKind.Line;
  name: string = '';
  transform: Matrix = new Matrix();   // 局部变换矩阵
  style: ShapeStyle = new ShapeStyle(); // 填充 + 描边
  visible: boolean = true;
  locked: boolean = false;

  // 子类必须实现的四个方法
  abstract drawSelf(ctx: CanvasDrawContext): void;
  abstract getLocalBounds(): BoundingBox;
  abstract getLocalKeyPoints(): Point[];
  abstract clone(): Shape;
  abstract toSvg(): string;
}

transform 是每个图形的"身份证"——它描述了图形在世界坐标系中的位置、旋转和缩放。style 描述了外观——填充色、描边色、透明度、虚线模式。

子类(RectShape、EllipseShape、FlowShape 等)只需要实现 drawSelf(怎么画自己)和 getLocalBounds(自己的边界在哪),矩阵变换和样式应用全由基类处理。

这是经典的模板方法模式——基类定流程,子类填细节。

二、draw 流程:save → transform → style → drawSelf → restore

基类的 draw 方法是渲染管线的入口:

收起
自动换行
深色代码主题
复制
draw(ctx: CanvasDrawContext): void {
  if (!this.visible) return;
  ctx.save();
  // 1. 应用变换
  const m = this.transform;
  if (!m.isIdentity()) {
    ctx.transform(m.a, m.b, m.c, m.d, m.e, m.f);
  }
  // 2. 应用样式
  this.style.apply(ctx);
  // 3. 子类绘制几何
  this.drawSelf(ctx);
  // 4. 恢复状态
  ctx.restore();
}

save/restore 是 Canvas 的"时间旅行"——save 保存当前状态,restore 回到 save 时的状态。这样每个图形的变换和样式都不会"泄漏"到下一个图形。

style.apply(ctx) 把 ShapeStyle 的属性写入 Canvas 上下文:

收起
自动换行
深色代码主题
复制
apply(ctx: CanvasDrawContext): void {
  ctx.globalAlpha = this.opacity;
  if (this.fillEnabled) ctx.fillStyle = this.fill;
  if (this.strokeEnabled) {
    ctx.strokeStyle = this.stroke;
    ctx.lineWidth = this.strokeWidth;
  }
  ctx.setLineDash(this.dash.length > 0 ? this.dash : []);
}

这套流程保证了:不管图形多复杂,渲染逻辑都是一致的——进入时 save,设置变换和样式,画几何,退出时 restore。

三、Matrix:2D 仿射变换矩阵

Matrix 是矢量引擎的数学核心。它用 SVG 风格的六参数表示 2D 仿射变换:

收起
自动换行
深色代码主题
复制
| a  c  e |     | cos(θ)  -sin(θ)  tx |
| b  d  f |  =  | sin(θ)   cos(θ)  ty |
| 0  0  1 |     |   0        0      1  |

六个参数(a, b, c, d, e, f)编码了三种基本变换:

  • 平移:e 和 f
  • 旋转:a, b, c, d
  • 缩放:a 和 d

矩阵乘法是变换组合的基础——先旋转再平移 = T × R:

收起
自动换行
深色代码主题
复制
multiply(other: Matrix): Matrix {
  const a = this.a * other.a + this.c * other.b;
  const b = this.b * other.a + this.d * other.b;
  const c = this.a * other.c + this.c * other.d;
  const d = this.b * other.c + this.d * other.d;
  const e = this.a * other.e + this.c * other.f + this.e;
  const f = this.b * other.e + this.d * other.f + this.f;
  return new Matrix(a, b, c, d, e, f);
}

围绕任意点旋转/缩放是编辑器最常用的操作——原理是"先平移到原点,变换,再平移回去":

收起
自动换行
深色代码主题
复制
static rotationAround(rad: number, cx: number, cy: number): Matrix {
  const t1 = Matrix.translation(cx, cy);   // 平移到旋转中心
  const r = Matrix.rotation(rad);           // 旋转
  const t2 = Matrix.translation(-cx, -cy);  // 平移回去
  return t1.multiply(r).multiply(t2);
}

逆矩阵用于"世界坐标 → 本地坐标"的转换——命中测试和拖拽都需要这个:

收起
自动换行
深色代码主题
复制
hitTest(worldPoint: Point): boolean {
  const inv = this.transform.invert();        // 求逆矩阵
  const local = inv.applyPoint(worldPoint);   // 世界 → 本地
  return this.getLocalBounds().contains(local); // 本地坐标命中测试
}

逆矩阵的计算用的是伴随矩阵法——行列式为 0 时退化为单位矩阵,避免崩溃。

四、BoundingBox:轴对齐包围盒(AABB)

BoundingBox 是最简单的空间数据结构——一个矩形区域,用 (x, y, width, height) 表示。

它的核心操作:

方法 用途 复杂度
fromPoints(pts) 从点集计算包围盒 O(n)
contains(p) 点是否在盒内 O(1)
intersects(other) 两盒是否相交 O(1)
transform(m) 矩阵变换后的新 AABB O(1)
union(other) 两盒的并集 O(1)
inflate(padding) 向外扩展 O(1)

transform 方法是关键——把包围盒的 4 个角点用矩阵变换,再从变换后的 4 个点重新算 AABB:

收起
自动换行
深色代码主题
复制
transform(m: Matrix): BoundingBox {
  const corners = [
    new Point(this.x, this.y),
    new Point(this.x + this.width, this.y),
    new Point(this.x + this.width, this.y + this.height),
    new Point(this.x, this.y + this.height),
  ];
  const transformed = corners.map(p => m.applyPoint(p));
  return BoundingBox.fromPoints(transformed);
}

这个方法的代价是:旋转一个 100×100 的矩形 45°,包围盒会膨胀到 141×141。这是 AABB 的固有缺陷——它不跟踪旋转角度,只跟踪"最坏情况"的轴对齐范围。但对于交互式编辑器来说,这个精度足够了。

五、Point:二维点与向量

Point 看起来最简单,但它是所有几何运算的原子:

收起
自动换行
深色代码主题
复制
export class Point {
  x: number;
  y: number;
  add(p: Point): Point { return new Point(this.x + p.x, this.y + p.y); }
  sub(p: Point): Point { return new Point(this.x - p.x, this.y - p.y); }
  scale(k: number): Point { return new Point(this.x * k, this.y * k); }
  distance(p: Point): number { return Math.sqrt((this.x-p.x)**2 + (this.y-p.y)**2); }
  normalize(): Point { const l = this.length(); return l === 0 ? new Point(0,0) : new Point(this.x/l, this.y/l); }
}

值得注意的是 normalize——归一化向量在连线路由、方向计算中大量使用。零向量的归一化返回原点,避免了除以零的崩溃。

distanceSquared 是优化版本——避免开方,在只需要比较距离大小的场景(如最近点查找)中用得很多。

六、坐标系统:本地坐标 vs 世界坐标

这是理解矢量引擎最关键的概念——每个图形都有两套坐标系。

本地坐标系:图形自己"认为"的坐标。矩形从 (0,0) 到 (width,height),椭圆以原点为中心。drawSelf 在本地坐标系下绘制。

世界坐标系:画布的绝对坐标。所有图形最终都要在世界坐标系中渲染。

转换关系:

收起
自动换行
深色代码主题
复制
世界坐标 = 本地坐标 × transform 矩阵
本地坐标 = 世界坐标 × transform 的逆矩阵

Shape 基类提供了两套 API:

方法 坐标系 用途
getLocalBounds() 本地 子类实现,定义几何
getWorldBounds() 世界 基类包装,用于选中框
getLocalKeyPoints() 本地 吸附用关键点
getWorldKeyPoints() 世界 吸附计算
hitTest(worldPoint) 世界→本地 命中测试

这种分离的好处是:子类只需要关心"自己的形状在自己的坐标系里长什么样",矩阵变换交给基类处理。

本地坐标系 vs 世界坐标系:transform 和 invert 的双向转换

七、命中测试:从鼠标点击到图形选中

命中测试是编辑器最频繁的操作——用户点击画布,引擎要找出"点了哪个图形"。

流程:

收起
自动换行
深色代码主题
复制
1. 遍历所有图形(后添加的在上面,优先命中)
2. 对每个图形:worldPoint → invert(transform) → localPoint
3. localPoint 是否在 getLocalBounds() 内?
4. 是 → 命中;否 → 继续下一个
收起
自动换行
深色代码主题
复制
hitTest(worldPoint: Point): boolean {
  const inv = this.transform.invert();
  const local = inv.applyPoint(worldPoint);
  return this.getLocalBounds().contains(local);
}

这里有个性能细节:invert() 每次都重新计算逆矩阵。在频繁命中测试的场景(如鼠标拖拽时实时检测),可以缓存逆矩阵。但对于大多数编辑器来说,每帧几十次 invert 的开销可以忽略。

八、CanvasDrawContext:统一 Canvas 与 OffscreenCanvas

这是一个只有 5 行的文件,却解决了一个实际问题:

收起
自动换行
深色代码主题
复制
export type CanvasDrawContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;

HarmonyOS 的 Canvas 组件有两种渲染上下文——CanvasRenderingContext2D(主线程 Canvas)和 OffscreenCanvasRenderingContext2D(离屏 Canvas)。它们的 API 完全一致,但类型不同。

如果不做统一,每个 drawSelf 都要写两份——一份给主线程 Canvas,一份给离屏 Canvas。用联合类型统一后,所有绘制代码只需要写一份。

离屏 Canvas 用于 PNG 导出和快照生成——不需要显示在屏幕上,只需要拿到像素数据。

九、ShapeStyle:外观属性的封装

ShapeStyle 把图形的视觉属性集中管理:

收起
自动换行
深色代码主题
复制
export class ShapeStyle {
  fill: string = '#FFFFFF';
  stroke: string = '#1F2933';
  strokeWidth: number = 2;
  fillEnabled: boolean = false;
  strokeEnabled: boolean = true;
  opacity: number = 1.0;
  dash: number[] = [];
  fontSize: number = 14;
  fontColor: string = '#1F2933';
  fontFamily: string = 'HarmonyOS Sans';
}

两个关键设计决策:

  1. fillEnabled 和 strokeEnabled 是独立的开关——可以只描边不填充(路径),也可以只填充不描边(背景块)
  2. dash 数组支持任意虚线模式——空数组表示实线,[5, 3] 表示 5px 实线 + 3px 空白

toSvgAttrs() 方法把样式转为 SVG 属性字符串——Canvas 渲染和 SVG 导出共用同一套样式定义,保证视觉一致性。

十、ShapeKind:9 种图形类型

收起
自动换行
深色代码主题
复制
export enum ShapeKind {
  Line = 'line',           // 线段
  Rect = 'rect',           // 矩形
  Ellipse = 'ellipse',     // 椭圆
  Path = 'path',           // 贝塞尔路径
  Polygon = 'polygon',     // 多边形
  Text = 'text',           // 文字
  Group = 'group',         // 组
  Flow = 'flow',           // 流程图节点
  Connection = 'connection', // 连线
}

Flow 和 Connection 是这个编辑器的特色——Flow 有 8 种子类型(开始/结束、处理、判断、IO、数据库、连接器、文档、子流程),Connection 有 3 种路由样式(直线、正交、平滑曲线)。

每种 ShapeKind 对应一个子类,子类通过 kind 字段标识自己。这比 instanceof 判断更安全——序列化/反序列化时不会丢失类型信息。

十一、EditorContext:中央控制器

EditorContext 是整个编辑器的"大脑"——它持有文档、视口、历史栈、吸附管理器和选中状态:

收起
自动换行
深色代码主题
复制
export class EditorContext {
  document: DiagramDocument;   // 图形文档
  viewport: Viewport;          // 视口(缩放 + 平移)
  history: HistoryManager;     // 撤销/重做
  snap: SnapManager;           // 吸附管理
  currentTool: ToolType;       // 当前工具
  selectedIds: string[];       // 选中的图形 ID
}

UI 通过 on/notify 订阅模式感知状态变化——任何状态变更(工具切换、选中变化、文档修改)都调用 notify(),触发 UI 刷新。

这种设计的好处是:状态变更集中在一个地方,不会出现"UI 状态和文档状态不一致"的问题。

十二、踩坑记录

坑 1:矩阵乘法顺序

矩阵乘法不满足交换律——A × B ≠ B × A。先旋转再平移和先平移再旋转,结果完全不同。

在实现 translate/rotate/scale 时,必须用 append(右乘)而不是左乘:

收起
自动换行
深色代码主题
复制
// 正确:先有的变换保留,新变换追加到末尾
this.transform = Matrix.translation(dx, dy).multiply(this.transform);

// 错误:新变换会"覆盖"之前的变换
this.transform = this.transform.multiply(Matrix.translation(dx, dy));

坑 2:AABB 旋转膨胀

旋转 45° 的 100×100 矩形,AABB 会变成 141×141。如果用户框选时用了 AABB 碰撞检测,旋转后的图形可能"比看起来更容易被选中"。

解决方案:对旋转角度非零的图形,做更精确的 OBB(有向包围盒)碰撞检测。但对于 MVP 来说,AABB 够用。

坑 3:逆矩阵退化

当缩放因子为 0 时(比如 scale(0, 1)),矩阵行列式为 0,逆矩阵不存在。

代码中做了防御:行列式为 0 时返回单位矩阵,hitTest 会返回 false(无法命中)。这比崩溃好——用户只是暂时选不中那个图形,缩放恢复后就正常了。

十三、算法参数一览

参数 值 说明
Matrix 参数数量 6 a, b, c, d, e, f
AABB 角点数 4 用于 transform 计算
Point 精度 0.0001 equals 的 eps 阈值
ShapeKind 数量 9 7 基础 + 2 复合
FlowKind 子类型 8 流程图节点变体
Canvas 状态栈深度 save/restore 配对 无硬性上限
逆矩阵退化处理 返回 identity 避免崩溃

十四、总结

矢量图形引擎的核心是三个概念的协作:

Shape 定义"画什么"——通过 drawSelf 多态,每种图形用自己的方式绘制几何体。 Matrix 定义"在哪画"——通过仿射变换,把本地坐标系映射到世界坐标系。 BoundingBox 定义"多大"——通过 AABB,快速判断命中、选中、碰撞。

这三者通过"本地坐标 ↔ 世界坐标"的转换连接在一起:

  • draw 时:本地 → 世界(通过 transform)
  • hitTest 时:世界 → 本地(通过 invert)
  • getWorldBounds 时:本地 AABB → 世界 AABB(通过 transform 4 角点)

十五、渲染管线的完整流程

从用户拖入一个矩形到它出现在屏幕上,完整链路:

收起
自动换行
深色代码主题
复制
1. 用户拖拽创建 → EditorCanvas 计算起点/终点
2. 创建 RectShape,设置 width/height
3. 设置 transform = Matrix.translation(x, y)
4. 将 Shape 加入 Document.shapes 数组
5. EditorContext.notify() → 触发 Canvas 重绘
6. 遍历 shapes,对每个 shape 调用 draw(ctx)
7. draw 内部:save → transform → style → drawSelf → restore

Canvas 的 onReady 回调每帧执行这个遍历。HarmonyOS 的 Canvas 组件默认 60fps,意味着每秒执行 60 次这个循环。

对于包含 100 个图形的画布,每帧的开销是:100 次 save/restore + 100 次 transform 矩阵判断 + 100 次 style.apply + 100 次 drawSelf。全部加起来 < 1ms——瓶颈不在渲染,在 I/O(文件读写)和布局计算。

Canvas 渲染管线:save → transform → style → drawSelf → restore

十六、视口变换:Viewport 的角色

Viewport 控制画布的缩放和平移——它本身也是一个 Matrix。

收起
自动换行
深色代码主题
复制
最终变换 = viewport.matrix × shape.transform

Viewport 的存在让"画布无限大"成为可能——用户可以通过滚轮缩放、拖拽平移来浏览任意区域,而所有图形的坐标不需要改变。

Shape 的 draw 方法不需要知道 Viewport 的存在——它只管自己的本地坐标 → 世界坐标。Viewport 的变换由 EditorCanvas 在遍历所有 shape 之前统一应用到 Canvas 上下文。

这种分层设计的好处是:Viewport 可以独立于图形系统变化(比如加动画、加过渡),而图形引擎完全不用改。

收藏
0
回复
0
分享
全部评论
暂无评论
暂无评论
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
矢量图形引擎:Shape 模型 + 矩阵变换 + 包围盒——在鸿蒙上从零搭建画板的核心三件套
引言
一、Shape 基类:所有图形的公约数
二、draw 流程:save → transform → style → drawSelf → restore
三、Matrix:2D 仿射变换矩阵
四、BoundingBox:轴对齐包围盒(AABB)
五、Point:二维点与向量
六、坐标系统:本地坐标 vs 世界坐标
七、命中测试:从鼠标点击到图形选中
八、CanvasDrawContext:统一 Canvas 与 OffscreenCanvas
九、ShapeStyle:外观属性的封装
十、ShapeKind:9 种图形类型
十一、EditorContext:中央控制器
十二、踩坑记录
十三、算法参数一览
十四、总结
十五、渲染管线的完整流程
十六、视口变换:Viewport 的角色
了解社区公约,与您携手共创和谐专业的开发者社区。