第1章 React Native 无障碍（Accessibility）开发指南

版本：0.77 # 第1章 Accessibility（无障碍） Android 和 iOS 都提供了与辅助技术（如内置屏幕阅读器 VoiceOver（iOS）和 TalkBack（Android））集成的 API。React Native 也提供了相应的 API，让你的应用能够照顾到所有用户。 > 提示：Android 和 iOS 的实现方式略有差异，因此 React Native 的相关实现也可能因平台而有所不同。 ## 无障碍属性 ### accessible 设为 true 时，表示该视图是一个无障碍元素。当视图成为无障碍元素后，它的子元素会被合并为一个可选中的整体组件。默认情况下，所有可触摸元素都是无障碍的。 在 Android 上，React Native View 的 accessible={true} 属性会被转换为原生的 focusable={true}。 React TSX ```tsx text one text two ``` 在上面的例子中，无障碍焦点只能落在设置了 accessible 属性的父视图上，无法单独选中 "text one" 和 "text two"。 ### accessibilityLabel 当视图被标记为无障碍元素时，最好为其设置 accessibilityLabel，这样使用 VoiceOver 或 TalkBack 的用户就能知道自己选中了什么元素。屏幕阅读器会在元素被选中时朗读这个字符串。 用法是在 View、Text 或 Touchable 上设置 accessibilityLabel 属性为自定义字符串： React TSX ```tsx Press me! ``` 在上面的例子中，TouchableOpacity 元素的 accessibilityLabel 默认会是 "Press me!"。这个标签是通过把所有 Text 子节点用空格拼接而成的。 ### accessibilityLabelledBy Android 引用另一个元素的 nativeID，用于构建复杂的表单。 accessibilityLabelledBy 的值应与相关元素的 nativeID 一致： React TSX ```tsx Label for Input Field ``` 如上例所示，当焦点位于 TextInput 上时，屏幕阅读器会依次播报“输入框”和“供输入字段标签使用的编辑框”。 accessibilityHint 当仅凭可访问性标签无法明确操作结果时，可使用可访问性提示向用户提供更多上下文信息。 在您的 View、Text 或 Touchable 组件上为 accessibilityHint 属性指定自定义字符串： React TSX accessible={true}
accessibilityLabel="后退"
accessibilityHint="导航到上一页"
onPress={onPress}>

返回


iOS 如上例所示，若用户在设备的 VoiceOver 设置中启用了提示，VoiceOver 会在播报标签后读取该提示。关于 accessibilityHint 的使用准则，请参阅 iOS 开发者文档。 Android 如上例所示，TalkBack 会在播报标签后读取该提示。目前，Android 无法关闭此提示功能。 accessibilityLanguage iOS 使用 accessibilityLanguage 属性后，屏幕阅读器将知晓在读取元素的标签、值和提示时应使用何种语言。提供的字符串值必须遵循 BCP 47 规范。 React TSX accessible={true}
accessibilityLabel="披萨"
accessibilityLanguage="it-IT">
🍕

accessibilityIgnoresInvertColors iOS 反转屏幕颜色是 iOS 和 iPadOS 中为色盲、低视力或视力受损用户提供的一项可访问性功能。如果存在不希望在此设置开启时被反转的视图（例如照片），请将该属性设为 true。 accessibilityLiveRegion Android 当组件动态更新时，我们希望 TalkBack 能够提醒最终用户。这可通过 accessibilityLiveRegion 属性实现。它可以设置为 none、polite 或 assertive： none：可访问性服务不应播报此视图的变化。 polite：可访问性服务应播报此视图的变化。 assertive：可访问性服务应中断当前语音并立即播报此视图的变化。 React TSX

点击我



已点击 {count} 次

