Flutter Mobile Development · 课时

语义、屏幕阅读器与无障碍组件

使用 Semantics API 为组件添加语义标注，支持 TalkBack 和 VoiceOver 用户。

语义、屏幕阅读器与无障碍组件 是 CoddyKit 上的免费 Flutter Mobile Development 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Flutter Mobile Development 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Flutter Mobile Development 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Accessibility Matters

Millions of people rely on screen readers to use mobile apps. On Android the screen reader is TalkBack; on iOS it is VoiceOver. When enabled, the user swipes between elements and the phone speaks a description of each one out loud.

Flutter does not draw native widgets, so the OS cannot inspect your UI directly. Instead, Flutter builds a parallel semantics tree describing each element (its label, role, and state) and hands it to the platform's accessibility services.

Good news: many built-in widgets (Text, ElevatedButton, Checkbox) already populate this tree automatically.
Your job: fix the cases where the automatic description is missing, wrong, or confusing.

The Semantics Tree

Every visible widget can contribute a SemanticsNode to a tree that mirrors your widget tree. Each node carries properties such as label, value, hint, and flags like isButton or isChecked.

You rarely build this tree by hand. Instead you annotate widgets using the Semantics widget or the convenience properties exposed by existing widgets (for example Image's semanticLabel).

The screen reader reads nodes in roughly top-to-bottom, left-to-right order.
You can merge several widgets into one spoken node, or exclude purely decorative widgets entirely.

The Semantics Widget

The core tool is the Semantics widget. Wrap any widget with it and supply the properties the screen reader should announce.

Here an icon-only button has no visible text, so without a label TalkBack would just say "button". Adding label makes it meaningful.

label — what the element is ("Delete item").
button: true — marks the node as tappable so the reader says "Delete item, button".

Semantics(
  label: 'Delete item',
  button: true,
  child: IconButton(
    icon: const Icon(Icons.delete),
    onPressed: _deleteItem,
  ),
)

Labeling Images and Icons

Images and icons are the most common accessibility gap: visually they convey meaning, but they carry no text. Provide a semanticLabel so the description is spoken.

If an image is purely decorative (adds no information), set excludeFromSemantics: true so the reader skips it instead of announcing a filename or "image".

Column(
  children: [
    // Meaningful image: describe it
    Image.asset(
      'assets/profile.png',
      semanticLabel: 'Profile photo of Ada Lovelace',
    ),
    // Decorative divider image: skip it
    Image.asset(
      'assets/flourish.png',
      excludeFromSemantics: true,
    ),
  ],
)

label, value, and hint

Three properties handle most situations, and they are not interchangeable:

label — the identity of the control ("Volume").
value — its current state ("70 percent").
hint — what happens on interaction ("Adjust to change volume").

A screen reader typically announces them as: label, value, hint. Keeping state in value (not baked into label) lets the reader re-announce only the changing part when the user interacts.

Semantics(
  label: 'Volume',
  value: '$volumePercent percent',
  hint: 'Swipe up or down to adjust',
  slider: true,
  child: VolumeSlider(value: volumePercent),
)

Merging Semantics

A card might contain an avatar, a name, and a subtitle as three separate widgets. By default the screen reader stops on each one, forcing three swipes for one logical item.

Wrap them in MergeSemantics to combine their descriptions into a single node. The reader then announces them together: "Ada Lovelace, Online".

Use merging when several widgets form one conceptual element. Do not merge unrelated controls, since merging also hides their individual interactions.

MergeSemantics(
  child: Row(
    children: const [
      CircleAvatar(child: Text('A')),
      SizedBox(width: 8),
      Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        children: [
          Text('Ada Lovelace'),
          Text('Online'),
        ],
      ),
    ],
  ),
)

Excluding Decorative Widgets

Sometimes a widget produces noise: a redundant decorative icon next to text, or a background graphic. Wrap it in ExcludeSemantics to drop it (and its subtree) from the semantics tree.

Here the chevron icon is purely visual; the row's text already tells the user everything, so we exclude the icon to avoid "chevron right" clutter.

Row(
  children: [
    const Text('Account settings'),
    const Spacer(),
    ExcludeSemantics(
      child: const Icon(Icons.chevron_right),
    ),
  ],
)

