Skip to main content

无障碍

Android 和 iOS 都提供 API，用于将应用与辅助技术集成，例如打包的屏幕阅读器 VoiceOver (iOS) 和 TalkBack (Android)。React Native 具有互补的 API，可让你的应用适应所有用户。

¥Both Android and iOS provide APIs for integrating apps with assistive technologies like the bundled screen readers VoiceOver (iOS) and TalkBack (Android). React Native has complementary APIs that let your app accommodate all users.

信息

Android 和 iOS 的方法略有不同，因此 React Native 实现可能会因平台而异。

¥Android and iOS differ slightly in their approaches, and thus the React Native implementations may vary by platform.

辅助功能属性​

¥Accessibility properties

accessible​

当 true 时，表示视图是辅助功能元素。当视图是辅助功能元素时，它将其子元素分组为单个可选组件。默认情况下，所有可触摸元素都是可访问的。

¥When true, indicates that the view is an accessibility element. When a view is an accessibility element, it groups its children into a single selectable component. By default, all touchable elements are accessible.

在 Android 上，react-native View 的 accessible={true} 属性将被转换为原生 focusable={true}。

¥On Android, accessible={true} property for a react-native View will be translated into native focusable={true}.

<View accessible={true}>
  <Text>text one</Text>
  <Text>text two</Text>
</View>

在上面的示例中，辅助功能焦点仅适用于具有 accessible 属性的父视图，而不单独适用于 '文本一' 和 '文本二'。

¥In the above example, accessibility focus is only available on the parent view with the accessible property, and not individually for 'text one' and 'text two'.

accessibilityLabel​

当视图被标记为可访问时，最好在视图上设置 accessibilityLabel，以便使用 VoiceOver 或 TalkBack 的人知道他们选择了哪个元素。当选择关联的元素时，屏幕阅读器将用语言表达该字符串。

¥When a view is marked as accessible, it is a good practice to set an accessibilityLabel on the view, so that people who use VoiceOver or TalkBack know what element they have selected. A screen reader will verbalize this string when the associated element is selected.

要使用，请将 accessibilityLabel 属性设置为 View、Text 或 Touchable 上的自定义字符串：

¥To use, set the accessibilityLabel property to a custom string on your View, Text, or Touchable:

<TouchableOpacity
  accessible={true}
  accessibilityLabel="Tap me!"
  onPress={onPress}>
  <View style={styles.button}>
    <Text style={styles.buttonText}>Press me!</Text>
  </View>
</TouchableOpacity>

在上面的示例中，TouchableOpacity 元素上的 accessibilityLabel 将默认为 "按我！"。该标签是通过连接所有以空格分隔的文本节点子节点来构造的。

¥In the above example, the accessibilityLabel on the TouchableOpacity element would default to "Press me!". The label is constructed by concatenating all Text node children separated by spaces.

accessibilityLabelledBy
Android
​

对用于构建复杂表单的另一个元素 本地 ID 的引用。accessibilityLabelledBy 的值应与相关元素的 nativeID 匹配：

¥A reference to another element nativeID used to build complex forms. The value of accessibilityLabelledBy should match the nativeID of the related element:

<View>
  <Text nativeID="formLabel">Label for Input Field</Text>
  <TextInput
    accessibilityLabel="input"
    accessibilityLabelledBy="formLabel"
  />
</View>

在上面的示例中，屏幕阅读器在聚焦于 TextInput 时读出 Input, Edit Box for Label for Input Field。

¥In the above example, the screen reader announces Input, Edit Box for Label for Input Field when focusing on the TextInput.

accessibilityHint​

当仅从可访问性标签中不清楚时，可访问性提示可用于向用户提供有关操作结果的附加上下文。

¥An accessibility hint can be used to provide additional context to the user on the result of the action when it is not clear from the accessibility label alone.

为 accessibilityHint 属性提供 View、Text 或 Touchable 上的自定义字符串：

¥Provide the accessibilityHint property a custom string on your View, Text, or Touchable:

<TouchableOpacity
  accessible={true}
  accessibilityLabel="Go back"
  accessibilityHint="Navigates to the previous screen"
  onPress={onPress}>
  <View style={styles.button}>
    <Text style={styles.buttonText}>Back</Text>
  </View>
