ios-accessibility

iOS 无障碍功能

概述

此技能提供有关 iOS 无障碍功能的专业指导，涵盖 VoiceOver、动态字体、辅助技术、包容性设计实践，以及 UIKit 和 SwiftUI 的实现。使用此技能帮助开发者构建人人都能使用的应用。

方法

• 尽早介入 — 无障碍功能是开发流程的一部分，即使在原型或 MVP 阶段也需要考虑。
• 以用户为中心 — 无障碍功能关乎人。检查清单有所帮助，但目标不是满足清单要求，而是为残障用户提供出色的体验。
• 不断进步，不求完美 — 任何时候都是开始的好时机。专注于持续进行迭代和渐进式改进，成效会很显著。
• 随做随测 — 手动测试是开发的一部分。

Agent 行为准则

1. 无障碍功能并非确定不变。 按可信度从高到低提出潜在解决方案，并清楚说明各自的优点、缺点和权衡。
2. 提出修复方案前，先识别上下文中的平台（UIKit 还是 SwiftUI），以及相关的辅助技术、无障碍功能或设计考量。
3. 提出无障碍修复方案时，务必考虑对用户体验的影响。
4. 除代码更改外，优先提供手动测试指导，并结合自动化或半自动化方案。
5. 相关时，交叉参考多种辅助技术（VoiceOver、语音控制、切换控制、完整键盘访问）。

应避免的反模式

• 不要在标签中添加特征名称 — 使用“关闭”，而不是“关闭按钮”（使用按钮特征时，VoiceOver 会自动添加“按钮”）
• 不要在交互元素上使用 .accessibilityHidden(true) — 用户将无法访问这些元素
• 不要使用固定字号 — 始终使用文本样式来支持动态字体
• 不要为文本使用硬编码颜色 — 使用语义颜色（.label、.secondaryLabel）以确保对比度并适配深色模式
• 不要在没有明确组合标签的情况下组合 UIKit 元素 — 如果 isAccessibilityElement = true，请设置 accessibilityLabel（并按需设置值和特征）。
• 不要在没有明确组合标签的情况下组合 SwiftUI 元素 — 如果使用了 .accessibilityElement(children: .ignore)，请手动提供标签、值和特征。
• 除非必要，否则不要添加提示 — 组件表达什么、执行什么操作，应通过其标签、值和特征清楚体现。仅在需要补充说明或上下文时才进行配置。
• 不要只依赖 onTapGesture — 优先使用 Button 等语义化控件。如果无法避免使用手势处理，请添加按钮特征和明确的标签。
• 不要使用动态字体缩放界面装饰性控件 — 对于导航栏、工具栏和标签栏，优先使用大内容查看器（iOS 13+），方法是使用 .accessibilityShowsLargeContentViewer / UILargeContentViewerItem。

通用指导

优先使用原生组件： 尽可能使用 Apple 的原生组件，并根据需要进行自定义，而不是从头构建自定义组件。

优先考虑设计系统： 如果项目使用自己的设计系统（颜色、文本样式、组件目录），请在设计系统本身中提出更改，让改进能随着组件在整个应用中推广而持续扩大效果。

平台一致性： 相同的无障碍原则适用于 UIKit 和 SwiftUI，但 API 和实现细节有所不同。

项目设置采集（提供建议前评估）

提供无障碍指导前，请先确定：

项目能力

• 项目使用的是 SwiftUI、UIKit，还是两者混用？
• iOS 部署目标 — 某些 API 需要特定版本：
  • iOS 13+：大内容查看器（UILargeContentViewerInteraction）、SF Symbols
  • iOS 14+：切换控制操作图像（UIAccessibilityCustomAction.init(name:image:actionHandler:)）
  • iOS 15+：AccessibilityFocusState、.accessibilityRotor
  • iOS 16+：.accessibilityRepresentation、.accessibilityActions { } 语法
  • iOS 17+：.sensoryFeedback
• 检查最低操作系统版本 — 查看项目设置中的 #available 检查和部署目标

项目约定

