浏览器标注功能优化实战：坐标系统、Canvas渲染与性能调优

Hermes Studio 的浏览器标注功能，是用来在页面元素、设计稿或者截图区域上快速画矩形、箭头和文字注释的模块。最初它只承担评审阶段的临时标记工作，功能简单，效果也勉强够用。但随着使用人数增加，标注位置漂移、高分屏模糊、触控设备无法拖动以及批量标注后卡顿这些反馈开始集中出现，于是对 Hermes Studio 的浏览器标注功能做了一轮系统优化。

这篇文章会围绕浏览器标注功能从基线实现到优化落地的完整过程展开，重点说明坐标系统怎么设计、Canvas 渲染层怎么处理高分屏和滚动、指针事件怎么兼容鼠标与触控，以及标注数量增加后怎么保持流畅。适合正在做页面批注、图片标记、元素高亮类功能的开发者阅读。读完以后，可以把文章里的坐标换算、渲染裁剪和生命周期管理思路直接用到自己的项目里。

1. 先选对标注形态，否则后续优化都是在补窟窿

浏览器端标注功能有很多种实现思路。如果不先想清楚使用场景，后续所有优化都会为了弥补基础架构的缺陷而反复返工。所以优化 Hermes Studio 标注功能之前，先明确页面里可能出现的标注形态。

1.1 DOM 覆盖层：实现简单，适合元素级注释

DOM 覆盖层方案是在目标节点上插入高亮 div、气泡、遮罩层。缺点也很直接：标注图形会参与页面布局和样式继承，一旦页面结构变化，覆盖节点可能找不到宿主元素，定位也随之失效。

DOM 覆盖层适合做“元素级提示”，比如某个按钮旁边挂一个说明气泡，或者用 outline 高亮表单字段。它不适合绘制自由形状，因为每个矩形、箭头都要创建节点，标注数量一多，DOM 节点数就会膨胀，重排成本很高。

1.2 Canvas 或 SVG 覆盖层：适合任意图形，但坐标要同步

Canvas 覆盖层是创建一个透明画布铺在页面上层，所有标注通过 Canvas 2D API 绘制。Canvas 是位图渲染，标注数量多时性能更稳定，也比较容易导出图片。

SVG 覆盖层和 Canvas 类似，但每个图形都是独立 DOM 元素，交互和拾取更灵活。缺点是节点数量同样会占用内存，并且复杂 SVG 图形的渲染成本不高但也不低。

Canvas 和 SVG 的共同难题是坐标同步。标注图形要跟随页面滚动和缩放，覆盖层尺寸要随时和视口保持一致，否则绘制的位置和回显的位置会出现偏差。

1.3 截图后标注：实现容易，但无法跟随页面变化

另一种思路是对当前页面截图，再在图片上覆盖标注层。这种方式不依赖页面 DOM，代码最简单，可以用第三方库快速实现。但问题也很明显：截图是静态画面，页面滚动、展开折叠、窗口 resize 之后，标注和真实元素的位置就完全对不上了。

截图标注适合“对最终效果图做批注”的场景，不适合“在真实页面上标注后还要交给人继续操作”的场景。

1.4 Hermes Studio 为什么选择 Canvas 加 DOM 混合方案

Hermes Studio 的标注功能需要同时满足两个需求：一是在真实页面上标注矩形和箭头，二是对设计稿图片追加文字批注。单一方案无法同时覆盖。

最终采用的思路是：使用一个全屏 Canvas 覆盖层负责图形标注，同时保留轻量 DOM 气泡用于文字说明。Canvas 负责矩形、箭头、高亮区域，DOM 气泡只在用户查看或编辑文字时出现，避免大量文字节点影响性能。

这里的关键判断是：Canvas 覆盖层只管“画”，不管“页面元素是谁”。页面结构和标注数据通过坐标关联，不通过 DOM 引用关联，这样即使页面 DOM 变化，标注数据也不会丢失。

2. 基线实现：先跑通最简标注流程

优化不是从零重写，而是先让一个最简标注流程跑通，再逐项优化。Hermes Studio 的基线版本包含：创建 Canvas 覆盖层、绘制矩形、保存标注数据、回显标注。

