VisBug（ProjectVisBug） - 完整学习教程

**教程级别：** 从零到一
**预计学习时间：** 4-6 小时（基础使用 1 小时 + 进阶特性 2 小时 + 插件开发 1-3 小时）
**前置知识：** 基本的浏览器使用能力；进阶部分需要了解 HTML/CSS 基础概念；插件开发部分需要 JavaScript 编程基础
**基于版本：** v0.3.0（浏览器扩展最新正式版）及代码库最新状态（2024-11-15 提交）

VisBug（ProjectVisBug） - 完整学习教程

教程级别： 从零到一 预计学习时间： 4-6 小时（基础使用 1 小时 + 进阶特性 2 小时 + 插件开发 1-3 小时） 前置知识： 基本的浏览器使用能力；进阶部分需要了解 HTML/CSS 基础概念；插件开发部分需要 JavaScript 编程基础 基于版本： v0.3.0（浏览器扩展最新正式版）及代码库最新状态（2024-11-15 提交）

环境搭建指南

系统要求

操作系统： Windows、macOS 或 Linux 均可
浏览器： Chrome（推荐）、Firefox、Safari 或 Edge
网络： 需要访问 Chrome Web Store 或 Firefox Add-ons 进行安装
（可选）开发环境： Node.js >= 14.x、Git（用于从源码构建或开发插件）

安装步骤

方式一：通过浏览器商店安装（推荐）

Chrome 用户：

打开 Chrome 浏览器
访问 Chrome Web Store - VisBug
点击"添加至 Chrome"按钮
在弹出的确认对话框中点击"添加扩展程序"
安装完成后，浏览器工具栏中会出现 VisBug 图标

Firefox 用户：

打开 Firefox 浏览器
访问 Firefox Add-ons - VisBug
点击"添加到 Firefox"按钮
在弹出的确认对话框中点击"添加"
安装完成后，浏览器工具栏中会出现 VisBug 图标

方式二：从源码构建安装（适合开发者）

# 1. 克隆仓库
git clone https://github.com/GoogleChromeLabs/ProjectVisBug.git
cd ProjectVisBug

# 2. 安装依赖
npm install

# 3. 构建
npm run build

# 4. 在 Chrome 中加载未打包的扩展
# 打开 chrome://extensions/
# 开启右上角的"开发者模式"
# 点击"加载已解压的扩展程序"
# 选择项目中的 extension/ 目录

验证安装

打开任意网页（如 https://example.com）
点击浏览器工具栏中的 VisBug 图标
如果页面顶部出现 VisBug 工具栏，说明安装成功

预期结果：
- 页面顶部出现一个水平工具栏
- 工具栏包含多个工具图标（移动、选择、文字编辑等）
- 鼠标悬停在页面元素上时，元素周围出现高亮边框和样式信息提示

练习题： 1. 在 https://example.com 上激活 VisBug，确认工具栏是否正确显示 2. 尝试在 Chrome 和 Firefox 上分别安装 VisBug，对比界面是否一致

第一部分：入门篇

1.1 核心交互范式：Point-Click-Tinker

概念讲解：

VisBug 的核心交互方式可以用三个词概括：指向（Point）→ 点击（Click）→ 修改（Tinker）。这与传统开发者工具的工作方式截然不同。

传统 DevTools 的工作流是：打开 DevTools → 在 DOM 树中找到目标元素 → 在样式面板中修改 CSS 属性。这个过程需要理解 HTML 结构和 CSS 语法。

VisBug 的工作流是：在页面上直接点击目标元素 → 在可视化工具中调整样式。整个过程完全可视化，无需接触代码。

这个范式之所以重要，是因为它是 VisBug 所有功能的基础。你后续学到的每一个工具和功能，都建立在这个"先选中、再操作"的交互模式之上。

操作示例：

激活 VisBug（点击工具栏中的 VisBug 图标）
将鼠标移动到页面上的任意元素上
观察：元素周围出现蓝色高亮边框，旁边显示样式信息提示（Metatip）
点击该元素
观察：元素被选中，出现选中框（带有调整手柄）

预期结果：
- 悬停时：元素周围出现蓝色虚线边框
- 悬停时：鼠标旁出现信息提示（包含字体、颜色、尺寸等信息）
- 点击后：元素周围出现实线选中框
- 点击后：VisBug 工具栏激活对应的工具选项

练习题： 1. 在任意网页上，使用 Point-Click-Tinker 方式选中一个段落元素（<p>） 2. 悬停在一张图片上，观察 Metatip 中显示了哪些样式信息 3. 尝试点击页面上的不同类型元素（标题、链接、按钮），观察选中状态的差异

