← 全部文章

前端窗口

JustZix 的悬浮按钮 —— 一个带悬停状态、吸附、弹出菜单的 3 字母小水滴

15 5月 2026 · 作者 JustZix Team

悬浮按钮是你在每个有激活 JustZix 规则的页面上看到的那个 3 字母小水滴。它是整个 JustZix UI 的入口 —— 点一下打开一个带开关的弹窗，拖动让你重新摆放它，吸附把它连到动作栏上。视觉上很小，却浓缩了许多功能。本文从内部把它打开。

按文件夹的 3 字母标签

JustZix 里每个文件夹（规则分组的主要单位）都有一个可选图标 —— 最多 3 个字符，自动大写。悬浮按钮显示第一个匹配文件夹（按 URL 前缀）的图标：

folder.icon = 'qa'      → 标签「QA」
folder.icon = 'dev'     → 标签「DEV」
folder.icon = '🐛'      → 标签「🐛」（emoji 截断到 3 字符）
folder.icon = (空)      → 标签「ZIX」（默认）

想法：一个高级用户按项目有 5-10 个文件夹，每个有不同的 3 字母标记。在悬浮按钮上看到「QA」意味着 QA 规则是激活的。任何交互之前的视觉反馈。

4 种视觉状态 —— 颜色 + 不透明度

状态在 storage onChanged 时自动更新 —— 从任何地方切换一条规则（选项页、widget 弹窗、Chrome 右键菜单）→ 悬浮按钮立刻改变外观。

一次点击的解剖 —— widget 弹窗

在悬浮按钮上左键点击 → 它旁边打开一个 widget 弹窗。widget 包含：

• 全局暂停 —— 顶部的 pauseToggle，一点 = 停用整个扩展
• 文件夹区域 —— 每个匹配 URL 的文件夹一个复选框，按文件夹开/关切换（持久）
• 动作栏区域 —— 分别切换每条栏的可见性（按标签页会话）
• CSS/JS/Console 窗口区域 —— 每个 pane 一个复选框（持久）
• 「打开选项」链接 —— 在新标签页里的完整编辑器

在外面点一下关闭弹窗（document 级别的事件监听器）。点击一个复选框会触发 setBarHidden / setCssPaneEnabled / setFolderEnabled —— 全都通过 Promise 串起来以避免竞态。

与栏和 pane 的吸附连接

悬浮按钮作为一个 ID 为 '__float' 的伪元素参与吸附连接。机制和 pane 完全一样：

1. 把悬浮按钮拖到一条动作栏旁边（≤20px）→ 吸附，两个元素 = 一组
2. 拖动组里任意一个元素 → 整个组一起移动
3. 在悬浮按钮上右键 → 带「从 X 断开」选项的右键菜单

使用场景：悬浮按钮作为整组的「锚点把手」。栏 + Output Console 吸附到悬浮按钮上 → 拖动悬浮按钮 = 移动整个仪表盘。

右键 = 右键菜单

和栏 / CSS pane 一样的机制 —— 按元素的右键菜单。悬浮按钮有：

• 「隐藏到刷新为止」 —— 悬浮按钮消失到下一次 F5。持久的 OFF 需要选项页（故意不放在右键菜单里 —— 这样用户不会把「隐藏」和「停用整个扩展」搞混）
• 「从 X 断开」 —— 按吸附连接。外加「断开所有连接」

没有字体/字号 —— 悬浮按钮是固定尺寸（32×32px）。那里除了 3 字母标签（来自 folder.icon）没有文本可个性化。

使用场景 1 —— 作用域的视觉指示器

你有 3 个文件夹：「ALL」（处处生效）、「GHB」（仅 github）、「GMA」（仅 gmail）。每个有不同的颜色（绿、黑、红）和一个 3 字母图标。访问 github.com → 悬浮按钮显示黑色「GHB」。访问 gmail.com → 红色「GMA」。不查看 widget 弹窗你就看到作用域。

使用场景 2 —— 快速全局暂停

Skype 通话、向某人在生产环境上演示一个新功能，JustZix 可能碍事。点击悬浮按钮 → 切换「全局暂停」→ 扩展停用所有规则。演示之后 → 再点一次 → 已激活。无需进 chrome://extensions。

使用场景 3 —— 按页面隐藏到刷新为止

「强制深色模式」规则也匹配你的银行网站 —— 而它已经有自己的深色模式。悬浮按钮挡住了银行的 logo。在悬浮按钮上右键 → 「隐藏到刷新为止」→ 悬浮按钮只在这个标签页消失，直到 F5。规则照样运行，只是 UI 被隐藏了。

使用场景 4 —— 按域名的位置

悬浮按钮的位置持久化在 chrome.storage.sync 里。默认在右下角（锚点 BR）。拖动 → 保存 → 下次访问那个域名时把它放回你留下它的地方。位置是按元素 ID的，但所有页面共享 ID '__float' —— 所以位置是跨域名全局的。如果你想按页面 → 用吸附连一条作用域特定的栏。

坑

• 3 字母图标 —— 截断到 3 个字符。「qa-team」→「QA-」（带连字符）。最佳实践：1-3 个字母数字字符。单个 emoji = OK（例如 🐛 →「🐛」），但多字符 emoji（👨‍💻 = 5 个码点）会被奇怪地截断。
• folder.icon 默认是「ZIX」，即便你没定义一个自定义的 —— 它曾经是「JZ」（2 字符），自 v2.13 起改为对齐品牌的「ZIX」。
• 全局暂停 vs 按文件夹停用。全局暂停不会重置按文件夹的启用状态 —— 解除暂停后，文件夹回到它们原来所处的状态。按文件夹停用是持久的，独立于全局暂停。
• sync 存储里的悬浮按钮位置 如果你在一台设备上快速拖动并在另一台上打开标签页，可能会失同步。Chrome 的最终一致性约 1-2 秒。
• 悬浮按钮的吸附不是双向的。悬浮按钮的位置是全局的，栏有按窗口状态的位置。吸附在视觉上有效，但如果你在另一个标签页上移动悬浮按钮，栏不会跟随它（它们被作用域锁定在自己的标签页上）。

接下来做什么

悬浮按钮是整个 JustZix UI 的「入口点」—— 所有其他元素（栏、pane）都更上下文相关。另见：

• 吸附连接 —— 悬浮按钮作为组的锚点
• pane 头部的右键菜单 —— 平行的机制
• 标签页里的迷你 IDE —— UI 的完整地图

安装 JustZix —— 你一添加第一条规则，悬浮按钮就会自己出现。