Skip to content

Commit e4d2b87

Browse files
authored
[web] API to customize semantics placeholder message (#178309)
To customize the accessibility placeholder message: ```dart import 'dart:ui_web' as ui_web; void main() { ui_web.accessibilityPlaceholderMessage = 'My Custom Accessibility Message!'; // .... } ``` Fixes #178172
1 parent d8a99e9 commit e4d2b87

7 files changed

Lines changed: 90 additions & 26 deletions

File tree

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,8 +60,8 @@ class EnginePlatformDispatcher extends ui.PlatformDispatcher {
6060
static final EnginePlatformDispatcher _instance = EnginePlatformDispatcher();
6161

6262
@visibleForTesting
63-
final DomElement accessibilityPlaceholder = EngineSemantics.instance.semanticsHelper
64-
.prepareAccessibilityPlaceholder();
63+
DomElement get accessibilityPlaceholder =>
64+
EngineSemantics.instance.semanticsHelper.accessibilityPlaceholder;
6565

6666
PlatformConfiguration configuration = PlatformConfiguration(
6767
locales: parseBrowserLanguages(),

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

Lines changed: 28 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -24,13 +24,6 @@ const int kMaxSemanticsActivationAttempts = 20;
2424
/// Otherwise these events can cause unintended gestures on the framework side.
2525
const Duration _periodToConsumeEvents = Duration(milliseconds: 300);
2626

27-
/// The message in the label for the placeholder element used to enable
28-
/// accessibility.
29-
///
30-
/// This uses US English as the default message. Set this value prior to
31-
/// calling `runApp` to translate to another language.
32-
String placeholderMessage = 'Enable accessibility';
33-
3427
/// A helper for [EngineSemanticsOwner].
3528
///
3629
/// [SemanticsHelper] prepares and placeholder to enable semantics.
@@ -56,8 +49,10 @@ class SemanticsHelper {
5649
return _semanticsEnabler.shouldEnableSemantics(event);
5750
}
5851

59-
DomElement prepareAccessibilityPlaceholder() {
60-
return _semanticsEnabler.prepareAccessibilityPlaceholder();
52+
DomElement get accessibilityPlaceholder => _semanticsEnabler.accessibilityPlaceholder;
53+
54+
void updatePlaceholderLabel(String message) {
55+
_semanticsEnabler.updatePlaceholderLabel(message);
6156
}
6257

6358
/// Stops waiting for the user to enable semantics and removes the
@@ -103,13 +98,16 @@ abstract class SemanticsEnabler {
10398
/// should be forwarded to the framework.
10499
bool tryEnableSemantics(DomEvent event);
105100

106-
/// Creates the placeholder for accessibility.
107-
///
108-
/// Puts it inside the glasspane.
101+
/// The placeholder element for enabling accessibility.
109102
///
110103
/// On focus the element announces that accessibility can be enabled by
111104
/// tapping/clicking. (Announcement depends on the assistive technology)
112-
DomElement prepareAccessibilityPlaceholder();
105+
late final DomElement accessibilityPlaceholder = _prepareAccessibilityPlaceholder();
106+
107+
DomElement _prepareAccessibilityPlaceholder();
108+
109+
/// Updates the placeholder's label to the given [message].
110+
void updatePlaceholderLabel(String message);
113111

114112
/// Whether platform is still considering enabling semantics.
115113
///
@@ -184,7 +182,7 @@ class DesktopSemanticsEnabler extends SemanticsEnabler {
184182
}
185183

186184
@override
187-
DomElement prepareAccessibilityPlaceholder() {
185+
DomElement _prepareAccessibilityPlaceholder() {
188186
final DomElement placeholder = _semanticsPlaceholder = createDomElement(
189187
'flt-semantics-placeholder',
190188
);
@@ -207,8 +205,9 @@ class DesktopSemanticsEnabler extends SemanticsEnabler {
207205
placeholder
208206
..setAttribute('role', 'button')
209207
..setAttribute('aria-live', 'polite')
210-
..setAttribute('tabindex', '0')
211-
..setAttribute('aria-label', placeholderMessage);
208+
..setAttribute('tabindex', '0');
209+
210+
updatePlaceholderLabel(ui_web.accessibilityPlaceholderMessage);
212211

213212
// The placeholder sits just outside the window so only AT can reach it.
214213
placeholder.style
@@ -220,6 +219,11 @@ class DesktopSemanticsEnabler extends SemanticsEnabler {
220219
return placeholder;
221220
}
222221

222+
@override
223+
void updatePlaceholderLabel(String message) {
224+
_semanticsPlaceholder?.setAttribute('aria-label', message);
225+
}
226+
223227
@override
224228
void dispose() {
225229
_semanticsPlaceholder?.remove();
@@ -383,7 +387,7 @@ class MobileSemanticsEnabler extends SemanticsEnabler {
383387
}
384388

385389
@override
386-
DomElement prepareAccessibilityPlaceholder() {
390+
DomElement _prepareAccessibilityPlaceholder() {
387391
final DomElement placeholder = _semanticsPlaceholder = createDomElement(
388392
'flt-semantics-placeholder',
389393
);
@@ -398,9 +402,8 @@ class MobileSemanticsEnabler extends SemanticsEnabler {
398402
true.toJS,
399403
);
400404

401-
placeholder
402-
..setAttribute('role', 'button')
403-
..setAttribute('aria-label', placeholderMessage);
405+
placeholder.setAttribute('role', 'button');
406+
updatePlaceholderLabel(ui_web.accessibilityPlaceholderMessage);
404407
placeholder.style
405408
..position = 'absolute'
406409
..left = '0'
@@ -411,6 +414,11 @@ class MobileSemanticsEnabler extends SemanticsEnabler {
411414
return placeholder;
412415
}
413416

417+
@override
418+
void updatePlaceholderLabel(String message) {
419+
_semanticsPlaceholder?.setAttribute('aria-label', message);
420+
}
421+
414422
@override
415423
void dispose() {
416424
_semanticsPlaceholder?.remove();

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,5 @@ export 'ui_web/navigation/platform_location.dart';
1818
export 'ui_web/navigation/url_strategy.dart';
1919
export 'ui_web/platform_view_registry.dart';
2020
export 'ui_web/plugins.dart';
21+
export 'ui_web/semantics.dart';
2122
export 'ui_web/testing.dart';
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Copyright 2013 The Flutter Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style license that can be
3+
// found in the LICENSE file.
4+
5+
import 'package:ui/src/engine.dart';
6+
7+
String _accessibilityPlaceholderMessage = 'Enable accessibility';
8+
9+
/// The message in the label for the placeholder element used to enable accessibility.
10+
///
11+
/// This uses US English as the default message. Set this value at any time to update the label
12+
/// in the placeholder element.
13+
String get accessibilityPlaceholderMessage => _accessibilityPlaceholderMessage;
14+
set accessibilityPlaceholderMessage(String message) {
15+
if (message == _accessibilityPlaceholderMessage) {
16+
return;
17+
}
18+
19+
_accessibilityPlaceholderMessage = message;
20+
EngineSemantics.instance.semanticsHelper.updatePlaceholderLabel(message);
21+
}

‎engine/src/flutter/lib/web_ui/test/engine/platform_dispatcher/platform_dispatcher_test.dart‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -481,6 +481,17 @@ void testMain() {
481481
expect(dispatcher.accessibilityPlaceholder.isConnected, isFalse);
482482
});
483483

484+
test('accessibility placeholder label can be updated', () {
485+
final placeholder = domDocument.querySelector('flt-semantics-placeholder')!;
486+
487+
const String testLabel = 'Test accessibility label';
488+
ui_web.accessibilityPlaceholderMessage = testLabel;
489+
expect(placeholder.getAttribute('aria-label'), testLabel);
490+
491+
ui_web.accessibilityPlaceholderMessage = 'Enable accessibility';
492+
expect(placeholder.getAttribute('aria-label'), 'Enable accessibility');
493+
});
494+
484495
test('scheduleWarmupFrame should call both callbacks', () async {
485496
bool beginFrameCalled = false;
486497
final Completer<void> drawFrameCalled = Completer<void>();

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

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ void testMain() {
2121
setUp(() {
2222
EngineSemantics.instance.semanticsEnabled = false;
2323
desktopSemanticsEnabler = DesktopSemanticsEnabler();
24-
placeholder = desktopSemanticsEnabler.prepareAccessibilityPlaceholder();
24+
placeholder = desktopSemanticsEnabler.accessibilityPlaceholder;
2525
domDocument.body!.append(placeholder!);
2626
});
2727

@@ -94,6 +94,16 @@ void testMain() {
9494
},
9595
);
9696

97+
test('Can update placeholder label', () {
98+
const String testLabel = 'Test label for placeholder';
99+
desktopSemanticsEnabler.updatePlaceholderLabel(testLabel);
100+
expect(placeholder!.getAttribute('aria-label'), testLabel);
101+
102+
const String anotherLabel = 'Another label for placeholder';
103+
desktopSemanticsEnabler.dispose();
104+
expect(() => desktopSemanticsEnabler.updatePlaceholderLabel(anotherLabel), returnsNormally);
105+
});
106+
97107
test('disposes of the placeholder', () {
98108
domDocument.body!.append(placeholder!);
99109

@@ -112,7 +122,7 @@ void testMain() {
112122
setUp(() {
113123
EngineSemantics.instance.semanticsEnabled = false;
114124
mobileSemanticsEnabler = MobileSemanticsEnabler();
115-
placeholder = mobileSemanticsEnabler.prepareAccessibilityPlaceholder();
125+
placeholder = mobileSemanticsEnabler.accessibilityPlaceholder;
116126
domDocument.body!.append(placeholder!);
117127
});
118128

@@ -140,6 +150,16 @@ void testMain() {
140150
expect(shouldForwardToFramework, isTrue);
141151
});
142152

153+
test('Can update placeholder label', () {
154+
const String testLabel = 'Test label for placeholder';
155+
mobileSemanticsEnabler.updatePlaceholderLabel(testLabel);
156+
expect(placeholder!.getAttribute('aria-label'), testLabel);
157+
158+
const String anotherLabel = 'Another label for placeholder';
159+
mobileSemanticsEnabler.dispose();
160+
expect(() => mobileSemanticsEnabler.updatePlaceholderLabel(anotherLabel), returnsNormally);
161+
});
162+
143163
test('Enables semantics when receiving a relevant event', () {
144164
expect(mobileSemanticsEnabler.semanticsActivationTimer, isNull);
145165

@@ -183,7 +203,7 @@ class FakeSemanticsEnabler extends SemanticsEnabler {
183203
bool get isWaitingToEnableSemantics => true;
184204

185205
@override
186-
DomElement prepareAccessibilityPlaceholder() {
206+
void updatePlaceholderLabel(String message) {
187207
throw UnimplementedError();
188208
}
189209

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

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -850,7 +850,10 @@ class MockSemanticsEnabler implements SemanticsEnabler {
850850
bool get isWaitingToEnableSemantics => throw UnimplementedError();
851851

852852
@override
853-
DomElement prepareAccessibilityPlaceholder() {
853+
DomElement get accessibilityPlaceholder => throw UnimplementedError();
854+
855+
@override
856+
void updatePlaceholderLabel(String message) {
854857
throw UnimplementedError();
855858
}
856859

0 commit comments

Comments
 (0)