Switch

本文档整理 Jetpack Compose 中 Switch 组件的常用 API、样式定制、典型用法与可访问性建议，并给出多个示例（基础、带标签、禁用、自定义颜色、设置列表中的用法）。

概览

• Switch：用于在两种状态之间切换（开/关）。通常用于设置或立即生效的布尔选项。
• SwitchDefaults：提供默认颜色与尺寸辅助函数，例如 colors()。

常用参数

• checked: Boolean：当前选中（开启）状态。
• onCheckedChange: (Boolean) -> Unit：切换回调。
• enabled: Boolean：是否可交互（禁用时视觉变暗且不可触发）。
• modifier: Modifier：布局、padding、点击目标等。
• colors: SwitchColors：自定义 humb 与 rack 的颜色，使用 SwitchDefaults.colors(checkedThumbColor=..., checkedTrackColor=..., uncheckedThumbColor=..., uncheckedTrackColor=...)。
• interactionSource: MutableInteractionSource：监听按下/悬停/聚焦等交互。

可访问性与语义

• Switch 本身应与描述文本一起使用；屏幕阅读器通常会先读到文本。
• 对于需要明确语义的场景，使用 Modifier.toggleable(...) 或 Modifier.semantics{}：

Modifier.toggleable(
    value = checked,
    onValueChange = onCheckedChange,
    role = Role.Switch
)

oggleable 会为无障碍服务添加合适的状态与行为。

示例：基础 Switch

@Composable
fun BasicSwitch() {
    var checked by remember { mutableStateOf(false) }
    Switch(checked = checked, onCheckedChange = { checked = it })
}

示例：带标签的可点击整行

将 Switch 和 Text 放在 Row 并为整行添加 Modifier.toggleable，可扩大点击目标并提供可访问性语义：

@Composable
fun LabeledSwitch(label: String) {
    var checked by remember { mutableStateOf(false) }
    Row(
        modifier = Modifier
            .fillMaxWidth()
            .toggleable(
                value = checked,
                onValueChange = { checked = it },
                role = Role.Switch
            )
            .padding(12.dp),
        verticalAlignment = Alignment.CenterVertically
    ) {
        Text(label, modifier = Modifier.weight(1f))
        Switch(checked = checked, onCheckedChange = null) // onValueChange 已由 Row 的 toggleable 处理
    }
}

示例：禁用状态

Switch(checked = false, onCheckedChange = {}, enabled = false)

自定义颜色

@Composable
fun ColoredSwitch() {
    var checked by remember { mutableStateOf(true) }
    Switch(
        checked = checked,
        onCheckedChange = { checked = it },
        colors = SwitchDefaults.colors(
            checkedThumbColor = Color.White,
            checkedTrackColor = Color(0xFF4CAF50),
            uncheckedThumbColor = Color.White,
            uncheckedTrackColor = Color.Gray,
            disabledCheckedTrackColor = Color(0x884CAF50)
        )
    )
}

在设置列表或表单中的用法

@Composable
fun SettingsList(items: List<Pair<String, Boolean>>) {
    val state = remember { items.toMutableStateList() }
    LazyColumn {
        itemsIndexed(state) { index, item ->
            val (label, checked) = item
            Row(
                modifier = Modifier
                    .fillMaxWidth()
                    .clickable { state[index] = label to !checked }
                    .padding(12.dp),
                verticalAlignment = Alignment.CenterVertically
            ) {
                Text(label, modifier = Modifier.weight(1f))
                Switch(
                    checked = checked,
                    onCheckedChange = { state[index] = label to it }
                )
            }
        }
    }
}

注意：将状态提升到 ViewModel 可在应用重组或配置更改后保持一致性。

交互细节与提示

• 使用 interactionSource 可以监听按下/释放并做交互动画或逻辑。
• 若希望自定义涟漪或焦点效果，结合 indication 与 ocusable() 使用。

Material3 注意

• 在 Material3 中颜色命名或默认值可能不同（参见 ndroidx.compose.material3 的 Switch 文档与 SwitchDefaults）。

性能与最佳实践

• 在长列表中使用 LazyColumn 并把状态放在外部集合或 ViewModel，避免在每项中创建独立复杂状态。
• 使用
  emember 缓存复杂 painter/资源（Switch 本身不常用 painter，但在自定义组件中有用）。

小结（速查）

• 组件：Switch
• 关键参数：checked、onCheckedChange、enabled、colors、interactionSource、modifier
• 常用模式：Row + toggleable（扩大点击区域并提供语义）、状态提升、在列表中使用 LazyColumn
• 可访问性：为必要时添加语义，优先使用 oggleable/selectable 来自动注入无障碍信息

如需，我可以把这些示例整理为带 @Preview 的可运行 Kotlin 文件并加入示例模块。

@Composable
fun SwitchComponents() {

    val checkedState = remember {
        mutableStateOf(false)
    }

    val bgColor = remember {
        mutableStateOf(Color.White)
    }

    Column(
        modifier = Modifier
            .fillMaxSize()
            .background(bgColor.value),
    ) {
        Row(
            modifier = Modifier
                .fillMaxWidth()
                .padding(16.dp),
            verticalAlignment = Alignment.CenterVertically
        ) {
            Text(
                text = "Switch",
                style = TextStyle(
                    color = Color.Red,
                    fontSize = 20.sp,
                )
            )
        }

        Switch(
            checked = checkedState.value,
            onCheckedChange = {
                checkedState.value = it
                bgColor.value = if (checkedState.value) Color.Yellow else Color.Gray
            },
            colors = SwitchDefaults.colors(
                checkedThumbColor = Color.Blue,
                checkedTrackColor = Color.Red,
                uncheckedThumbColor = Color.Red,
                uncheckedTrackColor = Color.Blue,
            )
        )

    }

}