2.1 技术栈与目录结构

基线版本使用 TypeScript 编写，构建工具为 Vite，运行环境是 Chromium 内核浏览器。目录结构设计成模块化，方便后续扩展渲染器和历史记录。

src/ annotations/ Annotation.ts AnnotationCanvas.ts createOverlay.ts renderer.ts history.ts

每个模块只负责一件事：

• Annotation.ts 定义标注数据结构。
• createOverlay.ts 负责创建和销毁 Canvas 覆盖层。
• AnnotationCanvas.ts 负责事件绑定和标注生命周期。
• renderer.ts 负责把标注数据绘制到 Canvas。
• history.ts 实现撤销重做的数据栈。

这样拆分以后，后续优化高性能渲染时，只需要改动 renderer.ts，不需要动事件模块。

2.2 先定义标注数据结构

标注数据设计是否合理，直接影响后续坐标换算、序列化和协同同步。基线版本使用下面这套结构。

export type AnnotationKind = 'rect' | 'arrow' | 'text'; export interface Annotation { id: string; kind: AnnotationKind; x: number; y: number; width: number; height: number; color: string; text?: string; createdAt: number; updatedAt: number; } export type AnnotationDraft = Omit<Annotation, 'id' | 'createdAt' | 'updatedAt'>;

这里最需要留意的是 x 和 y 的语义。基线版本中，x 和 y 存的是“文档坐标”，也就是相对整个文档左上角的位置，而不是相对当前浏览器视口左上角的位置。后面会专门解释为什么要这样存。

2.3 创建覆盖层并统一坐标换算

覆盖层需要铺满当前视口，并且使用固定定位，不参与页面布局。

export function createOverlay(): HTMLCanvasElement { const canvas = document.createElement('canvas'); canvas.style.cssText = [ 'position: fixed', 'left: 0', 'top: 0', 'z-index: 9999', 'pointer-events: auto' ].join(';'); document.body.appendChild(canvas); return canvas; }

坐标换算是浏览器标注功能最核心的部分。交互事件拿到的 clientX 和 clientY 是相对视口的坐标，而标注数据要保存成相对文档的坐标，这样滚动页面后标注不会偏移。

export function toDocumentPoint(clientX: number, clientY: number) { return { x: clientX + window.scrollX, y: clientY + window.scrollY }; } export function toScreenPoint(annotation: Pick<Annotation, 'x' | 'y'>) { return { x: annotation.x - window.scrollX, y: annotation.y - window.scrollY }; }

保存时用 toDocumentPoint，渲染时用 toScreenPoint。只要这两个函数保持一致，滚动带来的坐标漂移问题就能从根上解决。

2.4 用指针事件实现矩形绘制

基线版本直接使用 Pointer Events，而不是分别监听鼠标和触摸事件。Pointer Events 可以统一处理鼠标、触控笔和手指输入，后续优化触控体验时省去大量兼容代码。

export class AnnotationCanvas { private overlay: HTMLCanvasElement; private ctx: CanvasRenderingContext2D; private annotations: Annotation[] = []; private draft: AnnotationDraft | null = null; constructor() { this.overlay = createOverlay(); this.ctx = this.overlay.getContext('2d'); if (!this.ctx) { throw new Error('Canvas 2D context is not supported'); } this.resize(); this.bindEvents(); } private bindEvents() { this.overlay.addEventListener('pointerdown', this.handlePointerDown); this.overlay.addEventListener('pointermove', this.handlePointerMove); this.overlay.addEventListener('pointerup', this.handlePointerUp); } }

pointerup 需要绑定在 document 上，否则鼠标移出画布后松开，事件可能接收不到。更可靠的做法是在 pointerdown 时使用 setPointerCapture。

2.5 数据序列化与回显

标注数据需要保存到服务端或者本地存储，因此需要序列化。Hermes Studio 基线版本直接把标注数组序列化成 JSON 保存。

{ "version": 1, "annotations": [ { "id": "a1", "kind": "rect", "x": 320, "y": 180, "width": 200, "height": 120, "color": "#ff4d4f", "createdAt": 1710000000000, "updatedAt": 1710000000000 } ] }

