iOS: Introduce API for making screen reader announcements #14168

rigdern · 2017-05-25T00:17:48Z

This change introduces some APIs that are useful for making announcements through the screen reader on iOS:

announceForAccessibility: The screen reader announces the string that is passed in.
announcementFinished: An event that fires when the screen reader has finished making an announcement.

You can already solve similar problems with RN Android using the accessibilityLiveRegion prop. Live regions are a different feature but they can be used to solve the same problem. This commit does not attempt to add live region support in RN iOS because Apple did not build live region support into iOS.

Test Plan (required)

Verified that announceForAccessibility causes VoiceOver to announce the string when VoiceOver is enabled. Verified that announcementFinished fires with the appropriate data in the event object. Additionally, my team has been using this change in our app.

Adam Comella
Microsoft Corp.

eslint-bot · 2017-05-25T00:26:34Z

Libraries/Components/AccessibilityInfo/AccessibilityInfo.ios.js

-      VOICE_OVER_EVENT,
-      handler
-    );
+    var listener; 


no-trailing-spaces: Trailing spaces not allowed.

eslint-bot · 2017-05-25T00:26:34Z

Libraries/Components/AccessibilityInfo/AccessibilityInfo.ios.js

+        handler
+      );
+    }
+
    _subscriptions.set(handler, listener);
    return {
      remove: AccessibilityInfo.removeEventListener.bind(null, eventName, handler),
    };
  },

  /**


no-trailing-spaces: Trailing spaces not allowed.

eslint-bot · 2017-05-25T00:26:34Z

Libraries/Components/AccessibilityInfo/AccessibilityInfo.ios.js

-    var listener = RCTDeviceEventEmitter.addListener(
-      VOICE_OVER_EVENT,
-      handler
-    );


no-trailing-spaces: Trailing spaces not allowed.

javache · 2017-05-25T10:55:16Z

React/Modules/RCTAccessibilityManager.m

+{
+  NSDictionary *userInfo = notification.userInfo;
+  // Response dictionary to populate the event with.
+  NSDictionary *response = @{@"announcement": userInfo[@"UIAccessibilityAnnouncementKeyStringValue"],


Use the variable names for this instead of the string (so userInfo[UIAccessibilityAnnouncementKeyStringValue]

rigdern · 2017-05-25T20:30:48Z

@javache Thanks for reviewing. I addressed your comment.

facebook-github-bot · 2017-05-26T09:08:17Z

@javache has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

facebook-github-bot · 2017-05-26T23:48:14Z

I tried to merge this pull request into the Facebook internal repo but some checks failed. To unblock yourself please check the following: Does this pull request pass all open source tests on GitHub? If not please fix those. Does the code still apply cleanly on top of GitHub master? If not can please rebase. In all other cases this means some internal test failed, for example a part of a fb app won't work with this pull request. I've added the Import Failed label to this pull request so it is easy for someone at fb to find the pull request and check what failed. If you don't see anyone comment in a few days feel free to comment mentioning one of the core contributors to the project so they get a notification.

This change introduces some APIs that are useful for making announcements through the screen reader on iOS: - `announceForAccessibility`: The screen reader announces the string that is passed in. - `announcementFinished`: An event that fires when the screen reader has finished making an announcement. You can already solve similar problems with RN Android using the `accessibilityLiveRegion` prop. Live regions are a different feature but they can be used to solve the same problem. This commit does not attempt to add live region support in RN iOS because Apple did not build live region support into iOS.

rigdern · 2017-05-27T01:04:18Z

@javache Thanks for importing. It looks like the import failed due to merge conflicts. I fixed them.

facebook-github-bot · 2017-05-30T09:36:02Z

@javache has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

shergin · 2017-06-04T20:15:05Z

@rigdern That's awesome! Can we have it cross-platform? So, can we implement announceForAccessibility on Android using accessibilityLiveRegion? Should we?

rigdern · 2017-06-06T23:06:57Z

@shergin Yes, we could add an Android implementation of announceForAccessibility. My team built something like that into ReactXP by putting a live region as a child of the root view and storing the announcement text in there: https://github.com/Microsoft/reactxp/blob/3f515aeffdd5ebb209c3a06d15ccbbbb4f60a1a3/src/native-common/RootView.tsx#L102-L106

I'm not sure if there's a way to implement the announcementFinished event though.

shergin · 2017-06-07T00:22:05Z

React/Modules/RCTAccessibilityManager.m

+                              @"success": userInfo[UIAccessibilityAnnouncementKeyWasSuccessful]};
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"


Yeah, this is deprecated. We have to use typed event objects instead of strings.

shergin · 2017-06-07T00:22:24Z

React/Modules/RCTAccessibilityManager.m

@@ -101,6 +106,20 @@ - (void)didReceiveNewVoiceOverStatus:(__unused NSNotification *)notification
  }
 }

+- (void)accessibilityAnnouncementDidFinish:(__unused NSNotification *)notification


Remove __unused, please.

shergin · 2017-06-07T00:24:12Z

Libraries/Components/AccessibilityInfo/AccessibilityInfo.ios.js

+   */
+  announceForAccessibility: function(
+    announcement: string
+  ): void {


We don't need : void here because it can be inferred.

rigdern · 2017-06-07T00:28:31Z

@shergin The PR was already merged.

shergin · 2017-06-07T00:29:09Z

Libraries/Components/AccessibilityInfo/AccessibilityInfo.ios.js

-    );
+    var listener;
+
+    if (eventName === 'change') {


We have to unify native event names with JS ones, this will drastically simplify this code fragment.

shergin · 2017-06-07T00:32:06Z

@rigdern Oh, I see. Anyways, we can improve this. 😄

rigdern · 2017-06-07T00:42:03Z

@shergin They are good suggestions but I won't have time to submit another PR to address them.

For future reference, can you share an example of code that uses typed event objects instead of strings?

shergin · 2017-06-07T04:36:39Z

@rigdern Yes, sure, I will fix it myself.
See RCTEvent and RCTTouchEvent for reference.

caocao-melon · 2018-07-20T06:20:59Z

I am doing translation of this document. Can I interpret the 'announce' here as 'broadcast'?The meaning between the two words is different in Chinese. 'Announce' is more about expressing the meaning of the function declaration in coding，'Broadcast' is more about the screen reader. Which one is the right meaning?

rigdern · 2018-07-20T17:48:09Z

@caocao-melon Am I correct in assuming you a referring to these snippets?

  /**
   * ...
   * - `announcementFinished`: iOS-only event. Fires when the screen reader has
   *   finished making an announcement. The argument to the event handler is a
   *   dictionary with these keys:
   *     - `announcement`: The string announced by the screen reader.
   *     - `success`: A boolean indicating whether the announcement was
   *       successfully made.
   * ...
   */

  /**
   * Post a string to be announced by the screen reader.
   * ...
   */

If so, it sounds like "broadcast" is what you want. All of these usages of "announce" have to do with the screen reader speaking some information to the user.

facebook-github-bot added CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. GH Review: review-needed labels May 25, 2017

eslint-bot reviewed May 25, 2017

View reviewed changes

javache reviewed May 25, 2017

View reviewed changes

shergin added the Platform: iOS iOS applications. label May 26, 2017

facebook-github-bot added GH Review: accepted Import Started This pull request has been imported. This does not imply the PR has been approved. and removed GH Review: review-needed labels May 26, 2017

facebook-github-bot added Import Failed and removed Import Started This pull request has been imported. This does not imply the PR has been approved. labels May 26, 2017

Adam Comella added 3 commits May 26, 2017 17:49

Remove trailing spaces

a123da3

Use constants instead of strings

e0900d4

rigdern force-pushed the rigdern/announceForAccessibility branch from f877700 to e0900d4 Compare May 27, 2017 01:02

facebook-github-bot added the Import Started This pull request has been imported. This does not imply the PR has been approved. label May 30, 2017

facebook-github-bot closed this in cfe0032 May 30, 2017

rigdern deleted the rigdern/announceForAccessibility branch May 31, 2017 20:25

shergin reviewed Jun 7, 2017

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

iOS: Introduce API for making screen reader announcements #14168

iOS: Introduce API for making screen reader announcements #14168

rigdern commented May 25, 2017

eslint-bot May 25, 2017

eslint-bot May 25, 2017

eslint-bot May 25, 2017

javache May 25, 2017

rigdern commented May 25, 2017

facebook-github-bot commented May 26, 2017

facebook-github-bot commented May 26, 2017

rigdern commented May 27, 2017

facebook-github-bot commented May 30, 2017

shergin commented Jun 4, 2017

rigdern commented Jun 6, 2017

shergin Jun 7, 2017

shergin Jun 7, 2017

shergin Jun 7, 2017

rigdern commented Jun 7, 2017

shergin Jun 7, 2017

shergin commented Jun 7, 2017

rigdern commented Jun 7, 2017

shergin commented Jun 7, 2017

caocao-melon commented Jul 20, 2018

rigdern commented Jul 20, 2018

iOS: Introduce API for making screen reader announcements #14168

iOS: Introduce API for making screen reader announcements #14168

Conversation

rigdern commented May 25, 2017

Test Plan (required)

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rigdern commented May 25, 2017

facebook-github-bot commented May 26, 2017

facebook-github-bot commented May 26, 2017

rigdern commented May 27, 2017

facebook-github-bot commented May 30, 2017

shergin commented Jun 4, 2017

rigdern commented Jun 6, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rigdern commented Jun 7, 2017

Choose a reason for hiding this comment

shergin commented Jun 7, 2017

rigdern commented Jun 7, 2017

shergin commented Jun 7, 2017

caocao-melon commented Jul 20, 2018

rigdern commented Jul 20, 2018