在前面的示例中，addOne 方法会修改变量 count 的状态。当触发 TouchableWithoutFeedback 时，由于设置了 accessibilityLiveRegion="polite" 属性，TalkBack 会朗读 Text 视图中的文本。 accessibilityRole accessibilityRole 用于向辅助技术用户传达组件的用途。 accessibilityRole 可以是以下值之一： adjustable 当元素可以被“调整”时（例如滑块）使用。 alert 当元素包含需要呈现给用户的重要文本时使用。 button 当元素应被视为按钮时使用。 checkbox 当元素表示一个复选框，该复选框可以是选中、未选中或混合选中状态时使用。 combobox 当元素表示一个组合框，允许用户从多个选项中选择时使用。 header 当元素作为内容区域的标题时（例如导航栏标题）使用。 image 当元素应被视为图像时使用。可与按钮或链接组合使用。 imagebutton 当元素应被视为按钮且本身也是图像时使用。 keyboardkey 当元素充当键盘按键时使用。 link 当元素应被视为链接时使用。 menu 当组件是一个选项菜单时使用。 menubar 当组件是多个菜单的容器时使用。 menuitem 用于表示菜单中的某个项。 none 当元素没有特定角色时使用。 progressbar 用于表示指示任务进度的组件。 radio 用于表示单选按钮。 radiogroup 用于表示一组单选按钮。 scrollbar 用于表示滚动条。 search 当文本字段元素也应被视为搜索字段时使用。 spinbutton 用于表示打开选项列表的按钮。 summary 当元素可用于在应用启动时快速提供当前状态摘要时使用。 switch 用于表示可开/关的开关。 tab 用于表示选项卡。 tablist 用于表示选项卡列表。 text 当元素应被视为不可更改的静态文本时使用。 timer 用于表示计时器。 togglebutton 用于表示切换按钮。应与 accessibilityState 的 checked 属性一起使用，以指示按钮是开启还是关闭状态。 toolbar 用于表示工具栏（动作按钮或组件的容器）。 grid 与 ScrollView、VirtualizedList、FlatList 或 SectionList 一起使用，表示网格。这会在 Android 的 GridView 中添加网格进出时的播报。 accessibilityShowsLargeContentViewer 仅适用于 iOS 一个布尔值，决定当用户长按该元素时是否显示大型内容查看器。 适用于 iOS 13.0 及更高版本。 accessibilityLargeContentTitle 仅适用于 iOS 一个字符串，当显示大型内容查看器时，将用作其标题。 要求 accessibilityShowsLargeContentViewer 设置为 true。 React TSX accessibilityShowsLargeContentViewer={true}
accessibilityLargeContentTitle="Home Tab">
Home

