Front-End-Checklist 规则实战:避免侵入式插层(Interstitials)——从 Google 移动端惩罚到无障碍模态框焦点管理 📅 发布时间:2026/9/19 6:46:00 👁 浏览次数: Front-End-Checklist 规则实战避免侵入式插层Interstitials——从 Google 移动端惩罚到无障碍模态框焦点管理【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本篇以 Front-End-Checklist 仓库中「Avoid intrusive interstitials避免侵入式插层」规则为主线完整覆盖该规则的判定标准、修复方案与可访问性模态框实现模式并结合仓库源码说明这条规则如何从 MDX 内容文件生成、分发给 AI Agent 与人类开发者。读完本文你可以掌握一套识别侵入式弹窗的五问检查法、替换方案sticky banner 等的 CSS 实现、符合 WAI-ARIA dialog pattern 的焦点管理代码以及上线前的验证清单。规则定位与仓库中的来源在 Front-End-Checklist 仓库中这条规则的核心文档是 skills/interstitials/references/rule.md其元数据为Priority:medium中等优先级Difficulty:intermediate中级难度Time:10 min预计修复耗时 10 分钟分类:CSSresponsive 子分类规则的一句话定义见 rule.md 第 3 行在移动端阻断主内容的全屏插层弹窗、遮罩、cookie 横幅既是搜索引擎的排名惩罚信号也是无障碍障碍。应使用非侵入式替代方案。这条规则的完整定义实际上来源于 packages/content/rules/en/css/interstitials.mdx。该 MDX 文件的 frontmatter 中包含了tldr快速参考、whyItMatters、aiContext以及prompts.check / fix / explain / codeReview四段面向 Agent 的提示词并在sources中登记了 Google 搜索团队关于 Intrusive Interstitials 的说明、WCAG 2.1 SC 2.1.2、WAI-ARIA Authoring Practices 的 dialog-modal pattern 和 MDN 的dialogrole 文档作为一手权威来源。从源码结构看skills/目录下的文件并非手工维护而是由 scripts/generate/generate-skills.ts 从packages/content/rules/en/下的 MDX 规则批量生成的。该脚本读取每个规则的 frontmatter将aiContext改写为以 Use when 开头的 description 并写入SKILL.md再把 MDX 正文剥离 JSX 后输出为references/rule.md。因此 skills/interstitials/SKILL.md 与references/rule.md内容上的差异是设计使然前者是给 Agent 的「何时检查、怎么查、怎么修」指令后者是供人类阅读的完整规则说明。生成命令在仓库中以pnpm generate:skills形式提供支持全量或指定 MDX 文件增量生成。为什么侵入式插层是双重问题SEO 与无障碍规则文档将问题归纳为四个具体受众SEOGoogle 会对「从搜索结果点击进入后展示侵入式插层」的页面降低移动端搜索排名。键盘用户没有焦点管理的模态框键盘用户既无法与其中交互也无法将其关闭。屏幕阅读器用户一个没有焦点管理就出现的遮罩层对屏幕阅读器用户是「不可见」的——他们听到页面内容却不知有对话框出现。认知负荷意料之外的遮罩会打断用户意图对认知障碍用户尤其具有迷惑性。SKILL.md 的 Quick Reference 进一步给出了判定依据的要点移动端页面加载时立即覆盖主内容的全屏弹窗会被 Google Search 惩罚对应 2017 年 1 月的 Intrusive Interstitials Update可接受的插层年龄验证、法律强制要求的声明如法律强制的 cookie 同意、私有内容的登录墙不可接受覆盖移动端主内容区域且难以关闭的弹窗无障碍要求模态对话框必须捕获焦点focus trap、可用键盘Escape 键关闭、并在关闭后把焦点归还给触发元素WCAG 2.1 SC 2.1.2No Keyboard Trap用户必须能够用键盘将焦点移出任何组件。其 Explain 部分还指出一个不管理焦点的模态框同时会触碰 WCAG 2.1 SC 2.1.2键盘陷阱和 SC 4.1.3状态消息两条成功标准——屏幕阅读器用户既不知道对话框已出现、无法导航到它、或被困其中无法退出都属于 WCAG 失败项。WAI-ARIA dialog pattern 把焦点管理视为基线要求。识别插层五问检查法SKILL.md 的 Check 一节同样源自 interstitials.mdx 的prompts.check给出了一套可执行的静态审查流程。先定位「使用position: fixed或position: absolute且带高z-index、覆盖视口较大区域」的元素然后对每个元素逐条问五个问题它是否在页面加载时、或加载后几秒内出现在移动端屏幕宽度 600px上它是否覆盖了主内容的小范围以外它是否易于关闭——有没有一个可见的、带无障碍名称的关闭按钮能否按 Escape 键将其关闭打开时焦点是否移入对话框关闭时是否归还给触发元素任何一条不满足都应把该对话框标记为问题。这套检查同时面向 CSS定位与层叠和 JavaScript触发时机、焦点逻辑aiContext中明确提醒 Agent 注意「页面加载或加载后短时间内显示模态框的 JavaScript」。CSS 反模式与修复全屏遮罩 vs 底部 sticky 横幅rule.md 的 Code Example 给出了一对可直接对照的 CSS 示例。反模式是页面加载时出现的全视口遮罩/* ❌ Problem: full-viewport overlay appears on page load */ .modal-overlay { position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0, 0, 0, 0.8); z-index: 9999; }关键点在于width: 100%; height: 100%配合z-index: 9999它把整个视口完全盖住用户在关闭前无法触达任何主内容这正是 Google 惩罚的形态。推荐的替代形态是底部小尺寸 sticky 横幅以 cookie 横幅为例/* ✅ Better: small sticky banner at the bottom */ .cookie-banner { position: fixed; bottom: 0; left: 0; right: 0; max-height: 15vh; background: #fff; border-top: 2px solid #ccc; z-index: 100; padding: 1rem; }两个实现的关键差异max-height: 15vh把横幅限制在视口高度的 15% 以内Check/Fix 提示词中的建议区间是 10–15%主内容仍然可见、可滚动z-index从 9999 降到 100不再制造「压过一切」的层叠层级横幅锚定在bottom: 0成为页面布局的一部分而非对内容的拦截。对应的 Fix 策略来自 SKILL.md 的 Fix 一节共有四条按优先级排列把「页面加载时的全屏弹窗」替换为三种形态之一(a) 顶部或底部 sticky 横幅max-height 为视口的 10–15%、(b) 页面内的内联内容块、(c) 不覆盖主内容的滑入面板法律强制的声明如 cookie 同意使用小型 sticky 横幅而非全屏遮罩所有必须保留的模态对话框实现 ARIA dialog pattern加roledialog、aria-modaltrue、指向标题的aria-labelledby用 focus trap 把焦点限制在对话框内打开时把焦点移到内部第一个可聚焦元素支持 Escape 关闭关闭时把焦点归还给触发元素非关键的弹窗延迟到用户产生交互后再触发而不是在页面加载时触发。可接受 vs 不可接受的插层rule.md 中的对照表完整给出了判定边界类型是否可接受原因页面加载时的全屏弹窗移动端否Google 惩罚阻断内容Cookie 同意横幅小尺寸、sticky是法律要求占位小年龄验证门是法律要求的例外登录墙私有内容是内容需要认证订阅弹窗延迟触发、可关闭谨慎使用不能在页面加载时出现必须可访问GDPR/cookie 全屏遮罩避免改用 sticky 横幅注意表格中「谨慎使用」一行订阅类营销弹窗并非绝对禁止但前提是延迟到用户交互之后出现、且自身可访问有可聚焦的关闭按钮、支持 Escape 关闭。这与 Google 惩罚的判定条件「从搜索结果进入后立即弹出」精确对应——同样一个弹窗触发时机不同合规结论不同。当模态框不可避免可访问模态框模式当业务流程确实需要模态对话框例如 cookie 偏好设置面板rule.md 的 Accessible Modal Pattern 一节给出了最小完整实现。标记层遵循 WAI-ARIA dialog pattern!-- ✅ Accessible modal dialog -- div roledialog aria-modaltrue aria-labelledbydialog-title aria-describedbydialog-description idcookie-dialog h2 iddialog-titleCookie Preferences/h2 p iddialog-descriptionWe use cookies to improve your experience./p button typebutton idaccept-btnAccept all/button button typebutton idreject-btnReject non-essential/button button typebutton aria-labelClose dialog idclose-btn×/button /div四个 ARIA 属性各自承担一个职责roledialog声明控件类型aria-modaltrue告知辅助技术「这是模态的背景内容不可操作」aria-labelledby/aria-describedby把可见标题与说明文字关联为对话框的可访问名称与描述关闭按钮用aria-label提供可访问名称因为×字符本身没有语义。焦点管理 JavaScript规则强调这是「Required focus management」// Required focus management function openModal(dialog, triggerEl) { dialog.removeAttribute(hidden); dialog.querySelector([id$-btn]).focus(); // Focus first button } function closeModal(dialog, triggerEl) { dialog.setAttribute(hidden, ); triggerEl.focus(); // Return focus to trigger } // Dismiss on Escape document.addEventListener(keydown, (e) { if (e.key Escape) closeModal(dialog, triggerEl); });这段代码覆盖了 Check 一节中三个焦点相关判定点中的两个打开时把焦点移入对话框内第一个可聚焦按钮[id$-btn]选择器按 ID 后缀匹配-btn结尾的按钮关闭时把焦点归还给触发元素triggerEl.focus()以及 Escape 键关闭。需要说明的是示例展示的是「焦点进出」的最小闭环Tab 键在对话框内的循环完整 focus trap需要额外逻辑。纵深参考完整 focus trap 与原生dialog仓库中与之强相关的 modal-accessibility 规则参考文档Make modal dialogs keyboard accessible补充了 interstitials 规则未展开的两部分实现可作为本条规则 Fix 第 3 条「trap focus within the dialog」的落地参考完整 focus trapTSX 实现在keydown处理器中除了 Escape 分支外对 Tab 键枚举对话框内所有可聚焦元素选择器为button, [href], input, select, textarea, [tabindex]:not([tabindex-1])当 ShiftTab 停在前第一个元素时跳回最后一个当 Tab 停在最后一个元素时跳回第一个从而让焦点在模态框内循环同时打开时执行document.body.style.overflow hidden禁用背景滚动关闭时恢复。该文档还附了一张无障碍对照表明确列出 7 项要求roledialog、aria-modaltrue、aria-labelledby指向标题、focus trap、Escape 关闭、关闭后焦点归还触发器、打开期间禁用背景滚动。原生dialog元素若目标浏览器支持dialog.showModal()会自动处理焦点捕获与背景 inert 化可以显著减少手写 JS关闭时用dialog.close()。从源码结构看这两份参考文档遵循同一套「rule.md 正文 SKILL.md 指令」的生成模式因此可以组合使用用 interstitials 规则判断「该不该弹、何时弹、弹多大」用 modal-accessibility 规则实现「弹出来之后焦点如何管理」。验证清单rule.md 的 Verification 一节给出了上线前的四步验证在受影响的断点与交互状态下检查渲染后的 UI在 DevTools 中确认计算样式computed styles与预期修复一致发布前至少在移动与桌面各一个视口下测试若该规则影响到动效、对比度或布局稳定性直接验证这些面向用户的呈现结果。结合 modal-accessibility 的手动检查流程对「保留了模态框」的方案还应逐项手动验证用键盘Enter/Space 在触发器上打开模态框确认焦点移入模态框内部Tab 遍历所有元素焦点不应逃逸到背景内容按 Escape模态框应关闭确认焦点回到打开该模态框的元素。相关规则与延伸阅读interstitials.mdx 的 frontmatter 在relatedRules中将本规则与以下同属css/responsive领域、常一起审查的规则关联对应技能文件分别位于 skills/viewport-zoom/、skills/font-size/、skills/horizontal-scroll/、skills/touch-targets/viewport-zoomviewport 不得禁用缩放——与插层问题共同影响移动端内容可达性font-size移动端字号可读性horizontal-scroll固定定位的全宽横幅若宽度计算不当容易诱发横向滚动touch-targets横幅内的关闭/同意按钮触控目标尺寸。主题上紧密相邻的还有 cookie-consent 规则它关注 cookie 声明本身的数据最小化与同意机制而 interstitials 规则关注其呈现形态是否侵入。两条规则在「GDPR 全屏遮罩应改为 sticky 横幅」这一结论上汇合。此外该规则在仓库中的呈现还有两处README.md 的 CSS 规则清单与 docs/generated/rules-catalog.md 的规则目录中均以 Medium 优先级收录了「Avoid intrusive interstitials」条目。小结「Avoid intrusive interstitials」这条规则的价值在于把两类看似独立的约束——搜索引擎的排名信号与 WCAG 的焦点管理要求——收敛到同一组判定标准上插层是否阻断移动端主内容、是否易于关闭、焦点是否进出有据。修复路径也随之清晰能用 15vh 以内的 sticky 横幅或内联块解决的就不要用全屏遮罩必须用模态框的就完整实现 dialog pattern 的焦点管理并按「打开移入焦点、Tab 不逃逸、Escape 关闭、关闭归还焦点」的清单逐项验证。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考