Skip to content

Commit 89db44f

Browse files
authored
[material_ui][cupertino_ui] allow page routes to opt out of route semantics - #182556 (#12674)
Nested navigators may use routes to update only part of the visible screen. However, Material and Cupertino page routes currently introduce a semantics route scope, causing screen readers to treat these updates as navigation to a new screen. This adds `includeRouteSemantics` to: - `MaterialPageRoute` - `MaterialPage` - `CupertinoPageRoute` - `CupertinoPage` The option defaults to `true`, preserving existing behavior. When set to `false`, the route content is not wrapped in a semantics node with `scopesRoute: true`. Tests cover both imperative routes and declarative pages. Fixes flutter/flutter#168915. ## Pre-Review Checklist [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent 3a46e37 commit 89db44f

6 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎packages/cupertino_ui/lib/src/route.dart‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,18 @@ mixin CupertinoRouteTransitionMixin<T> on PageRoute<T> {
9797
@protected
9898
Widget buildContent(BuildContext context);
9999

100+
/// {@template cupertino_ui.CupertinoRouteTransitionMixin.includeRouteSemantics}
101+
/// Whether this route introduces a route scope in the semantics tree.
102+
///
103+
/// Defaults to true. When true, screen readers can treat pushes and pops of
104+
/// this route as navigation to a new screen and announce the change to users.
105+
///
106+
/// Set this to false for routes that update only part of the screen, such as
107+
/// tab or shell content in a nested navigator. This prevents screen readers
108+
/// from treating the route as a new screen.
109+
/// {@endtemplate}
110+
bool get includeRouteSemantics => true;
111+
100112
/// {@template cupertino_ui.CupertinoRouteTransitionMixin.title}
101113
/// A title string for this route.
102114
///
@@ -194,6 +206,9 @@ mixin CupertinoRouteTransitionMixin<T> on PageRoute<T> {
194206
Animation<double> secondaryAnimation,
195207
) {
196208
final Widget child = buildContent(context);
209+
if (!includeRouteSemantics) {
210+
return child;
211+
}
197212
return Semantics(scopesRoute: true, explicitChildNodes: true, child: child);
198213
}
199214

@@ -309,6 +324,7 @@ class CupertinoPageRoute<T> extends PageRoute<T> with CupertinoRouteTransitionMi
309324
this.maintainState = true,
310325
super.fullscreenDialog,
311326
super.allowSnapshotting = true,
327+
this.includeRouteSemantics = true,
312328
super.barrierDismissible = false,
313329
}) {
314330
assert(opaque);
@@ -330,6 +346,10 @@ class CupertinoPageRoute<T> extends PageRoute<T> with CupertinoRouteTransitionMi
330346
@override
331347
final bool maintainState;
332348

349+
/// {@macro cupertino_ui.CupertinoRouteTransitionMixin.includeRouteSemantics}
350+
@override
351+
final bool includeRouteSemantics;
352+
333353
@override
334354
String get debugLabel => '${super.debugLabel}(${settings.name})';
335355
}
@@ -362,6 +382,9 @@ class _PageBasedCupertinoPageRoute<T> extends PageRoute<T> with CupertinoRouteTr
362382
@override
363383
bool get fullscreenDialog => _page.fullscreenDialog;
364384

