复选框 · CheckboxInput

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

安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

复选框 · 综合展示 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

{
  "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.