CheckboxAPI

React Checkbox 组件的 API 参考文档。了解此导出模块的 props、CSS 和其他 API。

演示

有关此 React 组件用法的示例和详细信息，请访问组件演示页面

Checkbox

导入

import Checkbox from '@mui/joy/Checkbox';
// or
import { Checkbox } from '@mui/joy';

要了解差异，请阅读本指南，了解如何最小化 bundle 大小。

Props

名称	类型	默认值	描述
checked	bool	-	如果 `true`，则组件被选中。
checkedIcon	node	<CheckIcon />	组件选中时显示的图标。
className	string	-	应用于根元素的类名。
color	'danger' \| 'neutral' \| 'primary' \| 'success' \| 'warning' \| string	'neutral'	组件的颜色。它支持适用于此组件的那些主题颜色。要了解如何添加您自己的颜色，请查看主题组件—扩展颜色。
component	elementType	-	用于根节点的组件。可以是用于 HTML 元素的字符串或组件。
defaultChecked	bool	-	默认选中状态。当组件不受控制时使用。
disabled	bool	-	如果 `true`，则组件被禁用。
disableIcon	bool	false	如果 `true`，则移除选中图标，并将选定的 variant 应用于 `action` 元素。
indeterminate	bool	false	如果 `true`，则组件显示为不确定状态。由于浏览器之间行为不一致，这不会将原生 input 元素设置为不确定状态。但是，我们在 `input` 上设置了 `data-indeterminate` 属性。
indeterminateIcon	node	<IndeterminateIcon />	组件处于不确定状态时显示的图标。
label	node	-	复选框旁边的标签元素。
name	string	-	input 的 `name` 属性。
onChange	func	-	状态更改时触发的回调。签名：`function(event: React.ChangeEvent) => void` `event` 回调的事件源。您可以通过访问 `event.target.value`（字符串）来提取新值。您可以通过访问 `event.target.checked`（布尔值）来提取新的选中状态。
overlay	bool	false	如果 `true`，则根元素的位置设置为 initial，这允许操作区域填充最近的定位父元素。此 prop 对于将 Checkbox 与 ListItem 组件组合很有用。
readOnly	bool	-	如果 `true`，则组件为只读。
required	bool	-	如果 `true`，则 `input` 元素为必填项。
size	'sm' \| 'md' \| 'lg'	'md'	组件的大小。要了解如何向组件添加自定义尺寸，请查看主题组件—扩展尺寸。
slotProps	{ action?: func \| object, checkbox?: func \| object, input?: func \| object, label?: func \| object, root?: func \| object }	{}	用于内部每个插槽的 props。
slots	{ action?: elementType, checkbox?: elementType, input?: elementType, label?: elementType, root?: elementType }	{}	用于内部每个插槽的组件。有关更多详细信息，请参阅下面的插槽 API。
sx	Array<func \| object \| bool> \| func \| object	-	允许定义系统覆盖以及其他 CSS 样式的系统 prop。有关更多详细信息，请参阅 `sx` 页面。
uncheckedIcon	node	-	`checked` 为 false 时的图标。
value	Array<string> \| number \| string	-	组件的值。DOM API 将其转换为字符串。浏览器使用“on”作为默认值。
variant	'outlined' \| 'plain' \| 'soft' \| 'solid'	'solid'	要使用的全局 variant。要了解如何添加您自己的 variant，请查看主题组件—扩展 variant。

ref 被转发到根元素。

主题默认 props

您可以使用 JoyCheckbox 通过主题更改此组件的默认 props。

插槽

要了解如何自定义插槽，请查看覆盖组件结构指南。

插槽名称	类名	默认组件	描述
root	.MuiCheckbox-root	`'span'`	渲染根的组件。
checkbox	.MuiCheckbox-checkbox	`'span'`	渲染复选框的组件。
action	.MuiCheckbox-action	`'span'`	渲染 action 的组件。
input	.MuiCheckbox-input	`'input'`	渲染 input 的组件。
label	.MuiCheckbox-label	`'label'`	渲染 label 的组件。

CSS 类

这些类名对于使用 CSS 进行样式设置很有用。当触发特定状态时，它们将应用于组件的插槽。

类名	规则名称	描述
.Mui-checked		应用于 input 组件的 `checked` 类的状态类。
.Mui-disabled		应用于 input 组件的 disabled 类的状态类。
.Mui-focusVisible		如果开关具有可见焦点，则应用于根元素的类名
.MuiCheckbox-colorContext	colorContext	当颜色反转被触发时，应用于根元素的类名。
.MuiCheckbox-colorDanger	colorDanger	如果 `color="danger"`，则应用于根元素的类名。
.MuiCheckbox-colorNeutral	colorNeutral	如果 `color="neutral"`，则应用于根元素的类名。
.MuiCheckbox-colorPrimary	colorPrimary	如果 `color="primary"`，则应用于根元素的类名。
.MuiCheckbox-colorSuccess	colorSuccess	如果 `color="success"`，则应用于根元素的类名。
.MuiCheckbox-colorWarning	colorWarning	如果 `color="warning"`，则应用于根元素的类名。
.MuiCheckbox-indeterminate	indeterminate	如果 `indeterminate={true}`，则应用于根元素的状态类。
.MuiCheckbox-sizeLg	sizeLg	如果 `size="lg"`，则应用于根元素的类名。
.MuiCheckbox-sizeMd	sizeMd	如果 `size="md"`，则应用于根元素的类名。
.MuiCheckbox-sizeSm	sizeSm	如果 `size="sm"`，则应用于根元素的类名。
.MuiCheckbox-variantOutlined	variantOutlined	如果 `variant="outlined"`，则应用于根元素的类名。
.MuiCheckbox-variantSoft	variantSoft	如果 `variant="soft"`，则应用于根元素的类名。
.MuiCheckbox-variantSolid	variantSolid	如果 `variant="solid"`，则应用于根元素的类名。

您可以使用以下自定义选项之一覆盖组件的样式

使用全局类名。
使用规则名称作为自定义主题中组件的 styleOverrides 属性的一部分。

源代码

如果您在本页中没有找到所需信息，请考虑查看组件的实现以获取更多详细信息。