📚 课程目录第4章角色与语义

4. 角色与语义：role修饰符与常见角色类型

4.1 原理：语义化的无障碍角色

在 Android 无障碍体系中，每个可交互的界面元素都应向辅助服务（如 TalkBack）声明自身“是什么”——即语义角色（Role）。Jetpack Compose 提供 Modifier.semantics 和专用的 Modifier.clearAndSetSemantics 来赋予或覆盖无障碍属性，而 role 是其中最关键的一个字段。它为无障碍框架提供抽象的组件类型，使辅助服务能正确生成焦点提示、操作手势（如双击、长按）及状态播报。

Compose 的 Role 枚举定义了一组标准角色：

Role 常量	语义说明	典型系统组件	无障碍操作映射
`Role.Button`	可点击按钮	Button, OutlinedButton	单击触发 onClick，TalkBack 播报“按钮”
`Role.Image`	静态图像	Image, Icon	通常无操作，TalkBack 直接朗读 contentDescription
`Role.Checkbox`	复选框（双态/三态）	Checkbox, TriStateCheckbox	切换选中状态，播报“已选中/未选中”
`Role.RadioButton`	单选按钮	RadioButton	选中后不可手动取消，播报“已选中”
`Role.Switch`	开关（打开/关闭）	Switch	滑动切换，播报“打开/关闭”
`Role.DropdownList`	下拉列表（展开状态）	ExposedDropdownMenuBox	展开/收起，播报“下拉列表”
`Role.Tab`	标签页	Tab, TabRow	水平切换，播报“标签”
`Role.ProgressBar`	进度指示器	LinearProgressIndicator	播报进度百分比

当自定义组件未指定角色时，Compose 默认根据交互逻辑推断（如带 onClick 的可点击元素默认被视为 Button），但推断结果可能不准确。显式设置 role 能确保语义一致，避免辅助服务误判。

4.2 role 修饰符的实现流程

确定组件的语义类型（单选、复选、按钮、图像等）。
在 Modifier.semantics 或 Modifier.clearAndSetSemantics 块内，通过 role = Role.Button 等方式赋值。
同时补充必要的属性如 contentDescription、stateDescription、onClick（动作）。
使用无障碍测试工具（如 Accessibility Scanner 或 TalkBack 真人测试）验证播报内容。

以下是自定义按钮组件显式设置角色与操作的典型代码：

@Composable
fun AccessibleButton(
    text: String,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    Box(
        modifier = modifier
            .semantics {
                role = Role.Button
                contentDescription = text
                onClick { onClick(); true }
            }
            .clickable(onClick = onClick)
            .background(Color(0xFF3498DB))
            .padding(16.dp),
        contentAlignment = Alignment.Center
    ) {
        Text(text, color = Color.White)
    }
}

注意：semantics 块中的 onClick 与视图层的 clickable 并存。前者只用于无障碍事件（返回 Boolean 表示是否已处理），后者驱动实际的点击逻辑。两者必须保持同步，否则 TalkBack 会播报“按钮”但双击无响应。

4.3 自定义 Image 组件的角色设置

纯装饰性图像应设置 role = Role.Image 且 contentDescription = null（或空字符串），辅助服务会跳过朗读。但若图像是功能性图标（如“返回”图标），则必须赋予 Role.Button 并补充描述。

@Composable
fun IconButton(
    icon: ImageVector,
    description: String,
    onClick: () -> Unit
) {
    Icon(
        imageVector = icon,
        contentDescription = description,
        modifier = Modifier
            .semantics {
                role = Role.Button
                // contentDescription 已在 Icon 中设置，此块可省略
            }
            .clickable(onClick = onClick)
    )
}

4.4 调试：验证角色是否生效

开启手机“无障碍” → “无障碍菜单” → “TalkBack”，然后检查自定义组件。或使用 adb 命令直接 dump 视图树的无障碍信息：

adb shell dumpsys accessibility
# 或针对特定窗口
adb shell settings put secure accessibility_enabled 1
adb shell uiautomator events

更推荐使用 Accessibility Scanner 应用（Google Play 可下载）。安装后选择“扫描”，它会高亮显示所有无障碍违规项，包括缺失的 role、不正确的标签、可点击元素尺寸不足等。

常见错误1： 为纯装饰图像设置了 role = Role.Button，导致 TalkBack 提示“双击激活”，但实际并无点击逻辑，使用户困惑。

正确做法： 装饰图只需 contentDescription = null 且不设 role（默认为 None）。

提示： Modifier.clearAndSetSemantics 会清除父级所有语义属性后只保留块内定义的内容。当自定义组件继承某个已具语义的父组合项时，使用它能避免角色冲突。

4.5 常见错误与性能稳定性

角色与行为不匹配：例如将可滑动的滑块设为 Role.Button，TalkBack 会给出错误手势提示。应使用 Role.Slider（新版 Compose 1.5+ 已内置）。
重复设置 role：若父组件已经定义了 role，子组件再次 set 可能导致覆盖混乱。推荐在组合的最内层语义块中唯一一次赋值。
性能：role 本身只是一个 Int 字段，写入开销为纳秒级。不会引起测量或布局重排。但频繁重组时，应保持 semantics 块引用稳定（使用 remember 缓存 lambda），避免产生新的 SemanticsPropertyReceiver 实例。

4.6 角色映射关系内联 SVG

下图展示了自定义组件设置语义角色后，辅助服务如何识别并给出对应交互反馈：

4.7 总结

显式设置 role 是 Compose 自定义组件无障碍化的基础一步，它直接决定了辅助服务对组件的分类和操作提示。正确映射角色类型可以提升屏幕阅读效率，减少用户困惑。在组合使用 semantics 块时，务必同步视图逻辑与无障碍声明，并通过工具反复验证。