</TouchableOpacity>
iOS

在上面的示例中，如果用户在设备的 VoiceOver 设置中启用了提示，则 VoiceOver 将在标签后读取提示。阅读有关 iOS 开发者文档 中 accessibilityHint 指南的更多信息

¥In the above example, VoiceOver will read the hint after the label, if the user has hints enabled in the device's VoiceOver settings. Read more about guidelines for accessibilityHint in the iOS Developer Docs

安卓

在上面的示例中，TalkBack 将读取标签后面的提示。目前 Android 上无法关闭提示。

¥In the above example, TalkBack will read the hint after the label. At this time, hints cannot be turned off on Android.

accessibilityLanguage
iOS
​

通过使用 accessibilityLanguage 属性，屏幕阅读器将了解在读取元素的标签、值和提示时使用哪种语言。提供的字符串值必须遵循 BCP 47 规范。

¥By using the accessibilityLanguage property, the screen reader will understand which language to use while reading the element's label, value, and hint. The provided string value must follow the BCP 47 specification.

<View
  accessible={true}
  accessibilityLabel="Pizza"
  accessibilityLanguage="it-IT">
  <Text>🍕</Text>
</View>

accessibilityIgnoresInvertColors
iOS
​

反转屏幕颜色是 iOS 和 iPadOS 中为色盲、弱视或视力障碍人士提供的一项辅助功能。如果启用此设置时你不想反转某个视图（可能是照片），请将此属性设置为 true。

¥Inverting screen colors is an accessibility feature available in iOS and iPadOS for people with color blindness, low vision, or vision impairment. If there's a view you don't want to invert when this setting is on, possibly a photo, set this property to true.

accessibilityLiveRegion
Android
​

当组件动态变化时，我们希望 TalkBack 提醒终端用户。这是通过 accessibilityLiveRegion 属性实现的。可设置为 none、polite 和 assertive：

¥When components dynamically change, we want TalkBack to alert the end user. This is made possible by the accessibilityLiveRegion property. It can be set to none, polite, and assertive:

  • 无 辅助服务不应宣布对此视图的更改。

    ¥none Accessibility services should not announce changes to this view.

  • 礼貌的无障碍服务应该宣布对此视图的更改。

    ¥polite Accessibility services should announce changes to this view.

  • 自信的辅助服务应该中断正在进行的演讲，立即宣布对此视图的更改。

    ¥assertive Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

<TouchableWithoutFeedback onPress={addOne}>
  <View style={styles.embedded}>
    <Text>Click me</Text>
  </View>
</TouchableWithoutFeedback>
<Text accessibilityLiveRegion="polite">
  Clicked {count} times
</Text>

在上面的示例中，方法 addOne 更改了状态变量 count。当触发 TouchableWithoutFeedback 时，TalkBack 会根据其 accessibilityLiveRegion="polite" 属性读取文本视图中的文本。

¥In the above example method addOne changes the state variable count. When the TouchableWithoutFeedback is triggered, TalkBack reads the text in the Text view because of its accessibilityLiveRegion="polite" property.

accessibilityRole​

accessibilityRole 将组件的用途传达给辅助技术的用户。

¥accessibilityRole communicates the purpose of a component to the user of assistive technology.

accessibilityRole 可以是以下之一：

