Nvirya AdGuard v11.7.0
Ctrl K

功能指南

本指南记录了 Nvirya AdGuard v11.7.0 中所有面向用户的功能、控件与键盘快捷键。文中所有界面名称均与脚本内置的简体中文（TRANSLATIONS['zh-CN']）及英文（TRANSLATIONS.en）标签完全一致。

1. 快捷悬浮按钮 (FAB) 与键盘快捷键#

功能说明#

快捷悬浮按钮是一个渲染在顶层窗口（window.self === window.top）独立 Shadow DOM 容器（<div data-nvirya-ui>）中的浮动护盾图标（46×46 px）。它提供一键打开 Nvirya AdGuard X 控制面板的入口，并在右上角通过状态圆点指示当前防护状态：

  • 绿色圆点（data-state="ok"）： 当前网站防护已启用。
  • 橙色圆点（data-state="warn"）： 当前会话已暂停过滤，或当前域名位于白名单中。
  • 灰色圆点（data-state="off"）： 全局智能护盾（config.enabled）已关闭。

当控制面板关闭且连续 3,000 ms（3 秒）无交互时，悬浮按钮会进入 idle（空闲）状态，自动半隐藏吸附到屏幕左边缘或右边缘（translateX(±58%) scale(0.92)，opacity: 0.42）。当视频或页面元素进入全屏模式（fullscreenchange）时，悬浮按钮会自动隐藏。

如何激活与操作#

  • 触控 / 鼠标： 点按或点击快捷悬浮按钮。在触屏设备上，如果按钮处于半透明吸附（idle）状态，第一次点按会先唤醒按钮（resetFabIdle），防止滑动页面时误触打开菜单；唤醒后再次点按即可打开控制面板。您可以沿屏幕左右边缘上下拖动按钮调整位置（保存在 nvirya_x_fab 中）。
  • 键盘快捷键（Alt+A）： 在任意页面按 Alt+A 即可切换控制面板的打开与关闭，即使已在设置中关闭了快捷悬浮按钮显示也同样有效。
  • 用户脚本管理器菜单： 在脚本管理器的扩展菜单中选择 Open Control Panel (Alt+A)。
  • 关闭面板： 点按背景遮罩、点按右上角关闭（×）按钮、按 Escape 键，或在窄屏移动设备（宽度 ≤ 640 px）上向下滑动底部面板。

如何隐藏或恢复悬浮按钮#

  • 在设置标签页中切换快捷悬浮按钮（“自动吸附到屏幕边缘”）开关。
  • 如果您在不支持 GM_registerMenuCommand 菜单的移动浏览器上隐藏了悬浮按钮，仍可通过外接键盘按 Alt+A 或在用户脚本管理器中重置脚本存储来恢复。

2. 防护统计与本周活动#

位于概览标签页顶部：

  • 模式切换（本页 / 累计）： 在当前标签页会话计数（stats.session）与持久化存储在 nvirya_x_stats 中的累计计数（stats.lifetime）之间切换四个统计卡片。每个卡片底部还会显示另一模式的数值（累计：... 或 本页：...）。
  • 四个统计指标：
    • 广告（“已清理”）：移除广告节点、拦截广告脚本或处理视频广告时递增。
    • 已隐藏元素：通过 [data-nvirya-hidden] 隐藏元素、解除点击陷阱或应用手动选择器规则时递增。
    • 已拦截弹窗：拦截 window.open 调用或新标签页广告劫持点击时递增。
    • 已拦截跟踪器：拦截发往广告/跟踪器 URL 的 fetch、XMLHttpRequest、sendBeacon、<img> 或 <script> 请求时递增。
  • 本周活动（一–日）： 显示本周 7 天内广告 + 已隐藏元素总数的柱状图（在 nvirya_x_weekly_history 中最多保留 14 天历史记录）。点按本周任意已过去的日期柱即可在图表右上角查看当日统计详情。

3. 允许此网站与本次会话暂停#

位于 概览 → 快捷操作：