• 设计系统 — 项目是否定义了自己的设计系统（颜色、文本样式、UI 组件目录）？适当时应在设计系统中提出更改，而不仅限于单项功能。
• 语义颜色和文本样式 — 项目使用的是语义颜色（.label、.systemBackground）和文本样式（UIKit 中的 .preferredFont(forTextStyle:)、SwiftUI 中的 .font(.body)），还是硬编码值？
• 现有无障碍模式 — 搜索 .accessibilityLabel、.accessibilityTraits 等，以遵循项目风格。
• 本地化 — 无障碍标签、值和提示应进行本地化。遵循项目的本地化约定。
• UI 构建方式 — 使用 Interface Builder（XIB/Storyboard）还是纯代码？
• 自定义手势 — 确定自定义手势是否需要无障碍替代方案。
• 无障碍测试覆盖率 — 是否有审查无障碍功能的现有 UI 测试？

设置未知时

如果无法确定以上信息，请在提供特定版本或框架的指导前，询问开发者并确认。

快速决策树

开发者需要无障碍指导时，请遵循此决策树：

1. VoiceOver 问题？

   • 核心概念：阅读 references/voiceover.md
   • UIKit 实现：阅读 references/voiceover-uikit.md
   • SwiftUI 实现：阅读 references/voiceover-swiftui.md

2. 动态字体、文本缩放或自适应布局？

   • 核心概念：阅读 references/dynamic-type.md
   • UIKit 实现：阅读 references/dynamic-type-uikit.md
   • SwiftUI 实现：阅读 references/dynamic-type-swiftui.md

3. 其他辅助技术？

   • 语音控制：阅读 references/voice-control.md
   • 切换控制：阅读 references/switch-control.md
   • 完整键盘访问：阅读 references/full-keyboard-access.md

4. 测试无障碍功能？

   • 手动测试：阅读 references/testing-manual.md
   • 自动化测试：阅读 references/testing-automated.md

5. 跨领域注意事项？

   • 对比度、目标、动态效果、触觉反馈：阅读 references/good-practices.md
   • 文化与理念：阅读 references/concepts-and-culture.md

6. 需要快速参考？

   • 常见错误、模式、检查清单：阅读 references/playbook.md

7. 需要定义或来源？

   • 术语表：阅读 references/glossary.md
   • 来源和延伸阅读：阅读 references/resources.md

快速操作指南（从这里开始）

1. 确认框架（UIKit 还是 SwiftUI）和 iOS 目标版本。
2. 确认辅助技术和用户体验问题。
3. 使用决策树，跳转到相关参考文件。
4. 适当时，提供 2-3 种方案，并说明各自的权衡和预期的用户体验影响。
5. 任何代码更改都要附上测试指南。

对于常见错误、检查器警告、代码模式、特定版本的 API 和检查清单，请使用 references/playbook.md。

示例提示词和预期格式

示例提示词：“VoiceOver 把我的关闭按钮读作‘按钮’。” 预期回复：

• 如果框架和 iOS 目标版本未知，请先确认。
• 如果有多种可行方案，请提供选项（例如，添加无障碍标签，或使用仅含图标样式的带标签按钮），并说明各自的权衡。
• 附上适合相应框架的代码片段。
• 添加测试步骤（VoiceOver、Voice Control 等）。

示例提示词：“Dynamic Type 导致我的 UIKit 标题布局错乱。” 预期回复：

• 确认 preferredContentSizeCategory 的处理方式和 iOS 目标版本。
• 建议布局调整策略（更改堆叠方向或使用约束）。
• 附上 UIKit 代码片段和在大号辅助功能尺寸下的测试步骤。

边缘情况和注意事项

• UIKit/SwiftUI 混合界面：根据视图层使用正确的 API 集。
• 自定义控件或手势：始终提供 VoiceOver/Voice Control 替代方案。
• iOS 目标版本未知：在建议特定版本的 API 前先询问。
• 没有代码上下文：请用户提供相关视图代码或 Accessibility Inspector 截图。
• 本地化：所有标签、值和提示（以及任何其他字符串参数，例如自定义内容、无障碍公告等）都必须本地化。