capacitor-accessibility

Capacitor 应用中的无障碍功能

UI 是 WKWebView / Android WebView 中的 Web 内容，因此标准语义化 HTML 和 ARIA 就能解决大部分问题。本技能介绍 WebView 和原生层的行为与浏览器不同之处。

适用场景

在以下情况触发：

• 用户要求支持 VoiceOver/TalkBack、进行无障碍审计，或符合 WCAG 2.2 / EAA / ADA。
• iOS「更大字体」设置无法放大文本，或 Android 大字体导致布局错乱。
• 屏幕阅读器无法播报页面变化、Toast 或加载状态。
• 屏幕阅读器无法访问原生视图（地图、相机预览、视频播放器）。
• 用户需要 @capacitor/screen-reader 或 @capacitor/text-zoom。

请勿用于：

• Ionic 组件 API/主题 -> ionic-design；Konsta/Tailwind -> konsta-ui、tailwind-capacitor。
• 刘海屏/主屏幕指示条下方的内容 -> safe-area-handling。
• 键盘遮挡输入框 -> capacitor-keyboard。
• E2E 测试基础设施 -> capacitor-testing。

流程

1. 盘点屏幕并列出待办清单（身份验证、主标签页、表单、模态框、媒体、设置）。逐一审计。
2. 在 Web 构建版本上进行自动化检查：运行 axe（在测试中使用 @axe-core/playwright，或运行 npx @axe-core/cli@latest http://localhost:5173），并优先修复违规项（名称、角色、对比度、标签）。
3. 对每个屏幕进行设备检查：使用 VoiceOver 和 TalkBack、最大字号、「减少动态效果」以及蓝牙键盘（iPad）。参阅 references/testing.md 中的检查项。
4. 修复以下 Capacitor 特有的陷阱。
5. 按屏幕报告发现的问题，注明 WCAG 条款、严重程度和修复方法。进行大型重构前，请先询问；更改设计令牌（颜色、字号）前也请先询问。

Capacitor 专属陷阱

1. 默认情况下会忽略 iOS 动态字体。 无论“设置 > 辅助功能 > 更大字体”中的设置如何，WKWebView 都会以固定大小渲染 px/rem 文本。可选方案：
   • CSS：使用 html { font: -apple-system-body; }，其他所有内容都用 rem/em 设置大小（WebKit 会将其映射为用户的内容大小类别，并实时更新）。
   • 或者在启动时和 resume 时，从 @capacitor/text-zoom 调用 TextZoom.getPreferred()，然后调用 TextZoom.set({ value })。在 iPad 上，这需要在 capacitor.config.* 中设置 ios.preferredContentMode: 'mobile'。 选择其中一种，不要同时使用，否则文本会缩放两次。
2. Android 字体缩放会自动生效。 Android WebView 会随系统字体大小缩放文本，因此固定高度的容器、line-clamp 和绝对定位布局在 200% 缩放时会溢出。使用 adb shell settings put system font_scale 2.0 测试，并针对内容重排进行设计（WCAG 1.4.4、1.4.10）。
3. 捏合缩放。 zoomEnabled 默认为 false，许多模板还会附带 user-scalable=no。用户仍可通过陷阱 1/2 缩放文本；如果依赖缩放功能，请设置 zoomEnabled: true 并移除 user-scalable=no。
4. SPA 导航不会自动播报。 路由变化不会触发页面加载播报。导航后设置 document.title，将焦点移至主标题（<h1 tabindex="-1">），或更新礼貌型实时区域。不要将 ScreenReader.speak 用作主要机制：它仅在屏幕阅读器启用时才会播报，并会绕过用户的详细程度设置。
5. WebView 下方或上方的原生视图。 @capacitor/google-maps 会在透明的 WebView 区域后方渲染原生地图；摄像头预览插件也采用相同方式。屏幕阅读器看到的是 WebView，而非原生视图。请在 HTML 中提供无障碍替代内容（标记列表、文字摘要、带标签的拍摄按钮）。
6. 原生插件 UI。 官方插件中的对话框、操作表、分享表和选择器默认具备无障碍支持；你自己的插件中的自定义原生屏幕需要设置 accessibilityLabel/contentDescription（参见 references/native.md）。
7. 触控目标。 Apple HIG 最小尺寸为 44x44 pt；Material 为 48x48 dp；WCAG 2.2 2.5.8 最小尺寸为 24x24 CSS px。图标按钮需要添加内边距，而不只是放一个小型 SVG。
8. 动态效果和对比度。 两种 WebView 都支持 prefers-reduced-motion 和 prefers-contrast 媒体查询。启用减少动态效果时，禁用视差效果和自动播放的过渡；测试“提高对比度”。
9. 状态变化。 对于 Toast（@capacitor/toast 为原生 Toast，且会播报）、内联错误和加载指示器：网页 Toast 使用 role="status" / aria-live="polite"，加载区域使用 aria-busy；仅在错误时使用 role="alert"。
10. 原生界面往返后的焦点。 原生模态界面（摄像头、分享、身份验证浏览器）关闭后，焦点可能会落在 <body> 上。在 appStateChange/Promise 解析时，将焦点恢复到触发控件。

验证

• axe：每个经过审计的路由上，严重和高危违规项均为零。
• VoiceOver（iOS）和 TalkBack（Android）：每个控件都有可朗读的名称、角色和状态；滑动顺序与视觉顺序一致；路由变化会播报，或焦点移至标题。
• 最大字体：运行 xcrun simctl ui booted content_size accessibility-extra-extra-extra-large 和 adb shell settings put system font_scale 2.0；不得有文字裁切或重叠，正文不得出现水平滚动。
• Grep：运行 grep -rnE "user-scalable=no|maximum-scale=1" index.html src/ 和 grep -rn "outline: *none\|outline: *0" src/（每处都必须有对应的 :focus-visible 替代样式）。
• 测试后重置：运行 adb shell settings put system font_scale 1.0、xcrun simctl ui booted content_size large。

错误处理

症状 / 消息	修复方法
在 Web 上，ScreenReader.isEnabled 被拒绝 / 不可用	Web 不支持此功能（无法检测屏幕阅读器）；请使用 Capacitor.isNativePlatform() 进行判断。
在 Web 上，speak 抛出异常	浏览器不支持 SpeechSynthesis；仅在原生平台上调用，或通过 'speechSynthesis' in window 检测功能是否可用。
"TextZoom" plugin is not implemented on web	text-zoom 仅支持原生平台；请在 Web 上跳过。
iPad 上的文本缩放不起作用	设置 ios.preferredContentMode: 'mobile'。
iOS 上的文本缩放了两次	同时使用了 -apple-system-body 和 TextZoom；保留其中一种。
VoiceOver 读出“button”，但没有名称	仅包含图标的控件缺少 aria-label 或可见文本。

参考资料

仅在涉及相关主题时加载：

• references/testing.md：VoiceOver / TalkBack 手势、Accessibility Inspector、Android Accessibility Scanner、adb/simctl 设置命令、Playwright 中的 axe、逐屏检查清单。
• references/native.md：用于自定义原生插件视图的 Swift / Kotlin 无障碍 API、从原生代码发布播报。