1.2 工具栏与工具切换

概念讲解：

VisBug 的工具栏是所有编辑能力的入口。工具栏位于页面顶部，包含多个工具图标，每个图标对应一种编辑能力。理解工具栏的结构和工具切换方式是高效使用 VisBug 的关键。

VisBug 提供的核心工具及其快捷键如下（来源：GitHub Wiki - Keyboard Master List）：

工具	快捷键	功能
移动工具（Move）	`V`	拖拽移动元素位置（默认工具）
边距工具（Margin）	`M`	调整元素的外边距（margin）
内边距工具（Padding）	`P`	调整元素的内边距（padding）
对齐工具（Align）	`A`	调整元素的对齐方式
色相调整工具（Hueshift）	`H`	调整元素的颜色（色相偏移）
阴影工具（Shadow）	`D`	添加或修改盒阴影
定位工具（Position）	`L`	调整元素的定位偏移
排版工具（Typography）	`F`	调整字体族、大小、粗细等
文字编辑工具（Text Editing）	`T`	直接编辑页面上的文字内容
搜索工具（Search）	`S`	搜索页面元素
参考线工具（Guides）	`G`	显示对齐参考线
检查工具（Inspect）	`I`	检查元素的样式信息
无障碍工具（Accessibility）	`X`	检查无障碍属性

工具切换有两种方式：①点击工具栏中的图标；②使用键盘快捷键（推荐）。快捷键方式效率更高，让你在编辑时无需移动鼠标到工具栏。

操作示例：

激活 VisBug
将鼠标移动到页面上的一个元素上
按键盘 V 切换到移动工具
拖拽选中的元素到新位置
按键盘 H 切换到色相调整工具
调整颜色，观察元素颜色变化

预期结果：
- 按 V 后：鼠标光标变为移动手型，拖拽时元素跟随移动
- 按 H 后：出现颜色调整控件，调整后元素即时变色
- 切换工具后：前一个工具的交互状态被自动清理

注意事项： - 工具切换时会自动清理上一个工具的状态——这是 VisBug 工具系统（Tool System）的设计原则。每个工具在激活时进行初始化，在切换走时执行清理，防止工具之间的状态互相干扰。 - 快捷键不区分大小写。

练习题： 1. 使用快捷键依次切换所有工具（V、M、P、A、H、D、L、F、T、S、G、I、X），观察每个工具激活时界面变化 2. 选中一个按钮元素，使用移动工具（V）将其拖拽到页面另一位置

1.3 悬停检查器（Hover Inspect）

概念讲解：

悬停检查器是 VisBug 最常用的信息查看功能。当鼠标悬停在页面上的任意元素时，VisBug 会显示一个信息提示框（Metatip），包含该元素的关键样式和属性信息。

Metatip 显示的信息包括：

字体信息：字体族（font-family）、字号（font-size）、行高（line-height）
颜色信息：文本颜色（color）、背景颜色（background-color），以十六进制和 RGB 格式显示
间距信息：margin 和 padding 值
尺寸信息：元素的宽度和高度
无障碍属性：ARIA 角色和标签（如果存在）

这个功能的价值在于：设计师无需打开 DevTools 就能快速了解任何元素的设计参数。这对于设计验收和竞品分析特别有用。

操作示例：

激活 VisBug
将鼠标悬停在页面上任意元素上（不要点击）
观察鼠标旁出现的信息提示框
（可选）按住 Opt（Mac）或 Alt（Windows）键点击，可以"钉住"（Pin）Metatip，使其固定显示

预期结果：
- 悬停时出现信息提示框，包含以下字段：
  font-family: system-ui, -apple-system, ...
  font-size: 16px
  color: #333333
  background-color: transparent
  margin: 0px
  padding: 8px 16px
  width: 300px
  height: 24px

练习题： 1. 悬停在页面上的标题元素上，记录其字号和颜色值 2. 使用 Opt+Click（Mac）或 Alt+Click（Windows）钉住一个元素的 Metatip 3. 对比两个不同元素的字体信息差异

1.4 键盘导航与 DOM 遍历

概念讲解：

在 1.1 节中我们学习了通过点击选中元素，但有时目标元素很难精确点击（如被其他元素覆盖、尺寸太小等）。这时，键盘导航提供了更精确的元素选择方式。

VisBug 的 DOM 遍历快捷键如下：