回显逻辑就是遍历标注数组，把文档坐标转成屏幕坐标后绘制。基线版本到这里已经能完成“画一个矩形、保存、刷新后重新显示”的最小闭环。下一步优化，才是真正处理生产环境里遇到的问题。

3. 坐标漂移问题：滚动、缩放、容器变化

坐标漂移是浏览器标注功能最容易被反馈的问题。表现形式是：标注完成时位置正确，页面一滚动，标注就跑到了另外的位置。这个问题在基线版本里也可能出现，因为如果只处理了 clientX 到 document 坐标的转换，却没有处理渲染层的同步，漂移就依然存在。

3.1 问题现象描述

最常见现场是页面存在长滚动区域。用户在当前视口顶部画了一个红色矩形，标注的是页面顶部搜索按钮。向下滚动 1000 像素之后，红色矩形跑到当前视口中间，对应的搜索按钮已经在视口上方看不到的位置。

还有一种情况是窗口 resize 之后，Canvas 覆盖层尺寸没有更新，导致绘制区域比视口小，标注图形在视口边缘时无法完整显示。

3.2 根因：存储坐标和渲染坐标语义不一致

如果存储的是 clientX / clientY，那么数据本身就依赖“画标注那一刻”的滚动位置。一旦滚动值变化，旧标注的坐标点就失去意义。

如果渲染层始终用 document 坐标直接绘制到 canvas 上，没有减去 window.scrollX 和 window.scrollY，那么标注也会随着滚动失效。

排查坐标漂移问题时，先检查两件事：

• 保存坐标时是否调用 toDocumentPoint。
• 渲染坐标时是否调用 toScreenPoint。

只要任一处缺少转换，滚动后就会错位。

3.3 统一使用文档坐标存储、屏幕坐标渲染

修复后的核心逻辑是：存储永远用文档坐标，渲染永远用屏幕坐标。

public render() { const width = this.overlay.clientWidth; const height = this.overlay.clientHeight; this.ctx.clearRect(0, 0, width, height); for (const annotation of this.annotations) { const screen = toScreenPoint(annotation); this.drawAnnotation(annotation, screen); } }

drawAnnotation 内部只使用 screen.x 和 screen.y 作为 Canvas 绘制坐标，不再依赖任何全局状态。

这里要强调一点：toScreenPoint 每次渲染时都会读取 window.scrollX 和 window.scrollY。如果页面的滚动容器不是 window，而是某个嵌套 div，就需要把滚动元素暴露出来，在 toScreenPoint 里改成基于目标滚动元素的 scrollLeft 和 scrollTop。

3.4 用 ResizeObserver 监听容器尺寸变化

Canvas 覆盖层是 fixed 定位，窗口 resize 时需要重新设置 canvas.width 和 canvas.height。只用 window resize 事件虽然能满足大多数场景，但页面里有 iframe 或者 UI 框架动态调整侧边栏宽度时，viewport 可能不变，覆盖层尺寸也会受影响。

更稳妥的做法是使用 ResizeObserver 观察 overlay 的父节点或 body。

private handleResize = () => { this.resize(); this.render(); }; private observeResize() { this.resizeObserver = new ResizeObserver(this.handleResize); this.resizeObserver.observe(document.body); }

注意 ResizeObserver 回调触发后不能再次修改被观察元素的 size，否则可能造成循环触发。这里只修改 overlay 的 canvas 宽高，observer 观察的是 body，所以不会形成死循环。

3.5 验证坐标是否一致的实用方法

写一个临时调试函数，在滚动前后输出同一个标注的数据，可以快速确认坐标转换是否正确。

function debugAnnotation(annotation: Annotation) { const screen = toScreenPoint(annotation); const doc = toDocumentPoint(screen.x, screen.y); console.log({ stored: { x: annotation.x, y: annotation.y }, screen, restored: doc, scrollX: window.scrollX, scrollY: window.scrollY }); }

如果 stored 和 restored 一致，说明坐标转换是可逆的。之后再做滚动、缩放、窗口尺寸变化测试，标注位置都能保持稳定。

4. 绘制质量、触控交互和撤销重做

