vue3-sketch-ruler v3 升级详解：从 Vue 组件到跨框架标尺引擎
本文面向使用 vue3-sketch-ruler 的开发者，系统梳理 v3.x 相较于 v2.x 的架构变化、新增能力与迁移要点。
一、v3 的核心定位：从"Vue 组件"到"框架无关的标尺引擎"
v2.x 时代的 vue3-sketch-ruler 是一个纯粹的 Vue 3 组件库，缩放与平移能力依赖外部包 simple-panzoom，所有逻辑与 Vue 的响应式系统耦合在一起。
v3.x 彻底推翻了这个架构，将其重构为一个分层、可跨框架复用的标尺引擎：
| 层级 | 包名 | 职责 | 框架依赖 |
|---|---|---|---|
| 核心层 | @sketch-ruler/core | TransformEngine、状态管理、插件系统、吸附引擎、刻度计算 | 零外部依赖 |
| 渲染层 | @sketch-ruler/canvas | Canvas 2D 渲染、鼠标/键盘/滚轮输入管理 | 仅依赖 core |
| UI 适配层 | vue3-sketch-ruler | Vue 3 组件、composables、插槽封装 | Vue 3 |
这意味着：Vue 和 React 可以共用同一套核心逻辑。v3 发布后，基于 @sketch-ruler/core + @sketch-ruler/canvas 的 React 版本 react-sketch-ruler 也随之诞生，验证了这一架构的可行性。
二、插件系统：让标尺具备"可编程"能力
v3 最重要的新增能力之一是插件系统。它不再只是把标尺当做一个静态 UI 组件，而是提供了一套完整的生命周期钩子，让开发者可以在缩放、平移、参考线操作等关键节点插入自定义逻辑。
2.1 插件能做什么
插件通过 PluginManager 统一管理，每个插件可以注册以下钩子：
| 钩子名 | 触发时机 | 用途 |
|---|---|---|
beforeZoom | 缩放操作执行前 | 拦截非法缩放、记录操作日志、动态调整缩放限制 |
afterZoom | 缩放操作完成后 | 同步外部状态、触发自定义动画 |
beforePan | 平移操作执行前 | 限制平移边界、实现边界回弹 |
afterPan | 平移操作完成后 | 保存视口位置到 URL、联动其他组件 |
onLineCreate | 参考线创建时 | 自动命名、持久化到服务端 |
onLineMove | 参考线拖拽移动时 | 实时吸附提示、碰撞检测 |
onLineDelete | 参考线删除时 | 确认弹窗、撤销栈记录 |
2.2 拦截与优先级
插件支持两个关键机制：
1. 操作拦截（ctx.cancel()）
const limitZoomPlugin = {
name: 'limit-zoom',
beforeZoom: (ctx) => {
if (ctx.nextScale > 3) {
ctx.cancel() // 阻止本次缩放
}
}
}
2. 优先级控制（priority）
当多个插件注册同一钩子时，按 priority 升序执行。高优先级的插件可以先做拦截判断，低优先级的插件负责后续副作用：
const plugins = [
{ name: 'auth-check', priority: 1, beforeZoom: (ctx) => { /* 权限校验 */ } },
{ name: 'analytics', priority: 99, afterZoom: (ctx) => { /* 埋点上报 */ } }
]
2.3 与 v2.x 的对比
v2.x 完全没有插件机制。如果你想在缩放前后做点事情，只能hack panzoomInstance 的事件监听，既不稳定也不可控。v3 的插件系统把这一切变成了声明式的、类型安全的正式 API。
三、v3.x 新增了哪些能力
3.1 内置 TransformEngine（零外部 panzoom 依赖）
v2.x 依赖 simple-panzoom 处理所有变换逻辑，带来了几个问题：
- 额外依赖增加包体积
panzoomOption配置复杂且与组件 props 割裂- 缩放原点漂移、边界处理等 bug 难以自行修复
v3 自研了 TransformEngine，基于矩阵运算直接管理 scale / x / y 三种状态，支持：
- 鼠标中心缩放（
pointer） - 视口中心缩放（
viewport-center） - 内容中心缩放（
content-center）
配置也从晦涩的 panzoomOption 变成了直观的 zoomMode、zoomStep、minZoom、maxZoom。
3.2 Minimap 缩略图导航
v3 新增了独立的 Minimap 组件，提供 Photoshop 式的缩略图导航：
- 实时显示内容区域与当前视口位置
- 支持拖拽视口框快速定位
- 支持点击缩略图任意位置跳转
<Minimap
:content-width="canvasWidth"
:content-height="canvasHeight"
:viewport-x="offset.x"
:viewport-y="offset.y"
:scale="scale"
@navigate="handleNavigate"
/>
v2.x 没有这一能力，需要开发者自行实现。
3.3 动画引擎
v3 内置了四种动画模式，让缩放和平移更顺滑：
| 模式 | 效果 | 适用场景 |
|---|---|---|
direct | 无动画，瞬时到达 | 追求响应速度 |
ease-out | 减速缓动 | 常规缩放 |
damped | 阻尼衰减 | 弹性回弹效果 |
exponential | 指数衰减 | 快速定位后平滑收尾 |
通过 enableAnimation + animationMode 两个 props 即可开启，v2.x 完全不支持动画。
3.4 吸附引擎（SnapEngine）
参考线拖拽时，v3 会自动吸附到邻近刻度或已有参考线：
<SketchRuler :snap-threshold="5" />
吸附阈值可配置，吸附时会有视觉反馈。v2.x 没有吸附能力，参考线只能自由放置。
3.5 自动居中（autoCenter）
v3 新增了 autoCenter prop，初始化时自动将内容居中到视口，无需手动计算 startX / startY：
<SketchRuler :auto-center="true" :initial-offset="{ x: 0, y: 0 }" />
v2.x 依赖 panzoom 的 startX/startY，配置繁琐且行为不一致。
3.6 阴影高亮区域（shadow）
v3 支持配置一个高亮阴影区域，用于标识选中元素或画布边界：
<SketchRuler :shadow="{ x: 100, y: 100, width: 500, height: 300 }" />
3.7 多画布管理器（CanvasManager）
@sketch-ruler/core 提供了 CanvasManager，支持同时管理多个画布实例的状态，为大屏编辑器、多页面设计器等场景提供底层支持。
3.8 增强的双向绑定
v3 扩展了 v-model 的能力：
| 绑定项 | v2.x | v3.x |
|---|---|---|
| 缩放 | v-model:scale | v-model:scale（保留） |
| 偏移 | 无 | v-model:offset（新增） |
| 参考线锁定 | 无 | v-model:lockLine（新增） |
| 缩放/平移变化事件 | zoomStart | zoomchange（返回 { scale, x, y }） |
3.9 工具栏插槽重构
v2.x 的 #btn 插槽只暴露 reset、zoomIn、zoomOut 三个方法。v3 的 #toolbar 插槽提供了完整的 tools 和 state：
<template #toolbar="{ tools, state }">
<button @click="tools.reset">还原</button>
<button @click="tools.zoomToPreset(1)">100%</button>
<button @click="tools.setZoomMode('viewport-center')">视口居中缩放</button>
<button @click="tools.toggleReferLine">显示/隐藏参考线</button>
<span>{{ (state.scale * 100).toFixed(0) }}%</span>
</template>
npx vue3-sketch-ruler-migrate <path>
五、总结
v3.x 不是一次简单的功能迭代，而是一次架构层面的彻底重构。它解决了 v2.x 的三个核心痛点：
- 外部依赖耦合 —— 自研 TransformEngine 替代 simple-panzoom，零外部依赖，缩放原点控制更精确
- 逻辑与框架绑定 —— 核心逻辑下沉到
@sketch-ruler/core，Vue/React 只是薄 UI 层 - 扩展性不足 —— 插件系统让标尺从"静态组件"变成了"可编程引擎"
对于仍在使用 v2.x 的项目，建议评估以下收益后决定是否升级：
- 需要 Minimap、动画、吸附等新能力 → 强烈推荐升级
- 项目稳定且仅需基础标尺功能 → 可暂缓，但需留意 v2.x 不再迭代
- 有跨框架（React/Vue）复用需求 → 必须升级，v3 的 core/canvas 分层是唯一能复用逻辑的方案
体验地址: vue3-sketch-ruler
文章基于 vue3-sketch-ruler v3.x 源码与 README 迁移指南整理。
