SelectAPI

React Select 元件的 API 參考文件。了解此匯出模組的 props、CSS 和其他 API。

範例

如需此 React 元件用法的範例和詳細資訊，請造訪元件示範頁面

Select

Import

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

若要了解差異，請閱讀此關於最小化 bundle size 的指南。

Props

名稱	類型	預設值	描述
action	func \| { current?: { focusVisible: func } }	-	用於命令式動作的 ref。目前僅支援 `focusVisible()` 動作。
autoFocus	bool	false	如果 `true`，則在首次掛載期間會 focus select 元素
color	'danger' \| 'neutral' \| 'primary' \| 'success' \| 'warning' \| string	'neutral'	元件的顏色。它支援適用於此元件的 theme colors。若要了解如何新增自己的顏色，請查看Themed components—Extend colors。
component	elementType	-	用於 root node 的元件。可以是 HTML 元素的字串或元件。
defaultListboxOpen	bool	false	如果 `true`，select 將會初始開啟。
defaultValue	any	-	預設選取值。當元件不受控制時使用。
disabled	bool	false	如果 `true`，則停用元件。
endDecorator	node	-	select 的尾隨裝飾。
getSerializedValue	func	-	將目前選取的值轉換為字串的函式。用於設定與 select 關聯的隱藏輸入值，以便可以透過表單張貼選取的值。
indicator	node	-	select 的指示器 ()。 ________________ [ 值 ] ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
listboxId	string	-	listbox 元素的 `id` 屬性。也用於衍生選項的 `id` 屬性。
listboxOpen	bool	undefined	控制 select 的 listbox 的開啟狀態。
multiple	bool	-	如果 `true`，則允許選取多個值。這會影響 `value`、`defaultValue` 和 `onChange` props 的類型。
name	string	-	元素的名稱。例如，伺服器使用它來識別表單提交中的欄位。
onChange	func	-	選取選項時觸發的回呼。
onClose	func	-	當 focus 離開選單且選單應關閉時觸發。
onListboxOpenChange	func	-	當元件請求開啟時觸發的回呼。在受控模式中使用（請參閱 listboxOpen）。
placeholder	node	-	當沒有選取值時顯示的文字。
renderValue	func	-	自訂選取值呈現方式的函式。
required	bool	false	如果 `true`，提交表單時 Select 不得為空。
size	'sm' \| 'md' \| 'lg' \| string	-	元件的大小。若要了解如何將自訂大小新增至元件，請查看Themed components—Extend sizes。
slots	{ button?: elementType, endDecorator?: elementType, indicator?: elementType, listbox?: elementType, root?: elementType, startDecorator?: elementType }	{}	用於每個 slot 內部的元件。請參閱下方的Slots API以取得更多詳細資訊。
startDecorator	node	-	select 的前導裝飾。
sx	Array<func \| object \| bool> \| func \| object	-	允許定義系統覆寫以及其他 CSS 樣式的系統 prop。請參閱`sx` 頁面以取得更多詳細資訊。
value	any	-	選取的值。設定為 `null` 以取消選取所有選項。
variant	'outlined' \| 'plain' \| 'soft' \| 'solid' \| string	'outlined'	要使用的global variant。若要了解如何新增自己的 variants，請查看Themed components—Extend variants。

ref 會轉發到 root 元素。

Theme default props

您可以使用 JoySelect 透過 theme 變更此元件的預設 props。

Slots

若要了解如何自訂 slot，請查看Overriding component structure指南。

Slot 名稱	Class name	Default component	描述
root	.MuiSelect-root	`'div'`	呈現 root 的元件。
button	.MuiSelect-button	`'button'`	呈現 button 的元件。
startDecorator	.MuiSelect-startDecorator	`'span'`	呈現 start decorator 的元件。
endDecorator	.MuiSelect-endDecorator	`'span'`	呈現 end decorator 的元件。
indicator	.MuiSelect-indicator	`'span'`	呈現 indicator 的元件。
listbox	.MuiSelect-listbox	`'ul'`	呈現 listbox 的元件。

CSS classes

這些 class names 對於使用 CSS 設定樣式很有用。它們會在觸發特定狀態時套用至元件的 slots。

Class name	Rule name	描述
.Mui-disabled		如果 `disabled={true}`，則套用至 root slot 的狀態 class。
.Mui-expanded		如果 listbox 開啟，則套用至 root slot 的狀態 class。
.Mui-focusVisible		如果 button 是鍵盤 focus，則套用至 SelectBase root slot 的狀態 class。
.MuiSelect-colorContext	colorContext	當觸發顏色反轉時，套用至 root 元素的 Class name。
.MuiSelect-colorDanger	colorDanger	如果 `color="danger"`，則套用至 root slot 的 Class name。
.MuiSelect-colorNeutral	colorNeutral	如果 `color="neutral"`，則套用至 root slot 的 Class name。
.MuiSelect-colorPrimary	colorPrimary	如果 `color="primary"`，則套用至 root slot 的 Class name。
.MuiSelect-colorSuccess	colorSuccess	如果 `color="success"`，則套用至 root slot 的 Class name。
.MuiSelect-colorWarning	colorWarning	如果 `color="warning"`，則套用至 root slot 的 Class name。
.MuiSelect-multiple	multiple	如果 `multiple=true`，則套用至 root slot 的 Class name
.MuiSelect-popper	popper	套用至 popper slot 的 Class name。
.MuiSelect-sizeLg	sizeLg	如果 `size="lg"`，則套用至 root slot 的 Class name。
.MuiSelect-sizeMd	sizeMd	如果 `size="md"`，則套用至 root slot 的 Class name。
.MuiSelect-sizeSm	sizeSm	如果 `size="sm"`，則套用至 root slot 的 Class name。
.MuiSelect-variantOutlined	variantOutlined	如果 `variant="outlined"`，則套用至 root slot 的 Class name。
.MuiSelect-variantPlain	variantPlain	如果 `variant="plain"`，則套用至 root slot 的 Class name。
.MuiSelect-variantSoft	variantSoft	如果 `variant="soft"`，則套用至 root slot 的 Class name。
.MuiSelect-variantSolid	variantSolid	如果 `variant="solid"`，則套用至 root slot 的 Class name。

您可以使用以下其中一個客製化選項來覆寫元件的樣式

使用global class name。
在自訂 theme 中，使用作為元件styleOverrides 屬性一部分的 rule name。

原始碼

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