坐标问题解决后，标注功能已经基本可用。接下来要处理的是体验层面的问题：Canvas 在高分屏上模糊、触控设备无法拖动、鼠标松手后矩形意外丢失，以及撤销重做不完善。

4.1 高分屏 Canvas 模糊：必须处理 devicePixelRatio

在高分屏上，Canvas 的 CSS 尺寸和物理像素尺寸不一定一致。如果不做处理，画出来的线条边缘会发虚，看起来像整张画布被拉伸过。

修复方法是在设置 canvas 尺寸时乘上 devicePixelRatio，并在绘制前调用 ctx.scale。

private resize() { const dpr = window.devicePixelRatio || 1; const width = window.innerWidth; const height = window.innerHeight; this.overlay.style.width = `${width}px`; this.overlay.style.height = `${height}px`; this.overlay.width = Math.round(width * dpr); this.overlay.height = Math.round(height * dpr); this.ctx.setTransform(dpr, 0, 0, dpr, 0, 0); }

每次 resize 都要重新 setTransform，因为设置 canvas.width 或 canvas.height 会重置 Canvas 的变换状态。如果遗漏这一步，后续绘制坐标会被 dpr 放大，标注位置又会偏移。

4.2 鼠标事件改造成 Pointer Events，兼容触摸设备

基线版本已经使用 Pointer Events，但还需要处理细节：pointermove 和 pointerup 的绑定范围，以及 setPointerCapture 的使用。

正式实现时，pointerdown 后立刻把指针捕获到 overlay 上，保证后续 move 和 up 事件都派发给 overlay，即使指针移动到浏览器窗口边缘也不会丢事件。

