Flutter 无障碍可访问性：语义、屏幕阅读器与导航

// 内置组件大多自带语义
IconButton(
  icon: const Icon(Icons.add),
  onPressed: _add,               // 自动成为按钮语义
  tooltip: '添加商品',            // 自动成为读屏 label
)

// 自定义语义
Semantics(
  label: '订单状态：已发货',
  hint: '双击查看物流详情',
  button: true,                 // 声明这是按钮
  child: MyCustomBadge(),        // 自定义控件，无内置语义
)

// 合并装饰性图标，避免读屏逐个朗读
Semantics(
  label: '购物车中有 3 件商品',
  child: Badge(
    label: const Text('3'),
    child: const Icon(Icons.shopping_cart),
  ),
)

// 隐藏纯装饰元素
Semantics(
  excludeSemantics: true,
  child: const Divider(), // 分隔线无需朗读
)

// 自定义朗读顺序
Semantics(
  sortKey: const OrdinalSortKey(1),
  child: const Text('商品名称'),
),
Semantics(
  sortKey: const OrdinalSortKey(2),
  child: const Text('价格 ¥99'),
),

// 让自定义控件可聚焦
Focus(
  onFocusChange: (focused) => setState(() => _focused = focused),
  child: InkWell(
    onTap: _handleTap,
    child: Container(
      decoration: BoxDecoration(
        border: Border.all(
          color: _focused ? Colors.blue : Colors.grey,
          width: 2,
        ),
      ),
      child: const Text('可聚焦的自定义卡片'),
    ),
  ),
)

// 表单校验失败时，把焦点移到第一个错误字段
final _errorFocus = FocusNode();

void _validate() {
  final ok = _formKey.currentState!.validate();
  if (!ok) {
    _errorFocus.requestFocus(); // 读屏/键盘用户立即感知错误位置
  }
}

TextField(
  focusNode: _errorFocus,
  decoration: const InputDecoration(labelText: '邮箱', errorText: '邮箱格式错误'),
)

// 检查对比度的工具函数（示意）
double contrastRatio(Color a, Color b) {
  double luminance(Color c) {
    double lum(double v) =>
        v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055).pow(2.4) as double;
    return 0.2126 * lum(a.red / 255) +
        0.7152 * lum(a.green / 255) +
        0.0722 * lum(a.blue / 255);
  }
  final l1 = luminance(a), l2 = luminance(b);
  final hi = l1 > l2 ? l1 : l2;
  final lo = l1 > l2 ? l2 : l1;
  return (hi + 0.05) / (lo + 0.05);
}

// 允许文本随系统字号缩放，并保证布局自适应
Text(
  '重要提示',
  style: const TextStyle(fontSize: 16),
  // 不设置 textScaleFactor → 跟随系统缩放
)

// 大字号下布局仍不溢出的策略：
// 1. 用 Flex（Row/Column）而非固定宽度
// 2. 用 FittedBox 兜底（但不建议过度使用）
// 3. 用 MediaQuery.textScalerOf(context) 做精细控制
final textScaler = MediaQuery.textScalerOf(context);
final scaledFont = textScaler.scale(16);

// 读取用户无障碍偏好，主动适配
final mediaQuery = MediaQuery.of(context);
final textScale = mediaQuery.textScaler.scale(16); // 实际字号
final boldText = mediaQuery.boldTextOverride;       // 加粗设置
final highContrast = mediaQuery.highContrast;       // 高对比设置

import 'package:flutter/rendering.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('按钮有正确的语义标签', (tester) async {
    await tester.pumpWidget(
      MaterialApp(
        home: Scaffold(
          body: IconButton(
            icon: const Icon(Icons.delete),
            tooltip: '删除',
            onPressed: () {},
          ),
        ),
      ),
    );

    // 找到语义节点并断言 label
    final semantics = tester.getSemantics(find.byType(IconButton));
    expect(semantics.label, '删除');
    expect(semantics.hasFlag(SemanticsFlag.isButton), isTrue);
  });
}

// 启用语义后测试（读屏模式下）
await tester.binding.setSurfaceSize(const Size(400, 800));
final handle = tester.ensureSemantics();
// 执行交互并断言语义
await handle.dispose();

// 在开发模式打印整棵语义树
void debugPrintSemantics(BuildContext context) {
  final semantics = SemanticsBinding.instance;
  // 使用 debugSemanticsDump 类工具或 DevTools 查看
  debugPrint(SemanticsBinding.instance.debugSemanticsDebugInfo.toString());
}

// 全局开启语义（模拟读屏环境）
SemanticsBinding.instance.ensureSemantics();

// 自查清单（开发时对照）
class A11yChecklist {
  static const checks = [
    '所有可点击元素有语义 label',
    '图标按钮都有 tooltip',
    '装饰元素已隐藏语义',
    '对比度 ≥ 4.5:1（正文）',
    '大字号下布局不溢出',
    '键盘可完整操作核心流程',
    '错误提示伴随焦点定位',
  ];
}