- GitHub 仓库:DhvanilPatel/swarm-cursors
- 项目定位:一款极具视觉冲击力与创意的 Chrome 浏览器扩展程序(Manifest V3)
- 开源致敬:灵感与核心动效设计致敬自设计师 Joel Califa 的个人实验网站 Swarm
一、 项目概述
当你点击浏览器工具栏上的 Swarm Rebuild 图标,或按下快捷键时,当前浏览的任意网页会瞬间溶解为一张空白画布。紧接着,一群类似 Figma 协同设计工具里的**“多人光标(Swarm Cursors)”**会被召唤出来——它们先围绕网站图标盘旋集结,随后四散奔赴页面各处,用十字准星拉框、用 I 型光标敲字、用钢笔工具画线、拉出红色参考线对齐排版,在你眼前将整个网页从零开始一笔一划地重新“搭建”出来,直到完全恢复原貌。
原版 Swarm 网站仅能针对自身硬编码的页面生效,而 swarm-cursors 的作者通过编写一套纯原生、零外部依赖的实时 DOM 快照与设计蓝图解析引擎,成功将这种惊艳的动态构建体验带到了互联网上的任意网页。
二、 核心亮点与功能特性
1. 高度还原的设计工具重构动画
光标群不仅拥有基于群集物理引擎(Flocking Physics)的自然运动轨迹——开场时围绕站点 Favicon 盘旋,施工时自动避让与协同,全部完工后还会像一群好奇的萤火虫一样聚集在你的鼠标周围嬉戏——更极其细腻地还原了 UI 设计师在 Figma 等专业软件中的真实操作习惯:
- 绘制容器与媒体(Rect & Media):
- 光标会使用十字准星拖拽出一个带有实时宽高数值(
W × H)标注的灰底占位框,随后渐显出真实的背景色、边框、渐变、圆角、阴影乃至毛玻璃(backdrop-filter)效果。 - 图片与媒体元素采用极具仪式感的自上而下扫描式加载。
- 光标会使用十字准星拖拽出一个带有实时宽高数值(
- 实时打字与字号动画(Text & Headings):
- 文本区块会先由光标拉出文本框,随后切换为 I 型文本光标,伴随着闪烁的竖线逐字敲出文本内容(完整保留原有的字体、链接、行内代码与伪元素图标样式)。
- 页面中的大号标题在输入时,会从
18px起步,伴随着音调上升一步步阶梯式放大到目标字号。
- 钢笔工具与参考线对齐(Pen Tool & Guides):
- 单边边框(如底部分割线)和
<hr>标签不会被当作普通矩形,而是由钢笔工具点出锚点、拖着橡皮筋辅助线绘制而成。 - 当页面中存在共享同一左边缘或基线的多个文本块时,屏幕边缘会滑入 Figma 风格的标尺,由光标拉出一条红色参考线,文本块随之精准吸附对齐。
- 单边边框(如底部分割线)和
- ⌥-Drag(Option 拖拽)智能复用:
- 当引擎识别出导航栏菜单项、列表行、商品卡片或 Logo 墙等重复结构时,光标不会机械地重复绘制十遍,而是先精雕细琢出一个**“母版(Master)”,随后按住 Option 键拖拽出带有红色间距标尺的“副本(Duplicate)”**,最后逐一修改里面的文字、替换图片或微调样式。
2. 纯代码合成的拟真音效(Web Audio API)
整个项目没有引入任何外部 MP3 或 WAV 音频文件,所有声音均通过浏览器原生的 Web Audio API 实时波形合成,并且支持立体声左右声道定位(Stereo Panning)——声音的方位会随着光标在屏幕上的水平位置实时移动:
- 机械键盘与鼠标音效:打字时会发出清脆的机械轴体声(空格键的触底“Thock”声更加低沉),每一次点击与拖拽都有逼真的鼠标微动按压与释放声,参考线吸附时伴有清脆的卡扣声。
- 环境音乐化反馈:绘制矩形框、图片和复制元素时,会按照 E 大调五声音阶在八分音符网格上触发轻柔的玻璃钢琴音符——大区块音调低沉浑厚,小元素音调清脆灵动,且屏幕从左到右音高逐渐递增。
- 起承转合氛围音:页面溶解清空时伴随空气感的渐强音效,光标四散开工时响起短促琶音,页面全部重建完成时会奏响柔和的 E 大调和弦,点击恢复真实网页(Go live)时则伴随下行扫频音效。
3. 丰富的交互控制与录屏友好设计
- 滚动追随(Scroll Chasing):在未全部建完的页面上手动向下滚动时,光标群会立刻追随你的视线赶来施工,你滚得越快,加入干活的“Agent”数量就越多。
- 自动导览模式(Tour):点击底部工具栏的
Tour按钮后,页面会以光标刚好能跟上的舒适节奏自动平滑向下滚动,非常适合用来录制产品展示或社交媒体传播视频。 - 倍速调节与纯净无遮挡模式:
- 支持
1× / 2× / 3×三档建造速度自由切换。 - 按下
H键或点击Hide可以隐藏底部悬浮控制栏,获得完全纯净的录屏画面(鼠标移至屏幕底部或再按一次H即可重新唤出)。
- 支持
- 灵活的触发模式:除了手动点击图标或快捷键外,还可在扩展选项中配置“在指定网站自动播放”或“在所有网站自动播放”。
三、 项目架构与技术实现原理
1. 仓库目录结构
整个项目极其轻量化,零第三方构建工具或前端框架依赖,核心代码结构清晰明了:
swarm-cursors/
├── swarm-rebuild/ # 【核心目录】Chrome 扩展本体(可直接加载到浏览器运行)
│ ├── manifest.json # Manifest V3 配置文件(仅申请 activeTab、scripting、storage 基础权限)
│ ├── background.js # 后台 Service Worker:监听点击与快捷键、截取动态媒体画面、注入核心脚本
│ ├── swarm.js # 【核心引擎】集成了 DOM 快照解析、Shadow DOM 遮罩渲染、光标物理与音效合成
│ ├── autoplay.js # 自动播放轻量加载器(仅在用户授权开启自动播放的站点上动态注册注入)
│ ├── options.html # 扩展右键“选项”设置页面
│ └── options.js # 设置页面的网站权限申请与配置存储逻辑
├── demo/
│ └── index.html # 自包含的边缘测试用例页面(涵盖内部滚动容器、浮动元素、表单、卡片与媒体)
├── scripts/
│ └── package.sh # 一键打包脚本,生成可上传至 Chrome Web Store 的压缩包
├── store/ # Chrome 网上应用店上架文案、宣传图及权限说明文档
└── media/ # README 演示用的动图资源
2. 三阶段内部工作流
当扩展被激活时,内部引擎会严格按照以下三个阶段推进:
-
DOM 快照与蓝图翻译(Snapshot)
- 唤醒懒加载:脚本首先执行一次快速的隐藏滚动(Hidden Scroll Pass),提前触发页面底部的懒加载图片与滚动显现动画,随后瞬间归位。
- 动态媒体截图:对于 WebGL
<canvas>、正在播放的<video>或跨域<iframe>等无法直接读取内部像素的元素,background.js会在启动瞬间临时隐藏普通文本与背景容器,仅保留这些特殊媒体元素并截取当前屏幕画面,随后在快照阶段按坐标精确裁剪还原。 - 结构化抽象:
swarm.js递归遍历页面的实时 DOM 树(包含开放状态的 Shadow DOM),读取每个可见节点的坐标与计算样式,将其拆解为矩形层、文本层、钢笔路径和媒体层;同时自动将相似的同级兄弟节点归类为“母版 + 副本”,并提取文本共享的边缘坐标生成参考线任务。
-
隔离画布覆盖(Blank)
- 在当前网页的最顶层创建一个完全隔离了原网页 CSS 样式干扰的 Shadow DOM 全屏遮罩层,填满页面背景底色,形成一张干净独立的“画布”。
-
拓扑依赖与协同重建(Rebuild)
- 所有设计蓝图被转化为带有拓扑依赖关系的任务队列,并按照自上而下(随视口解锁)、先父容器后子元素、先母版后副本的顺序逐步解锁。
- 空闲的光标代理(Agent)通过群集物理算法飞向各自领到的任务坐标,运行对应的生成器脚本执行动画与音效。全部完成后,点击工具栏上的 Go live 即可让遮罩层平滑淡出,交还给你真实、可正常点击交互的原始网页(点击 Replay 则可再次重播)。
四、 安装、操作指南与使用限制
1. 安装方式
- 方式一:Chrome 网上应用店安装 前往 Chrome Web Store 搜索 Swarm Rebuild,点击添加并固定(Pin)到浏览器右上角工具栏即可使用。
- 方式二:本地加载最新源码(推荐体验最新特性)
由于应用商店审核存在一定延迟,若想第一时间体验最新版本(如隐藏工具栏录屏、自动播放等),可按以下步骤本地加载:
- 克隆或下载
DhvanilPatel/swarm-cursors仓库到本地; - 打开 Chrome 浏览器,在地址栏输入
chrome://extensions并开启右上角的开发者模式; - 点击左上角的加载已解压的扩展程序,选中项目中的
swarm-rebuild/文件夹; - 将扩展图标固定到工具栏即可(如需测试本地
demo/index.html文件,需在扩展详情页开启“允许访问文件网址”)。
- 克隆或下载
2. 常用操作与快捷键
| 快捷键 / 操作 | 功能说明 |
|---|---|
Alt + Shift + S 或点击扩展图标 |
启动 / 退出网页重建动画 |
M 或点击工具栏喇叭图标 |
静音 / 开启 Web Audio 合成音效(若页面未曾点击过,需先任意点击一次页面以解锁浏览器音频策略) |
H 或点击工具栏 Hide |
隐藏 / 显示底部悬浮控制栏(进入纯净录屏模式,鼠标移至屏幕底部也可唤醒) |
Esc 或点击工具栏 ✕ |
随时中断动画并退出遮罩层 |
3. 已知局限说明
- 受限页面:受限于 Chrome 浏览器安全策略,扩展无法在
chrome://系统设置页、Chrome 网上应用店以及内置 PDF 阅读器中运行(此时扩展图标会显示红色×提示)。 - 视觉重构非功能克隆:它本质上是对页面瞬时状态的“视觉重构”,在重建遮罩层内原网页的动态 JS 交互脚本不会运行;若启动时未点击页面或仅开启了部分站点自动播放,首屏以下的动态画布与视频会降级显示为占位符。
- 页面体量上限:为保证流畅度,超长网页默认上限约为 4,000 个图层(约
40,000px高度)。

