-
初始化 Web 无障碍访问（如适用） 对于 Web 目标，出于性能考虑，默认禁用无障碍访问。请在入口点强制启用它。
import 'package:flutter/foundation.dart';
import 'package:flutter/semantics.dart';
void main() {
runApp(const MyApp());
if (kIsWeb) {
SemanticsBinding.instance.ensureSemantics();
}
}
-
应用语义注解 使用 Semantics、MergeSemantics 和 ExcludeSemantics 来构建清晰的无障碍访问树。对于自定义 Web 组件，请显式定义 SemanticsRole。
Semantics(
role: SemanticsRole.button,
label: '提交表单',
hint: '按下以发送您的申请',
button: true,
child: GestureDetector(
onTap: _submit,
child: const CustomButtonUI(),
),
)
-
强制执行点击目标和对比度标准 确保所有交互元素满足 48x48 dp（Android）或 44x44 pt（iOS/Web）的最小尺寸要求。
// 强制执行最小点击目标尺寸的示例
ConstrainedBox(
constraints: const BoxConstraints(
minWidth: 48.0,
minHeight: 48.0,
),
child: IconButton(
icon: const Icon(Icons.info),
onPressed: () {},
tooltip: '信息', // Tooltip.message 在语义树中跟随 Tooltip.child
),
)
-
实现自适应布局 使用 LayoutBuilder 来响应可用空间，而不是设备类型。
LayoutBuilder(
builder: (context, constraints) {
if (constraints.maxWidth > 600) {
return const WideDesktopLayout();
} else {
return const NarrowMobileLayout();
}
},
)
-
实现键盘和鼠标支持 对于自定义控件，使用 FocusableActionDetector 来同时处理焦点、悬停和键盘快捷键。
FocusableActionDetector(
onFocusChange: (hasFocus) => setState(() => _hasFocus = hasFocus),
onShowHoverHighlight: (hasHover) => setState(() => _hasHover = hasHover),
actions: <Type, Action<Intent>>{
ActivateIntent: CallbackAction<Intent>(
onInvoke: (intent) {
_performAction();
return null;
},
),
},
child: MouseRegion(
cursor: SystemMouseCursors.click,
child: CustomWidget(isHovered: _hasHover, isFocused: _hasFocus),
),
)
-
管理焦点遍历 使用 FocusTraversalGroup 对相关小部件进行分组，以确保键盘用户有逻辑的 Tab 键顺序。
FocusTraversalGroup(
policy: OrderedTraversalPolicy(),
child: Column(
children: [
FocusTraversalOrder(
order: const NumericFocusOrder(1.0),
child: TextField(),
),
FocusTraversalOrder(
order: const NumericFocusOrder(2.0),
child: ElevatedButton(onPressed: () {}, child: Text('提交')),
),
],
),
)
-
通过自动化测试验证无障碍访问 请暂停并询问用户： "您是否希望我为您的 UI 生成小部件测试，以验证无障碍访问指南（对比度、点击目标）？" 如果是，请在测试套件中实现 AccessibilityGuideline API：
import 'package:flutter_test/flutter_test.dart';
void main() {
testWidgets('验证 a11y 指南', (WidgetTester tester) async {
final SemanticsHandle handle = tester.ensureSemantics();
await tester.pumpWidget(const MyApp());
await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
await expectLater(tester, meetsGuideline(textContrastGuideline));
handle.dispose();
});
}
