-
Notifications
You must be signed in to change notification settings - Fork 1.2k
Description
Add support for accessibilityLiveRegion / aria-live prop.
Documentation
accessibilityLiveRegion Documentation
Behavior
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:
| Value | Description |
|---|---|
| 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>
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.
The accessibilityLiveRegion prop should set the value of LiveSetting property. The value of the LiveSetting will be a value in the LiveSetting enum (See here for documentation)
The value mapping should be:
accessibilityLiveRegion Value |
LiveSetting Value |
|---|---|
| "none" | LiveSetting::Off |
| "polite" | LiveSetting::Polite |
| "assertive" | LiveSetting::Assertive |
The default value of the prop should be "none".
Implementation on Paper
react-native-windows/vnext/Microsoft.ReactNative/Views/FrameworkElementViewManager.cpp
Lines 301 to 317 in 78f9316
| } else if (propertyName == "accessibilityLiveRegion") { | |
| if (propertyValue.Type() == winrt::Microsoft::ReactNative::JSValueType::String) { | |
| auto value = propertyValue.AsString(); | |
| auto liveSetting = winrt::AutomationLiveSetting::Off; | |
| if (value == "polite") { | |
| liveSetting = winrt::AutomationLiveSetting::Polite; | |
| } else if (value == "assertive") { | |
| liveSetting = winrt::AutomationLiveSetting::Assertive; | |
| } | |
| element.SetValue(xaml::Automation::AutomationProperties::LiveSettingProperty(), winrt::box_value(liveSetting)); | |
| } else if (propertyValue.IsNull()) { | |
| element.ClearValue(xaml::Automation::AutomationProperties::LiveSettingProperty()); | |
| } | |
| AnnounceLiveRegionChangedIfNeeded(element); |
react-native-windows/vnext/Microsoft.ReactNative/Utils/AccessibilityUtils.cpp
Lines 15 to 24 in 78f9316
| AnnounceLiveRegionChangedIfNeeded(const xaml::FrameworkElement &element) { | |
| if (xaml::Automation::AutomationProperties::GetLiveSetting(element) != | |
| xaml::Automation::Peers::AutomationLiveSetting::Off && | |
| !xaml::Automation::AutomationProperties::GetName(element).empty()) { | |
| auto peer = xaml::Automation::Peers::FrameworkElementAutomationPeer::FromElement(element); | |
| if (nullptr != peer) { | |
| peer.RaiseAutomationEvent(xaml::Automation::Peers::AutomationEvents::LiveRegionChanged); | |
| } | |
| } | |
| } |
Implementation Plan
We should:
- Take the value of the
accessibilityLiveRegionprop and set the value of theLiveSettingproperty to match the prop value.
To Be Clarified
Unclear if an additional call is needed to UIA to indicate to the screen reader that the LiveSetting has changed and content may need to be reannounced or if UIA will handle this automatically.