Skip to content

Commit a9b22cf

Browse files
huycozyhuycozy
authored
Fix AppBar Semantics namesRoute for mismatched platforms (flutter#176694)
- Address a partial issue within flutter#176566 - Fix flutter#177000 - In this PR: - proposes using `defaultTargetPlatform` instead of platform from theme for Semantics namesRoute in AppBar widget (see use case at flutter#176566 (comment)); - improve documentation for this at `excludeHeaderSemantics` property. - add a test for this change. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --------- Signed-off-by: huycozy <[email protected]>
1 parent c648d89 commit a9b22cf

File tree

2 files changed

+145
-1
lines changed

2 files changed

+145
-1
lines changed

‎packages/flutter/lib/src/material/app_bar.dart‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -633,6 +633,16 @@ class AppBar extends StatefulWidget implements PreferredSizeWidget {
633633
/// {@template flutter.material.appbar.excludeHeaderSemantics}
634634
/// Whether the title should be wrapped with header [Semantics].
635635
///
636+
/// If false, the title will be used as [SemanticsProperties.namesRoute]
637+
/// for Android, Fuchsia, Linux, and Windows platform. This means the title is
638+
/// announced by screen reader when transition to this route.
639+
///
640+
/// The accessibility behavior is platform adaptive, based on the device's
641+
/// actual platform rather than the theme's platform setting. This ensures that
642+
/// assistive technologies like VoiceOver on iOS and macOS receive the correct
643+
/// `namesRoute` semantic information, even when the app's theme is configured
644+
/// to mimic a different platform's appearance.
645+
///
636646
/// Defaults to false.
637647
/// {@endtemplate}
638648
final bool excludeHeaderSemantics;
@@ -1066,7 +1076,7 @@ class _AppBarState extends State<AppBar> {
10661076
title = _AppBarTitleBox(child: title);
10671077
if (!widget.excludeHeaderSemantics) {
10681078
title = Semantics(
1069-
namesRoute: switch (theme.platform) {
1079+
namesRoute: switch (defaultTargetPlatform) {
10701080
TargetPlatform.android ||
10711081
TargetPlatform.fuchsia ||
10721082
TargetPlatform.linux ||

‎packages/flutter/test/material/app_bar_test.dart‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1495,6 +1495,140 @@ void main() {
14951495
semantics.dispose();
14961496
});
14971497

1498+
// Regression test for https://github.com/flutter/flutter/issues/176566
1499+
testWidgets(
1500+
'AppBar title Semantics.namesRoute flag should be null on iOS/macOS platforms regardless of theme platform',
1501+
(WidgetTester tester) async {
1502+
// Regression test for VoiceOver accessibility when theme platform differs from device platform.
1503+
// When someone sets theme.platform to TargetPlatform.android on an iOS/macOS device,
1504+
// VoiceOver should still work correctly by not having a namesRoute flag in the title's semantics.
1505+
final SemanticsTester semantics = SemanticsTester(tester);
1506+
await tester.pumpWidget(
1507+
MaterialApp(
1508+
theme: ThemeData(platform: TargetPlatform.android),
1509+
home: AppBar(title: const Text('Title')),
1510+
),
1511+
);
1512+
1513+
final List<SemanticsFlag> expectedFlags = <SemanticsFlag>[SemanticsFlag.isHeader];
1514+
1515+
expect(
1516+
semantics,
1517+
hasSemantics(
1518+
TestSemantics.root(
1519+
children: <TestSemantics>[
1520+
TestSemantics(
1521+
id: 1,
1522+
textDirection: TextDirection.ltr,
1523+
children: <TestSemantics>[
1524+
TestSemantics(
1525+
id: 2,
1526+
children: <TestSemantics>[
1527+
TestSemantics(
1528+
id: 3,
1529+
flags: <SemanticsFlag>[SemanticsFlag.scopesRoute],
1530+
children: <TestSemantics>[
1531+
TestSemantics(
1532+
id: 4,
1533+
children: <TestSemantics>[
1534+
TestSemantics(
1535+
id: 5,
1536+
flags: expectedFlags,
1537+
label: 'Title',
1538+
textDirection: TextDirection.ltr,
1539+
),
1540+
],
1541+
),
1542+
],
1543+
),
1544+
],
1545+
),
1546+
],
1547+
),
1548+
],
1549+
),
1550+
ignoreRect: true,
1551+
ignoreTransform: true,
1552+
),
1553+
);
1554+
1555+
semantics.dispose();
1556+
},
1557+
variant: const TargetPlatformVariant(<TargetPlatform>{
1558+
TargetPlatform.iOS,
1559+
TargetPlatform.macOS,
1560+
}),
1561+
);
1562+
1563+
// Regression test for https://github.com/flutter/flutter/issues/176566
1564+
testWidgets(
1565+
'AppBar title Semantics.namesRoute flag should be non-null on Android/Fuchsia/Linux/Windows platforms regardless of theme platform',
1566+
(WidgetTester tester) async {
1567+
// When someone sets theme.platform to TargetPlatform.iOS on an Android device,
1568+
// TalkBack should still work correctly by having a namesRoute flag in the title's semantics.
1569+
final SemanticsTester semantics = SemanticsTester(tester);
1570+
await tester.pumpWidget(
1571+
MaterialApp(
1572+
theme: ThemeData(platform: TargetPlatform.iOS),
1573+
home: AppBar(title: const Text('Title')),
1574+
),
1575+
);
1576+
1577+
final List<SemanticsFlag> expectedFlags = <SemanticsFlag>[
1578+
SemanticsFlag.isHeader,
1579+
SemanticsFlag.namesRoute,
1580+
];
1581+
1582+
expect(
1583+
semantics,
1584+
hasSemantics(
1585+
TestSemantics.root(
1586+
children: <TestSemantics>[
1587+
TestSemantics(
1588+
id: 1,
1589+
textDirection: TextDirection.ltr,
1590+
children: <TestSemantics>[
1591+
TestSemantics(
1592+
id: 2,
1593+
children: <TestSemantics>[
1594+
TestSemantics(
1595+
id: 3,
1596+
flags: <SemanticsFlag>[SemanticsFlag.scopesRoute],
1597+
children: <TestSemantics>[
1598+
TestSemantics(
1599+
id: 4,
1600+
children: <TestSemantics>[
1601+
TestSemantics(
1602+
id: 5,
1603+
flags: expectedFlags,
1604+
label: 'Title',
1605+
textDirection: TextDirection.ltr,
1606+
),
1607+
],
1608+
),
1609+
],
1610+
),
1611+
],
1612+
),
1613+
],
1614+
),
1615+
],
1616+
),
1617+
ignoreRect: true,
1618+
ignoreTransform: true,
1619+
),
1620+
);
1621+
1622+
semantics.dispose();
1623+
},
1624+
variant: const TargetPlatformVariant(<TargetPlatform>{
1625+
TargetPlatform.android,
1626+
TargetPlatform.fuchsia,
1627+
TargetPlatform.linux,
1628+
TargetPlatform.windows,
1629+
}),
1630+
);
1631+
14981632
testWidgets('Material3 - AppBar draws a light system bar for a dark background', (
14991633
WidgetTester tester,
15001634
) async {

0 commit comments

Comments
 (0)