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`，則移除勾選圖示，並在 `action` 元素上套用選取的變體。
indeterminate	bool	false	如果為 `true`，則元件會顯示為 indeterminate 狀態。由於瀏覽器之間行為不一致，因此這不會將原生 input 元素設定為 indeterminate 狀態。但是，我們會在 `input` 上設定 `data-indeterminate` 屬性。
indeterminateIcon	node	<IndeterminateIcon />	當元件為 indeterminate 狀態時顯示的圖示。
label	node	-	Checkbox 旁邊的標籤元素。
name	string	-	input 的 `name` 屬性。
onChange	func	-	狀態變更時觸發的回呼函數。簽名：`function(event: React.ChangeEvent<htmlinputelement>) => void</htmlinputelement>` `event` 回呼函數的事件來源。您可以透過存取 `event.target.value` (字串) 來取出新值。您可以透過存取 `event.target.checked` (布林值) 來取出新的勾選狀態。
overlay	bool	false	如果為 `true`，則根元素的位置會設定為 initial，這允許 action 區域填滿最近的已定位父元素。此 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 }	{}	用於每個插槽內部的元件。有關更多詳細資訊，請參閱下方的 Slots API。
sx	Array<func \| object \| bool> \| func \| object	-	系統屬性，允許定義系統覆寫以及額外的 CSS 樣式。有關更多詳細資訊，請參閱 `sx` 頁面。
uncheckedIcon	node	-	當 `checked` 為 false 時的圖示。
value	Array<string> \| number \| string	-	元件的值。DOM API 會將其轉換為字串。瀏覽器使用 "on" 作為預設值。
variant	'outlined' \| 'plain' \| 'soft' \| 'solid'	'solid'	要使用的全域變體。若要了解如何新增自己的變體，請查看主題元件 — 擴展變體。

ref 會轉發到根元素。

主題預設 props

您可以使用 JoyCheckbox 透過主題變更此元件的預設 props。

插槽

若要了解如何自訂插槽，請查看覆寫元件結構指南。

插槽名稱	類別名稱	預設元件	描述
root	.MuiCheckbox-root	`'span'`	呈現根元素的元件。
checkbox	.MuiCheckbox-checkbox	`'span'`	呈現 checkbox 的元件。
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		如果 switch 具有可見焦點，則套用至根元素的類別名稱
.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 屬性的一部分。

原始碼

如果您在此頁面中找不到資訊，請考慮查看元件的實作以取得更多詳細資訊。