前言
时隔 5 年，断断续续花了亿些时间完成了 js-screen-shot 项目的重构，这个插件最早的目标很简单：在 Web 端实现一个类似 QQ / 微信截图的功能。用户可以框选区域，然后在画布里画矩形、圆形、箭头、画笔、马赛克、文字，最后保存截图内容。
随着功能越来越多，再加上那会儿我的技术水平还不够好，架构设计的比较差，代码也不可避免地变复杂了。尤其是后面加入了 WebRTC 截屏、自定义工具栏、图片模式、Electron 适配等能力后，入口文件越堆越大。
插件从发布到现在，NPM 的周下载量保持在 1000+，同时有很多人反馈说画布里的内容无法二次编辑，于是就有了本次重构计划：让画布内的元素真正变成可管理、可选中、可移动、可重绘的对象。
本文就跟大家分享下我这次重构截图插件的整体思路、用到的技术点，以及过程中遇到的一些坑，欢迎各位感兴趣的开发者阅读本文。
为什么要重构
我们先来看下重构前的结构。
早期版本的核心目录大致如下：
src
├── main.ts
└── lib
├── main-entrance
│ ├── CreateDom.ts
│ ├── InitData.ts
│ └── PlugInParameters.ts
├── split-methods
├── common-methods
└── type
└── ComponentType.ts
这个结构在功能少的时候是可以接受的，main.ts 负责串联整个截图流程，split-methods 存放绘制逻辑，common-methods 存放一些公共方法，InitData 管理插件运行时数据。
但是当功能继续增加后，它逐渐暴露出了几个问题。
main.ts 变得太重
未重构前，在 pre_release 分支中，main.ts 已经有 1500 多行代码。
里面同时处理了：
这会导致一个很直接的问题：任何功能都能改到入口文件。
比如：我只是想优化一下鼠标移动时的命中判断，都需要在 main.ts 里翻很久，因为它既包含画布状态，也包含工具栏状态，还包含 DOM 结构。
状态管理过于集中
旧版本里大量状态集中在 InitData.ts 中，通过模块级变量保存。
let dragging = false;
let toolClickStatus = false;
let selectedColor = "#F53340";
let toolName = "";
let penSize = 2;
let history: Array> = [];
let cutOutBoxPosition = {
startX: 0,
startY: 0,
width: 0,
height: 0
};
这种方式写起来很快，但后期维护会比较痛苦。
因为这些状态虽然都跟截图有关，但它们的职责并不一样，零零散散的包含了：
当它们全部放在一起时，代码很难看出一个状态到底属于哪个模块，也很难判断修改它会影响哪些地方。
画布内容不可二次编辑
旧版本的绘制逻辑是：“直接画到 canvas 上”。比如用户画了一个矩形，代码会立刻在 canvas 上画线，然后通过 ImageData 保存历史记录，这种方式做撤销很容易，但是要做“二次编辑”就是个大工程了。
小科普：因为 canvas 本身是位图，它并不知道上面哪个区域是矩形、哪个区域是箭头、哪个区域是文字。你一旦画上去，它就变成了像素。所以要支持选中、移动、缩放、删除，就必须额外维护一份“画布元素数据”。
重构后的目录结构
这次重构后，核心目录变成了下面这样：
src
├── main.ts
├── store
│ ├── CropBoxStore.ts
│ ├── DrawingDataStore.ts
│ ├── ScreenShotCanvasStore.ts
│ ├── TextInputStore.ts
│ ├── ToolBarStore.ts
│ ├── UserParamStore.ts
│ └── dom
├── lib
│ ├── application
│ ├── constants
│ ├── features
│ ├── shared
│ ├── type
│ └── utils
└── tests
入口文件 main.ts 从原来的 1500 多行降到了 200 多行，它现在更像是一个调度器，只负责把各个模块串起来。
export default class ScreenShot {
constructor(options: ScreenShotOptions) {
const normalizedOptions = normalizeScreenShotOptions(options);
setPlugInParameters(normalizedOptions);
new CreateDom(normalizedOptions);
screenDomStore.initWebRtcDom();
setOptionalParameter(normalizedOptions);
screenDomStore.hydrateDomRefs();
toolPanelDomStore.hydrateDomRefs();
this.load(normalizedOptions);
}
}
这样调整后，入口文件不再关心具体怎么画矩形、怎么判断箭头命中、怎么移动文字，它只负责组织流程。
我的重构思路
这次重构我主要按下面几个方向推进。
按业务流程拆 application 层
application 目录负责插件运行流程。
src/lib/application
├── core
│ ├── ScreenFlowLoader.ts
│ ├── ScreenFrameDrawer.ts
│ ├── ScreenInitializer.ts
│ ├── ScreenShotModeExecutor.ts
│ ├── ScreenShotModeResolver.ts
│ ├── ScreenSourceManager.ts
│ └── UiCoordinator.ts
├── mouse
│ ├── CanvasMouseClickHandlers.ts
│ ├── CanvasMouseDownHandlers.ts
│ ├── CanvasMouseMoveHandlers.ts
│ ├── ToolbarDrawingHandler.ts
│ └── CustomToolEventBridge.ts
└── CreateDom.ts
这一层解决的是“截图流程怎么跑起来”的问题。
比如截图源加载，旧版本会在入口文件里判断 enableWebRtc、imgSrc、screenFlow 等参数。现在我把这块整理成了截图模式解析和执行流程。
const plan = resolveScreenShotPlan();
executeLoadPlan(
plan,
mouseEvents,
context,
triggerCallback,
cancelCallback,
() => this.screenShotImageController,
canvas => {
this.screenShotImageController = canvas;
}
);
这样后续如果要继续增加新的截图来源，不需要继续往 main.ts 里塞条件判断，而是扩展模式解析和执行器。
按功能拆 features 层
features 目录负责具体能力，比如绘制、配置处理、事件处理、历史记录。
src/lib/features/canvas
├── calculations
├── config
├── drawing
├── events
├── state
└── utils
这里面比较特殊的是 drawing 目录，它只处理 canvas 绘制。
drawing
├── DrawArrow.ts
├── DrawCircle.ts
├── DrawCutOutBox.ts
├── DrawImgToCanvas.ts
├── DrawLineArrow.ts
├── DrawMasking.ts
├── DrawMosaic.ts
├── DrawPencil.ts
├── DrawRectangle.ts
└── DrawText.ts
原来这些文件放在 split-methods 下面，名字虽然是拆开了，但从目录上看不出它们属于哪个业务模块。现在放到 features/canvas/drawing 后，职责会更明确：这些文件就是 canvas 绘制能力。
把可复用能力放到 shared 层
shared 目录放的是跨流程复用的能力。
比如：
src/lib/shared
├── canvas
│ ├── CanvasElementHitTest.ts
│ ├── CanvasElementSelection.ts
│ ├── CanvasElementTransform.ts
│ ├── CanvasElementToolbarSync.ts
│ ├── CustomCanvasElementUtils.ts
│ └── TextEditingController.ts
├── dom
├── platform
├── text
└── ui
这里最核心的是 shared/canvas。
因为这次大版本更新的重点是“画布内元素可二次编辑”，选中、命中检测、拖拽、缩放、重绘这些逻辑并不属于某一个具体工具，它们是所有画布元素都要复用的能力。
使用 Store 拆分运行时状态
为了尽可能的轻量化，这次我选择引入 mobx 来做全局的状态管理。
以前 InitData 里面放了所有状态，现在拆成了多个 store：
src/store
├── CropBoxStore.ts
├── DrawingDataStore.ts
├── ScreenShotCanvasStore.ts
├── TextInputStore.ts
├── ToolBarStore.ts
├── UserParamStore.ts
└── dom
├── ScreenDomStore.ts
└── ToolPanelDomStore.ts
这样拆完后，每个 store 的职责就比较清楚了。
其中 DrawingDataStore 是这次改动的核心。
canvasElements: [],
activeElementId: null,
rectOperateIndex: null,
editingTextElementId: null,
pendingEditingTextElement: null
这些状态让画布上的内容从“像素”变成了“元素对象”。
画布元素二次编辑是怎么实现的
canvas 的难点在于：它不会帮你保存图形对象。
当你在 canvas 上画了一个矩形，它只知道某些像素变成了红色，并不知道这里原来是一个矩形。
所以，这次我为每个绘制内容都维护了一份快照。
export interface BaseCanvasElement {
id: string;
x: number;
y: number;
drawNode?: boolean;
dotRadius?: number;
}
export interface SquareElement extends BaseCanvasElement {
width: number;
height: number;
borderWidth: number;
color: string;
}
export interface TextElement extends BaseCanvasElement {
width: number;
height: number;
color: string;
fontSize: number;
text: string;
borderWidth: number;
}
画布中的元素会统一存到 canvasElements 中。
export type CanvasElement =
| SquareElement
| RoundElement
| LineArrowElement
| ArrowElement
| PencilElement
| MosaicElement
| TextElement
| CustomCanvasElement;
当用户绘制时，流程变成了这样：
这样做以后，移动和缩放就不是去“移动像素”，而是修改元素数据，然后清空画布重新绘制。
clearCanvasSurface();
drawingDataStore.redrawCanvasElements();
这也是 canvas 编辑器比较常见的实现方式：数据驱动画布重绘。
元素选中与命中检测
支持二次编辑后，第一个要解决的问题就是：鼠标点下去时，怎么知道点中了哪个元素？
由于不同元素的命中规则是不一样的，矩形可以判断鼠标是否在边框附近，圆形要判断是否在椭圆边缘，箭头要判断鼠标是否在箭头线段附近，文字和画笔更适合用包围盒处理。
因此我把这块放到了 DrawingDataStore 和 CanvasElementSelection 中统一处理。
drawingDataStore.checkMouseInElement(x, y, elementId => {
if (elementId) {
selectCanvasElementBorder(elementId, dotRadius);
}
});
选中元素后，会记录当前选中的元素 ID 。
drawingDataStore.updateActiveElementId(canvasElement.id);
并且给当前元素打上 drawNode 标识，重绘时根据这个标识画出选中边框和操作节点。
这块实现后，矩形、圆形、箭头、画笔、文字、自定义元素都可以进入同一套选中逻辑。
元素移动与缩放
移动元素的核心逻辑放在 CanvasElementTransform.ts。
它并不直接操作 DOM ，也不直接关心鼠标事件，只接收当前鼠标位置、拖拽偏移量和目标元素 ID 。
export const moveCanvasElementOnCanvas = (
mouseX: number,
mouseY: number,
dragOffset: { x: number; y: number },
elementId: string | null
) => {
const targetElement = resolveCanvasElement(elementId);
if (targetElement == null) return;
drawingDataStore.updateDrawStatus(true);
clearCanvasSurface();
// 根据元素类型更新位置
// ...
drawingDataStore.redrawCanvasElements();
};
矩形和文字这类元素比较简单，只需要更新 x / y。
箭头就要麻烦一些，因为它除了包围盒，还有起点、终点、箭头顶点等信息。
画笔和马赛克也不能只更新包围盒，还要把内部的点位一起平移。
points: originalPoints.map(point => ({
x: point.x + deltaX,
y: point.y + deltaY
}))
这也是这次重构里比较容易踩坑的地方：不同元素看起来都叫移动，但内部数据结构并不一样。
如果强行用一套 x / y / width / height 处理所有元素，箭头、画笔、马赛克很快就会出问题。
自定义工具如何接入编辑逻辑
旧版本已经支持用户自定义工具栏，但那时的自定义工具是“把 canvas 暴露出去，让用户自己画”。
这种方式虽然灵活，但它画出来的内容无法进入插件内部的编辑系统。
这次重构后，我增加了 customElementAdapters 和 customElementApi。
自定义元素需要满足一个基础结构：
export interface CustomCanvasElement extends BaseCanvasElement {
customType: "custom";
width: number;
height: number;
toolId?: number;
toolName?: string;
payload?: unknown;
}
插件内部会给自定义工具回调传入一组 API：
export type CustomCanvasElementApi = {
addElement: (input: CustomCanvasElementInput) => CanvasElementSnapshot | null;
updateElement: (element: CanvasElement) => void;
removeElement: (id: string) => void;
selectElement: (id: string) => boolean;
getElement: (id: string) => CanvasElementSnapshot | undefined;
getActiveElement: () => CanvasElementSnapshot | undefined;
redraw: () => void;
};
用户自定义工具在绘制完成后，不再只是把内容画到 canvas 上，而是可以通过 addElement 把元素注册进插件内部。
同时，用户可以通过 adapter 告诉插件这个元素如何绘制、如何命中、如何移动、如何缩放。
export type CustomCanvasElementAdapter = {
draw: (
element: CustomCanvasElement,
context: CanvasRenderingContext2D
) => void;
hitTest?: (
element: CustomCanvasElement,
point: { x: number; y: number }
) => boolean;
move?: (
element: CustomCanvasElement,
delta: { x: number; y: number },
bounds: CropBoxBounds
) => CustomCanvasElement | void;
resize?: (
element: CustomCanvasElement,
handleIndex: number,
point: { x: number; y: number },
bounds: CropBoxBounds
) => CustomCanvasElement | void;
};
这样做之后，自定义元素就不再是插件体系外的“自由绘制内容”，而是可以进入统一的选中、移动、重绘、删除逻辑。
比如五角星这种自定义图形，就可以通过 draw 负责画星星，通过 hitTest 判断鼠标是否点中，通过 move 控制移动边界。
有关此处的使用，详细文档请移步：工具栏模块化扩展
优化截图源配置定义
这次还顺手整理了截图源的配置传入字段，以前配置项比较分散，比如：
这些参数都是在描述截图来源和渲染方式，但分散在多个字段里，后面继续扩展会越来越难理解。
因此现在增加了一个新的 capture 配置。
export type ScreenShotCaptureOptions = {
source?: "display-media" | "injected-stream" | "dom" | "image";
render?: "browser-frame" | "window-frame";
stream?: MediaStream;
imageSrc?: string;
};
处于兼容性考虑，插件内部会先把新旧参数统一归一化。
const normalizedOptions = normalizeScreenShotOptions(options);
如果用户继续使用旧参数，插件仍然兼容，只是内部会统一转成新的截图模式。
这块的好处是后面如果继续扩展截图来源，比如增加新的图片输入方式，或者增加某种自定义渲染模式，不需要再让入口文件继续膨胀。
这次遇到的几个坑
整个重构过程中自然遇到了一些问题，这里简单跟大家分享下。
选中态必须在正确时机清理
做元素编辑时，一开始很容易出现一个 bug：用户选中了一个旧元素，然后开始画新元素，旧元素的选中边框还在。
这个问题本质上是状态没有归属清楚。
现在的处理方式是：开始绘制新元素前，需要先清理当前选中元素的状态。
drawingDataStore.updateActiveElementId(null);
drawingDataStore.updateRectOperateIndex(null);
drawingDataStore.resetCanvasElementNodeState();
否则用户看到的就是“我明明在画新矩形，但旧元素还处于选中状态”。
这类问题不是 canvas 绘制问题，而是交互状态问题。
拖拽已有元素后，要切换当前选中元素
另一个问题是：如果当前已经选中了 A 元素，然后用户直接拖拽 B 元素，拖拽结束后应该选中 B 。
这个逻辑看起来很自然，但实现时要注意鼠标按下、移动、抬起之间的状态传递。
现在我用一个 pointerSession 保存本次指针操作的信息。
const pointerSession = {
prevElementId: null,
dragOffset: { x: 0, y: 0 },
transformingExisting: false
};
这样在 mousedown 时确认命中的元素，在 mousemove 时移动这个元素，在 mouseup 时完成本次编辑状态同步。
文字编辑不能只当普通矩形处理
设计文字元素结构对象的时候，它看起来也有 x / y / width / height，于是我就想把它纳入普通矩形去，实际做的时候，发现它还涉及输入框、文本内容、字号、二次编辑。就出现了两个问题：
最后只好将文字相关逻辑拆到 shared/text 和 TextEditingController 中，单独处理文本输入、提交、点击编辑等流程。
canvas 历史记录不能只保存 ImageData
旧版本的撤销主要依赖 ImageData。
但是做二次编辑后，只保存 ImageData 不够了。
因为画布元素还存在于 canvasElements 中，如果撤销时只恢复像素，不恢复元素数据，用户下一次选中、移动、删除时就会出现数据和画面不一致的问题。
所以现在历史记录需要同时保存画布像素和元素快照。
{
data: imageData,
canvasElements: [...]
}
注意：这点非常重要。只要你的 canvas 是“可编辑画布”，就不能只把它当成图片处理。
构建和开发体验优化
除了业务代码，这次也顺手调整了构建体验。
包管理器从原来的 yarn 切到了 pnpm，并在 package.json 中固定了版本。
{
"packageManager": "[email protected]"
}
Rollup 构建也做了一些优化，比如显式配置 babelHelpers，减少无意义警告；开发构建时输出更清晰的进度信息；启动时打印项目名，让终端输出更容易识别。
babel({
babelHelpers: "bundled"
})
这些不是核心功能，但对维护项目很重要。
我做事情喜欢做到极致，在开发阶段我会消除所有的警告，让后续的调试、构建、发布都尽量顺手。
项目地址
这次重构最大的变化，是把截图插件从“过程式地操作 canvas”调整成了“用数据描述画布元素，再根据数据重绘 canvas”。
简单来说，就是从：
用户操作 -> 直接画到 canvas -> 保存像素历史
变成：
用户操作 -> 更新元素数据 -> 清空画布 -> 根据元素数据重绘 -> 保存像素和元素快照
这个变化带来的收益非常明显：
当然，代价也有。
二次编辑会让 canvas 逻辑复杂很多，尤其是不同元素的命中检测、移动、缩放、历史记录同步，都需要单独处理。
但从长期维护角度看，这是值得的。
写在最后
至此，文章就分享完毕了。
我是神奇的程序员，一位前端开发工程师。
如果你对我感兴趣，请移步我的个人网站，进一步了解。