¥accessibilityRole can be one of the following:

  • 可调整 当元素可以是 "adjusted" 时使用（例如滑块）。

    ¥adjustable Used when an element can be "adjusted" (e.g. a slider).

  • 当元素包含要渲染给用户的重要文本时使用。

    ¥alert Used when an element contains important text to be presented to the user.

  • 按钮 当元素应被视为按钮时使用。

    ¥button Used when the element should be treated as a button.

  • checkbox 当元素表示可以选中、取消选中或具有混合选中状态的复选框时使用。

    ¥checkbox Used when an element represents a checkbox that can be checked, unchecked, or have a mixed checked state.

  • 组合框 当元素表示组合框时使用，它允许用户在多个选项中进行选择。

    ¥combobox Used when an element represents a combo box, which allows the user to select among several choices.

  • header 当元素充当内容部分的标题（例如导航栏的标题）时使用。

    ¥header Used when an element acts as a header for a content section (e.g. the title of a navigation bar).

  • image 当元素应被视为图片时使用。可以与按钮或链接结合使用。

    ¥image Used when the element should be treated as an image. Can be combined with a button or link.

  • imagebutton 当元素应被视为按钮并且也是图片时使用。

    ¥imagebutton Used when the element should be treated as a button and is also an image.

  • Keyboardkey 当元素充当键盘键时使用。

    ¥keyboardkey Used when the element acts as a keyboard key.

  • link 当元素应被视为链接时使用。

    ¥link Used when the element should be treated as a link.

  • menu 当组件是选择菜单时使用。

    ¥menu Used when the component is a menu of choices.

  • menubar 当组件是多个菜单的容器时使用。

    ¥menubar Used when a component is a container of multiple menus.

  • menuitem 用于表示菜单中的项目。

    ¥menuitem Used to represent an item within a menu.

  • none 当元素没有角色时使用。

    ¥none Used when the element has no role.

  • 进度条 用于表示指示任务进度的组件。

    ¥progressbar Used to represent a component that indicates the progress of a task.

  • radio 用于表示单选按钮。

    ¥radio Used to represent a radio button.

  • radiogroup 用于表示一组单选按钮。

    ¥radiogroup Used to represent a group of radio buttons.

  • 滚动条 用于表示滚动条。

    ¥scrollbar Used to represent a scroll bar.

  • 搜索 当文本字段元素也应被视为搜索字段时使用。

    ¥search Used when a text field element should also be treated as a search field.

  • spinbutton 用于表示打开选项列表的按钮。

    ¥spinbutton Used to represent a button that opens a list of choices.

  • 摘要 当应用首次启动时，元素可用于提供应用中当前状况的快速摘要时使用。

    ¥summary Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.

  • switch 用于表示可以打开和关闭的开关。

    ¥switch Used to represent a switch that can be turned on and off.

  • tab 用于表示一个选项卡。

    ¥tab Used to represent a tab.

  • tablist 用于表示选项卡列表。

    ¥tablist Used to represent a list of tabs.

  • text 当元素应被视为无法更改的静态文本时使用。

    ¥text Used when the element should be treated as static text that cannot change.

  • timer 用于表示计时器。

    ¥timer Used to represent a timer.

  • 切换按钮 用于表示切换按钮。应与可访问性状态选中一起使用，以指示按钮是打开还是关闭。

    ¥togglebutton Used to represent a toggle button. Should be used with accessibilityState checked to indicate if the button is toggled on or off.

  • 工具栏 用于表示工具栏（操作按钮或组件的容器）。

    ¥toolbar Used to represent a toolbar (a container of action buttons or components).

  • grid 与 ScrollView、VirtualizedList、FlatList 或 SectionList 一起使用来表示网格。将进入/离开网格公告添加到 Android 的 GridView。

    ¥grid Used with ScrollView, VirtualizedList, FlatList, or SectionList to represent a grid. Adds the in/out of grid announcements to Android's GridView.

accessibilityState​

向辅助技术用户描述组件的当前状态。

¥Describes the current state of a component to the assistive technology user.

accessibilityState 是一个对象。它包含以下字段：

¥accessibilityState is an object. It contains the following fields:

名称描述类型必需的
disabled指示该元素是否被禁用。boolean不
selected指示当前是否选择了可选元素。boolean不
checked指示可检查元素的状态。该字段可以采用布尔值或 "mixed" 字符串来表示混合复选框。布尔值或 'mixed'不
busy指示元素当前是否忙碌。boolean不
expanded指示可展开元素当前是展开还是折叠。boolean不

使用时，请将 accessibilityState 设置为具有特定定义的对象。

¥To use, set the accessibilityState to an object with a specific definition.

accessibilityValue​

表示组件的当前值。它可以是组件值的文本描述，或者对于基于范围的组件（例如滑块和进度条），它包含范围信息（最小值、当前和最大值）。

¥Represents the current value of a component. It can be a textual description of a component's value, or for range-based components, such as sliders and progress bars, it contains range information (minimum, current, and maximum).

accessibilityValue 是一个对象。它包含以下字段：

¥accessibilityValue is an object. It contains the following fields:

名称描述类型必需的
min该分量范围的最小值。integer如果设置了 now，则为必需。
max该组件范围的最大值。integer如果设置了 now，则为必需。
now该组件范围的当前值。integer不
text该组件值的文本描述。如果设置，将覆盖 min、now 和 max。string不

accessibilityViewIsModal
iOS
​

一个布尔值，指示 VoiceOver 是否应忽略视图中与接收者同级的元素。

¥A boolean value that indicates whether VoiceOver should ignore the elements within views that are siblings of the receiver.

例如，在包含同级视图 A 和 B 的窗口中，在视图 B 上将 accessibilityViewIsModal 设置为 true 会导致 VoiceOver 忽略视图 A 中的元素。另一方面，如果视图 B 包含子视图 C 并且你在视图 C 上将 accessibilityViewIsModal 设置为 true，则 VoiceOver 不会忽略视图 A 中的元素。

¥For example, in a window that contains sibling views A and B, setting accessibilityViewIsModal to true on view B causes VoiceOver to ignore the elements in view A. On the other hand, if view B contains a child view C and you set accessibilityViewIsModal to true on view C, VoiceOver does not ignore the elements in view A.

accessibilityElementsHidden
iOS
​

一个布尔值，指示此辅助功能元素中包含的辅助功能元素是否隐藏。

¥A boolean value indicating whether the accessibility elements contained within this accessibility element are hidden.

例如，在包含同级视图 A 和 B 的窗口中，在视图 B 上将 accessibilityElementsHidden 设置为 true 会导致 VoiceOver 忽略视图 B 中的元素。这与 Android 属性 importantForAccessibility="no-hide-descendants" 类似。

¥For example, in a window that contains sibling views A and B, setting accessibilityElementsHidden to true on view B causes VoiceOver to ignore the elements in view B. This is similar to the Android property importantForAccessibility="no-hide-descendants".

aria-valuemax​

表示基于范围的组件（例如滑块和进度条）的最大值。

¥Represents the maximum value for range-based components, such as sliders and progress bars.

aria-valuemin​

表示基于范围的组件（例如滑块和进度条）的最小值。

¥Represents the minimum value for range-based components, such as sliders and progress bars.

aria-valuenow​

表示基于范围的组件（例如滑块和进度条）的当前值。

¥Represents the current value for range-based components, such as sliders and progress bars.

aria-valuetext​

表示组件的文本描述。

¥Represents the textual description of the component.

aria-busy​

表示正在修改某个元素，并且辅助技术可能需要等到更改完成后再通知用户有关更新的信息。

¥Indicates an element is being modified and that assistive technologies may want to wait until the changes are complete before informing the user about the update.

类型默认
booleanfalse

aria-checked​

指示可检查元素的状态。该字段可以采用布尔值或 "mixed" 字符串来表示混合复选框。

¥Indicates the state of a checkable element. This field can either take a boolean or the "mixed" string to represent mixed checkboxes.

类型默认
布尔值，'mixed'false

aria-disabled​

指示该元素可感知但已禁用，因此不可编辑或不可操作。

¥Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

类型默认
booleanfalse

aria-expanded​

指示可展开元素当前是展开还是折叠。

¥Indicates whether an expandable element is currently expanded or collapsed.

类型默认
booleanfalse

aria-hidden​

指示此辅助功能元素中包含的辅助功能元素是否隐藏。

¥Indicates whether the accessibility elements contained within this accessibility element are hidden.

例如，在包含同级视图 A 和 B 的窗口中，在视图 B 上将 aria-hidden 设置为 true 会导致 VoiceOver 忽略视图 B 中的元素。

¥For example, in a window that contains sibling views A and B, setting aria-hidden to true on view B causes VoiceOver to ignore the elements in view B.

类型默认
booleanfalse

aria-label​

定义一个标记交互元素的字符串值。

¥Defines a string value that labels an interactive element.

类型
string

aria-labelledby
Android
​

标识为其应用的元素添加标签的元素。aria-labelledby 的值应与相关元素的 nativeID 匹配：

¥Identifies the element that labels the element it is applied to. The value of aria-labelledby should match the nativeID of the related element:

<View>
  <Text nativeID="formLabel">Label for Input Field</Text>
  <TextInput aria-label="input" aria-labelledby="formLabel" />
</View>
类型
string

aria-live
Android
​

