[iOS] Announce scroll position to VoiceOver by LouiseHsu · Pull Request #193384 · flutter/flutter

LouiseHsu · 2026-09-26T00:27:12Z

There were two bugs that this PR fixes.

Since on every scroll, the layout will change, so the else branch was unreachable.
We were passing in the wrong type - we passed it a semantic element, but UIAccessibilityPageScrolledNotification needs an NSString, so VoiceOver ignored it.

Android didn't have this problem because TalkBack receives numbers and builds the sentence by itself. On iOS though, we have to supply the finished, localized sentence.

For localization, this PR doesnt add any new localization. Instead, we look up the native string supplied by UIKit, using a public NSBundle API. This means that the the wording matches native apps in every language iOS supports, including languages that reorder the numbers, for free.

However, the keys are undocumented. So if a lookup ever fails, the announcement falls back to English, which is still better than today's complete silence. We already do this elsewhere in the engine, public api with undocumented keys, so I feel the risk is low.

Longer term, it would be good if the framework could supply its own localized strings, to remove that dependency on an undocumented key.

English VoiceOver scroll announcement

english.voiceover.scroll.mov

Chinese VoiceOver scroll announcement

chinese.voiceover.scroll.mov

Pre-launch Checklist

Fixes flutter#189285

Device testing showed VoiceOver still speaks the page-scrolled announcement when the existing layout-changed notification follows it, so there is no need to change focus handling. The scroll announcement is now purely additive.

…l-announcement # Conflicts: # engine/src/flutter/shell/platform/darwin/ios/framework/Source/accessibility_bridge.h # engine/src/flutter/shell/platform/darwin/ios/framework/Source/accessibility_bridge.mm

After merging master, notifications are only posted when the view is loaded, so the new tests need to stub viewIfLoaded like the existing ones.

- Format UIKit's scroll strings with +stringWithValidatedFormat:, which returns nil if a string's placeholders don't match, instead of hand-rolled substitution. English fallbacks are compiler-checked format literals. - Reset the scroll announcement dedupe on each VoiceOver scroll action, so every swipe is announced even if the status is unchanged, matching native UIScrollView behavior. Frames within one scroll are still deduplicated. - Comment rewrites.

gemini-code-assist

Code Review

This pull request updates the iOS accessibility bridge to improve scroll status announcements by tracking scroll states and utilizing UIKit's native accessibility strings. It also adds unit tests to verify scroll status calculations and deduplication. Feedback on the changes identifies a critical compatibility issue where the newly introduced stringWithValidatedFormat:validFormatSpecifiers:error: selector is only available on iOS 16.0 and later, which will cause runtime crashes on older supported iOS versions (iOS 13+). It is recommended to wrap these formatting calls in @available(iOS 16.0, *) checks.

gemini-code-assist · 2026-09-30T01:29:35Z

+      NSString* result = format ? [NSString stringWithValidatedFormat:format
+                                                validFormatSpecifiers:@"%@ %@ %@"
+                                                                error:nil, first, last, total]
+                                : nil;


The stringWithValidatedFormat:validFormatSpecifiers:error: selector was introduced in iOS 16.0. Since Flutter supports older iOS versions (iOS 13+), calling this selector directly on iOS 13, 14, or 15 will result in a runtime crash (NSInvalidArgumentException due to unrecognized selector). Wrap this call in an @available(iOS 16.0, *) check and fall back to the English string (or another safe formatting approach) on older iOS versions.

NSString* result = nil; if (format) { if (@available(iOS 16.0, *)) { result = [NSString stringWithValidatedFormat:format validFormatSpecifiers:@"%@ %@ %@" error:nil, first, last, total]; } }

bad bot. you are a BAD BOT.
https://developer.apple.com/documentation/foundation/nsstring/stringwithvalidatedformat:validformatspecifiers:error:

LongCatIsLooong · 2026-10-05T22:38:11Z

+  int64_t last = 0;
+  int64_t total = 0;
+
+  bool operator==(const AccessibilityScrollStatus& other) const {


nit: can this use the default implementation?https://en.cppreference.com/cpp/language/default_comparisons

LongCatIsLooong · 2026-10-05T22:40:04Z

+
+  Form form = Form::kNone;
+  int32_t uid = -1;
+  int64_t first = 0;


Consider giving these more descriptive names.

LongCatIsLooong · 2026-10-05T22:41:29Z


+namespace {
+
+// Uses UIKit's accessibility strings, so scroll announcements match native


Are these private APIs?

Discussed offline, it seems there are no known viable alternatives at the moment. Can't use a UIKit view to make the a11y announcement.

LongCatIsLooong · 2026-10-05T22:50:02Z

+NSBundle* UIKitAccessibilityBundle() {
+  static NSBundle* bundle = nil;
+  if (!bundle) {
+    bundle = [NSBundle bundleWithIdentifier:@(kUIKitAccessibilityBundleId)];


nit: the documentation seems to indicate the value is already cached: https://developer.apple.com/documentation/foundation/bundle/init(identifier:)#return-value

LongCatIsLooong · 2026-10-05T22:59:25Z

+      NSString* last = LocalizedCount(status.last);
+      NSString* total = LocalizedCount(status.total);
+      NSString* format = UIKitLocalizedFormat(kScrollRowStatusKey);
+      NSString* result = format ? [NSString stringWithValidatedFormat:format


nit: [NSBundle localizedStringForKey:value:table] already accepts a fallback: https://developer.apple.com/documentation/foundation/bundle/localizedstring(forkey:value:table:)#parameters.

or

NSString* format = UIKitLocalizedFormat(kScrollRowStatusKey) ?: @"rows %1$@ to %2$@ of %3$@"

Oh you're validating the format string UIKitLocalizedFormat returned but not for the fallback. Since we rarely hit the fallback, validating the fallback isn't that bad for performance I think?

LongCatIsLooong · 2026-10-06T00:31:28Z

+  if (action == flutter::SemanticsAction::kScrollUp ||
+      action == flutter::SemanticsAction::kScrollDown ||
+      action == flutter::SemanticsAction::kScrollLeft ||
+      action == flutter::SemanticsAction::kScrollRight) {


Should kScrollToOffset = 1 << 23 also reset the status (AFAIK it's only used by FKA)? Or strictly voice over scrolls?

LongCatIsLooong · 2026-10-06T00:35:33Z

+    }
+    int64_t total = node.scrollChildren;
+    int64_t first = std::clamp<int64_t>(node.scrollIndex + 1, 1, total);
+    status.form = AccessibilityScrollStatus::Form::kRows;


So when scrollChildren > 0 is announced as kPage and if we know the total number of children in the scrollable container then it will say "Rows x to y"? I'm curious why scrollChildren > 0 distinguishes page scroll views from row scroll views?

LongCatIsLooong · 2026-10-06T00:46:39Z

+  // A partial last screen counts as a page. The tolerance stops floating point
+  // error in the extents from adding a page.
+  constexpr double kPageTolerance = 1e-6;
+  const double range = std::max(extent_max - extent_min, 0.0);


uber nit: range -> scroll_range?

LongCatIsLooong · 2026-10-06T00:48:30Z

+
+  const bool horizontal = node.HasAction(flutter::SemanticsAction::kScrollLeft) ||
+                          node.HasAction(flutter::SemanticsAction::kScrollRight);
+  const double viewport = horizontal ? node.rect.width() : node.rect.height();


uber nit: viewport -> viewport_extent

LongCatIsLooong · 2026-10-06T00:55:15Z

+  constexpr double kPageTolerance = 1e-6;
+  const double range = std::max(extent_max - extent_min, 0.0);
+  int64_t total_pages = std::max<int64_t>(
+      static_cast<int64_t>(std::ceil((range + viewport) / viewport - kPageTolerance)), 1);


according to the comment the kPageTolerance thing is for preventing an extraneous page? Then shouldn't it be viewport + kPageTolerance for denominator to reduce the value?

LouiseHsu added 2 commits September 25, 2026 16:46

[iOS] Announce scroll position to VoiceOver

e876ccf

Fixes flutter#189285

Keep existing layout change handling during scrolls

821a112

Device testing showed VoiceOver still speaks the page-scrolled announcement when the existing layout-changed notification follows it, so there is no need to change focus handling. The scroll announcement is now purely additive.

github-actions Bot added platform-ios iOS applications specifically engine flutter/engine related. See also e: labels. a: accessibility Accessibility, e.g. VoiceOver or TalkBack. (aka a11y) team-ios Owned by iOS platform team labels Sep 26, 2026

LouiseHsu added 2 commits September 25, 2026 17:29

Merge remote-tracking branch 'upstream/master' into a11y-189285-scrol…

60edf2c

…l-announcement # Conflicts: # engine/src/flutter/shell/platform/darwin/ios/framework/Source/accessibility_bridge.h # engine/src/flutter/shell/platform/darwin/ios/framework/Source/accessibility_bridge.mm

Use StubLoadedView in scroll announcement tests

2a47f28

After merging master, notifications are only posted when the view is loaded, so the new tests need to stub viewIfLoaded like the existing ones.

LouiseHsu added the CICD Run CI/CD label Sep 28, 2026

LouiseHsu and others added 3 commits September 28, 2026 12:30

Merge branch 'master' into a11y-189285-scroll-announcement

a285e49

fix up comments

368f9da

LouiseHsu marked this pull request as ready for review September 30, 2026 01:28

LouiseHsu requested a review from a team as a code owner September 30, 2026 01:28

Merge branch 'master' into a11y-189285-scroll-announcement

8214e86

gemini-code-assist Bot reviewed Sep 30, 2026

View reviewed changes

LouiseHsu mentioned this pull request Sep 30, 2026

Scroll a full viewport per screen reader scroll action instead of 80% #193540

Draft

LouiseHsu requested a review from LongCatIsLooong September 30, 2026 20:02

LongCatIsLooong reviewed Oct 6, 2026

View reviewed changes

vashworth marked this pull request as draft October 14, 2026 21:48

LouiseHsu mentioned this pull request Nov 3, 2026

Change default cache extent #195722

Open

10 of 11 tasks


		namespace {

		// Uses UIKit's accessibility strings, so scroll announcements match native

Conversation

LouiseHsu commented Sep 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pre-launch Checklist

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LongCatIsLooong Oct 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

LouiseHsu commented Sep 26, 2026 •

edited

Loading

LongCatIsLooong Oct 6, 2026 •

edited

Loading