CheckBox 多选框

本文档整理了 Jetpack Compose 中 Checkbox 与相关变体的常用 API、属性说明、典型用法与示例代码，包含三态复选、与文本组合、在列表中使用、多选逻辑、自定义样式与无障碍建议。

概览

• Checkbox：用于表示布尔选择（选中 / 未选中）。通常与文本说明一起使用。
• TriStateCheckbox：三态复选（选中/未选中/不确定），适用于父级集合中部分子项被选中的场景。
• CheckboxDefaults：提供默认颜色和尺寸等辅助 API，例如 colors()。

常用属性（Checkbox / TriStateCheckbox）

• checked: Boolean / state: ToggleableState（TriState）：当前选中状态。
• onCheckedChange: ((Boolean) -> Unit)?：复选状态改变回调（可为 null，当想完全控制点击事件时）。
• enabled: Boolean：是否可交互。
• modifier: Modifier：设置尺寸、padding、clickable 等。
• colors: CheckboxColors：使用 CheckboxDefaults.colors(checkedColor = ..., uncheckedColor = ..., disabledColor = ...) 自定义颜色。
• interactionSource: MutableInteractionSource：监听按下/悬停等交互。

简单示例

@Composable
fun SimpleCheckbox() {
	var checked by remember { mutableStateOf(false) }
	Row(verticalAlignment = Alignment.CenterVertically) {
	Checkbox(checked = checked, onCheckedChange = { checked = it })
	Spacer(Modifier.width(8.dp))
	Text(if (checked) "已选" else "未选")
	}
}

要点：在 Compose 中推荐“状态提升”（state hoisting），将 `checked` 状态放在父组件或 ViewModel 中管理。

## TriStateCheckbox（三态复选）

```kotlin
@Composable
fun TriStateExample() {
	var state by remember { mutableStateOf(ToggleableState.Indeterminate) }

	TriStateCheckbox(
	state = state,
	onClick = {
			state = when (state) {
				ToggleableState.Off -> ToggleableState.On
				ToggleableState.On -> ToggleableState.Off
				ToggleableState.Indeterminate -> ToggleableState.On
			}
	}
	)
}

常见场景：父复选框反映子项集合的选中情况（全部选中 = On，部分选中 = Indeterminate，全部未选中 = Off）。

## 带文本与可点击区域扩展

建议将 `Checkbox` 与可点击文本包装在 `Row` 上并对整行设置 `Modifier.clickable`，以扩大点击目标：

```kotlin
@Composable
fun ClickableRowCheckbox(label: String) {
	var checked by remember { mutableStateOf(false) }
	Row(
	modifier = Modifier
			.fillMaxWidth()
			.clickable { checked = !checked }
			.padding(12.dp),
	verticalAlignment = Alignment.CenterVertically
	) {
	Checkbox(checked = checked, onCheckedChange = null) // onCheckedChange 放在 Row 的 clickable 中处理
	Spacer(Modifier.width(8.dp))
	Text(label)
	}
}

说明：当 `onCheckedChange` 为 null 时，Checkbox 本身不处理点击，这样可避免事件重复处理。

## 自定义颜色与样式

```kotlin
@Composable
fun ColoredCheckbox() {
	var checked by remember { mutableStateOf(true) }
	Checkbox(
	checked = checked,
	onCheckedChange = { checked = it },
	colors = CheckboxDefaults.colors(
			checkedColor = Color(0xFF1E88E5),
			uncheckedColor = Color.Gray,
			checkmarkColor = Color.White
	)
	)
}

## 列表中的多选（状态提升 + 选择集合）

```kotlin
@Composable
fun MultiSelectList(items: List<String>) {
	val selected = remember { mutableStateListOf<String>() }

	LazyColumn {
	items(items) { item ->
			Row(
				modifier = Modifier
					.fillMaxWidth()
					.clickable {
						if (selected.contains(item)) selected.remove(item) else selected.add(item)
					}
					.padding(12.dp),
				verticalAlignment = Alignment.CenterVertically
			) {
				Checkbox(checked = selected.contains(item), onCheckedChange = null)
				Spacer(Modifier.width(8.dp))
				Text(item)
			}
	}
	}
}

注意：将选择集合放在 `remember` 或 ViewModel 中以便在重组和配置更改时保持状态。

## 与表单交互与验证
- 在表单中，Checkbox 的值通常是布尔字段；提交时校验（例如至少选择一项）并显示错误文本（`Text(color = MaterialTheme.colors.error)`）。

## 无障碍与语义
- 设置 `contentDescription` 或在文本旁提供清晰的标签，使屏幕阅读器能正确描述控件用途。
- 使用 `Semantics` 补充更多信息，例如：

```kotlin
Modifier.semantics { contentDescription = "接收推送通知" }

性能与最佳实践

• 尽量避免在大列表中为每个项创建复杂的状态；使用集合与 remember/ViewModel 来管理状态。
• 使用 CheckboxDefaults.colors() 来保持主题一致性。

Material3 差异

• 在 Material3 主题下，颜色与默认样式可能有所不同，请查看 material3 包中的 Checkbox 文档和 CheckboxDefaults。

小结（速查）

• 基本组件：Checkbox、TriStateCheckbox
• 关键属性：checked/state、onCheckedChange/onClick、colors、enabled、modifier
• 常用模式：状态提升、扩大点击区域（Row+clickable）、列表多选、父子三态同步
• 可访问性：为非装饰性控件提供 contentDescription 或显式标签

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun CheckBoxComponents() {

    val myCheckedState = remember {
        mutableStateOf(false)
    }

    val myCheckedState2 = remember {
        mutableStateOf(false)
    }


    Column(
        modifier = Modifier.fillMaxSize(),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text(text = "请选择是否同意协议")

        Row(
            verticalAlignment = Alignment.CenterVertically
        ) {
            Checkbox(
                checked = myCheckedState.value,
                onCheckedChange = {
                    myCheckedState.value = it
                }
            )
            Text(text = "我已阅读隐私政策")
        }

        Row(
            // 使 checkbox 和 text 垂直居中
            verticalAlignment = Alignment.CenterVertically
        ) {
            Checkbox(
                checked = myCheckedState2.value,
                onCheckedChange = {
                    myCheckedState2.value = it
                }
            )
            Text(text = "我已阅读用户协议")
        }
        Text(
            text = "CheckBox value is ${myCheckedState.value}",
            color = if (myCheckedState.value) Color.Red else Color.Black
        )
    }


}