指示将更新的元素并描述用户代理、辅助技术和用户可以从实时区域期望的更新类型。

¥Indicates that an element will be updated and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.

  • off 辅助服务不应宣布对此视图的更改。

    ¥off Accessibility services should not announce changes to this view.

  • 礼貌的无障碍服务应该宣布对此视图的更改。

    ¥polite Accessibility services should announce changes to this view.

  • 自信的辅助服务应该中断正在进行的演讲，立即宣布对此视图的更改。

    ¥assertive Accessibility services should interrupt ongoing speech to immediately announce changes to this view.

类型默认
enum('assertive', 'off', 'polite')'off'

aria-modal
iOS
​

布尔值，指示 VoiceOver 是否应忽略视图中与接收者同级的元素。

¥Boolean value indicating whether VoiceOver should ignore the elements within views that are siblings of the receiver.

类型默认
booleanfalse

aria-selected​

指示当前是否选择了可选元素。

¥Indicates whether a selectable element is currently selected or not.

类型
boolean

importantForAccessibility
Android
​

对于具有相同父级的两个重叠 UI 组件的情况，默认辅助功能焦点可能会出现不可预测的行为。importantForAccessibility 属性将通过控制视图是否触发辅助功能事件以及是否将其报告给辅助功能服务来解决此问题。它可以设置为 auto、yes、no 和 no-hide-descendants（最后一个值将强制辅助功能服务忽略该组件及其所有子组件）。

¥In the case of two overlapping UI components with the same parent, default accessibility focus can have unpredictable behavior. The importantForAccessibility property will resolve this by controlling if a view fires accessibility events and if it is reported to accessibility services. It can be set to auto, yes, no and no-hide-descendants (the last value will force accessibility services to ignore the component and all of its children).

<View style={styles.container}>
  <View
    style={[styles.layout, {backgroundColor: 'green'}]}
    importantForAccessibility="yes">
    <Text>First layout</Text>
  </View>
  <View
    style={[styles.layout, {backgroundColor: 'yellow'}]}
    importantForAccessibility="no-hide-descendants">
    <Text>Second layout</Text>
  </View>
</View>

在上面的示例中，yellow 布局及其后代对于 TalkBack 和所有其他辅助功能服务完全不可见。因此，我们可以使用具有相同父级的重叠视图，而不会混淆 TalkBack。

¥In the above example, the yellow layout and its descendants are completely invisible to TalkBack and all other accessibility services. So we can use overlapping views with the same parent without confusing TalkBack.

onAccessibilityEscape
iOS
​

将此属性分配给一个自定义函数，当有人执行 "escape" 手势（这是一个两指 Z 形手势）时，将调用该函数。转义功能应在用户界面中按层次结构移回。这可能意味着在导航层次结构中向上或向后移动或关闭模式用户界面。如果选定的元素没有 onAccessibilityEscape 功能，系统将尝试向上遍历视图层次结构，直到找到具有 onAccessibilityEscape 功能的视图，或者闪烁以指示无法找到该功能。

¥Assign this property to a custom function which will be called when someone performs the "escape" gesture, which is a two finger Z shaped gesture. An escape function should move back hierarchically in the user interface. This can mean moving up or back in a navigation hierarchy or dismissing a modal user interface. If the selected element does not have an onAccessibilityEscape function, the system will attempt to traverse up the view hierarchy until it finds a view that does or bonk to indicate it was unable to find one.

onAccessibilityTap
iOS
​

使用此属性可以指定一个自定义函数，当有人通过双击选定的可访问元素来激活该元素时，将调用该函数。

¥Use this property to assign a custom function to be called when someone activates an accessible element by double tapping on it while it's selected.

onMagicTap
iOS
​

将此属性分配给一个自定义函数，当有人执行 "魔术龙头" 手势（即用两根手指双击）时将调用该函数。魔术点击功能应该执行用户可以对组件执行的最相关的操作。在 iPhone 上的“调用”应用中，只需轻点一下即可接听调用或结束当前通话。如果所选元素没有 onMagicTap 功能，系统将向上遍历视图层次结构，直到找到具有 onMagicTap 功能的视图。