快捷键	功能
`Tab`	进入子元素（深度优先遍历）
`Shift+Tab`	移到上一个兄弟元素
`Enter`	进入或退出分组元素
`Shift+Enter`	返回父元素
`Arrow Keys`	在选中状态下进行像素级微调（配合移动工具）

这个功能建立在浏览器 DOM API 的节点遍历能力之上（childNodes、parentElement、nextElementSibling 等）。VisBug 将这些 DOM API 封装为直觉式的键盘操作，让用户无需理解 DOM 树结构就能在元素层级间导航。

操作示例：

选中页面上的一个 <div> 容器
按 Tab 键多次，观察选中状态在子元素之间移动
按 Shift+Enter 返回父元素
按 Tab 键继续遍历其他子元素

预期结果：
- 按 Tab：选中状态从父元素移动到第一个子元素
- 继续按 Tab：选中状态依次移动到下一个兄弟元素
- 按 Shift+Enter：选中状态返回到父元素
- 每次移动时，Metatip 自动更新为新选中元素的信息

练习题： 1. 选中 <body> 元素，使用 Tab 键遍历到第 5 个子元素 2. 使用 Shift+Enter 返回父元素，然后用 Tab 键尝试另一条遍历路径 3. 在一个嵌套列表（<ul> > <li>）中，使用键盘导航深入到嵌套层级的第 3 层

第二部分：进阶篇

2.1 多选与批量操作

概念讲解：

在入门篇中，我们学习了选中单个元素的方式。进阶篇的第一节将扩展到多元素操作——这是 VisBug 区别于简单元素检查器的关键能力。

VisBug 支持两种多选方式：

框选（Marquee Select）：使用选择工具（V），在页面上拖拽绘制一个矩形区域，区域内所有元素被选中
增量选择（Incremental Select）：按住 Shift 键，逐个点击要选择的元素

选中多个元素后，任何工具操作都会同时应用于所有选中的元素。例如，使用颜色工具修改颜色时，所有选中元素的颜色会同时改变。

这背后是多选机制（Multiselect）在工作：工具函数接收的参数不是单个元素，而是一个元素列表（NodeList）。每个工具必须能够处理这个列表，逐一或批量应用操作。

操作示例：

激活 VisBug，切换到移动工具（V）
在页面上拖拽绘制矩形，框选多个段落元素
观察所有被框选的元素都出现选中框
切换到色相调整工具（H）
选择一个新颜色
观察所有选中元素的颜色同时改变

预期结果：
- 框选后：3-5 个段落元素同时被选中，各自出现选中框
- 修改颜色后：所有选中元素的颜色同时从原色变为新选择的颜色
- 取消选择（按 Esc）后：所有元素的选中状态同时清除

注意事项： - 框选时，VisBug 会选中矩形区域内的所有可交互元素，包括文本节点、图片、链接等。如果选中了不想要的元素，按住 Shift 再次点击该元素可以取消选中。 - 并非所有操作都适合批量应用。例如移动工具在多选时会同时移动所有元素（保持相对位置不变），这可能不是你期望的行为。建议在多选状态下优先使用样式修改工具（颜色、字体、间距）。 - 多选大量元素（>50 个）时可能出现性能延迟，因为每个工具需要对所有选中元素逐一计算和应用样式变更。

练习题： 1. 在一个新闻网站首页上，框选 3 个新闻标题，同时修改它们的字体颜色为红色 2. 使用 Shift+Click 方式选中页面上不相邻的 2 个元素，同时调整它们的字体大小 3. 尝试在多选状态下使用间距工具（S），观察所有选中元素的间距是否同时变化

2.2 文字编辑与图片替换

概念讲解：

VisBug 不仅能修改样式，还能直接编辑页面内容——文字和图片。这让 VisBug 从一个纯样式工具升级为内容编辑工具。

文字编辑： 切换到文字编辑工具（T）后，点击页面上的任意文字内容，该文字变为可编辑状态。你可以直接输入新文字，如同在文本编辑器中一样。按 Esc 退出编辑。

图片替换： 选中一张图片后，可以从本地文件系统拖拽一张新图片到 VisBug 界面中，替换当前图片。VisBug 会使用 FileReader API 读取本地图片，将其转换为 Data URL，然后设置为图片元素的 src 属性。

操作示例（文字编辑）：

激活 VisBug，按 T 切换到文字编辑工具
点击页面上的一个标题文字
输入新的标题内容
按 Esc 退出编辑

预期结果：
- 点击后：文字变为可编辑状态，出现文本光标
- 输入后：新文字即时显示，替换原有内容
- 按 Esc 后：退出编辑模式，保留修改后的文字

操作示例（图片替换）：

激活 VisBug，选中页面上的一张图片
从文件管理器中拖拽一张新图片到浏览器窗口
观察图片被替换

预期结果：
- 拖拽后：原图被新图片替换
- 新图片保持原图的尺寸和位置
- 替换后的图片以 Data URL 形式内联显示

注意事项： - 文字编辑修改的是 DOM 文本节点（textContent），不是 CSS 样式。刷新页面后修改会丢失。 - 图片替换使用 Data URL 方式，不会上传到任何服务器。图片数据仅存在于当前页面会话中。 - 某些使用 Shadow DOM 的 Web Components 内部的文字可能无法直接编辑，因为 VisBug 默认只能访问主文档的 DOM 树。 - 拖拽图片替换时，确保拖拽目标是选中图片的 VisBug 选中框区域，而非页面其他位置。

练习题： 1. 使用文字工具修改页面上的一个标题，将其内容改为 "Hello VisBug" 2. 选中一张图片，用本地文件替换它 3. 尝试编辑一个按钮上的文字，观察按钮尺寸是否自动调整

2.3 布局微调（Layout Nitpicking）

概念讲解：

布局微调是 VisBug 中最精确的编辑能力。它允许你对选中元素的 CSS 盒模型（Box Model）参数进行像素级调整，包括：

外边距（margin）：元素与其他元素之间的间距
内边距（padding）：元素内容与边框之间的间距
尺寸（width/height）：元素的宽度和高度
定位偏移（top/right/bottom/left）：元素相对于定位参考点的偏移量

使用边距工具（M）或内边距工具（P）时，VisBug 会在选中元素周围显示一个可视化的间距指示器，类似于 Chrome DevTools 中的 Box Model 图。你可以通过箭头键进行精确调整。

操作示例：

激活 VisBug，选中一个元素
按 M 切换到边距工具（或按 P 切换到内边距工具）
观察元素周围出现间距可视化指示器
使用箭头键调整间距：
↑ / ↓：增加/减少垂直方向间距
← / →：增加/减少水平方向间距
按住 Shift + 箭头键：以 10px 为单位调整（默认 1px）

预期结果：
- 激活边距/内边距工具后：元素周围出现带有数值标注的间距指示器
- 按 ↑：元素的对应方向间距增加 1px
- 按 Shift+↑：元素的对应方向间距增加 10px
- 每次调整后：页面布局即时更新

注意事项： - VisBug 的布局调整通过 inline styles 应用，优先级高于外部 CSS 规则。但无法覆盖使用 !important 的外部样式。 - 对于使用 Flexbox 或 Grid 布局的元素，调整 margin 和 padding 可能导致不可预期的布局变化，因为这些布局模式的元素位置由父容器的布局算法决定。 - 箭头键调整的是哪个方向的间距取决于 VisBug 的当前焦点区域（padding 四条边中的哪一条）。使用 Tab 可以在四条边之间切换焦点。

练习题： 1. 选中一个卡片组件，使用内边距工具（P）将其内边距从默认值调整到 24px 2. 使用 Shift+箭头键快速将一个元素的左侧 margin 增加 50px（使用边距工具 M） 3. 尝试调整一个 Flexbox 容器内子元素的间距，观察布局变化是否符合预期

2.4 深色模式实验

概念讲解：

深色模式实验是 VisBug 的一个典型高级用例，综合运用了前面学到的多个工具：颜色工具（C）、多选机制和布局微调。

其核心思路是：在一个浅色主题的页面上，使用 VisBug 逐步将所有元素的颜色反转为深色主题。这个过程展示了 VisBug 在设计探索方面的强大能力。

操作步骤：

打开一个浅色主题的网页
激活 VisBug
选中 <body> 元素（使用 DOM 遍历快捷键回到 body）
按 H 切换到色相调整工具，将 background-color 改为深色（如 #1a1a2e）
将 color 改为浅色（如 #e0e0e0）
逐个检查标题、链接、按钮等元素，使用颜色工具调整它们的配色
完成后截图保存设计方案

预期结果：
- body 背景变为深色
- 文字颜色变为浅色
- 各交互元素（链接、按钮）的颜色需要单独调整
- 最终呈现一个深色主题的页面设计方案

注意事项： - 深色模式实验通常需要调整 10-20 个元素的颜色才能达到理想效果。建议使用多选批量操作提高效率。使用色相调整工具（H）可以快速修改元素颜色。 - 某些元素的背景色来自 CSS 类名（如 Bootstrap 的 .bg-light），VisBug 通过 inline styles 覆盖时可能与类样式产生冲突。 - 完成实验后建议截图保存，因为刷新页面所有修改都会丢失。

练习题： 1. 在 https://example.com 上，将页面从浅色主题改为深色主题 2. 记录你修改了哪些元素的颜色，以及修改前后的颜色值 3. 尝试为深色主题设计一套配色方案，使用色相调整工具（H）在 VisBug 中实时预览效果

第三部分：高级篇

3.1 插件系统与自定义命令

概念讲解：

VisBug 的插件系统允许开发者创建自定义功能，通过 /command 的方式在 VisBug 中调用。这是 VisBug 最强大的扩展机制。

一个插件由两部分组成：

命令声明（commands）：一个字符串数组，定义插件可以通过哪些命令名被调用
处理函数（handler）：一个异步函数，当用户调用命令时执行，接收 {selected, query} 参数

代码示例：创建一个简单的插件

以下是一个"高亮所有链接"的插件完整代码：

// highlight-links.js
// VisBug 插件：高亮页面上的所有链接元素
// 来源：基于 GitHub Wiki - Plugins 模板编写

// 声明命令名称——用户通过 /highlight-links 调用
export const commands = ['highlight-links']

// 默认导出处理函数
export default async function({selected, query}) {
  // selected: 当前被 VisBug 选中的元素 NodeList（本例中不使用）
  // query: 查询工具

  // 查找页面上所有 <a> 元素
  const links = document.querySelectorAll('a')

  // 为每个链接添加高亮样式
  links.forEach(link => {
    link.style.outline = '3px solid #ff6600'
    link.style.outlineOffset = '2px'
  })

  // 在控制台输出结果信息
  console.log(`已高亮 ${links.length} 个链接`)

  // 返回统计信息（VisBug 会显示给用户）
  return `找到并高亮了 ${links.length} 个链接`
}

插件注册：

将插件注册到 VisBug 的插件系统中：

// plugins/_registry.js 中添加以下代码
// 来源：基于 GitHub Wiki - Plugins

import {
  commands as highlightLinksCommands,
  default as HighlightLinksPlugin
} from './highlight-links.js'

// 将命令名映射到处理函数
commandsToHash(highlightLinksCommands, HighlightLinksPlugin)

使用插件：

将 highlight-links.js 文件放入 plugins/ 目录
在 _registry.js 中注册插件
重新构建 VisBug 扩展
在 VisBug 激活状态下，输入 /highlight-links 调用插件

预期输出：
- 页面上所有 <a> 元素周围出现橙色高亮边框
- 浏览器控制台输出：已高亮 X 个链接
- VisBug 界面显示：找到并高亮了 X 个链接

注意事项： - 插件处理函数必须是异步函数（async function），即使内部没有异步操作。 - selected 参数可能为空 NodeList（用户未选中任何元素时），插件需要处理这种空选中的情况。 - 插件中的 DOM 操作不受 Shadow DOM 隔离保护——它们直接作用于宿主页面。这意味着插件可以修改页面内容，但也可能导致样式冲突。 - 注册新插件后需要重新构建扩展才能生效。

练习题： 1. 编写一个名为 count-images 的插件，统计页面上所有 <img> 元素的数量并显示 2. 修改 highlight-links 插件，让它只在链接包含特定文本时才高亮

3.2 性能优化与大型页面适配

概念讲解：

VisBug 通过事件拦截和 DOM 操作工作，在元素较少的页面上表现良好。但在包含大量 DOM 节点（>10,000 个元素）的页面上，可能出现以下性能问题：

悬停检查延迟：每次鼠标移动都需要计算悬停目标元素，DOM 节点过多时计算变慢
选中高亮渲染延迟：在选中框周围绘制高亮边框涉及样式计算和重绘
多选操作性能下降：对大量选中元素同时应用样式修改时，浏览器需要逐一重排（Reflow）

优化策略：

策略一：限制选中元素数量

// 在多选场景中，限制同时选中的元素数量
// 来源：基于 VisBug 架构分析的性能最佳实践
const MAX_SELECTION = 50

function handleSelection(elements) {
  // 只取前 MAX_SELECTION 个元素
  const selectedElements = Array.from(elements).slice(0, MAX_SELECTION)
  selectedElements.forEach(el => {
    el.style.outline = '2px solid blue'
  })
}

策略二：使用 requestAnimationFrame 批量更新

// 使用 requestAnimationFrame 将多次样式更新合并为一次重排
// 来源：通用 DOM 性能最佳实践
function batchApplyStyles(elements, styles) {
  requestAnimationFrame(() => {
    elements.forEach(el => {
      Object.assign(el.style, styles)
    })
  })
}

