Skip to content

Commit f31c22e

Browse files
xuelgongespipj
xuelgong
authored and
espipj
committed
Update accessibility related APIs (facebook#1326)
* Update accessibility related APIs * Add accessibilityValue prop to Touchable * Modify the accessibilityValue prop description * Using 'clear' instead of obvious * Update touchablewithoutfeedback.md Using 'clear' instead of obvious * Moving more content into tables and reducing h-tag hierarchy * Retooling opening paragraph and meta-description * Tweaking intro copy
1 parent 4d9809c commit f31c22e

File tree

7 files changed

+681
-502
lines changed

7 files changed

+681
-502
lines changed

‎docs/accessibility.md

Lines changed: 51 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,17 @@
11
---
22
id: accessibility
33
title: Accessibility
4-
---
5-
6-
## Native App Accessibility (iOS and Android)
4+
description: "Create mobile apps accessible to assistive technology with React Native's suite of APIs designed to work with iOS and Android."
75

8-
Both iOS and Android provide APIs for making apps accessible to people with disabilities. In addition, both platforms provide bundled assistive technologies, like the screen readers VoiceOver (iOS) and TalkBack (Android) for the visually impaired. Similarly, in React Native we have included APIs designed to provide developers with support for making apps more accessible. Take note, iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
6+
---
97

10-
In addition to this documentation, you might find [this blog post](https://engineering.fb.com/ios/making-react-native-apps-accessible/) about React Native accessibility to be useful.
8+
Both iOS and Android provide APIs for integrating apps with assitive technologies like the bundled screen readers VoiceOver (iOS) and Talkback (Android). React Native has complimentary APIs that let your app accommodate all users.
119

12-
## Making Apps Accessible
10+
> iOS and Android differ slightly in their approaches, and thus the React Native implementations may vary by platform.
1311
14-
### Accessibility properties
12+
## Accessibility properties
1513

16-
#### accessible (iOS, Android)
14+
### accessible (iOS, Android)
1715

1816
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.
1917

@@ -28,7 +26,7 @@ On Android, `accessible={true}` property for a react-native View will be transla
2826

2927
In the above example, we can't get accessibility focus separately on 'text one' and 'text two'. Instead we get focus on a parent view with 'accessible' property.
3028

31-
#### accessibilityLabel (iOS, Android)
29+
### accessibilityLabel (iOS, Android)
3230

3331
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 know what element they have selected. VoiceOver will read this string when a user selects the associated element.
3432

@@ -47,7 +45,7 @@ To use, set the `accessibilityLabel` property to a custom string on your View, T
4745

4846
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.
4947

50-
#### accessibilityHint (iOS, Android)
48+
### accessibilityHint (iOS, Android)
5149

5250
An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.
5351

@@ -69,11 +67,11 @@ iOS In the above example, VoiceOver will read the hint after the label, if the u
6967

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

72-
#### accessibilityIgnoresInvertColors(iOS)
70+
### accessibilityIgnoresInvertColors(iOS)
7371

7472
Inverting screen colors is an Accessibility feature that makes the iPhone and iPad easier on the eyes for some people with a sensitivity to brightness, easier to distinguish for some people with color blindness, and easier to make out for some people with low vision. However, sometimes you have views such as photos that you don't want to be inverted. In this case, you can set this property to be false so that these specific views won't have their colors inverted.
7573

76-
#### accessibilityRole (iOS, Android)
74+
### accessibilityRole (iOS, Android)
7775

7876
`accessibilityRole` communicates the purpose of a component to the user of an assistive technology.
7977

@@ -107,47 +105,60 @@ Inverting screen colors is an Accessibility feature that makes the iPhone and iP
107105
- **timer** Used to represent a timer.
108106
- **toolbar** Used to represent a tool bar (a container of action buttons or components).
109107

110-
#### accessibilityStates (iOS, Android)
108+
### accessibilityState (iOS, Android)
111109

112110
Describes the current state of a component to the user of an assistive technology.
113111

114-
`accessibilityStates` is an array of values, and may include any of the following:
112+
`accessibilityState` is an object. It contains the following fields:
113+
114+
| Name | Description | Type | Required |
115+
| -------- | ------------ | ------------------ | -------- |
116+
| disabled | Indicates whether the element is disabled or not. | boolean | No |
117+
| selected | Indicates whether a selectable element is currently selected or not. | boolean | No |
118+
| checked | Indicates the state of a checkable element. This field can either take a boolean or the "mixed" string to represent mixed checkboxes. | boolean or 'mixed' | No |
119+
| busy | Indicates whether an element is currently busy or not. | boolean | No |
120+
| expanded | Indicates whether an expandable element is currently expanded or collapsed. | boolean | No |
121+
122+
To use, set the `accessibilityState` to an object with a specific definition.
123+
124+
### accessibilityValue (iOS, Android)
125+
126+
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).
115127

116-
- **selected** Used when the element is in a selected state. For example, a button is selected.
117-
- **disabled** Used when the element is disabled and cannot be interacted with.
118-
- **checked** Used to indicate that a checkable element is currently checked.
119-
- **unchecked** Used to indicate that a checkable element is not currently checked.
120-
- **busy** Used to indicate that an element is currently busy.
121-
- **expanded** Used to indicate that an expandable element is currently expanded.
122-
- **collapsed** Used to indicate that an expandable element is currently collapsed.
128+
`accessibilityValue` is an object. It contains the following fields:
123129

124-
To use, set the `accessibilityStates` to an array containing the list of current states.
130+
| Name | Description | Type | Required |
131+
| ---- | ---------------------------------------------------------------------------------------------- | ------- | ------------------------- |
132+
| min | The minimum value of this component's range. | integer | Required if `now` is set. |
133+
| max | The maximum value of this component's range. | integer | Required if `now` is set. |
134+
| now | The current value of this component's range. | integer | No |
135+
| text | A textual description of this component's value. Will override `min`, `now`, and `max` if set. | string | No |
125136

126-
#### accessibilityViewIsModal (iOS)
137+
### accessibilityViewIsModal (iOS)
127138

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

130141
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 the 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`.
131142

132-
#### accessibilityElementsHidden (iOS)
143+
### accessibilityElementsHidden (iOS)
133144

134145
A Boolean value indicating whether the accessibility elements contained within this accessibility element are hidden.
135146

136147
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 the view `B`. This is similar to the Android property `importantForAccessibility="no-hide-descendants"`.
137148

138-
#### onAccessibilityTap (iOS)
149+
### onAccessibilityTap (iOS, Android)
139150

140151
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.
141152

142-
#### onMagicTap (iOS)
153+
### onMagicTap (iOS)
143154

144155
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.
145156

146-
#### onAccessibilityEscape (iOS)
157+
### onAccessibilityEscape (iOS)
147158

148159
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.
149160

150-
#### accessibilityLiveRegion (Android)
161+
### accessibilityLiveRegion (Android)
151162

152163
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’:
153164

@@ -168,7 +179,7 @@ When components dynamically change, we want TalkBack to alert the end user. This
168179

169180
In the above example method \_addOne changes the state.count variable. As soon as an end user clicks the TouchableWithoutFeedback, TalkBack reads text in the Text view because of its 'accessibilityLiveRegion=”polite”' property.
170181

171-
#### importantForAccessibility (Android)
182+
### importantForAccessibility (Android)
172183

173184
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).
174185

@@ -187,7 +198,7 @@ In the case of two overlapping UI components with the same parent, default acces
187198

188199
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.
189200

190-
### Accessibility Actions
201+
## Accessibility Actions
191202

192203
Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. In order to support accessibility actions, a component must do two things:
193204

@@ -240,39 +251,25 @@ To handle action requests, a component must implement an `onAccessibilityAction`
240251
/>
241252
```
242253

243-
### Checking if a Screen Reader is Enabled
254+
## Checking if a Screen Reader is Enabled
244255

245256
The `AccessibilityInfo` API allows you to determine whether or not a screen reader is currently active. See the [AccessibilityInfo documentation](accessibilityinfo.md) for details.
246257

247-
### Sending Accessibility Events (Android)
258+
## Sending Accessibility Events (Android)
248259

249-
Sometimes it is useful to trigger an accessibility event on a UI component (i.e. when a custom view appears on a screen or a custom radio button has been selected). Native UIManager module exposes a method ‘sendAccessibilityEvent’ for this purpose. It takes two arguments: view tag and a type of an event.
260+
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: view tag and a type of an event. The supported event types are `typeWindowStateChanged`, `typeViewFocused` and `typeViewClicked`.
250261

251262
```jsx
252-
import { UIManager, findNodeHandle } from 'react-native';
263+
import { Platform, UIManager, findNodeHandle } from 'react-native';
253264

254-
_onPress: function() {
255-
const radioButton = this.state.radioButton === 'radiobutton_checked' ?
256-
'radiobutton_unchecked' : 'radiobutton_checked'
257-
258-
this.setState({
259-
radioButton: radioButton
260-
});
261-
262-
if (radioButton === 'radiobutton_checked') {
265+
if (Platform.OS === 'android') {
263266
UIManager.sendAccessibilityEvent(
264267
findNodeHandle(this),
265-
UIManager.AccessibilityEventTypes.typeViewClicked);
268+
UIManager.AccessibilityEventTypes.typeViewFocused);
266269
}
267270
}
268-
269-
<CustomRadioButton
270-
accessibilityComponentType={this.state.radioButton}
271-
onPress={this._onPress}/>
272271
```
273272

274-
In the above example we've created a custom radio button that now behaves like a native one. More specifically, TalkBack now correctly announces changes to the radio button selection.
275-
276273
## Testing VoiceOver Support (iOS)
277274

278275
To enable VoiceOver, go to the Settings app on your iOS device (it's not available for simulator). Tap General, then Accessibility. There you will find many tools that people use to make their devices more usable, such as bolder text, increased contrast, and VoiceOver.
@@ -303,3 +300,7 @@ adb shell settings put secure enabled_accessibility_services com.android.talkbac
303300
# enable
304301
adb shell settings put secure enabled_accessibility_services com.google.android.marvin.talkback/com.google.android.marvin.talkback.TalkBackService
305302
```
303+
304+
## Additional Resources
305+
306+
* [Making React Native Apps Accessible](https://engineering.fb.com/ios/making-react-native-apps-accessible/)

‎docs/touchablewithoutfeedback.md

Lines changed: 84 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,26 @@ function MyComponent(props) {
3737

3838
---
3939

40+
### `accessible`
41+
42+
When `true`, indicates that the view is an accessibility element. By default, all the touchable elements are accessible.
43+
44+
| Type | Required |
45+
| ---- | -------- |
46+
| bool | No |
47+
48+
---
49+
50+
### `accessibilityLabel`
51+
52+
Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space.
53+
54+
| Type | Required |
55+
| ------ | -------- |
56+
| string | No |
57+
58+
---
59+
4060
### `accessibilityHint`
4161

4262
An accessibility hint helps users understand what will happen when they perform an action on the accessibility element when that result is not clear from the accessibility label.
@@ -47,45 +67,91 @@ An accessibility hint helps users understand what will happen when they perform
4767

4868
---
4969

50-
### `accessibilityLabel`
70+
### `accessibilityRole`
5171

52-
Overrides the text that's read by the screen reader when the user interacts with the element. By default, the label is constructed by traversing all the children and accumulating all the `Text` nodes separated by space.
72+
`accessibilityRole` communicates the purpose of a component to the user of an assistive technology.
73+
74+
`accessibilityRole` can be one of the following:
75+
76+
- `'none'` - Used when the element has no role.
77+
- `'button'` - Used when the element should be treated as a button.
78+
- `'link'` - Used when the element should be treated as a link.
79+
- `'search'` - Used when the text field element should also be treated as a search field.
80+
- `'image'` - Used when the element should be treated as an image. Can be combined with button or link, for example.
81+
- `'keyboardkey'` - Used when the element acts as a keyboard key.
82+
- `'text'` - Used when the element should be treated as static text that cannot change.
83+
- `'adjustable'` - Used when an element can be "adjusted" (e.g. a slider).
84+
- `'imagebutton'` - Used when the element should be treated as a button and is also an image.
85+
- `'header'` - Used when an element acts as a header for a content section (e.g. the title of a navigation bar).
86+
- `'summary'` - Used when an element can be used to provide a quick summary of current conditions in the app when the app first launches.
87+
- `'alert'` - Used when an element contains important text to be presented to the user.
88+
- `'checkbox'` - Used when an element represents a checkbox which can be checked, unchecked, or have mixed checked state.
89+
- `'combobox'` - Used when an element represents a combo box, which allows the user to select among several choices.
90+
- `'menu'` - Used when the component is a menu of choices.
91+
- `'menubar'` - Used when a component is a container of multiple menus.
92+
- `'menuitem'` - Used to represent an item within a menu.
93+
- `'progressbar'` - Used to represent a component which indicates progress of a task.
94+
- `'radio'` - Used to represent a radio button.
95+
- `'radiogroup'` - Used to represent a group of radio buttons.
96+
- `'scrollbar'` - Used to represent a scroll bar.
97+
- `'spinbutton'` - Used to represent a button which opens a list of choices.
98+
- `'switch'` - Used to represent a switch which can be turned on and off.
99+
- `'tab'` - Used to represent a tab.
100+
- `'tablist'` - Used to represent a list of tabs.
101+
- `'timer'` - Used to represent a timer.
102+
- `'toolbar'` - Used to represent a tool bar (a container of action buttons or components).
53103

54104
| Type | Required |
55105
| ------ | -------- |
56106
| string | No |
57107

58108
---
59109

60-
### `accessibilityRole`
110+
### `accessibilityState`
61111

62-
| Type | Required |
63-
| ------------------ | -------- |
64-
| AccessibilityRoles | No |
112+
Describes the current state of a component to the user of an assistive technology.
113+
114+
See the [Accessibility guide](accessibility.md#accessibilitystate-ios-android) for more information.
115+
116+
| Type | Required |
117+
| ---------------------------------------------------------------------------------------------- | -------- |
118+
| object: {disabled: bool, selected: bool, checked: bool or 'mixed', busy: bool, expanded: bool} | No |
65119

66120
---
67121

68-
### `accessibilityStates`
122+
### `accessibilityActions`
123+
124+
Accessibility actions allow an assistive technology to programmatically invoke the actions of a component. The `accessibilityActions` property should contain a list of action objects. Each action object should contain the field name and label.
69125

70-
| Type | Required |
71-
| ---------------------------- | -------- |
72-
| array of AccessibilityStates | No |
126+
See the [Accessibility guide](accessibility.md#accessibility-actions) for more information.
127+
128+
| Type | Required |
129+
| ----- | -------- |
130+
| array | No |
73131

74132
---
75133

76-
### `accessibilityState`
134+
### `onAccessibilityAction`
77135

78-
| Type | Required |
79-
| ------ | -------- |
80-
| Object | No |
136+
Invoked when the user performs the accessibility actions. The only argument to this function is an event containing the name of the action to perform.
137+
138+
See the [Accessibility guide](accessibility.md#accessibility-actions) for more information.
139+
140+
| Type | Required |
141+
| -------- | -------- |
142+
| function | No |
81143

82144
---
83145

84-
### `accessible`
146+
### `accessibilityValue`
85147

86-
| Type | Required |
87-
| ---- | -------- |
88-
| bool | No |
148+
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).
149+
150+
See the [Accessibility guide](accessibility.md#accessibilityvalue-ios-android) for more information.
151+
152+
| Type | Required |
153+
| ------------------------------------------------------------- | -------- |
154+
| object: {min: number, max: number, now: number, text: string} | No |
89155

90156
---
91157

0 commit comments

Comments
 (0)