¥Assign this property to a custom function which will be called when someone performs the "magic tap" gesture, which is a double-tap with two fingers. A magic tap function should perform the most relevant action a user could take on a component. In the Phone app on iPhone, a magic tap answers a phone call or ends the current one. If the selected element does not have an onMagicTap function, the system will traverse up the view hierarchy until it finds a view that does.

role​

role 传达组件的用途，并且优先于 accessibilityRole 属性。

¥role communicates the purpose of a component and has precedence over the accessibilityRole prop.

role 可以是以下之一：

¥role can be one of the following:

  • 当元素包含要渲染给用户的重要文本时使用。

    ¥alert Used when an element contains important text to be presented to the user.

  • 按钮 当元素应被视为按钮时使用。

    ¥button Used when the element should be treated as a button.

  • checkbox 当元素表示可以选中、取消选中或具有混合选中状态的复选框时使用。

    ¥checkbox Used when an element represents a checkbox that can be checked, unchecked, or have a mixed checked state.

  • 组合框 当元素表示组合框时使用，它允许用户在多个选项中进行选择。

    ¥combobox Used when an element represents a combo box, which allows the user to select among several choices.

  • grid 与 ScrollView、VirtualizedList、FlatList 或 SectionList 一起使用来表示网格。将进入/离开网格公告添加到 android GridView。

    ¥grid Used with ScrollView, VirtualizedList, FlatList, or SectionList to represent a grid. Adds the in/out of grid announcements to the android GridView.

  • 当元素充当内容部分的标题（例如导航栏的标题）时使用。

    ¥heading Used when an element acts as a header for a content section (e.g. the title of a navigation bar).

  • img 当元素应被视为图片时使用。例如，可以与按钮或链接组合。

    ¥img Used when the element should be treated as an image. Can be combined with a button or link, for example.

  • link 当元素应被视为链接时使用。

    ¥link Used when the element should be treated as a link.

  • list 用于标识项目列表。

    ¥list Used to identify a list of items.

  • menu 当组件是选择菜单时使用。

    ¥menu Used when the component is a menu of choices.

  • menubar 当组件是多个菜单的容器时使用。

    ¥menubar Used when a component is a container of multiple menus.

  • menuitem 用于表示菜单中的项目。

    ¥menuitem Used to represent an item within a menu.

  • none 当元素没有角色时使用。

    ¥none Used when the element has no role.

  • 当元素没有角色时使用。

    ¥presentation Used when the element has no role.

  • 进度条 用于表示指示任务进度的组件。

    ¥progressbar Used to represent a component that indicates the progress of a task.

  • radio 用于表示单选按钮。

    ¥radio Used to represent a radio button.

  • radiogroup 用于表示一组单选按钮。

    ¥radiogroup Used to represent a group of radio buttons.

  • 滚动条 用于表示滚动条。

    ¥scrollbar Used to represent a scroll bar.

  • searchbox 当文本字段元素也应被视为搜索字段时使用。

    ¥searchbox Used when the text field element should also be treated as a search field.

  • slider 当元素可以是 "adjusted" 时使用（例如滑块）。

    ¥slider Used when an element can be "adjusted" (e.g. a slider).

  • spinbutton 用于表示打开选项列表的按钮。

    ¥spinbutton Used to represent a button that opens a list of choices.

  • 摘要 当应用首次启动时，元素可用于提供应用中当前状况的快速摘要时使用。

    ¥summary Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.

  • switch 用于表示可以打开和关闭的开关。

    ¥switch Used to represent a switch that can be turned on and off.

  • tab 用于表示一个选项卡。

    ¥tab Used to represent a tab.

  • tablist 用于表示选项卡列表。

    ¥tablist Used to represent a list of tabs.

  • timer 用于表示计时器。

    ¥timer Used to represent a timer.

  • 工具栏 用于表示工具栏（操作按钮或组件的容器）。

    ¥toolbar Used to represent a toolbar (a container of action buttons or components).

无障碍行动​

¥Accessibility Actions

辅助功能操作允许辅助技术以编程方式调用组件的操作。为了支持辅助功能操作，组件必须做两件事：

¥Accessibility actions allow assistive technology to programmatically invoke the action(s) of a component. To support accessibility actions, a component must do two things:

  • 通过 accessibilityActions 属性定义它支持的操作列表。

    ¥Define the list of actions it supports via the accessibilityActions property.

  • 实现 onAccessibilityAction 函数来处理操作请求。

    ¥Implement an onAccessibilityAction function to handle action requests.