// 使用示例
const elements = document.querySelectorAll('.card')
batchApplyStyles(elements, {
  backgroundColor: '#f5f5f5',
  padding: '16px'
})

注意事项： - 在 SPA（单页应用）页面上使用 VisBug 时，路由切换可能导致 VisBug 的状态丢失。建议在每次路由切换后重新激活 VisBug。 - 使用了虚拟滚动（Virtual Scroll）的页面（如长列表）可能无法正确选中不可见区域的元素，因为虚拟滚动会动态创建和销毁 DOM 节点。 - 如果页面自身使用了大量 Shadow DOM（如 Lit、Stencil 等 Web Components 框架），VisBug 可能无法正确穿透 Shadow DOM 边界选中内部元素。

练习题： 1. 在一个包含大量 DOM 节点的页面（如电商商品列表页）上测试 VisBug 的响应速度 2. 使用 Chrome Performance 面板记录 VisBug 激活前后的性能差异

3.3 最佳实践

将 VisBug 用于设计探索，而非代码修改。VisBug 的所有修改都是临时的（inline styles），最适合用于快速实验和验证设计想法，而不是作为代码编辑工具的替代品。
截图保存设计方案。完成样式调整后，立即截图保存。刷新页面后修改会丢失，建议使用浏览器截图工具或系统截图快捷键保存当前状态。
结合 Chrome DevTools 使用。VisBug 适合快速视觉调整，Chrome DevTools 适合精确的代码调试。两者结合使用可以发挥最大效率。例如：用 VisBug 确定理想的颜色值，然后在 DevTools 中将修改写入 CSS 文件。
使用键盘快捷键提高效率。熟练掌握 V、M、P、H、F、T 等快捷键后，操作速度可以提升 3-5 倍。建议打印快捷键参考表贴在显示器旁边。完整快捷键列表参见 1.2 节。
注意项目维护状态。由于 VisBug 项目处于低活跃维护状态，建议定期检查是否有新版本更新，同时关注 Chrome DevTools 的可视化编辑功能作为备选方案。

第四部分：实战项目

项目需求

项目名称： VisBug 自定义设计检查插件

需求描述： 开发一个 VisBug 插件，帮助设计师一键检查页面上的设计一致性问题。具体功能：

检测页面上所有文本元素的字号（font-size），标记出偏离设计规范的元素
检测页面上的颜色使用，列出所有不同的颜色值及其出现次数
生成一个简明的设计检查报告

综合运用知识点： - 插件系统与自定义命令（3.1 节） - 工具函数模式（1.2 节） - DOM 遍历能力（1.4 节） - 样式检查（1.3 节）

项目设计

插件结构：
design-check/
├── index.js          # 主插件逻辑
└── _registry.js      # 注册入口（添加到 VisBug 插件目录）

设计规范（示例）：
- 正文字号：16px
- 标题字号：24px, 20px, 18px
- 允许偏差：±2px

完整实现代码

// design-check/index.js
// VisBug 设计检查插件：检测字号一致性和颜色使用情况
// 来源：本教程原创，基于 GitHub Wiki - Plugins 模板

// 定义插件命令——用户通过 /design-check 调用
export const commands = ['design-check']

// 设计规范定义
const DESIGN_SPEC = {
  // 允许的字号及其用途
  fontSizes: {
    '16px': '正文',
    '18px': '小标题',
    '20px': '二级标题',
    '24px': '一级标题',
    '32px': '页面标题'
  },
  // 允许的偏差范围（像素）
  tolerance: 2
}

