自動完成API

React 自動完成組件的 API 參考文件。了解此匯出模組的屬性、CSS 和其他 API。

示範

如需此 React 組件的使用範例和詳細資訊，請訪問組件示範頁面

自動完成

導入

import Autocomplete from '@mui/material/Autocomplete';
// or
import { Autocomplete } from '@mui/material';

閱讀這份關於最小化 bundle 大小的指南，了解差異。

屬性

原生組件的屬性也可用。

名稱	類型	預設值	描述
options*	陣列	-	將在自動完成中顯示的選項列表。
renderInput*	函數	-	渲染輸入。簽名：`function(params: object) => ReactNode`
autoComplete	布林值	否	如果為 `true`，使用者尚未輸入的選定建議部分（稱為完成字串）將在文字框中輸入游標後內嵌顯示。內嵌完成字串在視覺上會被高亮顯示，並具有選取狀態。
autoHighlight	布林值	否	如果為 `true`，則會自動高亮顯示第一個選項。
autoSelect	布林值	否	如果為 `true`，則當自動完成失去焦點時，選定的選項將成為輸入的值，除非使用者選擇不同的選項或更改輸入中的字元串。當使用 `freeSolo` 模式時，如果自動完成失去焦點而未高亮顯示任何選項，則輸入的值將為輸入值。
blurOnSelect	'滑鼠' \| '觸控' \| 布林值	否	控制在選取選項時是否應模糊輸入 `false` 輸入不會模糊。 `true` 輸入始終模糊。 `touch` 在觸控事件後輸入會模糊。 `mouse` 在滑鼠事件後輸入會模糊。
ChipProps	物件	-	應用於 `Chip` 元素的屬性。已棄用－請改用 `slotProps.chip`。此屬性將在 v7 版本中移除。詳情請參閱從已棄用的 API 遷移。
classes	物件	-	覆寫或擴展應用於組件的樣式。詳情請參閱下方的 CSS 類別 API。
clearIcon	節點	<ClearIcon fontSize="small" />	顯示以取代預設清除圖示的圖示。
clearOnBlur	布林值	!props.freeSolo	如果為 `true`，則在未選取任何值的情況下，當輸入失去焦點時，輸入的文字會被清除。如果您想幫助使用者輸入新值，請將其設定為 `true`。如果您想幫助使用者繼續搜尋，請將其設定為 `false`。
clearOnEscape	布林值	否	如果為 `true`，當使用者按下 Esc 鍵且彈出視窗關閉時，清除所有值。
clearText	字串	'清除'	覆寫清除圖示按鈕的預設文字。出於本地化目的，您可以使用提供的翻譯。
closeText	字串	'關閉'	覆寫關閉彈出視窗圖示按鈕的預設文字。出於本地化目的，您可以使用提供的翻譯。
componentsProps	{ clearIndicator?: object, paper?: object, popper?: object, popupIndicator?: object }	-	用於內部每個插槽的屬性。已棄用－請改用 `slotProps` 屬性。此屬性將在 v7 版本中移除。詳情請參閱從已棄用的 API 遷移。
defaultValue	any	props.multiple ? [] : null	預設值。當組件不受控制時使用。
disableClearable	布林值	否	如果為 `true`，則無法清除輸入。
disableCloseOnSelect	布林值	否	如果為 `true`，則在選取值時，彈出視窗不會關閉。
disabled	布林值	否	如果為 `true`，則組件已停用。
disabledItemsFocusable	布林值	否	如果為 `true`，則允許聚焦在已停用的項目上。
disableListWrap	布林值	否	如果為 `true`，彈出視窗中的列表框將不會循環聚焦。
disablePortal	布林值	否	如果為 `true`，`Popper` 內容將位於父組件的 DOM 階層下。
filterOptions	函數	createFilterOptions()	一個函數，用於確定在搜尋時要渲染的篩選選項。簽名：`function(options: Array<value>, state: object) => Array<value>` `options` 要渲染的選項。 `state` 組件的狀態。
filterSelectedOptions	布林值	否	如果為 `true`，從列表框中隱藏已選取的選項。
forcePopupIcon	'auto' \| 布林值	'auto'	強制顯示彈出圖示的可見性。
freeSolo	布林值	否	如果為 `true`，則自動完成是自由輸入模式，表示使用者輸入不受提供的選項限制。
fullWidth	布林值	否	如果為 `true`，則輸入將佔用其容器的完整寬度。
getLimitTagsText	函數	(more) => `+${more}`	當標籤被截斷時要顯示的標籤（`limitTags`）。簽名：`function(more: number) => ReactNode` `more` 被截斷的標籤數量。
getOptionDisabled	函數	-	用於確定給定選項的停用狀態。簽名：`function(option: Value) => boolean` `option` 要測試的選項。
getOptionKey	函數	-	用於確定給定選項的鍵。當選項的標籤不唯一時，這會很有用（因為預設情況下標籤會用作鍵）。簽名：`function(option: Value) => string \| number` `option` 要取得鍵的選項。
getOptionLabel	函數	(option) => option.label ?? option	用於確定給定選項的字串值。它用於填充輸入（以及列表框選項，如果未提供 `renderOption`）。如果在自由輸入模式中使用，則必須接受選項的類型和字串。簽名：`function(option: Value) => string`
groupBy	函數	-	如果提供，選項將在傳回的字串下分組。當未提供 `renderGroup` 時，groupBy 值也用作組標題的文字。簽名：`function(option: Value) => string` `option` 自動完成選項。
handleHomeEndKeys	布林值	!props.freeSolo	如果為 `true`，則當彈出視窗打開時，組件會處理「Home」和「End」鍵。它應分別將焦點移動到第一個選項和最後一個選項。
id	字串	-	此屬性用於幫助實作可訪問性邏輯。如果您未提供 id，它將退回到隨機生成的 id。
includeInputInList	布林值	否	如果為 `true`，則高亮可以移動到輸入。
inputValue	字串	-	輸入值。
isOptionEqualToValue	函數	-	用於確定選項是否代表給定的值。預設使用嚴格相等性。⚠️ 需要處理兩個引數，一個選項只能與一個值匹配。簽名：`function(option: Value, value: Value) => boolean` `option` 要測試的選項。 `value` 要測試的值。
limitTags	整數	-1	當未聚焦時將可見的標籤最大數量。設定 `-1` 以停用限制。
ListboxComponent	元素類型	'ul'	用於渲染列表框的組件。已棄用－請改用 `slotProps.listbox.component`。此屬性將在 v7 版本中移除。詳情請參閱從已棄用的 API 遷移。
ListboxProps	物件	-	應用於 Listbox 元素的屬性。已棄用－請改用 `slotProps.listbox`。此屬性將在 v7 版本中移除。詳情請參閱從已棄用的 API 遷移。
loading	布林值	否	如果為 `true`，則組件處於載入中狀態。這會顯示 `loadingText` 以取代建議（僅當沒有要顯示的建議時，例如 `options` 為空）。
loadingText	節點	'載入中…'	在載入中狀態時要顯示的文字。出於本地化目的，您可以使用提供的翻譯。
multiple	布林值	否	如果為 `true`，則 `value` 必須是陣列，且選單將支援多重選取。
noOptionsText	節點	'無選項'	當沒有選項時要顯示的文字。出於本地化目的，您可以使用提供的翻譯。
onChange	函數	-	當值變更時觸發的回呼。簽名：`function(event: React.SyntheticEvent, value: Value \| Array<value>, reason: string, details?: string) => void` `event` 回呼的事件來源。 `value` 組件的新值。 `reason` 其中之一：「createOption」、「selectOption」、「removeOption」、「blur」或「clear」。
onClose	函數	-	當彈出視窗請求關閉時觸發的回呼。在受控模式中使用（請參閱 open）。簽名：`function(event: React.SyntheticEvent, reason: string) => void` `event` 回呼的事件來源。 `reason` 可以是：「"toggleInput"」、「"escape"」、「"selectOption"」、「"removeOption"」、「"blur"」。
onHighlightChange	函數	-	當高亮選項變更時觸發的回呼。簽名：`function(event: React.SyntheticEvent, option: Value, reason: string) => void` `event` 回呼的事件來源。 `option` 高亮顯示的選項。 `reason` 可以是：「"keyboard"」、「"mouse"」、「"touch"」。
onInputChange	函數	-	當輸入值變更時觸發的回呼。簽名：`function(event: React.SyntheticEvent, value: string, reason: string) => void` `event` 回呼的事件來源。 `value` 文字輸入的新值。 `reason` 可以是：「"input"」（使用者輸入）、「"reset"」（程式化變更）、「"clear"」、「"blur"」、「"selectOption"」、「"removeOption"」。
onOpen	函數	-	當彈出視窗請求開啟時觸發的回呼。在受控模式中使用（請參閱 open）。簽名：`function(event: React.SyntheticEvent) => void` `event` 回呼的事件來源。
open	布林值	-	如果為 `true`，則會顯示組件。
openOnFocus	布林值	否	如果為 `true`，則彈出視窗將在輸入聚焦時開啟。
openText	字串	'開啟'	覆寫開啟彈出視窗圖示按鈕的預設文字。出於本地化目的，您可以使用提供的翻譯。
PaperComponent	元素類型	紙張	用於渲染彈出視窗主體的組件。已棄用－請改用 `slots.paper`。此屬性將在 v7 版本中移除。詳情請參閱從已棄用的 API 遷移。
PopperComponent	元素類型	浮動框	用於定位彈出視窗的組件。已棄用－請改用 `slots.popper`。此屬性將在 v7 版本中移除。詳情請參閱從已棄用的 API 遷移。
popupIcon	節點	<ArrowDropDownIcon />	顯示以取代預設彈出圖示的圖示。
readOnly	布林值	否	如果為 `true`，則組件變為唯讀。多個標籤也支援此功能，其中標籤無法刪除。
renderGroup	函數	-	渲染群組。簽名：`function(params: AutocompleteRenderGroupParams) => ReactNode` `params` 要渲染的群組。
renderOption	函數	-	渲染選項，預設使用 `getOptionLabel`。簽名：`function(props: object, option: Value, state: object, ownerState: object) => ReactNode` `props` 要應用於 li 元素的屬性。 `option` 要渲染的選項。 `state` 每個選項的狀態。 `ownerState` 自動完成組件的狀態。
renderTags	函數	-	渲染選定的值。簽名：`function(value: Array<value>, getTagProps: function, ownerState: object) => ReactNode` `value` 提供給組件的 `value`。 `getTagProps` 標籤屬性 getter。 `ownerState` 自動完成組件的狀態。
selectOnFocus	布林值	!props.freeSolo	如果為 `true`，則在聚焦時選取輸入的文字。這有助於使用者清除選定的值。
size	'small' \| 'medium' \| 字串	'medium'	組件的尺寸。
slotProps	{ chip?: func \| object, clearIndicator?: func \| object, listbox?: func \| object, paper?: func \| object, popper?: func \| object, popupIndicator?: func \| object }	{}	用於內部每個插槽的屬性。
slots	{ listbox?: elementType, paper?: elementType, popper?: elementType }	{}	用於內部每個插槽的組件。
sx	Array<func \| object \| bool> \| func \| object	-	允許定義系統覆寫以及額外 CSS 樣式的系統屬性。詳情請參閱 `sx` 頁面。
value	any	-	自動完成的值。為了被選取，值必須與選項具有參考相等性。您可以使用 `isOptionEqualToValue` 屬性自訂相等性行為。

