Skip to content

Commit 2b6b9d1

Browse files
authored
Adds semantics locale support for web (#171196)
<!-- Thanks for filing a pull request! Reviewers are typically assigned within a week of filing a request. To learn more about code review, see our documentation on Tree Hygiene: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md --> toward flutter/flutter#98948 This sets the ground work for framework and web still need to implement: 1. Android and iOS support 2. set application locale. ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [ ] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [ ] I signed the [CLA]. - [ ] I listed at least one issue that this PR fixes in the description above. - [ ] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. <!-- 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
1 parent 96d6ce0 commit 2b6b9d1

19 files changed

Lines changed: 691 additions & 307 deletions

File tree

‎engine/src/flutter/lib/ui/fixtures/ui_test.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ void sendSemanticsUpdate() {
234234
linkUrl: '',
235235
controlsNodes: null,
236236
inputType: SemanticsInputType.none,
237+
locale: null,
237238
);
238239
_semanticsUpdate(builder.build());
239240
}
@@ -287,6 +288,7 @@ void sendSemanticsUpdateWithRole() {
287288
role: SemanticsRole.tab,
288289
controlsNodes: null,
289290
inputType: SemanticsInputType.none,
291+
locale: null,
290292
);
291293
_semanticsUpdate(builder.build());
292294
}

‎engine/src/flutter/lib/ui/semantics.dart‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1790,6 +1790,9 @@ abstract class SemanticsUpdateBuilder {
17901790
/// The `role` describes the role of this node. Defaults to
17911791
/// [SemanticsRole.none] if not set.
17921792
///
1793+
/// The `locale` describes the language of the content in this node. i.e.
1794+
/// label, value, and hint.
1795+
///
17931796
/// If `validationResult` is not null, indicates the result of validating a
17941797
/// form field. If null, indicates that the node is not being validated, or
17951798
/// that the result is unknown. Form fields that validate user input but do
@@ -1840,6 +1843,7 @@ abstract class SemanticsUpdateBuilder {
18401843
required List<String>? controlsNodes,
18411844
SemanticsValidationResult validationResult = SemanticsValidationResult.none,
18421845
required SemanticsInputType inputType,
1846+
required Locale? locale,
18431847
});
18441848

18451849
/// Update the custom semantics action associated with the given `id`.
@@ -1917,6 +1921,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
19171921
required List<String>? controlsNodes,
19181922
SemanticsValidationResult validationResult = SemanticsValidationResult.none,
19191923
required SemanticsInputType inputType,
1924+
required Locale? locale,
19201925
}) {
19211926
assert(_matrix4IsValid(transform));
19221927
assert(
@@ -1964,6 +1969,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
19641969
controlsNodes,
19651970
validationResult.index,
19661971
inputType.index,
1972+
locale?.toString() ?? '',
19671973
);
19681974
}
19691975

@@ -2010,6 +2016,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
20102016
Handle,
20112017
Int32,
20122018
Int32,
2019+
Handle,
20132020
)
20142021
>(symbol: 'SemanticsUpdateBuilder::updateNode')
20152022
external void _updateNode(
@@ -2053,6 +2060,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
20532060
List<String>? controlsNodes,
20542061
int validationResultIndex,
20552062
int inputType,
2063+
String locale,
20562064
);
20572065

20582066
@override

‎engine/src/flutter/lib/web_ui/lib/semantics.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -710,6 +710,7 @@ class SemanticsUpdateBuilder {
710710
required List<String>? controlsNodes,
711711
SemanticsValidationResult validationResult = SemanticsValidationResult.none,
712712
required SemanticsInputType inputType,
713+
required Locale? locale,
713714
}) {
714715
if (transform.length != 16) {
715716
throw ArgumentError('transform argument must have 16 entries.');
@@ -753,6 +754,7 @@ class SemanticsUpdateBuilder {
753754
controlsNodes: controlsNodes,
754755
validationResult: validationResult,
755756
inputType: inputType,
757+
locale: locale,
756758
),
757759
);
758760
}

‎engine/src/flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -270,6 +270,7 @@ class SemanticsNodeUpdate {
270270
required this.controlsNodes,
271271
required this.validationResult,
272272
required this.inputType,
273+
required this.locale,
273274
});
274275

275276
/// See [ui.SemanticsUpdateBuilder.updateNode].
@@ -382,6 +383,9 @@ class SemanticsNodeUpdate {
382383

383384
/// See [ui.SemanticsUpdateBuilder.updateNode].
384385
final ui.SemanticsInputType inputType;
386+
387+
/// See [ui.SemanticsUpdateBuilder.updateNode].
388+
final ui.Locale? locale;
385389
}
386390

387391
/// Identifies [SemanticRole] implementations.
@@ -782,6 +786,10 @@ abstract class SemanticRole {
782786
if (semanticsObject.isControlsNodesDirty) {
783787
_updateControls();
784788
}
789+
790+
if (semanticsObject.isLocaleDirty) {
791+
semanticsObject.owner.addOneTimePostUpdateCallback(_updateLocale);
792+
}
785793
}
786794