防护启用时的按钮名称防护暂停时的按钮名称生效范围与存储键
允许此网站 (“暂停对当前域名的过滤”)恢复此网站的防护 (“重新启用此域名的广告过滤”)对当前域名及其子域名持久生效，跨浏览器重启保留（nvirya_x_whitelist）
本次会话暂停 (“关闭标签页前停用过滤”)恢复本次会话防护 (“立即重新启用过滤”)保存在 nvirya_x_session 中，仅对当前域名生效直至手动恢复

暂停或允许网站时会立即发生什么#

点按上述任一按钮都会立即触发 refreshProtection() → restorePageWhenDisabled()，无需刷新页面即可恢复页面状态：

  1. 在 <html> 上设置 window.__NVIRYA_DISABLED__ = true 与 data-nvirya-disabled="1"，使主世界 fetch 钩子直接放行后续请求。
  2. 还原所有反广告拦截弹窗隐藏操作与滚动锁定覆盖（AntiAdblockEngine.revertAll()）。
  3. 停止视频广告监听并恢复视频原有音量与倍速（stopVideoAdProtection()）。
  4. 断开 DOM MutationObserver 并禁用 <style data-nvirya-cosmetic> 与 <style data-nvirya-site-rules>。
  5. 恢复被解除点击陷阱元素的内联样式（state.disarmedNodes），移除 [data-nvirya-hidden] 属性，并将 state.removedNodes 中记录的已移除节点重新插回原父节点。

限制说明： 在 document-start 阶段已被阻止执行的脚本或元素，需要刷新一次页面才能重新运行其原始初始化代码。

4. 隐藏页面元素（元素选择器）#

功能说明#

隐藏页面元素（“点按或滑动即可隐藏任意元素”）启动交互式可视化选择器，包含蓝色高亮边框、元素标签/类名徽章以及底部浮动工具栏。

如何启动#

  • 打开 概览 → 快捷操作 → 隐藏页面元素，或
  • 在用户脚本管理器菜单中选择 Select the element to block (Picker)。

当选择器激活时，window.open 会被锁定（state.pickerActive = true），页面点击与触摸事件在捕获阶段被拦截，确保点按广告或链接时只会选中元素而不会发生页面跳转。

工具栏控件与触控手势#

点按页面上的任意元素后，选择器会构建祖先节点链（buildPickerChain，最多向上 7 层，在 <body> 与 <html> 前停止）并启用工具栏：

  • 深度滑块（层级 {current}/{total}）： 左右拖动水平滑块，在当前选中的子元素（层级 1/...）与其父级容器之间平滑切换。
  • 扩大： 向上切换一层至父元素（traversePicker(-1)）。
  • 缩小： 向下切换一层至子元素（traversePicker(1)）。
  • 隐藏元素： 为当前高亮元素生成唯一 CSS 选择器（makeSelector），弹出确认框（`隐藏此元素？

{sel}），将规则保存至 nvirya_x_site_rules[hostname]` 并立即隐藏该元素。

  • 全部隐藏 ({count})： 仅当 makeSimilarSelector 在页面上找到 2 个及以上共享相同标签与稳定 CSS 类名的元素时显示。确认后（隐藏所有匹配元素 ({sel})？）可一次性隐藏所有同类元素。
  • 触屏滑动 / 甩出隐藏手势（Swipe / Fling）： 在触屏设备上选中高亮元素后，您可以直接在高亮元素上快速滑动（距离 > 60 px 或速度 > 0.4 px/ms）。元素会以旋转飞出动画消失（triggerPickerFling）并自动保存隐藏规则，无需弹出确认框（若选中元素属于受保护的视频播放器，则会提示：“该元素属于视频播放器，隐藏后可能中断播放。是否继续？”）。
  • 取消（或按 Escape 键）： 退出选择器且不保存任何更改。

5. 本站过滤规则#

位于 概览 → 快捷操作 → 本站过滤规则（“管理此网站的自定义隐藏元素”）：

  • 打开弹窗列出当前 hostname 保存的所有自定义 CSS 选择器。
  • 点按任一选择器右侧的红色关闭（×）按钮即可删除该条规则（removeSingleRule），并立即在页面上恢复显示对应元素。
  • 若要一次性清空当前网站的所有自定义规则，请前往 关于 → 存储与更新 → 清除本站规则。

6. 连接日志#