accessibilityState 向辅助技术用户描述组件的当前状态。 accessibilityState 是一个对象，包含以下字段： Name | Description | Type | Required ---|---|---|--- disabled | 指示元素是否处于禁用状态。 | boolean | 否 selected | 指示可选元素当前是否处于选中状态。 | boolean | 否 checked | 指示可勾选元素的状态。该字段可以取布尔值，或取 "mixed" 字符串以表示混合复选框。 | boolean 或 'mixed' | 否 busy | 指示元素当前是否处于忙碌状态。 | boolean | 否 expanded | 指示可展开元素当前是处于展开还是折叠状态。 | boolean | 否 使用时，将 accessibilityState 设置为具有特定定义的对象。 accessibilityValue 表示组件的当前值。它可以是组件值的文本描述；对于基于范围的组件（如滑块和进度条），它包含范围信息（最小值、当前值和最大值）。 accessibilityValue 是一个对象，包含以下字段： Name | Description | Type | Required ---|---|---|--- min | 该组件范围的最小值。 | integer | 若设置了 now 则为必填 max | 该组件范围的最大值。 | integer | 若设置了 now 则为必填 now | 该组件范围的当前值。 | integer | 否 text | 该组件值的文本描述。若设置了该字段，将覆盖 min、now 和 max。 | string | 否 accessibilityViewIsModal iOS 一个布尔值，指示 VoiceOver 是否应忽略接收者兄弟视图内的元素。 例如，在一个包含兄弟视图 A 和 B 的窗口中，将视图 B 的 accessibilityViewIsModal 设置为 true 会导致 VoiceOver 忽略视图 A 中的元素。另一方面，如果视图 B 包含子视图 C，且将视图 C 的 accessibilityViewIsModal 设置为 true，VoiceOver 不会忽略视图 A 中的元素。 accessibilityElementsHidden iOS 一个布尔值，指示包含在该辅助功能元素内的辅助功能元素是否被隐藏。 例如，在一个包含兄弟视图 A 和 B 的窗口中，将视图 B 的 accessibilityElementsHidden 设置为 true 会导致 VoiceOver 忽略视图 B 中的元素。这与 Android 属性 importantForAccessibility="no-hide-descendants" 类似。 aria-valuemax 表示基于范围的组件（如滑块和进度条）的最大值。 aria-valuemin 表示基于范围的组件（如滑块和进度条）的最小值。 aria-valuenow 表示基于范围的组件（如滑块和进度条）的当前值。 aria-valuetext 表示组件的文本描述。 aria-busy 指示元素正在被修改，辅助技术可能希望在更新完成后才通知用户该变更。 Type | Default ---|--- boolean | false aria-checked 指示可勾选元素的状态。该字段可以取布尔值，或取 "mixed" 字符串以表示混合复选框。 Type | Default ---|--- boolean, 'mixed' | false aria-disabled 指示元素可感知但处于禁用状态，因此不可编辑或以其他方式操作。 Type | Default ---|--- boolean | false aria-expanded 指示可展开元素当前是处于展开还是折叠状态。 Type | Default ---|--- boolean | false aria-hidden 指示包含在该辅助功能元素内的辅助功能元素是否被隐藏。 例如，在一个包含兄弟视图 A 和 B 的窗口中，将视图 B 的 aria-hidden 设置为 true 会导致 VoiceOver 忽略视图 B 中的元素。 Type | Default ---|--- boolean | false aria-label 定义一个字符串值，用于标识交互式元素。 Type --- string aria-labelledby Android 标识标记了所应用元素的那个元素。aria-labelledby 的值应与相关元素的 nativeID 匹配： React TSX
输入字段的标签


typestring aria-live Android​ 用于指示某个元素将发生更新，并描述用户代理、辅助技术以及用户预期从实时区域接收到的更新类型。 off 辅助服务不应宣布此视图的任何变更。 polite 辅助服务应宣布此视图的变更。 assertive 辅助服务应立即宣布此视图的变更，并可打断正在进行的语音播报。 typeDefaultenum('assertive', 'off', 'polite')'off' aria-modal iOS​ 一个布尔值，用于指示 VoiceOver 是否应忽略接收者同级视图内的元素。 typeDefaultbooleanfalse aria-selected​ 指示可选择元素当前是否被选中。 typeboolean importantForAccessibility Android​ 当两个具有相同父级的 UI 组件发生重叠时，默认的辅助功能焦点行为可能不可预测。importantForAccessibility 属性通过控制视图是否触发辅助功能事件，以及是否向辅助服务上报该视图，来解决这一问题。它可设置为 auto、yes、no 和 no-hide-descendants（最后一个值会强制辅助服务忽略该组件及其所有子级）。 React TSX
style={[styles.layout, {backgroundColor: 'green'}]}
importantForAccessibility="yes">
第一个布局

style={[styles.layout, {backgroundColor: 'yellow'}]}
importantForAccessibility="no-hide-descendants">
第二个布局


