复选列表 · CheckboxList

复选列表用于表单输入场景。下面的官方示例展示原生用法与状态，属性名保持上游 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：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
复选列表 · 交互示例 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

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

Checkbox List

CheckboxList shows a small group of checkboxes so users can turn several options on or off at once. Place it in settings pages, filter panels, or forms where every choice should be visible without scrolling. For a single standalone checkbox (like "I agree to the terms"), use CheckboxInput instead. If only one option can be picked, use RadioList. If the list is long enough to need searching or scrolling, use MultiSelector instead.

属性	类型	默认值	说明
label *	string		Label text for the checkbox group (always rendered for accessibility).
children *	ReactNode		CheckboxListItem elements.
value	string[]		The currently selected values (collection mode).
onChange	(values: string[]) => void		Callback fired when the selected values change.
changeAction	(values: string[]) => void \| Promise<void>		Async action on change with optimistic updates. While the promise is pending, the toggled item shows a spinner inside its checkbox and is marked aria-busy.
isLabelHidden	boolean	false	Whether to visually hide the label.
description	string		Description text displayed below the label.
density	'compact' \| 'balanced' \| 'spacious'	'balanced'	Spacing density for list items.
hasDividers	boolean	false	Whether to show dividers between items.
isDisabled	boolean	false	Whether all checkbox items are disabled.
disabledMessage	string		Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the checkboxes focusable via aria-disabled (toggling stays blocked). Use this instead of wrapping a disabled CheckboxList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
isReadOnly	boolean	false	Whether all checkbox items are read-only. Displays the current state at full opacity but prevents interaction. Unlike isDisabled, read-only checkboxes are not visually dimmed.
status	{type: 'warning' \| 'error' \| 'success', message?: string}		Status indicator ({ type, message }).
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.
containerXstyle	StyleXStyles		StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.
containerClassName	string		Class name for the field container. Same targeting as `containerXstyle`.
containerStyle	CSSProperties		Inline styles for the field container. Same targeting as `containerXstyle`.
controlXstyle	StyleXStyles		StyleX styles for the visual control box: the element that paints the border and background and holds icons and end controls. Never the native input.
controlClassName	string		Class name for the visual control box.
controlStyle	CSSProperties		Inline styles for the visual control box.

使用建议

Keep the list short: three to seven options is the sweet spot. Beyond that, switch to MultiSelector which adds search and scrolling.
Turn on dividers (hasDividers) when items have helper text underneath; without them the labels and descriptions blur together.
Write a group label that says what the choices represent: "Export formats" tells users more than "Options".
避免：Show a CheckboxList when the user can only pick one thing; that is what RadioList is for.
避免：Put buttons or links inside the trailing slot (endContent); the whole row is already tappable, so a nested button creates two competing click targets.
避免：Wrap a disabled CheckboxList 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-list"
    }
  ]
}

CheckboxListItem

组件结构

Group: Container for the labeled checkbox group.
Group label: Text identifying what the checkbox options represent.
Description: Helper text below the group label.
Options list: List containing the available checkbox options.
Option row: Selectable row containing one option.
Checkbox: Selection indicator for an option.
Option label: Primary content identifying an option.
Option description: Secondary text below an option label.
End content: Caller-provided content at the end of an option row.
Spinner: Loading indicator shown inside the pending checkbox.
Status message: Error, warning, or success message below the group.

Checkbox List Item

单个复选框选项，包含标签、描述和尾部内容插槽。可在集合模式（位于带 value 数组的 CheckboxList 内）或独立模式（位于 List 内，或位于不带 value 的 CheckboxList 内，例如“全选”选项）下使用。

属性	类型	默认值	说明
label *	ReactNode		选项的主标签。富内容标签可包含链接或按钮，它们保留自身行为且不会切换该选项。ReactNode 标签会以其可见文本为复选框命名；仅当可见文本缺失时使用 aria-label，否则覆盖值必须保留全部可见文字。
aria-label	string		复选框的纯文本无障碍名称，会替换由 label 推导出的名称。仅当富标签没有可见文本时才完全替代；否则必须保留全部可见文字。
value	string		标识键。当父级 CheckboxList 带有 value 数组时为必填；缺少时该选项会抛出错误。
description	ReactNode		标签下方的辅助内容。可为字符串或 ReactNode。会通过 aria-describedby 作为复选框的无障碍描述暴露，便于辅助技术识别它是该选项的说明。
endContent	ReactNode		在标签区域后渲染的内容。
isDisabled	boolean	false	是否禁用此单个选项。
isLoading	boolean	false	此选项是否处于加载状态。在复选框内显示加载旋转器并阻止该选项的交互。在集合模式下，当父级 changeAction 处于待定状态时，被切换的选项会自动显示此状态。
isChecked	boolean \| 'indeterminate'		独立模式下的直接选中状态：位于 List 内，或位于不带 value 的 CheckboxList 内（例如“全选”选项）。当父级 CheckboxList 带有 value 数组时忽略。
onCheck	(checked: boolean) => void		独立模式下的直接选中处理函数：位于 List 内，或位于不带 value 的 CheckboxList 内。当父级 CheckboxList 带有 value 数组时忽略，改由该列表的 onChange 接收变更。

Rich label with an overriding aria-label

<CheckboxListItem
  label={<span>Pro plan <Badge label="Recommended" /></span>}
  aria-label="Pro plan Recommended option"
  value="pro"
/>