从零开发FxEmbed:Firefox扩展实现页面截图与网页内标注
拿Firefox当主力浏览器几年了,截图这件事一直让我有点膈应。系统自带的截图工具只能截可见区域,想截整页得装第三方扩展,装完还得给权限、开开关关,偶尔还要看它脸色。直到我决定自己动手写一个Firefox扩展,彻底把截图这件事揉进浏览器里,这就是你要看的FxEmbed。
FxEmbed不是那种大而全的截图工具,它的核心思路很简单:把整个页面捕获成一张图,然后直接嵌入到当前网页里,让你能在这张“照片”上随手标注、画框、加箭头,甚至打马赛克,最后保存成一张完整的PNG。听起来和那些截图扩展差不多,但实际用起来差别很大,尤其是“嵌入网页”这一步,体验完全不同。
这篇文章不会只贴代码,我会把FxEmbed从0到能用的完整过程聊清楚,包括为什么选Manifest V3、截图到底走哪条链路、标注层的坐标换算怎么处理、Shadow DOM怎么避免样式打架,以及踩过的那些坑。不管你是想写扩展、做浏览器工具,还是单纯想给自己的工作流加点效率,这文章都值得你泡杯茶慢慢看。
1. 为什么要做FxEmbed:痛点、定位与方案选型
1.1 Firefox内置截图差在哪
很多人的第一反应都是:Firefox不是内置截图了吗?确实,Firefox 102之后自带截图功能,按Ctrl+Shift+S能进入一个“编辑模式”,可以截取可见区域或整个页面,还能画框、箭头、文字、头部涂鸦。功能看起来挺全,但有两个致命伤。
第一个是流程断裂。截图之后,图片进入剪贴板,你要么粘贴到聊天框、要么打开一个图片软件保存文件、要么临时建个网页贴上去看。这个过程里,截图是“离开”了它本来的上下文的。尤其在调试页面、审阅设计稿、给同事标bug的时候,我需要的是“图就在当前页面里”,而不是跳到另一个软件。
第二个是编辑能力太弱。内置截图能做的标注非常基础,箭头和文字一旦画上去就不能改,马赛克也是整块整块地涂,想局部模糊某个区域、想调整标注位置,都做不到。更麻烦的是,Firefox截图在整页截图时对某些动态元素处理得很糙,截出来的图经常缺帧、白条或者错位。
FxEmbed就是冲着这两个痛点去的:把截图直接嵌入当前页面,在嵌入的副本上完成所有标注操作,标注全部矢量可编辑,最后统一渲染导出。说白了,它把“截图”从一次性操作变成了一种页面内的轻量设计工作流。
1.2 技术路线选型:MV3 + Shadow DOM + Canvas
做个扩展,第一件事就是定技术路线。我最初考虑过三个方向。
方向一是基于html2canvas这类库在页面内重新渲染DOM,把整个页面“画”到canvas上。这个方案思路简单,但对现代页面的兼容性太差,webgl、canvas元素、跨域iframe、CSS滤镜、复杂的混合模式,全都可能翻车,而且性能开销极高。做出来的东西只能“看起来能用”,一遇到真实站点就露馅。
方向二是直接用浏览器的captureTab API,把页面截成真实的光栅图。这是浏览器原生能力,截图质量和用户所见完全一致,不挑站点,不用管CSS兼容性问题。代价是:要后台页面配合、截图是位图、不能像DOM那样在标注时“选中真实元素”。
方向三是混合方案:截图用原生API,标注层用DOM叠加。也就是截一张真实位图当作底层画布,在它上面盖一个透明层做标注,最后把标注层通过canvas合成回位图。这个方案是性能、兼容性、扩展性的均衡点。
最后我选了方向三,具体三个核心选型是:
- 扩展架构:用Manifest V3。Firefox从109版本开始全面支持MV3,虽然目前仍保留MV2,但扩展生态迟早要迁移,没必要开新项目走老路。
- 标注容器:用Shadow DOM。标注层要叠加到页面里,还要做到和页面自身样式隔离。iframe也能隔离,但跨域通信、定位、快捷键处理都麻烦,Shadow DOM配上托管挂载点,干净利落。
- 渲染引擎:原生Canvas。所有标注都以矢量路径记录,最终导出时才统一rasterize,这样既能支持撤销/重做,又不会因为放大缩小损失线条质量。
路线定了,后面的事情就顺了。
2. FxEmbed整体设计与核心原理
2.1 扩展的三层结构与数据流
FxEmbed的结构是这样设计的:三层,各管一摊。
第一层是background service worker,负责全局状态、权限管理、截图时机的调度。MV3里service worker不能长期驻留,所以它只处理“短平快”的任务——比如响应快捷键、发起截图、接收后台面板生成的结果。别在service worker里写长任务,随时会被休眠,这是我踩过的最深的坑之一。
第二层是content script,这是整个扩展的核心。它注入到每个页面里,负责创建嵌入层、绘制标注、处理鼠标事件、维护标注数据。内容脚本和页面共享DOM,但通过Shadow DOM隔离样式,所以不会污染页面,也不被页面污染。
第三层是offscreen/document页面,用于处理截图和导出。截图要在后台上下文里执行,导出要经过canvas再编码,都不能在content script里直接完成。
三者之间的数据流大概是这样:
用户按下快捷键 → content script监听并请求background创建截图 → background通过浏览器API截取页面 → 截图以dataURL形式传回content script → content script把图显示在Shadow DOM嵌入层里 → 用户做标注 → 导出时content script将标注数据和原始截图丢给canvas合成 → 生成最终PNG → 触发下载或复制到剪贴板。
这个流程看起来直白,但有一个关键设计点:标注数据和渲染是分离的。标注操作不直接往canvas上画死,而是先记录数据结构(线段、矩形、文字、箭头各自作为对象存坐标和样式),再根据这份数据实时渲染。这样撤销、重做、缩放、导出,全都能基于数据统一处理,而不是操作一堆像素。
2.2 截图引擎:从tab到canvas的关键链路
截图是FxEmbed的地基。截不好,后面标注做得再漂亮也白搭。MV3下Firefox截图的主流做法是用browser.tabs.captureTab(),这个API会返回一个dataURL,就是当前tab可视区域的截图。
但这里有个细节:captureTab()只能截可视区域。整页截图需要自己来,我的做法是三步走,每一步都踩过坑:
第一步是在截图前把页面滚到顶部,等两帧让页面把懒加载内容补上,然后记录当前位置和滚动容器的相关信息。
第二步是循环滚动,每滚动一个视口的高度就调用一次captureTab(),把截图拼起来。这里有两个大坑:一是滚动会触发页面的动态渲染,导致每次截图内容出现差异(比如固定导航栏、懒加载图片),最终的拼接图惨不忍睹;二是Firefox对超大页面截图时,位图尺寸有上限,直接拼一张几万像素高的图,canvas可能会直接空转甚至崩溃。
针对第一个坑,我在滚动截图前先判断页面是否有“固定元素”,有的话用CSS把它们的position临时改成absolute,截图完再恢复。动态加载的部分没法彻底解决,但可以靠滚动前休眠300ms来缓解。针对上限问题,我把导出目标宽度限制在1440px以下,高度超过12000px就分块导出。
第三步是在后台页里用canvas把所有截图块按坐标绘制到一张大图上。这个阶段不能用drawImage直接画超大图,要分块处理,不然内存直接爆掉。实测90%的普通页面高度都在4000px以内,这步能顺利完成;超过的页面,FxEmbed会提示走“分区导出”模式。
2.3 标注层与交互模型
标注层的设计,是整个项目里最让我纠结的部分。刚写第一版的时候,我直接在一个canvas上叠加鼠标事件,画一条线就存一条线,做完才发现根本没法“选中已画好的标注”。一块箭头画歪了,只能撤销重画,而且没法拖动调整位置。
后来参照了图形编辑软件的思路,重构成基于对象的模型:每个标注都是一个对象,有自己的类型、坐标、样式、变换信息。渲染循环统一把它们画到canvas上。鼠标命中检测时,遍历这些对象做数学几何计算,判断是否点中了某条线、某个矩形的边缘、或者某段文本的包围盒。
这个模型带来一个好处:调整和撤销变得特别自然。点中一个箭头,能看到四个控制点,拖动控制点改变长度和方向,也可以按住整体移动;撤销操作直接操作对象数组,删掉最后一个对象就行。
另一个设计决策是标注层不直接铺整个页面高,而是只覆盖可视区域,同时提供一个“移动页面”的模式。这样用户可以自由滚动页面,随时把标注“放置”在需要的位置上。放置的时候,标注的坐标记录的是相对于页面的绝对坐标(滚动无关),而不是相对视口的坐标,否则一滚动标注就飘了。
3. 实操过程:从manifest到第一个能用的版本
3.1 搭建项目骨架与manifest配置
先建项目目录,不用啥脚手架,纯手工搭,结构特别简单:
manifest.json是整个扩展的身份证,MV3最核心的变更就在这。我这里列出关键部分:
几个关键点说一下。activeTab权限是为了截图API需要的临时tab访问权,不给<all_urls>这种全站权限也能截当前页,但涉及到跨域iframe或者被限制的页面时攻击面会更大,权衡了一下决定给全站host权限,装的时候提示也会更清楚。storage用来保存标注模板和用户设置,downloads管导出。
commands这里注册了快捷键Alt+Shift+X。快捷键在commands里定义后,浏览器会自动把它接到扩展的键盘事件上,在content script里通过commands.onCommand监听即可。选Alt+Shift+X是避开和现有快捷键冲突的实测结果,之前用Ctrl+Shift+S会和Firefox自带截图直接撞车,调用后先弹系统截图工具,整个人都麻了。
3.2 截图捕获与图像传递的实现细节
截图的第一步,是content script告诉background干活。我这里用runtime.sendMessage提交一个{type: "capture-page"}消息。background收到后调用captureTab。
核心代码长这样:
这里有个细节:MV3下service worker可能处于休眠状态,消息来了会被唤醒,但异步函数里的代码在高版本浏览器里通常能保证执行完成。稳妥做法是在消息回调里return true,告诉浏览器“这个响应我要异步等一下发出来”,不然你的sendResponse可能石沉大海。
captureTab返回的是整个tab可视区域的PNG的dataURL,分辨率是当前设备像素比的。比如显示器scale是2,截图就是2倍尺寸。这块不能直接塞给content script使用,要先做一层像素比归一化——把CSS像素尺寸和目标尺寸分开算,不然后面标注坐标全是对不上的。
接下来是整页截图的循环滚动逻辑,精简版:
这里assembleChunks是拼接逻辑:在后台offscreen document里建canvas,按每个块的目标位置drawImage,最后导出。sleep(200)是我实测下来渲染稳定的折中值,太短会导致动态内容没画完,太长交互会拖沓。
截图拿到之后,dataURL通过sendResponse传回content script。这里有个坑:数据量大的时候消息体可能超限。一整页4K宽截图,base64编码后可能是十几MB,直接塞消息里,轻则消息失败,重则整个service worker崩。我的方案是:截图过程完成后,把dataURL先存到sessionStorage里(sessionStorage的容量在Firefox下够用),然后content script从sessionStorage里读。实测下来,12MB左右的图能平稳传输,更大就直接走磁盘临时文件了。
3.3 标记功能实现:画布、事件与坐标换算
标注层的核心是坐标换算。这绝对是所有浏览器标注工具共通的噩梦。页面在滚动、缩放、设备像素比不是1、元素有CSS transform,任何一个变量变一下,你画的线就“飘”了。
我的处理方式分三步。
第一步,确定标注坐标基准。FxEmbed里的所有标注坐标,统一存成“页面绝对CSS像素坐标”,也就是window.scrollX + e.clientX这样算出来的值。标注对象里存的是相对于整个页面文档的坐标,和当前滚了多少完全无关。这样滚动后重绘,直接把坐标拿到viewport里画就行。
第二步,坐标系转换。绘制时,canvas上下文首先要做一个变换。用户看到的可视区域,左上角对应页面坐标(scrollX, scrollY)。所以在每次绘制标注的时候,先ctx.translate(-scrollX, -scrollY),把整个canvas的原点挪到页面坐标系的零点。这样所有标注对象里的坐标就可以原封不动地画上去,不做任何手工加减。
第三步,设备像素比适配。物理像素和CSS像素不同,canvas如果不乘devicePixelRatio,在Retina屏上画出来的字和线全是糊的。做法是:把canvas的实际宽高设置成CSS宽高乘以devicePixelRatio,然后ctx.scale(devicePixelRatio, devicePixelRatio),之后的绘制逻辑就当devicePixelRatio等于1来写。
核心的鼠标交互逻辑在content script里,大致结构是:
hitTest是命中检测,遍历标注对象,分类型判断:线段求点到线段的距离,矩形判断点是否在边线附近,文字判断点是否在包围盒内。命中后进入“选中态”,拖动时更新对象坐标,实现移动和缩放。
我推荐用Pointer Events而不是Mouse Events,因为Pointer Events天然兼容触屏,而且setPointerCapture能解决鼠标拖出canvas外后收不到事件的问题。Firefox对Pointer Events的支持已经很成熟了,不用有顾虑。
最后导出PNG时,把标注对象按坐标绝对值画到一张新的canvas上,和底层截图合成。这里有个必须处理的细节:分块拼接的截图宽度和用户当前视口宽度可能不一致。整页截图时,宽度是整个文档的scrollWidth,而标注层宽度是视口宽度。导出时需要标注画到“整页宽度”的坐标系里,坐标是绝对的,所以直接画就行,但线的粗细会因为目标canvas的缩放而看起来不一致。我的解法是:导出时把所有线宽乘上一个scaleFactor,数值等于“内容总宽度 ÷ 视口宽度”。
4. 常见问题与排查技巧实录
4.1 截图黑屏、空白和“总差一截”
这三个问题其实是同一个根源:截图的时机不对。
黑屏,通常发生在页面还在加载中就触发截图,或者页面有canvas/webgl图层在后台渲染,captureTab抓到的是一帧还没画完的内容。解决套路是:截图前滚到目标位置后,至少等两个requestAnimationFrame,再用setTimeout多等150-200ms。我给这个等待起名叫“渲染喘息窗口”,太小会黑,太大新手会觉得扩展坏了。
空白,则是页面用visibility: hidden或display: none隐藏了内容,截图API拿到的就是一张没有内容的纯背景。这个没太好的自动化解法,只能建议用户先关闭阅读模式、关闭“自动隐藏滚动条”之类的设置。
“总差一截”是我调试期间最崩溃的问题。整页截图的底部总是少掉最后一行,因为滚动高度和视图高度不是严格整除,最后一块内容不足一个视口高,while循环直接跳过了。修正逻辑很简单:循环条件加一个容差——while (y < fullHeight - 2),也就是最后如果不足2px就不用滚了。
4.2 大页面截图内存爆炸
整页截图最爽的时候最危险。Firefox的canvas对单张位图尺寸有上限,不同平台不一样,一般在32767像素以内,但内存开销是按像素呈平方级走的。
一张宽度1200px、高度20000px的截图,光像素数据就是1200×20000×4字节,等于96MB。再叠加drawImage时的中间缓冲、base64编码翻倍、dataURL传回页面时的字符串复制,最多可以吃掉300-400MB内存,低配置机器直接卡成PPT。
我的实际处理是加一道限制:当页面高度超过8000px时,就不走“拼成大图再标注”的路线,而是开启“分块模式”——把页面按视口切成多张截图,让用户逐块标注,最后导出时从后台把所有标注合成提交。这个模式牺牲了一点连贯性,但换来了内存稳定。实用的很,尤其面对那种无限滚动的电商长页面。
4.3 页面样式冲突与事件穿透问题
这是内容脚本技术的永恒主题。我第一版嵌入层直接append进body,马上被页面的z-index秩序碾碎:有的网站的header层级高得离谱,标注层被压在底下。还有的网站写了* { box-sizing: border-box; }、button { all: unset; }这种全局规则,直接把我嵌进来的DOM样式全重置了。
最后统一改成Shadow DOM挂载,所有内部样式都封装在Shadow root里。对外只有一行host元素CSS,设成position: fixed; top: 0; left: 0; z-index: 2147483647; pointer-events: all;。2147483647是z-index的上限,就是为了压在一切页面元素上面。
事件穿透是另一个坑。标注层要接收鼠标事件,但底下的页面正常滚动也需要鼠标事件。我的方案是给shadow root内部加一个半透明的“事件接收垫”,只有这个垫子接收pointer事件,垫子之外的区域事件穿透给页面。这样用户可以在标注层旁边正常滚动、点击,一旦鼠标移进标注层范围,事件就被拦截。
4.4 MV3下聊胜于无的remote code限制
MV3最大的变化之一就是不能再执行eval和远程代码。这意味着你没法动态加载一个脚本字符串来执行。有些旧教程教你用chrome.scripting.executeScript传入一个对面页面函数的字符串,这在MV3里是行不通的——传入的必须是“函数体”,且不能引用扩展context里的变量。
我做FxEmbed时也踩过这个:想在页面上下文里读取window.__INITIAL_STATE__(很多SPA把首屏数据挂在这),但MV3的隔离环境拿不到页面自己的变量。最后是用scripting.executeScript注入一个纯函数,函数体内通过DOM序列化把需要的数据以JSON字符串传回来。注意,这个函数不能闭包引用扩展内部的任何东西,所有需要的数据都得通过参数传进去。
5. 经验总结与后续扩展
FxEmbed写完到现在,我用它替代了之前所有截图工具。说实话,和成熟的商业截图工具比,它的导出修饰细节还差得远,但它解决了一个很本质的问题:截图不再是把画面“拿出去”,而是把画面“放进来”。这种页面内直接标注的工作流,在写技术文章、记录bug复现步骤、审阅视觉稿的时候,效率提升不是一点半点。
比较典型的场景是,以前给前端同事报bug,要截图、开图、画红圈、存文件、拖进聊天框,五个步骤。现在按Alt+Shift+X,截完直接在页面上画圈写备注,一键保存,一步到位。编辑完还不用手动清理,直接关闭嵌入层,页面干干净净。
后续我想给FxEmbed加两个能力。一个是标注模板:把常用的箭头样式、文字颜色、马赛克大小存成模板,下次截图直接套用,省得每次调。另一个是跨页面标注数据导出:把标注数据导出成JSON,配合自动化测试用——让QA在页面上标了问题后,直接把标注坐标和截图交给开发,开发能精确知道问题点位。这个方向前几天试了个原型,坐标序列化已经跑通了,再打磨打磨UI就能放出来。
最后分享一个藏在代码角落里的小技巧。导出PNG时,如果图片里有大面积的半透明标注(比如半透明的矩形高亮),直接导出会发现高亮底下原本的文字变得很淡。这是因为亮度混合过后,PNG的透明通道被浏览器在显示时做了色彩补偿。解法是:最终导出前,把canvas先铺一层纯白底再合成,所有半透明标注就不会被“沉底”了。就这么一个小改动,导出的图肉眼看起来才干净。这些细节没人会写进文档,都是自己踩过坑才明白的。