在上面的例子里，黄色布局及其子视图对 TalkBack 和其他无障碍服务完全不可见。因此我们可以让同一父视图下的多个视图相互重叠，而不会干扰 TalkBack。 onAccessibilityEscape iOS​ 将此属性设为一个自定义函数，当用户执行"escpae"手势（两指画 Z 形）时会调用它。escape 函数应在界面上按层级向后返回，比如在导航层级中上移或返回，或者关闭模态界面。如果当前选中元素没有 onAccessibilityEscape 函数，系统会沿视图层级向上查找，直到找到具备该函数的视图，若找不到则发出提示音表示失败。 onAccessibilityTap iOS​ 将此属性设为一个自定义函数，当用户在选中某个无障碍元素后双击它时会被调用。 onMagicTap iOS​ 将此属性设为一个自定义函数，当用户执行"magic tap"手势（两指双击）时会调用它。magic tap 函数应执行该组件上最合理的操作。例如在 iPhone 的电话应用中，magic tap 可以接听或挂断当前通话。如果当前选中元素没有 onMagicTap 函数，系统会沿视图层级向上查找，直到找到具备该函数的视图为止。 role​ role 用于描述组件的用途，其优先级高于 accessibilityRole 属性。 role 可以是以下值之一： alert 当元素包含需要呈现给用户的重要文本时使用。 button 当元素应被视为按钮时使用。 checkbox 当元素表示一个可勾选、取消勾选或处于半选状态的复选框时使用。 combobox 当元素表示一个允许用户从多个选项中选择组合框时使用。 grid 配合 ScrollView、VirtualizedList、FlatList 或 SectionList 表示网格。会在 Android 的 GridView 基础上增加进入/离开网格的播报。 heading 当元素作为某段内容的标题时使用（例如导航栏的标题）。 img 当元素应被视为图片时使用。例如可以与 button 或 link 组合。 link 当元素应被视为链接时使用。 list 用于标识一个列表。 listitem 用于标识列表中的一项。 menu 当组件是一个选项菜单时使用。 menubar 当组件是包含多个菜单的容器时使用。 menuitem 用于表示菜单中的一项。 none 当元素没有角色时使用。 presentation 当元素没有角色时使用。 progressbar 用于表示展示任务进度的组件。 radio 用于表示单选按钮。 radiogroup 用于表示一组单选按钮。 scrollbar 用于表示滚动条。 searchbox 当文本输入框应被视为搜索框时使用。 slider 当元素可以被"调节"时使用（例如滑块）。 spinbutton 用于表示会展开选项列表的按钮。 summary 当元素用于在应用启动时快速展示当前状态摘要时使用。 switch 用于表示可开关的开关组件。 tab 用于表示标签页。 tablist 用于表示一组标签页。 timer 用于表示计时器。 toolbar 用于表示工具栏（操作按钮或组件的容器）。 Accessibility Actions​ 无障碍操作（accessibility actions）让辅助技术能够以编程方式触发组件的操作。要支持无障碍操作，组件需要做两件事： 通过 accessibilityActions 属性定义其支持的操作列表。 实现 onAccessibilityAction 函数来处理操作请求。 accessibilityActions 属性应包含一个操作对象列表，每个操作对象包含以下字段： NameTypeRequirednamestringYeslabelstringNo 操作可以是标准操作（如点击按钮、调节滑块），也可以是组件特有的自定义操作（如删除一封邮件）。标准操作和自定义操作都必须提供 name 字段，但标准操作的 label 字段是可选的。 添加标准操作支持时，name 必须是以下之一： 'magicTap' - 仅限 iOS - 当 VoiceOver 焦点位于组件上或其内部时，用户双指双击。 'escape' - 仅限 iOS - 当 VoiceOver 焦点位于组件上或其内部时，用户执行了两指擦除手势（左、右、左）。 'activate' - 激活组件。无论是否借助辅助技术，都应执行相同的操作。屏幕阅读器用户双击组件时触发。 'increment' - 增加可调节组件的值。在 iOS 上，当组件的 role 为 'adjustable' 且用户聚焦后向上滑动时，VoiceOver 会触发此操作。在 Android 上，TalkBack 8.1 及以下版本中，用户聚焦组件后按音量上键会触发此操作；TalkBack 9.1 及之后版本改为"调整阅读控件"手势（在聚焦控件上向上滑动）。 'decrement' - 减少可调节组件的值。在 iOS 上，当组件的 role 为 'adjustable' 且用户聚焦后向下滑动时，VoiceOver 会触发此操作。在 Android 上，TalkBack 8.2 及以下版本中，用户聚焦组件后按音量下键会触发此操作；TalkBack 9.2 及之后版本改为"调整阅读控件"手势（在聚焦控件上向下滑动）。 'longpress' - 仅限 Android - 当用户将无障碍焦点置于组件上，然后双击并按住不放时触发此操作。无论是否借助辅助技术，都应执行相同的操作。 label 字段对标准操作来说是可选的，辅助技术会用它来描述操作的具体结果。例如 TalkBack 会用这个字段把默认的"双击以激活"提示替换为自定义描述，如"双击打开聊天"。对于自定义操作，label 是一个本地化字符串，包含面向用户的操作描述。 要处理操作请求，组件必须实现 onAccessibilityAction 函数。该函数唯一的参数是一个事件对象，其中包含要执行的操作名称。下面这个来自 RNTester 的示例展示了如何创建一个定义并处理多个自定义操作的组件。 React TSX accessible={true}
accessibilityActions={[
{name: 'cut', label: 'cut'},
{name: 'copy', label: 'copy'},
{name: 'paste', label: 'paste'},
]}
onAccessibilityAction={event => {
switch (event.nativeEvent.actionName) {
case 'cut':
Alert.alert('Alert', 'cut action success');
break;
case 'copy':
Alert.alert('Alert', 'copy action success');
break;
case 'paste':
Alert.alert('Alert', 'paste action success');
break;
}
}}
/>
检查是否启用了屏幕阅读器 AccessibilityInfo API 可用于确定当前是否激活了屏幕阅读器。详细请参阅 AccessibilityInfo 文档。 发送无障碍事件（Android） 有时，为了增强用户体验，需要在 UI 组件上触发自定义无障碍事件（例如，当自定义视图出现在屏幕上或需要将无障碍焦点设置到某个视图时）。原生 UIManager 模块提供了一个 sendAccessibilityEvent 方法来实现此功能。该方法接收两个参数：视图标签（view tag）和事件类型。支持的事件类型包括 typeWindowStateChanged、typeViewFocused 和 typeViewClicked。 React TSXimport {Platform, UIManager, findNodeHandle} from 'react-native';