組件無法持有 ref。

主題預設屬性

您可以使用 MuiAutocomplete 來變更此組件的預設屬性透過主題。

插槽

插槽名稱	類別名稱	預設組件	描述
listbox	.MuiAutocomplete-listbox	`'ul'`	用於渲染列表框的組件。
paper	.MuiAutocomplete-paper	`紙張`	用於渲染彈出視窗主體的組件。
popper	.MuiAutocomplete-popper	`浮動框`	用於定位彈出視窗的組件。

CSS 類別

這些類別名稱對於使用 CSS 設定樣式很有用。它們在觸發特定狀態時應用於組件的插槽。

類別名稱	規則名稱	描述
.Mui-expanded		如果顯示列表框，則應用於根元素的狀態類別。
.Mui-focused		如果聚焦，則應用於根元素的狀態類別。
.Mui-focusVisible		如果選項元素是鍵盤聚焦的，則應用於選項元素的樣式。
.MuiAutocomplete-clearIndicator	clearIndicator	應用於清除指示器的樣式。
.MuiAutocomplete-endAdornment	endAdornment	應用於 endAdornment 元素的樣式。
.MuiAutocomplete-fullWidth	fullWidth	如果 `fullWidth={true}`，則應用於根元素的樣式。
.MuiAutocomplete-groupLabel	groupLabel	應用於群組標籤元素的樣式。
.MuiAutocomplete-groupUl	groupUl	應用於群組 ul 元素的樣式。
.MuiAutocomplete-hasClearIcon	hasClearIcon	在渲染清除圖示時應用的樣式。
.MuiAutocomplete-hasPopupIcon	hasPopupIcon	在渲染彈出圖示時應用的樣式。
.MuiAutocomplete-input	input	應用於輸入元素的樣式。
.MuiAutocomplete-inputFocused	inputFocused	如果輸入已聚焦，則應用於輸入元素的樣式。
.MuiAutocomplete-inputRoot	inputRoot	應用於 Input 元素的樣式。
.MuiAutocomplete-loading	loading	應用於載入中包裝器的樣式。
.MuiAutocomplete-noOptions	noOptions	應用於無選項包裝器的樣式。
.MuiAutocomplete-option	option	應用於選項元素的樣式。
.MuiAutocomplete-popperDisablePortal	popperDisablePortal	如果 `disablePortal={true}`，則應用於 popper 元素的樣式。
.MuiAutocomplete-popupIndicator	popupIndicator	應用於彈出指示器的樣式。
.MuiAutocomplete-popupIndicatorOpen	popupIndicatorOpen	如果彈出視窗已開啟，則應用於彈出指示器的樣式。
.MuiAutocomplete-root	root	應用於根元素的樣式。
.MuiAutocomplete-tag	tag	應用於標籤元素的樣式，例如晶片。
.MuiAutocomplete-tagSizeMedium	tagSizeMedium	如果 `size="medium"`，則應用於標籤元素的樣式，例如晶片。
.MuiAutocomplete-tagSizeSmall	tagSizeSmall	如果 `size="small"`，則應用於標籤元素的樣式，例如晶片。

您可以使用以下自訂選項之一來覆寫組件的樣式

使用全域類別名稱。
在自訂主題中使用規則名稱作為組件 `styleOverrides` 屬性的一部分。

原始碼

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