位于 概览 → 快捷操作 → 连接日志（“查看并拦截第三方域名”）：

  • 显示内容： 展示当前页面会话期间记录的第三方域名（包括 networkRingBuffer 中最多 MAX_NET_BUFFER = 80 条最近的 fetch、xhr、beacon、script 和 img 请求，加上 scanStaticDomResources() 扫描到的最多 300 个跨源静态 <script>、<iframe>、<img > 元素），以及您此前手动拦截的域名。
  • 操作控件：
    • 搜索框（筛选域名...）： 按主机名或示例 URL 实时过滤列表。
    • 筛选标签（全部 / 已拦截）： 在全部第三方域名与仅已拦截域名之间切换。
    • 拦截 / 允许按钮： 点按拦截会将域名加入 nvirya_x_custom_blocked、更新 <style data-nvirya-cosmetic> 并立即清理页面上匹配的 DOM 节点（purgeCustomBlockedDom）。点按允许可移除自定义拦截域名。
    • 内置徽章： 被内置规则（RE_AD_HOST、RE_GAMBLING_HOST 或 RE_SUSPECT_TLD）拦截的域名会显示禁用的内置按钮；若需在特定网站放行内置规则，请使用本次会话暂停或允许此网站。
    • 清除会话日志： 清空内存中的当前会话请求列表。

7. 清理残留框架、预览原始页面（3 秒）、解除页面滚动锁定与撤销#

  • 清理残留框架（“立即折叠空白广告占位”）：查找最多 200 个匹配 [id^="google_ads_"], ins.adsbygoogle, iframe[src*="googlesyndication"], iframe[src*="doubleclick"] 的元素（跳过视频播放器）并标记 data-nvirya-hidden="clean"，同时运行 handleAntiAdblock()。
  • 预览原始页面（3 秒）（“临时显示被隐藏的元素 3 秒”）：临时禁用 <style data-nvirya-site-rules> 与 <style data-nvirya-cosmetic> 持续 3,000 ms，随后自动恢复过滤。注意：该功能仅揭示被 CSS 隐藏的元素，不会重建已从 DOM 树移除的节点（若需完整恢复已移除节点，请使用本次会话暂停）。
  • 解除页面滚动锁定（“恢复被隐藏遮罩锁定的滚动”）：在 <html> 与 <body> 上强制设置 overflow: auto !important 并重置 position: fixed。
  • 撤销 (Ctrl+Z)（“恢复最近隐藏的元素”）：可在面板中点按，或在面板与选择器关闭且未处于输入框焦点时按 Ctrl+Z（macOS/iPadOS 上为 Cmd+Z）。优先弹出并移除当前站点最近添加的一条自定义 CSS 规则；若当前站点无自定义规则，则从 state.removedNodes（上限 200 条）中恢复最近被自动移除的 DOM 节点。

8. 设置标签页控件#

在设置标签页中，您可以自定义外观、语言和防护模块：

  • 外观主题（自动 | 浅色 | 深色）： 控制 Shadow DOM 面板与弹窗的配色方案（也可通过面板顶部的太阳/月亮图标快速切换）。
  • 界面语言（自动 | EN | VI | 中文）： 在自动跟随浏览器语言、英文（en）、越南语（vi）与简体中文（zh-CN）之间实时切换。
  • 防护开关：
    • 智能护盾（“拦截弹窗、跳转和隐形陷阱”）：总开关，同步控制 enabled、popupProtection、redirectProtection 与 cosmeticFiltering。
    • 视频保护（“优化视频播放器并自动跳过广告”）：控制 playerProtection（默认：开启）。
    • 深度网络过滤（“严格拦截跟踪和统计域名”）：控制 strictMode（默认：关闭）。开启后会额外拦截匹配 RE_TRACKER 的统计分析域名，并将 DOM 启发式隐藏阈值降低至单信号（signals >= 1）。
    • 快捷悬浮按钮（“自动吸附到屏幕边缘”）：显示或隐藏浮动护盾按钮（showFloatingButton）。
    • 绕过反广告拦截（“绕过新闻网站的反广告拦截墙”）：控制 antiAdblock（默认：开启；在 iOS WebKit 沙盒隔离无法注入主世界脚本时自动禁用）。