385+
@override
386+
bool get includeRouteSemantics => _page.includeRouteSemantics;
387+
365388
@override
366389
String get debugLabel => '${super.debugLabel}(${_page.name})';
367390
}
@@ -390,6 +413,7 @@ class CupertinoPage<T> extends Page<T> {
390413
this.title,
391414
this.fullscreenDialog = false,
392415
this.allowSnapshotting = true,
416+
this.includeRouteSemantics = true,
393417
super.canPop,
394418
super.onPopInvoked,
395419
super.key,
@@ -413,6 +437,9 @@ class CupertinoPage<T> extends Page<T> {
413437
/// {@macro flutter.widgets.TransitionRoute.allowSnapshotting}
414438
final bool allowSnapshotting;
415439

440+
/// {@macro cupertino_ui.CupertinoRouteTransitionMixin.includeRouteSemantics}
441+
final bool includeRouteSemantics;
442+
416443
@override
417444
Route<T> createRoute(BuildContext context) {
418445
return _PageBasedCupertinoPageRoute<T>(page: this, allowSnapshotting: allowSnapshotting);
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds an option for `CupertinoPageRoute` and `CupertinoPage` to opt out of introducing a semantics route scope.
3+
version: minor

‎packages/cupertino_ui/test/route_test.dart‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2340,6 +2340,44 @@ void main() {
23402340
expect(find.text('Visible'), findsOneWidget);
23412341
});
23422342

2343+
testWidgets('CupertinoPageRoute can opt out of route semantics', (WidgetTester tester) async {
2344+
final SemanticsHandle handle = tester.ensureSemantics();
2345+
2346+
await tester.pumpWidget(
2347+
CupertinoApp(
2348+
onGenerateRoute: (RouteSettings settings) {
2349+
return CupertinoPageRoute<void>(
2350+
includeRouteSemantics: false,
2351+
builder: (BuildContext context) => const Text('Page'),
2352+
);
2353+
},
2354+
),
2355+
);
2356+
2357+
expect(find.semantics.byFlag(SemanticsFlag.scopesRoute), findsNothing);
2358+
handle.dispose();
2359+
});
2360+
2361+
testWidgets('CupertinoPage can opt out of route semantics', (WidgetTester tester) async {
2362+
final SemanticsHandle handle = tester.ensureSemantics();
2363+
2364+
await tester.pumpWidget(
2365+
buildNavigator(
2366+
view: tester.view,
2367+
pages: const <Page<void>>[
2368+
CupertinoPage<void>(includeRouteSemantics: false, child: Text('Page')),
2369+
],
2370+
onPopPage: (Route<dynamic> route, dynamic result) {
2371+
assert(false); // The test shouldn't call this.
2372+
return true;
2373+
},
2374+
),
2375+
);
2376+
2377+
expect(find.semantics.byFlag(SemanticsFlag.scopesRoute), findsNothing);
2378+
handle.dispose();
2379+
});
2380+
23432381
testWidgets('CupertinoPage works', (WidgetTester tester) async {
23442382
final LocalKey pageKey = UniqueKey();
23452383
final detector = TransitionDetector();

‎packages/material_ui/lib/src/page.dart‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ class MaterialPageRoute<T> extends PageRoute<T> with MaterialRouteTransitionMixi
4141
this.maintainState = true,
4242
super.fullscreenDialog,
4343
super.allowSnapshotting = true,
44+
this.includeRouteSemantics = true,
4445
super.barrierDismissible = false,
4546
super.traversalEdgeBehavior,
4647
super.directionalTraversalEdgeBehavior,
@@ -57,6 +58,10 @@ class MaterialPageRoute<T> extends PageRoute<T> with MaterialRouteTransitionMixi
5758
@override
5859
final bool maintainState;
5960

61+
/// {@macro material_ui.MaterialRouteTransitionMixin.includeRouteSemantics}
62+
@override
63+
final bool includeRouteSemantics;
64+
6065
@override
6166
String get debugLabel => '${super.debugLabel}(${settings.name})';
6267
}
@@ -87,6 +92,18 @@ mixin MaterialRouteTransitionMixin<T> on PageRoute<T> {
8792
@protected
8893
Widget buildContent(BuildContext context);
8994

95+
/// {@template material_ui.MaterialRouteTransitionMixin.includeRouteSemantics}
96+
/// Whether this route introduces a route scope in the semantics tree.
97+
///
98+
/// Defaults to true. When true, screen readers can treat pushes and pops of
99+
/// this route as navigation to a new screen and announce the change to users.
100+
///
101+
/// Set this to false for routes that update only part of the screen, such as
102+
/// tab or shell content in a nested navigator. This prevents screen readers
103+
/// from treating the route as a new screen.
104+
/// {@endtemplate}
105+
bool get includeRouteSemantics => true;
106+
90107
@override
91108
Duration get transitionDuration =>
92109
_getPageTransitionBuilder(navigator!.context)?.transitionDuration ??
@@ -191,6 +208,9 @@ mixin MaterialRouteTransitionMixin<T> on PageRoute<T> {
191208
Animation<double> secondaryAnimation,
192209
) {
193210
final Widget result = buildContent(context);
211+
if (!includeRouteSemantics) {
212+
return result;
213+
}
194214
return Semantics(scopesRoute: true, explicitChildNodes: true, child: result);
195215
}
196216

@@ -233,6 +253,7 @@ class MaterialPage<T> extends Page<T> {
233253
this.maintainState = true,
234254
this.fullscreenDialog = false,
235255
this.allowSnapshotting = true,
256+
this.includeRouteSemantics = true,
236257
super.key,
237258
super.canPop,
238259
super.onPopInvoked,
@@ -253,6 +274,9 @@ class MaterialPage<T> extends Page<T> {
253274
/// {@macro flutter.widgets.TransitionRoute.allowSnapshotting}
254275
final bool allowSnapshotting;
255276

277+
/// {@macro material_ui.MaterialRouteTransitionMixin.includeRouteSemantics}
278+
final bool includeRouteSemantics;
279+
256280
@override
257281
Route<T> createRoute(BuildContext context) {
258282
return _PageBasedMaterialPageRoute<T>(page: this, allowSnapshotting: allowSnapshotting);
@@ -282,6 +306,9 @@ class _PageBasedMaterialPageRoute<T> extends PageRoute<T> with MaterialRouteTran
282306
@override
283307
bool get fullscreenDialog => _page.fullscreenDialog;
284308

309+
@override
310+
bool get includeRouteSemantics => _page.includeRouteSemantics;
311+
285312
@override
286313
String get debugLabel => '${super.debugLabel}(${_page.name})';
287314
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds an option for `MaterialPageRoute` and `MaterialPage` to opt out of introducing a semantics route scope.
3+
version: minor

‎packages/material_ui/test/page_test.dart‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1197,6 +1197,44 @@ void main() {
11971197
}),
11981198
);
11991199

1200+
testWidgets('MaterialPageRoute can opt out of route semantics', (WidgetTester tester) async {
1201+
final SemanticsHandle handle = tester.ensureSemantics();
1202+
1203+
await tester.pumpWidget(
1204+
MaterialApp(
1205+
onGenerateRoute: (RouteSettings settings) {
1206+
return MaterialPageRoute<void>(
1207+
includeRouteSemantics: false,
1208+
builder: (BuildContext context) => const Text('Page'),
1209+
);
1210+
},
1211+
),
1212+
);
1213+
1214+
expect(find.semantics.byFlag(SemanticsFlag.scopesRoute), findsNothing);
1215+
handle.dispose();
1216+
});
1217+
1218+
testWidgets('MaterialPage can opt out of route semantics', (WidgetTester tester) async {
1219+
final SemanticsHandle handle = tester.ensureSemantics();
1220+
1221+
await tester.pumpWidget(
1222+
buildNavigator(
1223+
view: tester.view,
1224+
pages: const <Page<void>>[
1225+
MaterialPage<void>(includeRouteSemantics: false, child: Text('Page')),
1226+
],
1227+
onPopPage: (Route<dynamic> route, dynamic result) {
1228+
assert(false); // The test shouldn't call this.
1229+
return true;
1230+
},
1231+
),
1232+
);
1233+
1234+
expect(find.semantics.byFlag(SemanticsFlag.scopesRoute), findsNothing);
1235+
handle.dispose();
1236+
});
1237+
12001238
testWidgets('MaterialPage works', (WidgetTester tester) async {
12011239
final LocalKey pageKey = UniqueKey();
12021240
final detector = TransitionDetector();

0 commit comments

Comments
 (0)