private handlePointerDown = (event: PointerEvent) => { if (event.button !== 0 && event.pointerType === 'mouse') { return; } const point = toDocumentPoint(event.clientX, event.clientY); this.draft = { kind: 'rect', x: point.x, y: point.y, width: 0, height: 0, color: this.currentColor }; try { this.overlay.setPointerCapture(event.pointerId); } catch (error) { // 个别浏览器在异常状态下调用 setPointerCapture 会抛错，不影响主流程 } this.render(); };

这里还要处理一个常见问题：用户从右下角往左上角拖拽时，draft.width 和 draft.height 可能是负数。绘制时会得到反向矩形，视觉上非常别扭。处理方式是在绘制前对宽高做归一化，确保 x 始终是矩形左上角。

private handlePointerMove = (event: PointerEvent) => { if (!this.draft) return; const point = toDocumentPoint(event.clientX, event.clientY); const x = Math.min(this.draft.x, point.x); const y = Math.min(this.draft.y, point.y); const width = Math.abs(point.x - this.draft.x); const height = Math.abs(point.y - this.draft.y); this.draft.x = x; this.draft.y = y; this.draft.width = width; this.draft.height = height; this.render(); };

4.3 处理 touch-action 和用户选中冲突

触控设备上，手指在 Canvas 上滑动时，浏览器默认会把滑动手势解释为页面滚动或双击缩放。这会导致用户画矩形时页面跟着滚动。

在覆盖层的 CSS 中加入 touch-action: none，可以禁止浏览器对该区域的手势处理。

canvas.style.touchAction = 'none';

另外还需要阻止文本选中。用户连续快速绘制时，如果页面中有文本节点，可能会触发文本选择，干扰交互。推荐在绘制状态下临时给 body 添加 user-select 样式，或者统一在覆盖层上设置 user-select: none。

.annotation-overlay { touch-action: none; user-select: none; -webkit-user-select: none; }

4.4 撤销重做：用快照还是用命令模式

撤销重做的核心是保存历史状态。最直接的实现是每次完成一个标注后，把 annotations 数组的深拷贝压入 undo 栈。

export class AnnotationHistory { private undoStack: Annotation[][] = []; private redoStack: Annotation[][] = []; private limit = 50; push(snapshot: Annotation[]) { const copy = snapshot.map((item) => ({ ...item })); this.undoStack.push(copy); if (this.undoStack.length > this.limit) { this.undoStack.shift(); } this.redoStack = []; } undo(): Annotation[] | null { if (this.undoStack.length === 0) return null; const snapshot = this.undoStack.pop(); if (snapshot) { this.redoStack.push(snapshot); } return snapshot ?? null; } redo(): Annotation[] | null { if (this.redoStack.length === 0) return null; const snapshot = this.redoStack.pop(); if (snapshot) { this.undoStack.push(snapshot); } return snapshot ?? null; } }

快照方案在标注数量少于几百条时足够用。如果标注数量很大，或者每次操作后数组都要深拷贝，就需要改成命令模式，记录“新增”“删除”“修改”的操作对象，用操作反推历史。

5. 大量标注场景下的性能优化

当页面里出现几十、上百个标注时，如果每次滚动和 resize 都全量重绘所有标注，浏览器会明显掉帧。性能优化不是一上来就引入虚拟列表，而是先确认瓶颈在哪里。

5.1 使用 requestAnimationFrame 合并高频事件

scroll 和 resize 事件触发频率很高，不能每次事件都同步执行 render。推荐的做法是保存一个标记位，在下一帧执行时统一渲染。

private renderScheduled = false; private scheduleRender() { if (this.renderScheduled) return; this.renderScheduled = true; requestAnimationFrame(() => { this.render(); this.renderScheduled = false; }); }

事件回调里只调用 scheduleRender，render 函数本身保持同步绘制。这样即使滚动事件连续触发几十次，真正执行渲染的只有每帧一次。

5.2 按视口裁剪，减少无效绘制

当页面很长，标注分散在不同区域时，Canvas 绘制所有标注是浪费的。可以把坐标判断放在绘制前，只绘制与当前视口相交的标注。

private getVisibleAnnotations(): Annotation[] { const left = window.scrollX; const top = window.scrollY; const right = left + window.innerWidth; const bottom = top + window.innerHeight; return this.annotations.filter((annotation) => { return ( annotation.x + annotation.width > left && annotation.x < right && annotation.y + annotation.height > top && annotation.y < bottom ); }); }

这里的核心思路叫作“视口裁剪”。对于长度几万像素的页面，视口裁剪能明显减少绘制调用次数。这个优化对文本标注和箭头标注同样有效，因为箭头和文本都有 bounding box，可以先用外接矩形做粗过滤。

5.3 把静态标注和正在绘制的标注分层

正在绘制的 draft 每帧都会变化，而已完成的标注在滚动前不会变化。如果每次都把已完成标注全部重新绘制，浪费很大。

优化思路是使用两个 Canvas：

• 底层 Canvas 只绘制已完成的 static 标注。
• 上层 Canvas 只绘制当前正在绘制的 draft。

滚动或 resize 时重绘底层，指针移动时只重绘上层。这样交互响应会更快。代价是增加一个 Canvas 节点和对应的事件处理。

实现拆分前要先确认，浏览器对多个 Canvas 重叠渲染的内存开销是否在接受范围内。一般来说，两个全屏 Canvas 对现代浏览器压力不大。

5.4 销毁时清理监听器和 Canvas，避免内存泄漏

标注模块在单页应用里可能被反复创建和销毁。如果不清理全局事件，上一次实例的监听器还在运行，会造成多次渲染和内存泄漏。

销毁逻辑必须包含：

destroy() { this.resizeObserver?.disconnect(); this.overlay.removeEventListener('pointerdown', this.handlePointerDown); this.overlay.removeEventListener('pointermove', this.handlePointerMove); document.removeEventListener('pointerup', this.handlePointerUp); window.removeEventListener('resize', this.handleResize); window.removeEventListener('scroll', this.scheduleRender); this.overlay.remove(); }

注意事件处理函数必须是类字段，确保引用稳定，这样才能用 removeEventListener 精确移除。

6. 常见问题定位与浏览器兼容性

浏览器标注功能出现问题，大多数时候不是框架问题，而是坐标、事件、样式或生命周期问题。下面整理一份排查清单，遇到问题可以先按顺序检查。

6.1 常见问题现象与处理方案

6.2 按这条链路排查浏览器标注问题

标注功能出问题，排查顺序比排查单个变量更重要。建议按照下面流程来：

1. 检查是否有多个 Canvas 覆盖层实例叠加。单页应用路由切换后，旧实例没有销毁，新实例叠加在上方。
2. 检查坐标转换函数。保存和渲染必须使用互逆的转换，否则滚动一定出错。
3. 检查 Canvas 尺寸。如果 canvas.width 小于视口宽度，画布右侧会出现空白区域。
4. 检查 pointer 事件是否被页面其他元素拦截。很多 UI 库会调用 stopPropagation，导致 pointerdown 无法到达 overlay。
5. 检查 destroy 是否执行。重复进入页面会导致事件监听叠加，表现就是绘制一次生成多个标记。

6.3 浏览器兼容性注意事项

Pointer Events 在现代 Chrome、Edge、Firefox、Safari 中都能使用，但需要兼容旧版移动浏览器时，仍然要提供 MouseEvent 和 TouchEvent 的回退逻辑。

Canvas 的 getContext('2d') 在所有主流浏览器中都支持，但 toDataURL 导出图片时要注意：如果 Canvas 中绘制了来自其他域的图片资源，canvas 会被污染，toDataURL 会抛出 SecurityError。Hermes Studio 中标注图层只绘制几何图形和文字，不读取页面像素，所以不受污染问题影响。

建议在浏览器兼容测试中至少覆盖：

• 桌面端 Chrome、Edge、Firefox、Safari。
• 移动端 WebView 的 touch 事件。
• 页面使用 CSS transform 缩放后，标注坐标是否仍然正确。

CSS transform 缩放是比较容易忽略的边界情况。如果页面本身没有缩放，只需要处理滚动；如果页面有 scale 变换，坐标换算还要除以 scale 系数。

7. 生产环境落地和扩展方向

基线功能跑通、优化完成之后，浏览器标注功能要真正放到生产环境，还需要补齐不少工程能力。

7.1 从 Demo 到生产还需要补齐的能力

第一是数据持久化。标注数组要保存到服务端，至少要附带 version 字段，方便以后调整数据结构。前端拉取后通过 version 做迁移。

第二是权限控制。标注功能要区分“只读模式”和“编辑模式”。只读模式下 overlay 不绑定 pointer 事件，Canvas 只负责回显。

第三是记录操作日志。用户在评审场景中对同一页面反复标注，编辑历史需要留存。每次新增、删除、修改都提交一条日志，方便追溯。

第四是多人协作。多用户同时标注同一个页面时，需要 WebSocket 同步标注数据。推荐为每条标注生成 ID，并通过 updatedAt 决定冲突时的合并策略。

7.2 发布前检查清单

以下是 Hermes Studio 标注功能发布前使用的检查清单，也可以直接用于自己的项目。

• Canvas 覆盖层创建后是否只存在一个实例。
• 坐标转换是否统一使用文档坐标存储、屏幕坐标渲染。
• devicePixelRatio 变化时（比如拖拽窗口到高分屏）是否重新 resize。
• 滚动、resize、缩放后标注位置是否与页面元素对齐。
• touch-action 和 user-select 是否配置。
• pointermove 和 pointerup 是否在 destroy 时解绑。
• 大量标注场景下是否启用视口裁剪。
• Canvas 导出图片时是否被跨域资源污染。
• 只读模式下 overlay 的 pointer-events 是否设置为 none。
• 数据持久化字段是否包含 version，便于后续迁移。

7.3 从标注图形到完整批注系统

浏览器标注功能优化完成后，可以继续向完整批注系统扩展。比较有价值的三个方向是：

• 矢量导出：把 Canvas 标注转换为 SVG 或 JSON 描述，服务端可以生成可编辑的批注图层。
• AI 辅助标注：根据元素文本和位置自动生成建议标签，降低人工标注成本。
• 多页面标注：同一测试任务包含多个 URL，将标注数据和页面 URL 关联，形成完整评审记录。

如果浏览器标注功能是项目里的核心交互之一，建议把坐标转换和渲染器拆成独立模块，并用单元测试覆盖滚动、缩放和窗口变化场景。这样后续增加图形类型、接入协同协议时，底层的稳定性不会成为瓶颈。