accessibilityActions 属性应包含操作对象的列表。每个操作对象应包含以下字段：

¥The accessibilityActions property should contain a list of action objects. Each action object should contain the following fields:

名称类型必需的
namestring是的
labelstring不

操作要么代表标准操作（例如单击按钮或调整滑块），要么代表特定于给定组件的自定义操作（例如删除电子邮件）。name 字段对于标准操作和自定义操作都是必需的，但 label 对于标准操作是可选的。

¥Actions either represent standard actions, such as clicking a button or adjusting a slider, or custom actions specific to a given component such as deleting an email message. The name field is required for both standard and custom actions, but label is optional for standard actions.

添加对标准操作的支持时，name 必须是以下之一：

¥When adding support for standard actions, name must be one of the following:

  • 'magicTap' - 仅限 iOS - 当 VoiceOver 焦点位于组件上或组件内部时，用户用两根手指双击。

    ¥'magicTap' - iOS only - While VoiceOver focus is on or inside the component, the user double tapped with two fingers.

  • 'escape' - 仅限 iOS - 当 VoiceOver 焦点位于组件上或组件内部时，用户执行了两指滑动手势（左、右、左）。

    ¥'escape' - iOS only - While VoiceOver focus is on or inside the component, the user performed a two-finger scrub gesture (left, right, left).

  • 'activate' - 激活该组件。无论是否使用辅助技术，都应该执行相同的操作。当屏幕阅读器用户双击该组件时启用。

    ¥'activate' - Activate the component. This should perform the same action with, or without, assistive technology. Engaged when a screen reader user double taps the component.

  • 'increment' - 增加一个可调组件。在 iOS 上，当组件的角色为 'adjustable' 并且用户将焦点放在该组件上并向上滑动时，VoiceOver 会生成此操作。在 Android 上，当用户将辅助功能焦点放在组件上并按下音量增大按钮时，TalkBack 会生成此操作。

    ¥'increment' - Increment an adjustable component. On iOS, VoiceOver generates this action when the component has a role of 'adjustable' and the user places focus on it and swipes upward. On Android, TalkBack generates this action when the user places accessibility focus on the component and presses the volume-up button.

  • 'decrement' - 减少可调整组件。在 iOS 上，当组件的角色为 'adjustable' 并且用户将焦点放在该组件上并向下滑动时，VoiceOver 会生成此操作。在 Android 上，当用户将辅助功能焦点放在组件上并按下音量减小按钮时，TalkBack 会生成此操作。

    ¥'decrement' - Decrement an adjustable component. On iOS, VoiceOver generates this action when the component has a role of 'adjustable' and the user places focus on it and swipes downward. On Android, TalkBack generates this action when the user places accessibility focus on the component and presses the volume-down button.

  • 'longpress' - 仅限安卓 - 当用户将辅助功能焦点放在组件上，然后双击并用一根手指按住屏幕时，会生成此操作。无论是否使用辅助技术，都应该执行相同的操作。

    ¥'longpress' - Android only - This action is generated when the user places accessibility focus on the component, then double-taps and holds one finger on the screen. This should perform the same action with, or without, assistive technology.

label 字段对于标准操作是可选的，并且通常不被辅助技术使用。对于自定义操作，它是一个本地化字符串，其中包含要渲染给用户的操作的描述。

¥The label field is optional for standard actions and is often unused by assistive technologies. For custom actions, it is a localized string containing a description of the action to be presented to the user.

为了处理操作请求，组件必须实现 onAccessibilityAction 函数。该函数的唯一参数是一个包含要执行的操作名称的事件。以下来自 RNTester 的示例展示了如何创建定义和处理多个自定义操作的组件。

¥To handle action requests, a component must implement an onAccessibilityAction function. The only argument to this function is an event containing the name of the action to perform. The below example from RNTester shows how to create a component that defines and handles several custom actions.

<View
  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;
    }
  }}
/>

检查屏幕阅读器是否已启用​

¥Checking if a Screen Reader is Enabled

AccessibilityInfo API 允许你确定屏幕阅读器当前是否处于活动状态。详细信息请参见 AccessibilityInfo 文档。

¥The AccessibilityInfo API allows you to determine whether or not a screen reader is currently active. See the AccessibilityInfo documentation for details.

发送辅助功能事件
Android
​

¥Sending Accessibility Events

Android

有时，在 UI 组件上触发辅助功能事件很有用（即，当自定义视图出现在屏幕上或将辅助功能焦点设置到视图时）。原生 UIManager 模块为此目的公开了一个方法“sendAccessibilityEvent”。它需要两个参数：视图标签和事件类型。支持的事件类型为 typeWindowStateChanged、typeViewFocused 和 typeViewClicked。

¥Sometimes it is useful to trigger an accessibility event on a UI component (i.e. when a custom view appears on a screen or set accessibility focus to a view). Native UIManager module exposes a method ‘sendAccessibilityEvent’ for this purpose. It takes two arguments: a view tag and a type of event. The supported event types are typeWindowStateChanged, typeViewFocused, and typeViewClicked.

import {Platform, UIManager, findNodeHandle} from 'react-native';

if (Platform.OS === 'android') {
  UIManager.sendAccessibilityEvent(
    findNodeHandle(this),
    UIManager.AccessibilityEventTypes.typeViewFocused,
  );
}

测试 TalkBack 支持
Android
​

¥Testing TalkBack Support

Android

要启用 TalkBack，请转到 Android 设备或模拟器上的“设置”应用。点击“辅助功能”，然后点击“话语提示”。切换 "使用服务" 开关以启用或禁用它。

¥To enable TalkBack, go to the Settings app on your Android device or emulator. Tap Accessibility, then TalkBack. Toggle the "Use service" switch to enable or disable it.

Android 模拟器默认不安装 TalkBack。你可以通过 Google Play 商店在模拟器上安装 TalkBack。确保选择安装了 Google Play 商店的模拟器。这些可以在 Android Studio 中找到。

¥Android emulators don't have TalkBack installed by default. You can install TalkBack on your emulator via the Google Play Store. Make sure to choose an emulator with the Google Play store installed. These are available in Android Studio.

你可以使用音量键快捷键来切换 TalkBack。要打开音量键快捷键，请转到“设置”应用，然后转到“辅助功能”。在顶部，打开音量键快捷键。

¥You can use the volume key shortcut to toggle TalkBack. To turn on the volume key shortcut, go to the Settings app, then Accessibility. At the top, turn on the volume key shortcut.

要使用音量键快捷键，请同时按住两个音量键 3 秒钟以启动辅助工具。

¥To use the volume key shortcut, press both volume keys for 3 seconds to start an accessibility tool.

此外，如果你愿意，你可以通过命令行切换 TalkBack：

¥Additionally, if you prefer, you can toggle TalkBack via the command line with:

# 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

测试 VoiceOver 支持
iOS
​

¥Testing VoiceOver Support

iOS

要在 iOS 或 iPadOS 设备上启用 VoiceOver，请前往“设置”应用，轻点“常规”，然后轻点“辅助功能”。在那里，你会发现许多工具可供人们使用，以提高其设备的可用性，其中包括 VoiceOver。要启用 VoiceOver，请点击 "想象" 下的 VoiceOver 并切换顶部出现的开关。

¥To enable VoiceOver on your iOS or iPadOS device, go to the Settings app, tap General, then Accessibility. There you will find many tools available for people to enable their devices to be more usable, including VoiceOver. To enable VoiceOver, tap on VoiceOver under "Vision" and toggle the switch that appears at the top.

在辅助功能设置的最底部，有一个 "辅助功能快捷方式"。你可以通过三次单击“主页”按钮来使用它来切换 VoiceOver。

¥At the very bottom of the Accessibility settings, there is an "Accessibility Shortcut". You can use this to toggle VoiceOver by triple-clicking the Home button.

VoiceOver 无法通过模拟器使用，但你可以使用 Xcode 中的辅助功能检查器通过应用使用 macOS VoiceOver。请注意，最好使用设备进行测试，因为 macOS 的 VoiceOver 可能会带来不同的体验。

¥VoiceOver isn't available via the simulator, but you can use Accessibility Inspector from Xcode to use the macOS VoiceOver through an application. Note it's always best to test with a device as macOS's VoiceOver may result in varied experiences.

其他资源​

¥Additional Resources