← 全部文章

API 与辅助工具

window.JZ：从代码里驱动按钮、滑块和 Output Console 的辅助函数

15 5月 2026 · 作者 JustZix Team

暂时忘掉 JustZix 会向每个页面注入 CSS 和 JS 这件事。把注意力放在这一点上：每一个动作 —— 按钮、滑块、选择框、toggle3、输入框、文本框 —— 都是一个活的 DOM 元素，你可以从别的代码里驱动它。这需要 MAIN world 里两个独立的命名空间：window.JZ（动作辅助函数）和 window.JUSTZIX（日志器）。每个都有自己的生命周期、自己的用途，并且故意不混在一起。

为什么是两个命名空间而不是一个

日志器（只写，向 Output Console 派发）和 DOM 可寻址性（读取/操作已经活在页面 DOM 里的元素）是两种不同的语义。把它们打包在一起会混淆职责。一个阅读代码的用户看到 JUSTZIX.log(...) 就知道：「那是个日志器」。看到 document.querySelector('[data-jz-action-id="x"]') 就知道：「那是个 DOM 查询」。此外 —— 原生 DOM API + data-* 属性永远胜过专有包装器（它能配合 DevTools 的 inspect、配合第三方库、配合从网上复制粘贴的代码工作）。

幂等 —— 安装按版本管理（JZ 用 _jzVersion，JUSTZIX 用钩子标志），所以扩展更新不会在会话进行到一半时覆盖掉命名空间。

完整的 API 表面

// ============================================================
// window.JZ — 动作辅助函数
// 操作 DOM 中的 data-jz-action-id 元素。
// 可能被页面脚本占用 → 兜底：原生 DOM 查询。
// ============================================================
JZ.action(labelOrId)     // 按 label 或 id 取元素。按 label 时不区分大小写。
JZ.actionById(id)        // 按 data-jz-action-id 取元素。不回退到 label。
JZ.actions()             // DOM 中所有动作元素的数组。
JZ.labels()              // label 数组（保留原始大小写）。
JZ.click(labelOrId)      // 程序化点击。对 <select> 选择第一个选项。
                          // 返回 true/false。
JZ.value(labelOrId)      // 动作的当前值（string 或 null）。
JZ.setValue(labelOrId, value)  // 程序化 setter + 派发 input 和 change。
JZ.bars()                // DOM 中所有 .jz-actions-bar 的数组。
JZ.barById(id)           // 按 data-jz-bar-id 取栏。
JZ.floatingBtn()         // JustZix 悬浮按钮元素（处于激活状态时）。

// ============================================================
// window.JUSTZIX — 日志器（自 v2.13.73，自 v2.13.76 为首选别名）
// 向 Output Console 派发（kind='jz'）；不转发到原生 console.*。
// 品牌名 = 冲突风险微乎其微。处处可用。
// ============================================================
JUSTZIX.log(...args)
JUSTZIX.warn(...args)
JUSTZIX.error(...args)
JUSTZIX.info(...args)
JUSTZIX.debug(...args)

// 指向同一 API 的别名：
window.__JUSTZIX__       // 始终设置（与 v2.13.72-75 向后兼容）
window.JZ                // 也是，仅在未被占用时 —— 一个更短的快捷方式

// 当 window.JZ 被页面占用时（例如 Google Ads）的兜底：
// → 没有 JUSTZIX.click() 的对应物；用原生 DOM。
document.querySelector('[data-jz-action-id="..."]').click();

使用场景 1 —— 一个按钮点击另一个按钮

你有「Login → Dashboard → Statistics」三个动作。动作栏里三个独立按钮。再加一个第四个「🚀 Quick」，依次执行这三个：

// BUTTON 动作「Quick」—— 代码字段：
JZ.click('Login');
await new Promise(r => setTimeout(r, 800));
JZ.click('Dashboard');
await new Promise(r => setTimeout(r, 500));
JZ.click('Statistics');
JUSTZIX.log('Quick 流程完成 —— 3 次点击合一');

额外好处：这段脚本对页面一无所知，只知道它的 JustZix 动作。改变「Login」/「Dashboard」里的选择器 —— 「Quick」照样工作，因为它是按 label 调用它们的。

使用场景 2 —— 一个滑块驱动一个 CSS 变量

SLIDER 动作「亮度」（范围 50-150，默认 100）。在它的「Code」字段里：

// 滑块每次改变都执行这段代码。
// `value` 是扩展注入的一个 extraVar（自 v2.12.2）。
document.documentElement.style.setProperty('--brightness', value + '%');

现在在另一个动作（BUTTON「Reset」）里，你可以程序化地设置滑块的值：