export default async function({selected, query}) {
  // ====== 知识点：DOM 遍历（1.4 节）======
  // 获取页面上所有文本元素
  const textElements = document.querySelectorAll(
    'h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button'
  )

  // ====== 知识点：样式检查（1.3 节）======
  // 检查字号一致性
  const fontSizeReport = []
  const allowedSizes = Object.keys(DESIGN_SPEC.fontSizes).map(
    s => parseFloat(s)
  )

  textElements.forEach(el => {
    const computedStyle = window.getComputedStyle(el)
    const fontSize = parseFloat(computedStyle.fontSize)

    // 检查是否在允许范围内
    const isAllowed = allowedSizes.some(
      allowed => Math.abs(fontSize - allowed) <= DESIGN_SPEC.tolerance
    )

    if (!isAllowed) {
      // 标记偏离规范的元素
      el.style.outline = '2px solid red'
      el.style.outlineOffset = '1px'

      // 获取最近的允许字号
      const closestAllowed = allowedSizes.reduce((prev, curr) =>
        Math.abs(curr - fontSize) < Math.abs(prev - fontSize) ? curr : prev
      )

      fontSizeReport.push({
        element: el.tagName.toLowerCase(),
        text: el.textContent.substring(0, 30),
        currentSize: fontSize + 'px',
        closestSpec: closestAllowed + 'px',
        diff: Math.round(fontSize - closestAllowed) + 'px'
      })
    }
  })

  // ====== 知识点：样式检查（1.3 节）——颜色分析 ======
  const colorMap = {}
  const allElements = document.querySelectorAll('*')

  allElements.forEach(el => {
    const computedStyle = window.getComputedStyle(el)
    const textColor = computedStyle.color
    const bgColor = computedStyle.backgroundColor

    // 统计文本颜色
    if (textColor && textColor !== 'rgba(0, 0, 0, 0)') {
      colorMap[textColor] = (colorMap[textColor] || 0) + 1
    }

    // 统计背景颜色（排除透明）
    if (bgColor && bgColor !== 'rgba(0, 0, 0, 0)') {
      const key = 'bg:' + bgColor
      colorMap[key] = (colorMap[key] || 0) + 1
    }
  })

  // ====== 知识点：插件系统（3.1 节）——输出报告 ======
  // 排序颜色按使用频率
  const sortedColors = Object.entries(colorMap)
    .sort((a, b) => b[1] - a[1])
    .slice(0, 10)

  // 构建报告
  let report = '===== 设计检查报告 =====\n\n'
  report += `扫描了 ${textElements.length} 个文本元素\n`
  report += `发现 ${fontSizeReport.length} 个字号偏离规范的元素（已用红色边框标记）\n\n`

  if (fontSizeReport.length > 0) {
    report += '--- 字号问题 ---\n'
    fontSizeReport.forEach(item => {
      report += `<${item.element}> "${item.text}..." `
      report += `当前: ${item.currentSize} → 建议: ${item.closestSpec} (偏差 ${item.diff})\n`
    })
  }

  report += '\n--- 颜色使用统计（前 10）---\n'
  sortedColors.forEach(([color, count]) => {
    report += `${color}: ${count} 次\n`
  })

  // 输出到控制台
  console.log(report)

  // 返回简短摘要给 VisBug 界面
  return `检查完成：${fontSizeReport.length} 个字号问题，${sortedColors.length} 种颜色。详见控制台。`
}

插件注册代码：

// 添加到 plugins/_registry.js
// 来源：基于 GitHub Wiki - Plugins 注册模式

import {
  commands as designCheckCommands,
  default as DesignCheckPlugin
} from './design-check/index.js'

commandsToHash(designCheckCommands, DesignCheckPlugin)

代码解析

DOM 遍历（1.4 节知识点）：使用 document.querySelectorAll 获取页面上所有文本元素。选择器 h1, h2, h3, h4, h5, h6, p, span, a, li, td, th, label, button 覆盖了常见的文本容器元素。
样式检查（1.3 节知识点）：使用 window.getComputedStyle(el) 获取每个元素的计算样式。这比直接读取 el.style 更可靠，因为 getComputedStyle 会返回所有生效的样式（包括继承的样式）。
插件系统（3.1 节知识点）：插件导出 commands 数组和默认异步函数，遵循 VisBug 的标准插件接口模式。函数参数 {selected, query} 中，selected 是当前选中元素，query 是查询工具。
工具函数模式（1.2 节知识点）：偏离规范的元素通过 inline styles（el.style.outline）标记为红色边框，与 VisBug 的核心设计理念一致——所有修改通过 inline styles 应用。

扩展挑战

添加间距检查：扩展插件功能，检查所有元素的 margin/padding 是否符合设计规范，将异常间距用黄色边框标记
生成可视化报告面板：不只是在控制台输出，而是在页面上创建一个悬浮面板（使用 Shadow DOM 隔离），以卡片形式展示检查结果
支持自定义设计规范：允许用户通过 /design-check?fontSize=14,18,24 的方式传入自定义字号规范

第五部分：常见问题与排查指南

常见错误及解决方案

