Vue3 + Canvas 实现类 Pixso 钢笔工具：贝塞尔曲线与路径编辑

1. 项目动机与整体设计思路

钢笔工具这东西，我用一句话概括就是：看着是工具栏里一个不起眼的小图标，实际做起来是图形编辑器里最磨人的那块骨头。这次我用Vue3从头实现了一遍类Pixso的钢笔工具，核心功能包括路径创建、锚点拖拽、贝塞尔控制柄调整、路径闭合与二次编辑。如果你打算做白板、海报编辑器、流程图工具或者任何带自由绘制的产品，这个项目的思路可以直接移植过去用。

先说为什么要选Vue3。做图形编辑器，最绕不开的问题就是状态同步。你拖一下控制柄，面板上的坐标数值要变，路径预览要变，历史记录要进栈，多图层场景下还要保证其他元素不受影响。如果用原生DOM操作，这些逻辑散落在各个事件回调里，撑到后面就是一团乱麻。Vue3的响应式系统刚好能把这层关系理顺——你把路径数据定义成响应式对象，Canvas画布只负责渲染，数据一变、画面跟着变，不用手动去操作DOM属性。实现下来，数据层和渲染层的耦合度很低，后续加缩放、旋转、撤销重做都比较好接。

再聊Canvas和SVG的选型。钢笔工具路径这种东西，SVG原生就是矢量结构，看起来是天然契合的。但实际做起来你会发现一个问题：路径的实时预览、大量锚点的高亮检测、后续还要叠加橡皮擦、多路径合并这类操作，SVG的DOM节点一多，性能就开始拉胯。Canvas这边没有DOM层面的开销，渲染几百个锚点加贝塞尔曲线完全可以稳住60帧。代价是命中的检测、选中态的高亮这些都要自己算，但算下来的代码量其实可控，后面会详细讲。

整个项目的架构我分了三层：

• 数据层：路径、锚点、控制柄的响应式定义与状态管理
• 渲染层：纯粹的Canvas绘制函数，输入数据、输出画面
• 交互层：鼠标事件解析，把用户操作翻译成数据变化

三层各自独立、单向依赖，交互层改数据、数据触发渲染，这比在事件回调里上下其手要清爽得多。特别是Vue3的reactive配合watch，你可以在路径闭合的时候自动去跑一遍面积计算、自动更新图层面板，这些都是一条数据流的自然延伸。

2. 核心数据结构设计

写钢笔工具之前，我先把数据结构想透了。图形编辑器里有一句老话：数据模型设计得好，后面所有功能都是加滤镜；数据模型设计得烂，每加一个功能都是在给旧屎山打补丁。钢笔工具的核心数据就这么几个：路径（Path）、锚点（Point）、控制柄（Handle）。

我先定义了一个锚点对象：

