Skip to content

Commit 6cfc099

Browse files
Add some violations in a11y inspector (flutter#191994)
Make the traverse function in [_accessibility_evaluations.dart] public. Add violations in a11y inspector. tracking issue: flutter/devtools#9893 ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [ ] 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]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **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 [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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 --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
1 parent 876ebe4 commit 6cfc099

7 files changed

Lines changed: 394 additions & 54 deletions

‎packages/flutter/lib/src/widgets/_accessibility_evaluations.dart‎

Lines changed: 80 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
// found in the LICENSE file.
44

55
/// @docImport 'package:flutter/material.dart';
6+
///
7+
/// @docImport 'accessibility_inspector.dart';
8+
/// @docImport 'service_extensions.dart';
69
library;
710

811
import 'dart:async';
@@ -23,6 +26,50 @@ import 'title.dart';
2326
/// Flutter will make breaking changes to this API, even in patch versions.
2427
/// {@endtemplate}
2528
///
29+
/// Types of accessibility evaluations that can be performed on the semantics tree.
30+
///
31+
/// The `.name` of each enum value is used:
32+
/// * As the `type` parameter value in the
33+
/// [WidgetsServiceExtensions.accessibilityEvaluations] service extension.
34+
/// * As the `rule` field value in each issue map returned by the
35+
/// [AccessibilityServiceExtensions.getSemanticsTree] service extension.
36+
@internal
37+
enum AccessibilityEvaluationType {
38+
/// Enforces that all tappable semantics nodes have a minimum size.
39+
///
40+
/// Evaluated by [MinimumTapTargetEvaluation].
41+
minimumTapTarget,
42+
43+
/// Enforces that all nodes with a tap or long press action also have a label.
44+
///
45+
/// Evaluated by [LabeledTapTargetEvaluation].
46+
labeledTapTarget,
47+
48+
/// Enforces that all text nodes meet minimum color contrast levels.
49+
///
50+
/// Evaluated by [MinimumTextContrastEvaluation].
51+
minimumTextContrast,
52+
53+
/// Enforces that all nodes representing non-text controls meet minimum
54+
/// contrast levels.
55+
///
56+
/// Evaluated by [MinimumNonTextContrastEvaluation].
57+
minimumNonTextContrast,
58+
59+
/// Enforces that all leaf semantics nodes have a label, value, hint, or tooltip.
60+
///
61+
/// Evaluated by [UnlabeledLeafNodeEvaluation].
62+
unlabeledLeafNode,
63+
64+
/// Enforces that the application has at least one [Title] widget to set the
65+
/// web page title.
66+
///
67+
/// Evaluated by [TitleEvaluation].
68+
title,
69+
}
70+
71+
/// {@macro flutter.widgets.accessibility_evaluations.internal}
72+
///
2673
/// A violation of a semantics node.
2774
@internal
2875
class Violation {
@@ -56,6 +103,9 @@ abstract class AccessibilityEvaluation {
56103
/// A const constructor allows subclasses to be const.
57104
const AccessibilityEvaluation();
58105

106+
/// The type of this accessibility evaluation.
107+
AccessibilityEvaluationType get type;
108+
59109
/// Evaluate whether the current state of the `binding` conforms to the rule.
60110
FutureOr<EvaluationResult> evaluate(WidgetsBinding binding);
61111
}
@@ -79,13 +129,17 @@ class MinimumTapTargetEvaluation extends AccessibilityEvaluation {
79129
/// result in a smaller tap area.
80130
static const double _kMinimumGapToBoundary = 0.001;
81131

132+
@override
133+
AccessibilityEvaluationType get type => AccessibilityEvaluationType.minimumTapTarget;
134+
82135
@override
83136
FutureOr<EvaluationResult> evaluate(WidgetsBinding binding) {
84137
final violations = <Violation>[];
85138
for (final RenderView view in binding.renderViews) {
86-
violations.addAll(
87-
_traverse(view.flutterView, view.owner!.semanticsOwner!.rootSemanticsNode!),
88-
);
139+
final SemanticsNode? root = view.owner?.semanticsOwner?.rootSemanticsNode;
140+
if (root != null) {
141+
violations.addAll(_traverse(view.flutterView, root));
142+
}
89143
}
90144

91145
return EvaluationResult(violations);
@@ -178,12 +232,18 @@ class MinimumTapTargetEvaluation extends AccessibilityEvaluation {
178232
class LabeledTapTargetEvaluation extends AccessibilityEvaluation {
179233
const LabeledTapTargetEvaluation();
180234

235+
@override
236+
AccessibilityEvaluationType get type => AccessibilityEvaluationType.labeledTapTarget;
237+
181238
@override
182239
FutureOr<EvaluationResult> evaluate(WidgetsBinding binding) {
183240
final violations = <Violation>[];
184241

185242
for (final RenderView view in binding.renderViews) {
186-
violations.addAll(_traverse(view.owner!.semanticsOwner!.rootSemanticsNode!));
243+
final SemanticsNode? root = view.owner?.semanticsOwner?.rootSemanticsNode;
244+
if (root != null) {
245+
violations.addAll(_traverse(root));
246+
}
187247
}
188248

189249
return EvaluationResult(violations);
@@ -351,6 +411,9 @@ class MinimumTextContrastEvaluation extends _ContrastEvaluation {
351411

352412
static const double _kDefaultFontSize = 12.0;
353413

414+
@override
415+
AccessibilityEvaluationType get type => AccessibilityEvaluationType.minimumTextContrast;
416+
354417
@override
355418
bool _shouldSkipNodeEvaluation(SemanticsData data) =>
356419
data.flagsCollection.scopesRoute || (data.label.trim().isEmpty && data.value.trim().isEmpty);
@@ -508,6 +571,9 @@ class MinimumNonTextContrastEvaluation extends _ContrastEvaluation {
508571
/// Defined by http://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html
509572
static const double _kMinimumRatioNonText = 3.0;
510573

574+
@override
575+
AccessibilityEvaluationType get type => AccessibilityEvaluationType.minimumNonTextContrast;
576+
511577
@override
512578
bool _shouldSkipNodeEvaluation(SemanticsData data) {
513579
if (data.flagsCollection.scopesRoute) {
@@ -763,11 +829,17 @@ bool _isImportantForAccessibility(SemanticsNode node) {
763829
class UnlabeledLeafNodeEvaluation extends AccessibilityEvaluation {
764830
const UnlabeledLeafNodeEvaluation();
765831

832+
@override
833+
AccessibilityEvaluationType get type => AccessibilityEvaluationType.unlabeledLeafNode;
834+
766835
@override
767836
FutureOr<EvaluationResult> evaluate(WidgetsBinding binding) {
768837
final violations = <Violation>[];
769838
for (final RenderView view in binding.renderViews) {
770-
violations.addAll(_traverse(view.owner!.semanticsOwner!.rootSemanticsNode!));
839+
final SemanticsNode? root = view.owner?.semanticsOwner?.rootSemanticsNode;
840+
if (root != null) {
841+
violations.addAll(_traverse(root));
842+
}
771843
}
772844
return EvaluationResult(violations);
773845
}
@@ -821,6 +893,9 @@ class TitleEvaluation extends AccessibilityEvaluation {
821893
/// Create a new [TitleEvaluation].
822894
const TitleEvaluation();
823895

896+
@override
897+
AccessibilityEvaluationType get type => AccessibilityEvaluationType.title;
898+
824899
@override
825900
FutureOr<EvaluationResult> evaluate(WidgetsBinding binding) {
826901
final violations = <Violation>[];

‎packages/flutter/lib/src/widgets/accessibility_inspector.dart‎

Lines changed: 111 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,38 @@
55
import 'package:flutter/foundation.dart';
66
import 'package:flutter/rendering.dart';
77

8+
import '_accessibility_evaluations.dart';
9+
import 'binding.dart';
810
import 'service_extensions.dart';
911

12+
/// Response map keys used by the [AccessibilityServiceExtensions.getSemanticsTree]
13+
/// service extension in [AccessibilityInspector].
14+
abstract final class AccessibilityInspectorKeys {
15+
/// Top-level response map key containing the map of semantics node IDs to
16+
/// serialized [SemanticsNode] entries (from [SemanticsNode.toJson]).
17+
static const String data = 'data';
18+
19+
/// Top-level response map key containing an error message if the semantics
20+
/// tree could not be retrieved.
21+
static const String error = 'error';
22+
23+
/// Top-level response map key containing the list of accessibility issue maps
24+
/// detected in the application.
25+
static const String issues = 'issues';
26+
27+
/// Issue map key containing the ID of the [SemanticsNode] associated with the
28+
/// issue.
29+
static const String nodeId = 'nodeId';
30+
31+
/// Issue map key containing the [AccessibilityEvaluationType] `.name` of the
32+
/// violated accessibility rule.
33+
static const String rule = 'rule';
34+
35+
/// Issue map key containing the human-readable [Violation.reason] describing
36+
/// why the rule was violated.
37+
static const String description = 'description';
38+
}
39+
1040
/// Service that handles accessibility and semantics inspection.
1141
class AccessibilityInspector {
1242
AccessibilityInspector._();
@@ -25,6 +55,10 @@ class AccessibilityInspector {
2555
name: AccessibilityServiceExtensions.getSemanticsTree.extensionName,
2656
callback: _getSemanticsTree,
2757
);
58+
registerServiceExtension(
59+
name: AccessibilityServiceExtensions.getIssuesAndSemanticsTree.extensionName,
60+
callback: _getIssuesAndSemanticsTree,
61+
);
2862
registerServiceExtension(
2963
name: AccessibilityServiceExtensions.enableSemantics.extensionName,
3064
callback: _enableSemantics,
@@ -59,22 +93,28 @@ class AccessibilityInspector {
5993
return <String, Object?>{};
6094
}
6195

62-
/// Evaluates and returns the semantics tree hierarchy of the application.
63-
Future<Map<String, Object?>> _getSemanticsTree(Map<String, String> parameters) async {
96+
(SemanticsOwner, SemanticsNode)? _getSemanticsOwnerAndRoot(Map<String, Object?> errorMap) {
6497
if (!SemanticsBinding.instance.semanticsEnabled) {
65-
return <String, Object?>{'error': 'Semantics not enabled.'};
98+
errorMap[AccessibilityInspectorKeys.error] = 'Semantics not enabled.';
99+
return null;
66100
}
67-
final PipelineOwner? pipelineOwner = _findPipelineOwner();
101+
final RenderView? renderView = _findRenderView();
102+
final PipelineOwner? pipelineOwner = renderView?.owner;
68103
final SemanticsOwner? semanticsOwner = pipelineOwner?.semanticsOwner;
69-
if (semanticsOwner == null) {
70-
return <String, Object?>{'error': 'No PipelineOwner with SemanticsOwner found'};
104+
if (renderView == null || semanticsOwner == null) {
105+
errorMap[AccessibilityInspectorKeys.error] = 'No PipelineOwner with SemanticsOwner found';
106+
return null;
71107
}
72108
final SemanticsNode? root = semanticsOwner.rootSemanticsNode;
73109
if (root == null) {
74110
RendererBinding.instance.ensureVisualUpdate();
75-
return <String, Object?>{'error': 'rootSemanticsNode is null', 'needsFrame': true};
111+
errorMap[AccessibilityInspectorKeys.error] = 'rootSemanticsNode is null, needs a frame.';
112+
return null;
76113
}
114+
return (semanticsOwner, root);
115+
}
77116

117+
Map<String, Object?> _buildSemanticsNodes(SemanticsNode root) {
78118
final nodes = <String, Object?>{};
79119
final visited = <int>{};
80120
final queue = <SemanticsNode>[root];
@@ -83,7 +123,9 @@ class AccessibilityInspector {
83123
if (!visited.add(node.id)) {
84124
continue;
85125
}
126+
86127
nodes[node.id.toString()] = node.toJson();
128+
87129
for (final SemanticsNode child in node.debugListChildrenInOrder(
88130
DebugSemanticsDumpOrder.traversalOrder,
89131
)) {
@@ -99,23 +141,77 @@ class AccessibilityInspector {
99141
}
100142
}
101143
}
144+
return nodes;
145+
}
102146

103-
return <String, Object?>{'data': nodes};
147+
/// Returns the semantics tree hierarchy of the application.
148+
Future<Map<String, Object?>> _getSemanticsTree(Map<String, String> parameters) async {
149+
final errorMap = <String, Object?>{};
150+
final (SemanticsOwner, SemanticsNode)? result = _getSemanticsOwnerAndRoot(errorMap);
151+
if (result == null) {
152+
return errorMap;
153+
}
154+
final (SemanticsOwner _, SemanticsNode root) = result;
155+
156+
return <String, Object?>{AccessibilityInspectorKeys.data: _buildSemanticsNodes(root)};
157+
}
158+
159+
/// Evaluates accessibility rules and returns detected issues along with the
160+
/// semantics tree hierarchy from the same frame.
161+
Future<Map<String, Object?>> _getIssuesAndSemanticsTree(Map<String, String> parameters) async {
162+
final errorMap = <String, Object?>{};
163+
final (SemanticsOwner, SemanticsNode)? ownerAndRoot = _getSemanticsOwnerAndRoot(errorMap);
164+
if (ownerAndRoot == null) {
165+
return errorMap;
166+
}
167+
final (SemanticsOwner semanticsOwner, SemanticsNode root) = ownerAndRoot;
168+
169+
// The violations are displayed in Devtool.
170+
// TODO(hannah-hyj): If we add a "target platforms" option on the devtool side,
171+
// we can display violations for both iOS/android standards
172+
// regardless of the testing device platform.
173+
final Size minSize = switch (defaultTargetPlatform) {
174+
TargetPlatform.android => const Size(48.0, 48.0),
175+
TargetPlatform.iOS || TargetPlatform.macOS => const Size(44.0, 44.0),
176+
_ => const Size(48.0, 48.0),
177+
};
178+
179+
final issues = <Map<String, Object?>>[];
180+
181+
final evaluations = <AccessibilityEvaluation>[
182+
MinimumTapTargetEvaluation(size: minSize),
183+
const LabeledTapTargetEvaluation(),
184+
const UnlabeledLeafNodeEvaluation(),
185+
];
186+
187+
for (final evaluation in evaluations) {
188+
final EvaluationResult result = await evaluation.evaluate(WidgetsBinding.instance);
189+
for (final Violation violation in result.violations) {
190+
if (violation.node.owner == semanticsOwner) {
191+
issues.add(<String, Object?>{
192+
AccessibilityInspectorKeys.nodeId: violation.node.id,
193+
AccessibilityInspectorKeys.rule: evaluation.type.name,
194+
AccessibilityInspectorKeys.description: violation.reason,
195+
});
196+
}
197+
}
198+
}
199+
200+
return <String, Object?>{
201+
AccessibilityInspectorKeys.data: _buildSemanticsNodes(root),
202+
AccessibilityInspectorKeys.issues: issues,
203+
};
104204
}
105205

106-
// TODO(hannahjin): This returns the first SemanticsOwner of any RenderView.
206+
// TODO(hannah-hyj): https://github.com/flutter/devtools/issues/9991 - This returns the first RenderView with a SemanticsOwner.
107207
// This getSemanticsTree feature is used in DevTools, which currently only supports
108208
// single-view inspection. Add multi-view support when DevTools needs it.
109-
PipelineOwner? _findPipelineOwner() {
209+
RenderView? _findRenderView() {
110210
for (final RenderView renderView in RendererBinding.instance.renderViews) {
111211
if (renderView.owner?.semanticsOwner != null) {
112-
return renderView.owner;
212+
return renderView;
113213
}
114214
}
115-
final PipelineOwner deprecatedOwner = RendererBinding.instance.pipelineOwner;
116-
if (deprecatedOwner.semanticsOwner != null) {
117-
return deprecatedOwner;
118-
}
119215
return null;
120216
}
121217
}

‎packages/flutter/lib/src/widgets/binding.dart‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -764,8 +764,12 @@ mixin WidgetsBinding
764764
throw Exception('type parameter is required');
765765
}
766766

767-
switch (type) {
768-
case 'MinimumTextContrastEvaluation':
767+
final AccessibilityEvaluationType? evaluationType = AccessibilityEvaluationType.values
768+
.where((AccessibilityEvaluationType e) => e.name == type)
769+
.firstOrNull;
770+
771+
switch (evaluationType) {
772+
case AccessibilityEvaluationType.minimumTextContrast:
769773
if (parameters case {
770774
'minNormalTextContrastRatio': final String minNormalTextContrastRatio,
771775
'minLargeTextContrastRatio': final String minLargeTextContrastRatio,
@@ -777,20 +781,23 @@ mixin WidgetsBinding
777781
return _formatEvaluationResult(result.violations);
778782
}
779783
throw Exception('Invalid arguments');
780-
case 'MinimumTapTargetEvaluation':
784+
case AccessibilityEvaluationType.minimumTapTarget:
781785
if (parameters case {'targetSize': final String targetSize}) {
782786
final EvaluationResult result = await MinimumTapTargetEvaluation(
783787
size: Size.square(double.parse(targetSize)),
784788
).evaluate(this);
785789
return _formatEvaluationResult(result.violations);
786790
}
787791
throw Exception('Invalid arguments');
788-
case 'LabeledTapTargetEvaluation':
792+
case AccessibilityEvaluationType.labeledTapTarget:
789793
final EvaluationResult result = await const LabeledTapTargetEvaluation().evaluate(
790794
this,
791795
);
792796
return _formatEvaluationResult(result.violations);
793-
default:
797+
case AccessibilityEvaluationType.minimumNonTextContrast:
798+
case AccessibilityEvaluationType.unlabeledLeafNode:
799+
case AccessibilityEvaluationType.title:
800+
case null:
794801
throw Exception('unknown type: $type');
795802
}
796803
},

0 commit comments

Comments
 (0)