错误信息/现象	原因	解决方案
点击 VisBug 图标无反应	扩展未正确安装或已被禁用	打开 `chrome://extensions/`，检查 VisBug 是否已启用，尝试重新安装
工具栏不显示	当前页面可能是 chrome:// 或 about: 页面	浏览器内置页面不支持扩展注入，请在普通网页上使用
选中元素后无法编辑	当前工具不是编辑工具	确保已切换到对应的编辑工具（如 T 编辑文字、C 修改颜色）
悬停检查器不显示信息	Metatip 被关闭或页面有 JS 错误	刷新页面后重新激活 VisBug；检查控制台是否有 JavaScript 错误
颜色修改不生效	元素样式使用了 `!important`	VisBug 的 inline styles 无法覆盖 `!important` 规则，需在 DevTools 中手动修改
刷新页面后修改丢失	VisBug 的修改是临时的（inline styles）	这是正常行为。建议修改完成后截图保存设计方案
多选框选不准确	框选区域包含了不可见或覆盖的元素	使用 Shift+Click 逐个精确选择，避免框选
插件命令不识别	插件未注册或构建未更新	确认插件已添加到 `plugins/_registry.js` 并重新构建扩展
在 SPA 页面上路由切换后 VisBug 失效	SPA 路由切换不会触发页面重新加载	手动重新激活 VisBug（点击工具栏图标）
Firefox 上部分功能不可用	浏览器扩展 API 差异	VisBug 的 Firefox 版本功能略少于 Chrome 版本，参见 GitHub Issue 列表

调试技巧

使用 Chrome DevTools 并行调试：当 VisBug 行为异常时，打开 Chrome DevTools（F12），在 Console 面板中检查是否有 JavaScript 错误。VisBug 的错误通常会以红色文字显示在控制台中。
检查 Shadow DOM 内部状态：在 Chrome DevTools 的 Elements 面板中，展开 <vis-bug> 自定义元素可以看到其 Shadow DOM 内部结构。这有助于理解 VisBug 的内部状态和调试 UI 显示问题。开启方式：DevTools → Settings → Preferences → 勾选 "Show user agent shadow DOM"。
使用 document.querySelector('vis-bug') 检查注入状态：在浏览器控制台中运行此命令，如果返回 null 说明 VisBug 未正确注入；如果返回元素节点说明注入成功。进一步检查 document.querySelector('vis-bug').shadowRoot 可以确认 Shadow DOM 是否已初始化。

第六部分：学习路线推荐

官方文档推荐阅读顺序

顺序	资源	重点内容
1	VisBug 官方网站	在线体验基本功能，了解工具定位
2	Medium — VisBug 101	官方入门文章，完整功能介绍和设计理念
3	GitHub Wiki - Tool Architecture	理解工具系统的设计模式和接口规范
4	GitHub Wiki - Plugins	学习插件系统的使用和开发方法
5	GitHub 源码	深入理解架构实现，阅读核心模块代码

术语对照表

英文术语	中文译名	说明
Custom Element	自定义元素	Web Components 标准的一部分，允许创建自定义 HTML 标签
Shadow DOM	Shadow DOM	一种 DOM 封装技术，提供样式和结构的隔离
Inline Style	内联样式	直接写在 HTML 元素 style 属性中的 CSS 样式
Tool	工具	VisBug 中独立的编辑功能模块
Plugin	插件	VisBug 的扩展机制，通过命令调用自定义功能
Metatip	悬停信息提示	鼠标悬停时显示的元素样式信息
Marquee Select	框选	通过拖拽矩形区域选中多个元素
Multiselect	多选	同时选中多个元素进行批量操作
Manifest V2/V3	扩展清单 V2/V3	浏览器扩展的配置文件格式标准
Point-Click-Tinker	点击即编辑	VisBug 的核心交互范式

教程信息来源： - 基于 VisBug v0.3.0（2020-11-05 发版）和代码库最新状态（2024-11-15 提交） - GitHub Wiki - Tool Architecture - GitHub Wiki - Plugins - Medium — VisBug 101 - VisBug 官方网站 - 信息获取日期：2026-04-10

VisBug（ProjectVisBug） - 完整学习教程

环境搭建指南

系统要求

安装步骤

验证安装

第一部分：入门篇

1.1 核心交互范式：Point-Click-Tinker

1.2 工具栏与工具切换

1.3 悬停检查器（Hover Inspect）

1.4 键盘导航与 DOM 遍历

第二部分：进阶篇

2.1 多选与批量操作

2.2 文字编辑与图片替换

2.3 布局微调（Layout Nitpicking）

2.4 深色模式实验

第三部分：高级篇

3.1 插件系统与自定义命令

3.2 性能优化与大型页面适配

3.3 最佳实践

第四部分：实战项目

项目需求

项目设计

完整实现代码

代码解析

扩展挑战

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

第六部分：学习路线推荐

官方文档推荐阅读顺序

推荐进阶资源

术语对照表