JZ.setValue('亮度', 100);  // 滑块跳到 100，CSS 变量更新，亮度恢复。
JUSTZIX.log('亮度已恢复到 100%');

对 TOGGLE3（像「Dev / Staging / Prod」这样的 3 态开关）也一样：JZ.setValue('环境', 'staging') 激活那个特定状态并执行它的代码。

使用场景 3 —— 把 Output Console 当「记事本」用

Output Console（自 v2.13.66）是一个会捕获页面所有 console.log 输出的 pane。像 Gmail 这样的页面每秒往控制台塞几百行。字符串过滤有帮助，但更好的诀窍是：只通过 JUSTZIX.log 写你自己的消息，然后把 pane 设为 [J] 模式（Just JustZix，仅 JustZix）。

// 在「检查购物车」动作里：只记录你自己的消息，没有页面噪音。
const items = document.querySelectorAll('.cart-item');
JUSTZIX.log(`购物车里有 ${items.length} 件商品`);
items.forEach((it, i) => {
  const price = parseFloat(it.querySelector('.price')?.textContent || 0);
  JUSTZIX.log(`  [${i}] ${it.dataset.sku} — $${price}`);
});
const total = [...items].reduce((s, it) => s + parseFloat(it.querySelector('.price')?.textContent || 0), 0);
JUSTZIX.log(`总计: $${total}`);

处于 [J] 模式的 Output Console pane 只显示那 3 行 —— 完全干净，非常适合 QA 工具栏或面向客户的场景。

如果页面已经有 window.JZ 怎么办？

日志器总是可用 —— JUSTZIX.log() 用的是品牌名（冲突风险微乎其微），并且是首选。此外 window.__JUSTZIX__ 始终被设置为兜底别名。window.JZ 上的冲突只影响动作辅助函数 —— 即便如此你也有原生的退路。

有些网站（例如 Google Ads）有自己的 window.JZ。JustZix 会检测到：如果日志器安装时 window.JZ 已存在，扩展不会覆盖页面的 API，并在 Output Console 的欢迎消息里指出这一点。于是短快捷方式 JZ 留给了页面 —— 用 JUSTZIX 做日志、用原生 DOM 做动作：

// 日志器：永远用 JUSTZIX（即便 JZ 被页面占用也有效）
JUSTZIX.log('购物车已处理');

// 点击一个动作：当 window.JZ 被占用时 → 用原生 DOM 而非 JZ.click()
document.querySelector('[data-jz-action-id="actionId"]').click();
// 或者按 data-jz-key（大写 label）：
document.querySelector('.jz-actions-bar [data-jz-key="LOGIN"]').click();

这是有意的设计：data-jz-action-* + querySelector 是一种原生模式 —— 它能配合 DevTools 的 inspect、第三方库、从网上复制粘贴的代码工作。JZ.click() 是语法糖 —— 一层可选的间接，在它不可用时你可以跳过它。

坑

• JZ.click() 对 INPUT/TEXTAREA 只是点击它们，不会改变它们的值。要设置文本：JZ.setValue('搜索', 'foo')。其他类型（button、select、toggle3、slider）对点击都有合理的默认行为。
• JZ.value()/setValue() 自 v2.13.33 起更完整了。更老的版本没有把滑块的值放进 dataset —— 如果你看到滑块返回 null，检查一下扩展版本。
• 按 label 查找不区分大小写，但按 ID 查找区分大小写。建议：坚持用 label（你自己的），别用 ID（自动生成的）。
• JUSTZIX.log 不转发到 DevTools 的控制台。这是故意的 —— 我们想给 JustZix 脚本一个单独的通道。如果你想要 DevTools —— 用普通的 console.log。
• JS Console 只捕获 DevTools 风格的流量，不会自动捕获 JUSTZIX.log。JS Console 里的「console.log('hi')」照常工作；JS Console 里的「JUSTZIX.log('hi')」不会出现在 Output Console 里，除非你有一个处于 [J] 或 [C+J] 模式的 Output Console pane。
• 没有 JUSTZIX.click() 之类的东西。日志器和动作辅助函数是有意分开的命名空间。当页面占用了 window.JZ，你通过原生 DOM（querySelector + data-jz-action-*）来触发动作 —— 这是模式，不是 bug。

接下来做什么

这篇结束了 JustZix 前端窗口的迷你系列：

• CSS pane —— 标签页里的实时 CSS 编辑器
• JS Console —— 带 ↑↓ 历史的 REPL
• JS pane —— 按需运行
• window.JZ 辅助函数（本文） —— 程序化 API

这一切合在一起，就是每个浏览器标签页里的一个迷你 IDE，外加一个驱动你按钮的迷你 API。安装 JustZix 亲自试试 —— 完全免费，无需账号，没有服务器。