if (Platform.OS === 'android') {
UIManager.sendAccessibilityEvent(
findNodeHandle(this),
UIManager.AccessibilityEventTypes.typeViewFocused,
);
}
测试 TalkBack 支持（Android） 要启用 TalkBack，请在 Android 设备或模拟器上打开“设置”应用。点击“无障碍”，然后选择“TalkBack”。通过切换“使用服务”开关来启用或禁用该功能。 Android 模拟器默认未安装 TalkBack。你可以通过 Google Play 商店在模拟器上安装它。请务必选择预装了 Google Play 商店的模拟器镜像，这些镜像可以在 Android Studio 中找到。 你可以使用音量键快捷键来切换 TalkBack 状态。要启用音量键快捷键，请进入“设置”应用，然后点击“无障碍”。在页面顶部，打开“音量键快捷键”开关。 使用音量键快捷键时，需同时按住两个音量键 3 秒钟以启动无障碍工具。 此外，如果你更习惯使用命令行，可以通过以下指令来切换 TalkBack： # disable
adb shell settings put secure enabled_accessibility_services com.android.talkback/com.google.android.marvin.talkback.TalkBackService

# enable
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService
iOS 上测试 VoiceOver 支持 要在 iOS 或 iPadOS 设备上启用 VoiceOver，请进入设置应用，点击通用，然后选择辅助功能。这里有很多工具可以让设备更易用，包括 VoiceOver。要启用 VoiceOver，请在“视觉”部分点击 VoiceOver，然后打开顶部出现的开关。 在辅助功能设置的底部，有一个“辅助功能快捷键”。您可以使用三击 Home 键的方式，通过此快捷键来切换 VoiceOver。 模拟器中无法使用 VoiceOver，但您可以使用 Xcode 的 Accessibility Inspector，通过 macOS 的 VoiceOver 来测试应用。注意，最好始终使用真机进行测试，因为 macOS 的 VoiceOver 可能会导致体验存在差异。 更多资源 让 React Native 应用具备无障碍能力