# 复选框 · CheckboxInput

- 页面: https://jiguang132.com/zh/resources/astryx/docs/checkbox-input
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

复选框用于表单输入场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

## 安装与前置条件

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

- **复选框 · 综合展示 1**：首先体验这个示例，再查看代码理解组件的组合方式。
- **复选框 · 基础用法 2**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **复选框 · 交互示例 3**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
- **复选框 · 状态 4**：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

## API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

## Checkbox Input

CheckboxInput toggles a single on/off value. Use it for settings like "Enable notifications", terms acceptance, or opt-in choices. For multiple checkboxes in a group, use CheckboxList instead.

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| ref | React.Ref<HTMLInputElement> |  | 转发至底层 <input> 元素的 ref。 |
| label * | string |  | 复选框的标签文本（始终为无障碍性而渲染）。 |
| isLabelHidden | boolean | false | 是否视觉隐藏标签（屏幕阅读器仍可访问）。 |
| description | string |  | 显示在标签下方的描述文本。 |
| value * | boolean \| 'indeterminate' |  | 复选框是否为选中、未选中或不确定状态。 |
| onChange | (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void |  | 复选框状态变更时触发的回调。 |
| changeAction | (checked: boolean, e: ChangeEvent<HTMLInputElement>) => void \| Promise<void> |  | 异步变更操作。在 onChange 之后触发（未被阻止时）。等待期间显示加载旋转器。 |
| isLoading | boolean | false | 复选框是否处于加载状态。显示旋转器并阻止交互。 |
| isDisabled | boolean | false | 复选框是否禁用。 |
| htmlName | string |  | 底层复选框输入的 HTML name 属性，用于表单提交（勾选时提交 "on"）。 |
| disabledMessage | string |  | Explains why the checkbox is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkbox focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxInput in Tooltip: disabled controls swallow the hover events an external Tooltip needs. |
| isReadOnly | boolean | false | 复选框是否为只读。以完整不透明度显示当前状态但阻止交互。与 isDisabled 不同，只读复选框不会变暗。 |
| isOptional | boolean | false | 字段是否可选。与 isRequired 互斥。 |
| isRequired | boolean | false | 复选框是否必填。与 isOptional 互斥。 |
| size | 'sm' \| 'md' | 'md' | 复选框尺寸。sm 用于紧凑布局，md 为默认。 |
| onFocus | (e: FocusEvent<HTMLInputElement>) => void |  | 复选框获得焦点时触发的回调。 |
| onBlur | (e: FocusEvent<HTMLInputElement>) => void |  | 复选框失去焦点时触发的回调。 |
| labelIcon | ReactNode \| IconType |  | 标签文本前显示的语义图标名称或自定义内容。 |
| status | { type: 'error' \| 'warning' \| 'success', message: string } |  | 状态指示器。在复选框下方显示彩色消息框，错误时设置 aria-invalid。 |
| width | SizeValue |  | Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned. |

### 使用建议

- Always provide a visible label so the user knows what they are toggling. Use isLabelHidden only when surrounding context makes it obvious.
- Add a description for choices that need extra context, like explaining what "Share usage data" actually shares.
- Use the indeterminate state for "select all" checkboxes when only some items in a group are selected.
- 避免：Use a checkbox for mutually exclusive choices; use RadioList when only one option can be selected.
- 避免：Use a checkbox for actions that take effect immediately; use a toggle switch or button instead.
- 避免：Wrap a disabled checkbox in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

### 主题 API

```json
{
  "targets": [
    {
      "className": "astryx-checkbox-input",
      "visualProps": [
        "size"
      ]
    },
    {
      "className": "astryx-checkbox-indicator",
      "visualProps": [
        "size"
      ],
      "states": [
        "checked",
        "disabled"
      ]
    },
    {
      "className": "astryx-checkbox-label"
    }
  ]
}
```

### 无障碍

- **Checkbox box**: The box edge (unchecked) and fill (checked) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied. — 3:1

### 组件结构

- **Checkbox**: The check box itself: unchecked, checked, or indeterminate.
- **Label**: Text describing what the checkbox controls. Always present for accessibility.
- **Description**: Helper text below the label with additional context.
- **Status message**: An error, warning, or success message below the checkbox.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt