Front-End-Checklist 无障碍规则实战彻底解决 Autoplay Media 自动播放媒体问题【免费下载链接】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 中的autoplay-media规则对应 技能定义 与其完整实现参考 references/rule.md系统讲解如何杜绝页面自动播放音频/视频对视障用户、认知障碍用户及低带宽场景造成的伤害。读完本文你将掌握 WCAG 1.4.2 与 2.2.2 的合规要点、可复制的 HTML/React 修复代码以及一套自动加人工的双层验证流程。规则是什么autoplay-media是 Front-End-Checklist 无障碍accessibility分类下的一条高优先级、入门难度、预计耗时 10 分钟的检查规则。其核心要求可以概括为一句断言Audio and video content does not autoplay, or provides immediate controls to pause or stop playback.音频和视频内容不得自动播放或必须提供立即可用的暂停/停止控制。在仓库中该规则有三份互相印证的载体面向 Agent/LLM 的技能定义skills/autoplay-media/SKILL.md —— 提供check检查、fix修复、explain解释、code review代码评审四个标准动作完整的规则参考文档skills/autoplay-media/references/rule.md —— 包含代码示例、WCAG 对照、验证清单规则源文件packages/content/rules/en/accessibility/autoplay-media.mdx —— 站点的结构化数据源同时被 README.md 中的总清单引用并可通过pnpm generate:skills重新生成技能。为什么必须禁止自动播放自动播放媒体带来的不是体验小瑕疵而是三重真实伤害淹没屏幕阅读器语音自动播放的音频与屏幕阅读器朗读的内容同时输出视障用户会完全无法听清页面内容等于页面对其不可用惊吓与眩晕突然响起的音视频会惊吓认知障碍、前庭障碍用户甚至引发不适反应浪费带宽在流量受限或弱网环境下无声浪费用户流量会直接推高跳出率。原规则用一句话点明立场Always require user interaction to start audio.—— 音频的启动必须以用户交互为前提这是底线。快速参考清单在开始写代码前先记住四条铁律同样收录于 SKILL.md 与 MDX 的tldr字段永远不要自动播放音频——它会干扰屏幕阅读器如果视频必须自动播放确保默认静音muted提供立即可达的暂停/停止控制自动播放应在 5 秒后停止或提供停止机制。HTML 层三种写法的对错示范规则参考文档给出了最直观的 HTML 对比示例这是任何框架方案的基础!-- ❌ 错误带音频自动播放 -- video autoplay srcvideo.mp4/video !-- ✅ 可接受静音自动播放背景视频 -- video autoplay muted loop playsinline srchero-bg.mp4/video !-- ✅ 最佳实践不自动播放交给用户控制 -- video controls srcvideo.mp4 track kindcaptions srccaptions.vtt srclangen labelEnglish /video三个要点第一个示例是典型违规——autoplay配合有声内容是屏幕阅读器用户最痛恨的模式第二个示例展示了背景视频的通行做法muted消音、loop循环、playsinline保证移动端内联播放。静音是自动播放得以成立的先决条件第三个示例是首选方案不写autoplay通过原生controls让用户自己决定是否播放并顺手用track kindcaptions补充字幕这正是同属媒体分类的 video-captions 规则所要求的。React 实战可访问视频播放器组件规则参考文档提供了一个完整的 React 播放器组件基于useStateuseRef它演示了用户控制优先的核心交互模式。以下为补全类型标注与完整 JSX 的可运行版本function VideoPlayer({ src, poster }) { const [isPlaying, setIsPlaying] useState(false) const [isMuted, setIsMuted] useState(true) const videoRef useRefHTMLVideoElement(null) const togglePlay () { if (videoRef.current) { if (isPlaying) { videoRef.current.pause() } else { videoRef.current.play() } setIsPlaying(!isPlaying) } } return ( div classNamevideo-container video ref{videoRef} src{src} poster{poster} muted{isMuted} playsInline / div classNamecontrols button onClick{togglePlay} aria-label{isPlaying ? Pause video : Play video} {isPlaying ? PauseIcon / : PlayIcon /} /button button onClick{() setIsMuted(!isMuted)} aria-label{isMuted ? Unmute video : Mute video} {isMuted ? MutedIcon / : VolumeIcon /} /button /div /div ) }这个组件暗含三条无障碍设计原则值得逐条拆解默认不自动播放初始状态isPlaying false视频静默等待用户操作原生按钮 aria-label播放/暂停与静音/取消静音都是真正的button而非 div 加点击事件天然支持键盘与屏幕阅读器动态变化的aria-label如Pause video↔Play video保证辅助技术始终能读出当前动作语义状态切换通过muted属性单向控制避免直接操作volume造成播放策略上的不确定性。React 实战背景视频 显眼的停止按钮对于必须自动播放的场景如 Hero 区背景视频规则给出了带暂停背景视频按钮的完整方案。要点是自动播放可以被容忍但用户必须能立即且显眼地叫停它。function HeroWithVideo() { const [isPlaying, setIsPlaying] useState(true) const videoRef useRefHTMLVideoElement(null) const toggleVideo () { if (videoRef.current) { if (isPlaying) { videoRef.current.pause() } else { videoRef.current.play() } setIsPlaying(!isPlaying) } } return ( section classNamehero video ref{videoRef} autoPlay muted loop playsInline classNamehero-video source srchero.mp4 typevideo/mp4 / /video {/* 显眼的暂停控制 */} button onClick{toggleVideo} classNamevideo-control aria-label{isPlaying ? Pause background video : Play background video} {isPlaying ? Pause : Play} Background /button div classNamehero-content h1Welcome/h1 /div /section ) }工程要点autoPlay必须与muted搭配使用——这也解释了为什么多数现代浏览器只对静音媒体放行自动播放loopplaysInline保证背景视频在桌面与移动端表现一致控制按钮必须显眼video-control样式类而不是藏在某个菜单里SKILL.md 特别强调对含多个媒体元素的页面考虑增加一个全局暂停按钮一键停掉整页所有媒体。对照 WCAG两条必须满足的成功准则规则参考文档给出了与本规则直接相关的两条 WCAG 准则这也是审计与验收的合规依据准则要求1.4.2 Audio Control自动播放超过 3 秒的音频必须提供暂停/停止/静音控制2.2.2 Pause, Stop, Hide移动、闪烁、滚动的内容必须提供暂停、停止或隐藏的机制将这两条与快速参考清单中的5 秒结合理解WCAG 1.4.2 给出的合规窗口是3 秒而项目建议的自动播放上限是5 秒——换言之即便被允许短暂自动播放也必须尽快交给用户控制二者并不矛盾3 秒是硬性合规线5 秒是项目内的从严实践上限。例外情况什么时候不必一票否决规则文档专门列出 Exceptions例外提醒审计者在真实渲染环境中做判断而非机械地扫静态代码先看渲染后的实际体验交互时机、浏览器行为、辅助技术的实际输出往往决定严重程度静态代码中的疑似违规不一定是阻断项按影响排序并非每个次要的无障碍问题权重相同应优先处理最直接阻碍感知、操作、理解的那一个不为合规而堆 ARIA如果更简单的原生语义实现如原生button、原生controls能彻底消除问题就不要添加冗余标记或 ARIA。这一点与项目的一贯方法论一致——规则源文件packages/content/rules/en/accessibility/autoplay-media.mdx中反复强调verify the rendered experience, not only the source code。验证自动化 人工双通道自动化检查使用浏览器无障碍工具axe DevTools、Lighthouse 或等价工具针对有代表性的渲染状态运行检查。注意关键词是渲染状态——autoplay这类行为的触发条件依赖真实运行环境静态分析无法覆盖。人工检查清单SKILL.md 与规则文档共用的 Manual Checks加载页面确认没有意外播放的音频如果视频自动播放确认它是静音的检查暂停控件是否可通过键盘访问并且位于 Tab 顺序靠前的位置within the first few tab stops验证屏幕阅读器能否播报并与控件交互。在项目中的落地方式作为技能使用本规则在仓库中被打包成一个可安装的技能Skill。项目 README.md 说明了用法想获得可复用的审计工作流或聚焦的规则级指引可安装 Front-End Checklist skillsnpx skills add frontendchecklist/skills # 只装某一条规则对应的技能例如 npx skills add frontendchecklist/skills --skill https全局审计入口是 skills/frontend-checklist-global/SKILL.mdautoplay-media则属于规则级技能的代表其 SKILL.md 头部元数据声明了适用时机Use when reviewing rendered HTML, interactive components, or design-system patterns related to Avoid autoplaying media.审查渲染后的 HTML、交互组件或设计系统模式中与自动播放媒体相关的内容时使用并给出了检查优先级——先看原生语义再检查键盘行为、焦点流、可访问名称与屏幕阅读器输出。技能与规则源文件由脚本同步生成pnpm generate:skills因此 SKILL.md 中的 Quick Reference、Check、Fix、Explain、Code Review 五个部分与规则源文件的tldr、prompts字段一一对应保证 Agent 拿到的指引永远与站点规则保持一致。相关规则联动autoplay-media在媒体无障碍accessibility/media子类中与以下规则常被一起审查见规则源文件的relatedRules字段video-captions视频必须提供同步字幕WCAG 2.1 SC 1.2.2/1.2.4通过track kindcaptions.vtt文件实现audio-descriptions纯音频内容需要文本替代video-accessibility视频元素的整体可访问性。在实际审查中建议把四条规则作为媒体审计包一次性执行先解决自动播放问题本规则再补字幕、音频描述与整体语义。小结Autoplay media 从来不是一个锦上添花的体验问题而是直接决定视障用户能否使用页面的合规红线。遵循本规则的三步走默认不自动播放 → 必须自动播放则静音 立即可达的暂停控制 → 用 axe/Lighthouse 加人工键盘与读屏验证即可同时满足 WCAG 1.4.2 / 2.2.2 与良好的用户体验。完整代码示例与验证细节可随时查阅 skills/autoplay-media/references/rule.md 与规则源文件 packages/content/rules/en/accessibility/autoplay-media.mdx。【免费下载链接】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），仅供参考