787795
void _updateIdentifier() {
@@ -812,6 +820,16 @@ abstract class SemanticRole {
812820
removeAttribute('aria-controls');
813821
}
814822

823+
void _updateLocale() {
824+
final String locale = semanticsObject.locale?.toString() ?? '';
825+
final isSameAsParent = semanticsObject.locale == semanticsObject.parent?.locale;
826+
if (locale.isEmpty || isSameAsParent) {
827+
removeAttribute('lang');
828+
return;
829+
}
830+
setAttribute('lang', locale);
831+
}
832+
815833
/// Applies the current [SemanticsObject.validationResult] to the DOM managed
816834
/// by this role.
817835
///
@@ -1472,6 +1490,18 @@ class SemanticsObject {
14721490
_dirtyFields |= _controlsNodesIndex;
14731491
}
14741492

1493+
/// The language of this node.
1494+
ui.Locale? locale;
1495+
1496+
static const int _localeIndex = 1 << 28;
1497+
1498+
/// Whether the [locale] field has been updated but has not been
1499+
/// applied to the DOM yet.
1500+
bool get isLocaleDirty => _isDirty(_localeIndex);
1501+
void _markLocaleDirty() {
1502+
_dirtyFields |= _localeIndex;
1503+
}
1504+
14751505
/// Bitfield showing which fields have been updated but have not yet been
14761506
/// applied to the DOM.
14771507
///
@@ -1754,6 +1784,11 @@ class SemanticsObject {
17541784
_markControlsNodesDirty();
17551785
}
17561786

1787+
if (locale != update.locale) {
1788+
locale = update.locale;
1789+
_markLocaleDirty();
1790+
}
1791+
17571792
// Apply updates to the DOM.
17581793
_updateRole();
17591794

‎engine/src/flutter/lib/web_ui/test/engine/semantics/semantics_test.dart‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,9 @@ void runSemanticsTests() {
151151
group('landmarks', () {
152152
_testLandmarks();
153153
});
154+
group('locale', () {
155+
_testLocale();
156+
});
154157
}
155158

156159
void _testSemanticRole() {
@@ -5415,6 +5418,97 @@ void _testLandmarks() {
54155418
semantics().semanticsEnabled = false;
54165419
}
54175420

5421+
void _testLocale() {
5422+
test('nodes with locale update correctly', () {
5423+
semantics()
5424+
..debugOverrideTimestampFunction(() => _testTime)
5425+
..semanticsEnabled = true;
5426+
5427+
SemanticsObject pumpSemantics() {
5428+
final SemanticsTester tester = SemanticsTester(owner());
5429+
tester.updateNode(
5430+
id: 0,
5431+
locale: const ui.Locale('es-MX'),
5432+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5433+
);
5434+
tester.apply();
5435+
return tester.getSemanticsObject(0);
5436+
}
5437+
5438+
final SemanticsObject object = pumpSemantics();
5439+
expect(object.element.getAttribute('lang'), 'es-MX');
5440+
});
5441+
5442+
test('nodes with same locale as parent does not set lang', () {
5443+
semantics()
5444+
..debugOverrideTimestampFunction(() => _testTime)
5445+
..semanticsEnabled = true;
5446+
5447+
final SemanticsTester tester = SemanticsTester(owner());
5448+
SemanticsObject pumpSemantics() {
5449+
tester.updateNode(
5450+
id: 0,
5451+
locale: const ui.Locale('es-MX'),
5452+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5453+
children: <SemanticsNodeUpdate>[
5454+
tester.updateNode(
5455+
id: 1,
5456+
locale: const ui.Locale('es-MX'),
5457+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5458+
),
5459+
],
5460+
);
5461+
tester.apply();
5462+
return tester.getSemanticsObject(0);
5463+
}
5464+
5465+
final SemanticsObject object = pumpSemantics();
5466+
expect(object.element.getAttribute('lang'), 'es-MX');
5467+
final SemanticsObject node1 = tester.getSemanticsObject(1);
5468+
expect(node1.element.getAttribute('lang'), null);
5469+
});
5470+
5471+
test('nodes changing locale set lang correctly', () {
5472+
semantics()
5473+
..debugOverrideTimestampFunction(() => _testTime)
5474+
..semanticsEnabled = true;
5475+
5476+
final SemanticsTester tester = SemanticsTester(owner());
5477+
SemanticsObject pumpSemantics() {
5478+
tester.updateNode(
5479+
id: 0,
5480+
locale: const ui.Locale('es-MX'),
5481+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5482+
children: <SemanticsNodeUpdate>[
5483+
tester.updateNode(
5484+
id: 1,
5485+
locale: const ui.Locale('es-MX'),
5486+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5487+
children: <SemanticsNodeUpdate>[
5488+
tester.updateNode(
5489+
id: 2,
5490+
locale: const ui.Locale('en-US'),
5491+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5492+
),
5493+
],
5494+
),
5495+
],
5496+
);
5497+
tester.apply();
5498+
return tester.getSemanticsObject(0);
5499+
}
5500+
5501+
final SemanticsObject object = pumpSemantics();
5502+
expect(object.element.getAttribute('lang'), 'es-MX');
5503+
final SemanticsObject node1 = tester.getSemanticsObject(1);
5504+
expect(node1.element.getAttribute('lang'), null);
5505+
final SemanticsObject node2 = tester.getSemanticsObject(2);
5506+
expect(node2.element.getAttribute('lang'), 'en-US');
5507+
});
5508+
5509+
semantics().semanticsEnabled = false;
5510+
}
5511+
54185512
/// A facade in front of [ui.SemanticsUpdateBuilder.updateNode] that
54195513
/// supplies default values for semantics attributes.
54205514
void updateNode(
@@ -5455,6 +5549,7 @@ void updateNode(
54555549
List<String>? controlsNodes,
54565550
ui.SemanticsRole role = ui.SemanticsRole.none,
54575551
ui.SemanticsInputType inputType = ui.SemanticsInputType.none,
5552+
ui.Locale? locale,
54585553
}) {
54595554
transform ??= Float64List.fromList(Matrix4.identity().storage);
54605555
childrenInTraversalOrder ??= Int32List(0);
@@ -5497,6 +5592,7 @@ void updateNode(
54975592
linkUrl: linkUrl,
54985593
controlsNodes: controlsNodes,
54995594
inputType: inputType,
5595+
locale: locale,
55005596
);
55015597
}
55025598

‎engine/src/flutter/lib/web_ui/test/engine/semantics/semantics_tester.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@ class SemanticsTester {
8888
List<String>? controlsNodes,
8989
ui.SemanticsValidationResult validationResult = ui.SemanticsValidationResult.none,
9090
ui.SemanticsInputType inputType = ui.SemanticsInputType.none,
91+
ui.Locale? locale,
9192
}) {
9293
// Actions
9394
if (hasTap ?? false) {
@@ -218,6 +219,7 @@ class SemanticsTester {
218219
controlsNodes: controlsNodes,
219220
validationResult: validationResult,
220221
inputType: inputType,
222+
locale: locale,
221223
);
222224
_nodeUpdates.add(update);
223225
return update;

‎engine/src/flutter/shell/platform/embedder/fixtures/main.dart‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,7 @@ Future<void> a11y_main() async {
198198
additionalActions: Int32List(0),
199199
controlsNodes: null,
200200
inputType: SemanticsInputType.none,
201+
locale: null,
201202
)
202203
..updateNode(
203204
id: 84,
@@ -233,6 +234,7 @@ Future<void> a11y_main() async {
233234
childrenInTraversalOrder: Int32List(0),
234235
controlsNodes: null,
235236
inputType: SemanticsInputType.none,
237+
locale: null,
236238
)
237239
..updateNode(
238240
id: 96,
@@ -268,6 +270,7 @@ Future<void> a11y_main() async {
268270
additionalActions: Int32List(0),
269271
controlsNodes: null,
270272
inputType: SemanticsInputType.none,
273+
locale: null,
271274
)
272275
..updateNode(
273276
id: 128,
@@ -303,6 +306,7 @@ Future<void> a11y_main() async {
303306
childrenInTraversalOrder: Int32List(0),
304307
controlsNodes: null,
305308
inputType: SemanticsInputType.none,
309+
locale: null,
306310
)
307311
..updateCustomAction(id: 21, label: 'Archive', hint: 'archive message');
308312

@@ -390,6 +394,7 @@ Future<void> a11y_string_attributes() async {
390394
additionalActions: Int32List(0),
391395
controlsNodes: null,
392396
inputType: SemanticsInputType.none,
397+
locale: null,
393398
);
394399

395400
PlatformDispatcher.instance.views.first.updateSemantics(builder.build());
@@ -1686,6 +1691,7 @@ Future<void> a11y_main_multi_view() async {
16861691
additionalActions: Int32List(0),
16871692
controlsNodes: null,
16881693
inputType: SemanticsInputType.none,
1694+
locale: null,
16891695
);
16901696
}
16911697

‎engine/src/flutter/shell/platform/windows/fixtures/main.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,7 @@ Future<void> sendSemanticsTreeInfo() async {
466466
role: ui.SemanticsRole.tab,
467467
controlsNodes: null,
468468
inputType: ui.SemanticsInputType.none,
469+
locale: null,
469470
);
470471
return builder.build();
471472
}

‎engine/src/flutter/testing/ios_scenario_app/lib/src/locale_initialization.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ class LocaleInitialization extends Scenario {
7474
additionalActions: Int32List(0),
7575
controlsNodes: null,
7676
inputType: SemanticsInputType.none,
77+
locale: null,
7778
);
7879

7980
final SemanticsUpdate semanticsUpdate = semanticsUpdateBuilder.build();
@@ -133,6 +134,7 @@ class LocaleInitialization extends Scenario {
133134
additionalActions: Int32List(0),
134135
controlsNodes: null,
135136
inputType: SemanticsInputType.none,
137+
locale: null,
136138
);
137139

138140
final SemanticsUpdate semanticsUpdate = semanticsUpdateBuilder.build();

0 commit comments

Comments
 (0)