• role="button"
• tabIndex={0}
• onKeyDown / onKeyPress 键盘事件处理（Enter/Space 触发点击）

修复：添加 role="button"、tabIndex={0}，以及一个在 Enter/Space 时触发点击的 onKeyDown 处理器。

规则 3：图片 alt 文本（img-alt-a11y）

检测： 元素中：

• alt 属性完全缺失
• alt 为无意义值，如 alt="image"、alt="photo"、alt="picture"、alt="icon"

装饰性图片使用 alt="" 是合法的，不应标记。

修复：根据上下文（文件名、周围文本、父组件语义）添加描述性 alt。如确为装饰性图片，添加 alt="" 和 role="presentation"。

规则 4：表单标签（form-label-a11y）

检测：、</code>、<code><select></code> 没有关联的 <code><label></code>（通过 <code>htmlFor</code> / 包裹方式）或 <code>aria-label</code> / <code>aria-labelledby</code>。</p><p><strong>修复</strong>：根据 placeholder、附近标题或父级上下文推断文本，添加 <code>aria-label</code>。可行时优先使用显式的 <code><label></code> 包裹。</p><h3>规则 5：弹窗/对话框无障碍（dialog-a11y）</h3><p><strong>检测</strong>：弹窗/对话框组件（如 <code>Dialog</code>、<code>Modal</code>、<code>YbcDialog</code>、<code>Drawer</code>）缺少：</p><ul><li><code>aria-modal="true"</code>（如果底层库未设置）</li><li><code>aria-labelledby</code> 或 <code>aria-label</code> 指向对话框标题</li><li>焦点捕获 / 焦点归还逻辑</li></ul><p><strong>修复</strong>：添加指向标题元素 id 的 <code>aria-labelledby</code>，或在无标题元素时添加 <code>aria-label</code>。焦点管理问题以警告形式标注。</p><h3>规则 6：实时区域（live-region-a11y）</h3><p><strong>检测</strong>：动态内容区域（Toast 通知、加载状态、错误提示、聊天消息）缺少 <code>aria-live</code>、<code>aria-atomic</code> 或 <code>role="status"</code> / <code>role="alert"</code>。</p><p><strong>修复</strong>：添加合适的 <code>aria-live="polite"</code>（默认）或 <code>aria-live="assertive"</code>（错误/警告），以及需要整体重新播报时添加 <code>aria-atomic="true"</code>。</p><h2>扫描工作流</h2><pre><code>任务进度： - [ ] 步骤 1：确定扫描范围（文件/目录） - [ ] 步骤 2：按 7 条规则搜索违规项（含兼容性） - [ ] 步骤 3：汇总审查报告 - [ ] 步骤 4：应用自动修复 - [ ] 步骤 5：验证修复未引入新问题 </code></pre><h3>步骤 1：确定扫描范围</h3><p>使用 Glob 查找目标目录下所有 <code>.tsx</code> 文件：</p><pre><code>**/*.tsx </code></pre><p>排除 <code>node_modules</code>、<code>dist</code>、<code>build</code>、<code>.next</code>、<code>__tests__</code>、<code><em>.test.tsx</code>、<code></em>.spec.tsx</code>。</p><h3>步骤 2：搜索违规项</h3><p>针对每条规则，使用 Grep 查找潜在违规项：</p><p><strong>纯图标按钮：</strong></p><pre><code>onClick.*<(YbIcon|Icon|SvgIcon) </code></pre><p>然后验证父级可点击元素是否存在 <code>aria-label</code>。</p><p><strong>div 模拟按钮：</strong></p><pre><code><(div|span)[\s\S]*?onClick </code></pre><p>然后验证是否存在 <code>role="button"</code> 和 <code>tabIndex</code>。</p><p><strong>缺失 alt：</strong></p><pre><code><img[\s\S]*?(?!alt=) </code></pre><p><strong>未标注的表单元素：</strong></p><pre><code><(input|textarea|select)[\s\S]*?(?!aria-label) </code></pre><p><strong>未标注的弹窗：</strong></p><pre><code><(Dialog|Modal|YbcDialog|Drawer) </code></pre><p>然后验证是否存在 <code>aria-labelledby</code> 或 <code>aria-label</code>。</p><p><strong>缺少实时区域标注的动态内容：</strong></p><pre><code>(toast|Toast|notification|Notification|loading|Loading|errorMsg|errorMessage) </code></pre><p>然后验证附近是否存在 <code>aria-live</code> 或 <code>role="alert"</code> / <code>role="status"</code>。</p><p><strong>兼容性问题：</strong></p><pre><code>inert[^a-zA-Z] </code></pre><p>检查是否有 <code>inert</code> 回退。</p><pre><code>:focus-visible </code></pre><p>检查是否有 <code>:focus</code> 基础样式回退。</p><pre><code>suppressHydrationWarning </code></pre><p>检查同一元素是否有正确的 <code>alt</code> / <code>aria-label</code>。</p><pre><code>role="(status|alert|feed)" </code></pre><p>在微信/QQ 环境中这些 role 不可靠，检查是否有语义化元素替代或多通道回退。</p><h3>步骤 3：汇总报告</h3><p>按以下格式输出审查结果：</p><pre><code>## 无障碍审查报告 ### 文件：src/components/Example.tsx | 行号 | 规则 | 问题 | 建议修复 | |------|------|------|----------| | 42 | icon-button-a11y | onClick div 中的 `<YbIcon>` 缺少 aria-label | 添加 `aria-label={t('关闭')}` | | 78 | div-button-a11y | `<div onClick>` 缺少 role 和键盘交互 | 添加 `role="button"` tabIndex={0} onKeyDown | </code></pre><h3>步骤 4：应用修复</h3><p>使用 StrReplace 逐项应用修复。保留：</p><ul><li>现有缩进风格（空格 vs Tab）</li><li>代码格式（引号风格与周围代码一致）</li><li>i18n 包裹：若项目使用 <code>t()</code> / <code>useTranslation</code>，用其包裹标签文本</li></ul><h3>步骤 5：验证</h3><p>修复后，对修改过的文件运行 ReadLints，检查是否引入了新错误。</p><h2>框架特定注意事项</h2><h3>TDesign 组件</h3><p>TDesign 的 <code>Button</code>、<code>Dialog</code>、<code>Input</code> 等通常内部处理了基本无障碍。重点关注：</p><ul><li>覆盖或遗漏了内置属性的自定义包装组件</li><li><code>content</code> 或 <code>children</code> 等提供隐式标签的 props</li></ul><h3>@tencent/yb-component</h3><p><code>YBButton</code>、<code>YbcDialog</code> 是薄层封装。检查 a11y props 是否被正确透传。如果封装层吞掉了 <code>aria-*</code> props，需要标记。</p><h3>Next.js <code><Image></code></h3><p>Next.js 的 <code>Image</code> 组件默认要求 <code>alt</code> 并会发出警告。仍需验证 alt 文本是否有实际意义。</p><h2>规则 7：跨平台兼容性（compat-a11y）</h2><p>本项目运行在多种平台上，不同引擎对无障碍 API 的支持存在差异，修复时必须考虑兼容性。</p><h3>目标平台一览</h3><table><thead><tr><th>平台</th><th>引擎</th><th>无障碍支持等级</th></tr></thead><tbody><tr><td>------</td><td>------</td><td>----------------</td></tr><tr><td>桌面端（Tauri macOS）</td><td>WKWebView</td><td>较好，VoiceOver 支持完整</td></tr><tr><td>桌面端（Tauri Windows）</td><td>WebView2 (Chromium)</td><td>好，NVDA/JAWS 支持完整</td></tr><tr><td>桌面端（Tauri Linux）</td><td>WebKitGTK</td><td>一般，Orca 支持有限</td></tr><tr><td>Chrome/Edge 扩展</td><td>Chromium</td><td>好</td></tr><tr><td>微信内置浏览器</td><td>自研 X5 / 系统 WebView</td><td>较差，部分 ARIA 属性被忽略</td></tr><tr><td>QQ 内置浏览器</td><td>MQQBrowser 内核</td><td>较差</td></tr><tr><td>PC 微信</td><td>Chromium 内嵌</td><td>一般</td></tr><tr><td>企业微信</td><td>系统 WebView</td><td>一般</td></tr><tr><td>小程序 WebView</td><td>受限沙箱</td><td>差，焦点管理受限</td></tr></tbody></table><h3>兼容性检测规则</h3><p><strong>7a. <code>inert</code> 属性兼容（compat-inert）</strong></p><p><code>inert</code> 属性在旧版 WebView 中不被支持。如果使用了 <code>inert</code>，需要同时提供 polyfill 或回退方案（<code>aria-hidden="true"</code> + <code>tabIndex={-1}</code>）。</p><p><strong>7b. <code><dialog></code> 元素兼容（compat-dialog）</strong></p><p>原生 <code><dialog></code> 元素在 X5 内核、旧版 WKWebView、小程序 WebView 中可能不受支持。优先使用库组件（TDesign <code>Dialog</code> / <code>YbcDialog</code>）而非原生 <code><dialog></code>。</p><p><strong>7c. <code>focus-visible</code> 伪类兼容（compat-focus-visible）</strong></p><p><code>:focus-visible</code> 在微信 X5 内核中可能不生效。需要同时保留 <code>:focus</code> 样式作为回退：</p><pre><code>.btn:focus { outline: 2px solid var(--focus-color); } .btn:focus:not(:focus-visible) { outline: none; } .btn:focus-visible { outline: 2px solid var(--focus-color); } </code></pre><p><strong>7d. <code>aria-live</code> 在受限 WebView 中的兼容（compat-live-region）</strong></p><p>微信/QQ 内置浏览器中 <code>aria-live</code> 可能不触发屏幕阅读器播报。对于关键通知，除了 ARIA 标注外，建议同时提供视觉反馈（如 Toast 动画）和触觉反馈（如震动 API）作为多通道回退。</p><p><strong>7e. 焦点管理在小程序 WebView 中的限制（compat-focus-trap）</strong></p><p>小程序 WebView 沙箱中 <code>document.activeElement</code> 和程序化 <code>focus()</code> 行为不一致。弹窗焦点捕获应通过库组件实现，避免直接操作 DOM focus。检查是否存在 <code>isMpWebview</code> 条件分支来处理此类差异。</p><p><strong>7f. <code>role</code> 属性在 X5 内核中的支持（compat-role）</strong></p><p>微信 X5 内核对某些 ARIA role（如 <code>role="status"</code>、<code>role="alert"</code>、<code>role="feed"</code>）支持不完整。在这些环境中，优先使用语义化 HTML 元素（<code><button></code> 替代 <code>role="button"</code>、<code><nav></code> 替代 <code>role="navigation"</code>）。</p><p><strong>7g. <code>suppressHydrationWarning</code> 与无障碍的交叉（compat-hydration）</strong></p><p>项目中大量使用 <code>suppressHydrationWarning</code>。检查设置了此属性的 <code><img></code> 元素是否同时有正确的 <code>alt</code>，防止 SSR/CSR 不一致导致 alt 文本丢失。</p><h3>兼容性修复策略</h3><ol><li><strong>优先使用语义化 HTML</strong> — 原生 <code><button></code>、<code><a></code>、<code><input></code> 在所有引擎中的无障碍支持都优于 ARIA 标注的 <code><div></code></li><li><strong>ARIA 作为增强而非依赖</strong> — 先确保语义化，再用 ARIA 补充</li><li><strong>多通道反馈</strong> — 不依赖单一的辅助技术 API，结合视觉、听觉、触觉反馈</li><li><strong>平台条件分支</strong> — 利用项目现有的 <code>isDesktop</code>、<code>isMpWebview</code>、<code>isWeChat</code> 等环境检测，为受限平台提供替代方案</li><li><strong>渐进增强</strong> — 使用特性检测（<code>if ('inert' in HTMLElement.prototype)</code>）而非 UA 嗅探</li></ol><h2>修复优先级</h2><p>当存在大量违规时，按以下顺序修复（影响从高到低）：</p><ol><li><strong>交互控件</strong>缺少标签（纯图标按钮、div 模拟按钮）— 完全阻碍使用</li><li><strong>表单</strong>缺少标签 — 无法输入</li><li><strong>图片</strong>缺少 alt — 信息丢失</li><li><strong>弹窗</strong>缺少 aria 属性 — 导航混乱</li><li><strong>实时区域</strong> — 降低实时感知</li></ol><h2>补充资料</h2><ul><li>规则的详细说明和边界情况，参见 <a href="reference.md" target="_blank" rel="noopener">reference.md</a></li><li>修复前后的代码示例，参见 <a href="examples.md" target="_blank" rel="noopener">examples.md</a></li></ul></div> </div> </div> <div id="tab-versions" class="detail-content"> <div class="detail-section"> <h2>版本历史</h2> <p style="margin-bottom:12px;font-size:14px;color:#94a3b8;">共 1 个版本</p> <ul class="version-list"> <li> <div> <span class="version-tag">v1.0.0</span> <span style="font-size:11px;color:#5b6abf;margin-left:8px;background:#eef0ff;padding:1px 8px;border-radius:10px;">当前</span> </div> <div style="font-size:12px;color:#94a3b8;"> 2026-05-03 08:43 安全 安全 </div> </li> </ul> </div> </div> <div id="tab-security" class="detail-content"> <div class="detail-section"> <h2>安全检测</h2> <div class="sec-grid"> <div class="sec-card"> <h4>腾讯云安全 (Keen)</h4> <div class="sec-status sec-safe"> 安全，无风险 </div> <a href="https://tix.qq.com/search/skill?keyword=396d514e740ee200c0da50fae0f7800b" target="_blank">查看报告</a> </div> <div class="sec-card"> <h4>腾讯云安全 (Sanbu)</h4> <div class="sec-status sec-safe"> 安全，无风险 </div> <a href="https://static.cloudsec.tencent.com/html-report-v2/2026/05/26/431328_a86695d0609fbfe95e1d2e6afaed8a4e.html?q-sign-algorithm=sha1&q-ak=AKID8JMG1bzBC1dz96qNhssfFftujT1NCoFi&q-sign-time=1781418103%3B1812954103&q-key-time=1781418103%3B1812954103&q-header-list=host&q-url-param-list=&q-signature=351164b34328d5c57b5785e40b13eed4174a14fc" target="_blank">查看报告</a> </div> </div> </div> </div> <!-- Recommended Skills --> <div style="margin-top:24px;"> <h2 style="font-size:18px;font-weight:600;margin-bottom:16px;">🔗 相关推荐</h2> <div class="rec-grid"> <div class="rec-card"> <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">ai-intelligence</span> <h3><a href="/s/self-improving">Self-Improving + Proactive Agent</a></h3> <div class="rec-owner">ivangdavila</div> <div class="rec-desc">自我反思+自我批评+自我学习+自组织记忆。智能体评估自身工作、发现错误并持续改进。</div> <div class="rec-stats"> <span style="color:#f39c12;">★ 1,363</span> <span style="color:#5b6abf;">📥 319,036</span> </div> </div> <div class="rec-card"> <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">ai-intelligence</span> <h3><a href="/s/self-improving-agent">self-improving agent</a></h3> <div class="rec-owner">pskoett</div> <div class="rec-desc">捕获经验教训、错误和纠正，以实现持续改进。使用时机：（1）命令或操作意外失败；（2）用户纠正……</div> <div class="rec-stats"> <span style="color:#f39c12;">★ 4,062</span> <span style="color:#5b6abf;">📥 799,864</span> </div> </div> <div class="rec-card"> <span class="badge-cat" style="margin-bottom:8px;display:inline-block;">security-compliance</span> <h3><a href="/s/skill-vetter">Skill Vetter</a></h3> <div class="rec-owner">spclaudehome</div> <div class="rec-desc">AI智能体技能安全预审工具。安装ClawdHub、GitHub等来源技能前，检查风险信号、权限范围及可疑模式。</div> <div class="rec-stats"> <span style="color:#f39c12;">★ 1,219</span> <span style="color:#5b6abf;">📥 266,846</span> </div> </div> </div> </div> </div> <script> document.addEventListener('DOMContentLoaded',function(){ document.querySelectorAll('.detail-tab').forEach(function(btn){ btn.addEventListener('click',function(e){ var tab = this.getAttribute('data-tab'); document.querySelectorAll('.detail-tab').forEach(function(b){b.classList.remove('active')}); document.querySelectorAll('.detail-content').forEach(function(c){c.classList.remove('active')}); this.classList.add('active'); var el = document.getElementById('tab-'+tab); if(el) el.classList.add('active'); }); }); }); </script> <div class="footer"> <p>Skill工具集 © 2026</p> </div></body> </html>