{ id: 'p_1699999999_001', x: 120, // 锚点坐标 y: 80, controlIn: null, // 入控制柄，相对锚点的偏移量，形如 {x: -20, y: -10} controlOut: null, // 出控制柄，相对锚点的偏移量 type: 'smooth' // 锚点类型：'smooth' | 'mirror' | 'corner' }

这里的关键设计是：controlIn和controlOut存相对偏移量，而不是绝对坐标。为什么这样设计？因为锚点本体一旦被拖拽移动，控制柄要跟着一起平移。如果用绝对坐标，每次拖锚点都要同时修改三个坐标值；用相对偏移量，改锚点的x和y控制柄自动跟随，而且控制柄的“相对锚点的方向”这个语义也保住了。

锚点类型的含义是这样的：

• smooth：平滑点，入控制柄和出控制柄在一条直线上，长度可以不一样。拖一边控制柄，另一边保持反向但长度不变。对应设计工具里的“平滑曲线”。
• mirror：镜像点，两个控制柄不仅共线而且等长。拖一边另一边完全同步，适合做圆周或对称的曲线。
• corner：角点，两边控制柄可以各自独立旋转，用来做尖角过渡。

举个生活里的例子帮助理解：smooth就像门上的铰链，两扇门可以各自开合但合页固定方向；corner就像两段独立的绳子打了个结，两边各自摆动互不影响。

路径对象长这样：

{ id: 'path_001', points: [], // 锚点数组 closed: false, // 是否闭合 fill: 'transparent', stroke: '#333333', strokeWidth: 2, opacity: 1, createTime: 1699999999999 }

在Vue3里的状态管理，我直接用了reactive：

import { reactive, computed } from 'vue' const state = reactive({ paths: [], // 所有路径 activePathId: null, // 当前正在编辑的路径 hoverPointId: null, // 鼠标悬停的锚点 selectedPointId: null, // 选中的锚点 mode: 'draw' // 'draw' | 'edit' })

这样设计有个很直观的好处：往paths里push一条新路径，Canvas会自动通过watch触发重绘；把hoverPointId一换，画布上那个锚点的外圈高亮也随即更新。这比在Canvas绘制函数内部维护一堆“当前状态”要稳得多。

3. 环境初始化与Canvas画布搭建

实现之前先把环境搭好。我用Vite初始化了一个Vue3项目，这个不过多说了，直接看Canvas画布的搭建要点。

<template> <div class="editor-container" @mousedown="onMouseDown" @mousemove="onMouseMove" @mouseup="onMouseUp"> <canvas ref="canvasRef" width="1000" height="600"></canvas> </div> </template>

有几个容易踩坑的点：

第一，Canvas的高宽务必在JavaScript里通过设备像素比做适配。不做适配的话，在Mac的Retina屏幕上画出来的曲线会发虚、发糊，专业工具出现这个问题基本上就是劝退级体验。我在onMounted里加了这样一段：

function initCanvas() { const dpr = window.devicePixelRatio || 1 canvas.width = width * dpr canvas.height = height * dpr canvas.style.width = width + 'px' canvas.style.height = height + 'px' ctx.setTransform(dpr, 0, 0, dpr, 0, 0) }

逻辑很简单：画布的实际像素按物理像素设置，但样式尺寸保持CSS像素。这样绘制的时候坐标还是按CSS像素逻辑走，但线条渲染出来会细腻很多。

第二，事件的坐标换算。鼠标事件拿到的是clientX/clientY，这是相对于浏览器视口的坐标；Canvas自己的坐标系是从画布左上角算起的。画布经常会被放在有padding的容器里，或者页面整体有滚动。正确的换算公式是：

const rect = canvas.getBoundingClientRect() const x = e.clientX - rect.left const y = e.clientY - rect.top

用getBoundingClientRect比用offsetX/offsetY更稳，因为offsetX碰到有border或padding的容器时会偏移。

第三，整个编辑器容器要设置user-select: none。不然鼠标拖拽的时候会选中页面上的文字，视觉上非常出戏。

第四，拖拽的时候我给容器加了cursor: crosshair，这是钢笔工具的标配光标。路径悬停在已有锚点上方时，光标切成pointer，提示用户可以点击选中或闭合路径。闭合检测我留到交互环节再细说。

4. 钢笔工具的交互逻辑实现

4.1 直线段的绘制

钢笔工具的最基础形态是点击放置锚点，两个锚点之间连一条直线。这个逻辑最简单的实现就是：捕获到第一个点击时创建一条新路径，把坐标作为第一个锚点；接下来每次点击，往当前路径的points数组里push一个新锚点。渲染的时候，相邻锚点用moveTo和lineTo画线：

function renderPath(ctx, path) { if (path.points.length < 2) return ctx.beginPath() ctx.moveTo(path.points[0].x, path.points[0].y) for (let i = 1; i < path.points.length; i++) { const p1 = path.points[i - 1] const p2 = path.points[i] if (p1.controlOut || p2.controlIn) { const cp1x = p1.x + (p1.controlOut ? p1.controlOut.x : 0) const cp1y = p1.y + (p1.controlOut ? p1.controlOut.y : 0) const cp2x = p2.x + (p2.controlIn ? p2.controlIn.x : 0) const cp2y = p2.y + (p2.controlIn ? p2.controlIn.y : 0) ctx.bezierCurveTo(cp1x, cp1y, cp2x, cp2y, p2.x, p2.y) } else { ctx.lineTo(p2.x, p2.y) } } ctx.stroke() }

因为controlIn/controlOut有可能是null，所以这里做了一个判断：只要这两个锚点之间存在任何一个控制柄，就走贝塞尔曲线；否则走直线段。线段画完就地显示，用户能实时看到自己画的路径长什么样。

4.2 贝塞尔控制柄的生成逻辑

钢笔工具真正难的地方，就是“点击、按住、拖拽”这个手势。普通的点击放置锚点，锚点的两个控制柄都是null，路径段是直线；但如果用户点击后不松开，而是拖拽了一段距离，就必须生成一个出控制柄，控制柄的方向是鼠标相对锚点的方向，长度是鼠标相对锚点的距离——这里就涉及到一个核心的数学逻辑。

我们拿一个场景举例：当前鼠标位置在(300, 200)，按住并拖拽到(340, 160)，那么新的锚点controlOut就应该是(40, -40)，也就是相对偏移量。在实现中需要用距离和角度来转成控制柄的偏移量：

function createControlOffset(fromX, fromY, toX, toY) { const dx = toX - fromX const dy = toY - fromY const dist = Math.sqrt(dx * dx + dy * dy) return { x: dx, y: dy, length: dist } }

拖拽的过程中，画布要实时重绘。刚才那个锚点的controlOut更新后，路径的预览线也跟着变，用户就能看到一个带弧度的曲线从锚点平滑地拉出来。这里不宜每帧都创建新的对象，因为频繁的响应式更新有性能开销，我习惯在mousedown拖拽时先用一个临时变量存控制柄，只在mouseup时真正写回store。视觉反馈上不受影响——render函数读的是store，临时变量同样触发draw。

4.3 悬停高亮与锚点选中检测

Canvas本身不支持“命中测试”这种概念，所有的选区逻辑都要自己算。锚点的选中检测比较简单：鼠标位置和锚点位置之间的距离小于某个阈值（我用的7px），就算命中。注意这是屏幕空间的距离，所以如果做了缩放或者有坐标变换，要在同一坐标系里比：

function hitTest(points, mouseX, mouseY, threshold = 7) { for (let i = points.length - 1; i >= 0; i--) { const p = points[i] const dist = Math.sqrt((p.x - mouseX) ** 2 + (p.y - mouseY) ** 2) if (dist < threshold) return p } return null }

命中之后，渲染层要画出高亮效果。锚点通常画成小空心圆（未选中）或小实心圆（选中）。控制柄的命中检测类似，但更细一些，因为控制柄比锚点小，阈值我会放宽到10px，否则确实很难点中。

4.4 悬停闭合与路径闭合检测

路径闭合是钢笔工具里很有仪式感的操作。初始化时，当前路径的第一个锚点被记录下来。当鼠标移到起点附近时，光标变成“闭合提示”状态，如果此时点击，路径就闭合。判定起点是否命中，和锚点命中检测一样，只对path.points[0]做一次距离判断：

function isNearStartPoint(point, mouseX, mouseY, threshold = 10) { if (!point) return false return Math.sqrt((point.x - mouseX) ** 2 + (point.y - mouseY) ** 2) < threshold }

但是“闭合”和“继续画新路径”这两个动作在同一块画布上，就必须有个模式区分。我的处理是：如果当前路径至少有一个锚点，而且鼠标悬停在起点附近，那么点击执行闭合；否则点击新建锚点追加到当前路径。同时按下一个新按键可以显式结束当前路径，路径对象进入编辑模式而不是绘制模式。这个交互看似简单，实际项目中很容易出现“想闭合却新增了一个点”的情况，所以在光标反馈上必须及时、明确。

4.5 路径的二次编辑：拖锚点与调控制柄

路径画完不是就结束了，钢笔工具的完成态是“可编辑”。我加了一个模式切换：绘制模式下点击路径任意一段，会选中这条路径；在路径被选中的情况下，所有锚点和控制柄都会可视化地显示出来。此时你可以拖拽锚点调整位置，也可以拖控制柄调整曲线的度。

拖控制柄有一个细节需要处理好：控制柄被拖离锚点时，controlIn和controlOut就“断”开了。对于smooth类型的锚点，修改controlOut时controlIn要同步对称更新，但只更新方向、不更新长度。我在代码里这样处理：

function updateControlOut(point, newOffsetX, newOffsetY) { point.controlOut = { x: newOffsetX, y: newOffsetY } if (point.type === 'mirror') { point.controlIn = { x: -newOffsetX, y: -newOffsetY } } else if (point.type === 'smooth') { // 方向镜像，但长度保持controlIn的长度 const inLength = Math.sqrt( (point.controlIn?.x || 0) ** 2 + (point.controlIn?.y || 0) ** 2 ) const outLength = Math.sqrt(newOffsetX ** 2 + newOffsetY ** 2) if (outLength > 0 && inLength > 0) { const scale = inLength / outLength point.controlIn = { x: -newOffsetX * scale, y: -newOffsetY * scale } } } }

这个逻辑就是做设计工具时“手柄”的物理直觉来源。大部分新手在这一步容易搞反方向：controlOut往右拉，曲线往右凸，但controlIn这端如果也跟着往右，曲线就会拧成一个波浪，而不是顺滑的弧线。记住一条脑内口诀：控制柄永远指向曲线的切线方向。锚点左侧的控制柄如果朝上，那么曲线进入这个锚点时一定是从下方切进来的；反过来也一样。

5. 实时预览渲染与性能优化

钢笔工具和普通的绘图工具不一样，用户的每一次点击、拖拽，都要有即时的视觉反馈。我在这里做了一个实时渲染循环：

watch( () => [state.paths, state.hoverPointId, state.selectedPointId], () => renderAll(), { deep: true } )

renderAll做的事情分三步：清理画布、渲染所有路径、渲染当前路径的锚点与控制柄。这样设计的核心好处是：所有逻辑都在“数据变化后重绘”这一个入口里，不会出现渲染滞后或者局部没刷新的问题。

用一个简单的requestAnimationFrame循环会更好：

let rafId = null function scheduleRender() { if (rafId) return rafId = requestAnimationFrame(() => { renderAll() rafId = null }) }

这样在拖拽高频触发更新的时候，渲染会自动合并到下一帧，不会出现一帧内被调用好几十次的情况。

做性能优化还有一个诀窍：不要把不透明物体的阴影、渐变、滤镜这些重操作放在高频重绘路径上。渲染锚点时，小圆点直接用arc和fill就够了；如果觉得外圈高亮不够精致，可以用一个稍微大一圈的arc + stroke，不要上shadowBlur，那个东西帧率直接减半。

实测下来：1000个锚点，悬停高亮和拖拽帧率稳定60帧；如果把整个画布重新铺满shadowBlur的话直接掉到20帧。踩坑之后我养成了一个习惯，任何Canvas性能问题，第一个排查项就是shadowBlur和globalCompositeOperation。

6. 常见问题与排查速查表

做钢笔工具这种偏底层交互的功能，踩坑的频率远高于普通业务组件。我整理了一张速查表，后面项目里再遇到同类型问题，直接对照排查就行。

排查的时候有一个小窍门：把Canvas的渲染逻辑拆成好几个可以独立调用的函数。比如单独调renderAnchors()看锚点是否正常，单独调renderHandles()看控制柄是否正常。这样定位问题不用每次从头过一遍事件流程。生产环境下，Debug面板里放一个“重绘”按钮非常管用，能帮你快速区分“数据问题”和“渲染问题”。

7. 导出与数据持久化

钢笔工具做完路径，下一步一定会遇到的问题就是导出和保存。我实现了SVG和JSON两种导出格式。

SVG导出相对直接，把Canvas绘制逻辑里的每个moveTo、lineTo、bezierCurveTo翻译成SVG对应的path命令就行：

function exportSVG(paths) { let d = '' for (const path of paths) { const firstPoint = path.points[0] d += `M${firstPoint.x},${firstPoint.y} ` for (let i = 1; i < path.points.length; i++) { const p1 = path.points[i - 1] const p2 = path.points[i] if (p1.controlOut || p2.controlIn) { const cp1x = p1.x + (p1.controlOut.x || 0) const cp1y = p1.y + (p1.controlOut.y || 0) const cp2x = p2.x + (p2.controlIn.x || 0) const cp2y = p2.y + (p2.controlIn.y || 0) d += `C${cp1x},${cp1y} ${cp2x},${cp2y} ${p2.x},${p2.y} ` } else { d += `L${p2.x},${p2.y} ` } } if (path.closed) d += 'Z ' } return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1000 600"><path d="${d}" fill="none" stroke="#333" stroke-width="2"/></svg>` }

JSON导出则直接序列化state.paths，保存后下次打开能原样恢复。序列化之前建议做一次防呆处理：把控制柄为null的字段过滤掉，或者统一成{ x: 0, y: 0 }，不然恢复的时候null和{ x: 0, y: 0 }的语义会被混在一起。

值得注意的是，如果你用的Canvas画布有其他图形对象（矩形、圆形、文本），那么导出的数据结构要统一抽象成GraphicsObject类型，路径只是其中一种。这样导出逻辑可以收敛到一个函数里，不会散落到各图形类中。

8. 扩展思路与进阶玩法

钢笔工具做完了基础路径，我到这一步没有停，因为我知道真正的价值是在“能自由编辑路径”这个能力之上再去叠加新玩法。分享一下我实际开发后续功能的思路。

第一，路径的布尔运算。这是高级设计工具区分业余和专业的标志。两条路径交叠，能求并集、交集、差集。Canvas本身没有这个能力，图论上要跑多边形裁剪算法，工程上比较重的方案是引入Clipper库。如果只是做白板工具，建议先只做“路径合并成一个组”，布尔运算暂时押后。

第二，自动平滑算法。手绘的路径很多都是锯齿状的，钢笔工具的smooth锚点本身可以一键做平滑处理。思路是对每个锚点重新计算控制柄方向，取前后锚点连线的法线方向。这个算法做出来的曲线很像Sketch里那根动态的钢笔工具。代码上可以用三次样条插值先行拟合，再反推贝塞尔控制柄。

第三，吸附功能做精细化。网格吸附、锚点互相吸附、路径中点吸附，每个都是一个独立的方向。吸附判定时要设置吸附优先级，我实测下来“锚点吸附 > 网格吸附 > 自由移动”这样排不会出现突然跳变的情况。

第四，历史记录栈。这个是所有编辑器的刚需。做法是在每次数据变更前做一次深浅合适的快照，然后维护一个undo栈和redo栈。Vue3的响应式数据对快照有一个坑：reactive对象不能直接塞进历史栈，会出现直接引用导致旧数据跟着变化的问题。要解决就必须在入栈时做一次结构化克隆。这里可以用JSON序列化，但路径数据量一大就慢，更合适的方案是实现一个专门针对路径数据的克隆函数，注意控制柄和锚点是分开克隆的。

第五，路径转形状。钢笔工具画完的路径，可以一键转换成矩形、圆形、星形等基础形状。这对产品来说是很自然的交互延展。

9. 实战中的踩坑记录

最后写几个我印象最深的坑。

第一个坑是控制柄的长度缩放。我一开始图省事，把controlIn和controlOut的长度都做成固定的30px，拖拽控制柄的时候只改角度、不改长度。结果画出来的曲线全是圆头圆脑的包子形，弧线缺少张力，想画一个拉长的花瓣形完全做不到。后来改成控制柄长度与鼠标拖拽距离成正比，这才解决了问题。

第二个坑是smooth锚点在拖拽时逐帧重算另一半控制柄的逻辑。在快速拖拽的时候，响应式对象的更新会导致渲染线程频繁触发，如果不做requestAnimationFrame合并，帧数会肉眼可见地往下掉。这个坑估计所有做Canvas编辑器的人都会碰到，解决起来也不复杂，就是要在所有write操作的外层包一层节流。

第三个坑是最容易被忽略的：Canvas的context状态泄漏。绘制路径的时候如果用了ctx.save()和ctx.restore()，一定要成对出现。我在绘制路径描边的时候加了阴影，忘了restore，后面的所有锚点渲染全部带着阴影，整个画布性能崩了。排查了半天才发现是上一帧的ctx状态没有还原。这个坑很隐蔽，因为视觉上只是一点点模糊，但性能下降幅度大，很容易误判成别的性能问题。

第四个坑关于数组索引。在做锚点拖拽这种高频操作时，如果使用splice或者按索引修改数组项，Vue3的响应式追踪其实能正常工作，但如果你用arr[index] = newValue来整体替换锚点对象，视图不会更新。这就是Vue3响应式拦截器的一个特性：数组索引的追踪只对已有位置的读取有效，新增或替换要使用splice。做历史记录快照恢复的时候尤其容易踩到这个坑，因为恢复通常就是整体替换数组。

10. 项目收尾的个人心得

钢笔工具这种功能，我从数据模型设计到交互调优，前前后后改了三版。第一版数据结构设计得太简单，控制柄就单独拎了两个字段，结果平滑锚点同步镜像的功能根本没法写，因为不知道另一头控制柄的原始长度。第二版引入了锚点类型，但没处理拖拽过程的临时状态，每次mouseup才更新store，预览曲线拖拽时严重掉帧。第三版才稳定下来，也就是前面写的这套方案。

现在回看整个项目，我认为最值得琢磨的部分是数据结构怎么设计。很多初学者一上来就想着“怎么画出好看的曲线”，但真正决定工具天花板的其实是“锚点、控制柄、路径类型”这三者之间的关系怎么定义。关系定义清晰了，后续加多少功能都是顺水推舟。数据结构定义不好，光一个曲线编辑就能把你折磨到怀疑人生。

如果你正在做类似的东西，我的建议是：先把锚点类型和控制柄的同步逻辑想明白，再动笔写Canvas渲染代码也完全来得及。另外，Vue3在这种场景下确实是个好选择——响应式数据和Canvas渲染层的结合，至少让我在写交互逻辑的时候省了一半的心。