Live Announcements

Some changes are not tied to a focused widget — for example "Message sent" after a network call. To speak these immediately, use SemanticsService.announce.

Pass the message and the current TextDirection (so right-to-left languages are handled correctly). Use this sparingly; too many announcements overwhelm the user.

import 'package:flutter/semantics.dart';

Future<void> _onSendComplete(BuildContext context) async {
  await SemanticsService.announce(
    'Message sent',
    Directionality.of(context),
  );
}

Touch Target Size

Accessibility is not only about screen readers. People with motor difficulties need targets large enough to tap reliably. The recommended minimum is roughly 48 x 48 logical pixels (matching Material's kMinInteractiveDimension).

Wrapping a small control with a tight SizedBox can shrink its hit area. Prefer IconButton (which enforces a minimum) or expand the target explicitly.

// Guarantee a comfortable tap target
ConstrainedBox(
  constraints: const BoxConstraints(
    minWidth: kMinInteractiveDimension,
    minHeight: kMinInteractiveDimension,
  ),
  child: InkWell(
    onTap: _toggleFavorite,
    child: const Icon(Icons.favorite_border),
  ),
)

Building Accessible Labels in Dart

Labels are just strings, so you often build them with plain Dart logic before passing them to Semantics. Keeping this logic in a pure function makes it easy to test without any UI.

The snippet below is standalone Dart: it formats a button's accessible label from its state. Notice how the label describes identity while a separate state word communicates the current value clearly.

String favoriteLabel({required bool isFavorited, required String title}) {
  final action = isFavorited ? 'Remove from favorites' : 'Add to favorites';
  return '$action: $title';
}

void main() {
  print(favoriteLabel(isFavorited: false, title: 'Dart Basics'));
  print(favoriteLabel(isFavorited: true, title: 'Dart Basics'));
}

Testing Your Semantics

You do not have to guess what the screen reader will say. Flutter offers several ways to verify:

Turn on TalkBack or VoiceOver on a real device and swipe through your screen.
Use the Accessibility Inspector in DevTools to view the live semantics tree.
Write widget tests with the SemanticsTester / matchesSemantics matcher to assert labels and flags.

Flutter also ships accessibility guideline checks you can run in tests, such as minimum tap-target size and text contrast.

testWidgets('delete button is labeled', (tester) async {
  await tester.pumpWidget(const MyApp());
  expect(
    tester.getSemantics(find.byIcon(Icons.delete)),
    matchesSemantics(label: 'Delete item', isButton: true),
  );
});

Quick Check

You have an icon-only IconButton showing a trash can. With TalkBack enabled, users only hear "button" and cannot tell what it does. What is the most appropriate fix?

Recap

You learned how to make Flutter widgets usable with TalkBack and VoiceOver:

Flutter builds a semantics tree from your widgets; built-ins fill it in, but icons and images often need help.
Use the Semantics widget with label (identity), value (state), and hint (interaction).
Give images a semanticLabel, or set excludeFromSemantics: true when decorative.
MergeSemantics combines several widgets into one spoken node; ExcludeSemantics removes noise.
Announce dynamic events with SemanticsService.announce, and keep tap targets at least 48 x 48.
Verify with TalkBack/VoiceOver, the DevTools Accessibility Inspector, and matchesSemantics in widget tests.

Accessible apps reach more users and are simply better engineered.

常见问题解答

「语义、屏幕阅读器与无障碍组件」课时是免费的吗？

是的 — 「语义、屏幕阅读器与无障碍组件」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Flutter Mobile Development 课程的其余内容，请升级到 CoddyKit PRO。 Flutter Mobile Development 课程共包含 4 节课。

「语义、屏幕阅读器与无障碍组件」这节课中我会学到什么？

使用 Semantics API 为组件添加语义标注，支持 TalkBack 和 VoiceOver 用户。你通过在浏览器中直接运行的动手代码来练习 Flutter Mobile Development，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Flutter Mobile Development 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Flutter Mobile Development 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「语义、屏幕阅读器与无障碍组件」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Flutter Mobile Development 课中编写并运行代码吗？

能。每节 Flutter Mobile Development 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Flutter Mobile Development