自動完成

自動完成元件是一個文字輸入框，透過建議選項面板來增強功能。

useAutocomplete API

Import

import { useAutocomplete } from '@mui/base/useAutocomplete';
// or
import { useAutocomplete } from '@mui/base';

請閱讀這份關於最小化套件大小的指南，以了解差異。

參數

名稱	類型	預設值	描述
options*	ReadonlyArray<Value>	-	選項陣列。
autoComplete	boolean	false	若為 `true`，使用者尚未輸入的所選建議部分（稱為完成字串）將會以內嵌方式出現在文字框中輸入游標之後。內嵌完成字串會以視覺方式醒目提示，並具有選取狀態。
autoHighlight	boolean	false	若為 `true`，則會自動醒目提示第一個選項。
autoSelect	boolean	false	若為 `true`，當 Autocomplete 失去焦點時，所選選項會變成輸入框的值，除非使用者選擇不同的選項或變更輸入框中的字元字串。當使用 `freeSolo` 模式時，如果 Autocomplete 失去焦點且未醒目提示任何選項，則輸入的值將會是輸入框的值。
blurOnSelect	'touch' \| 'mouse' \| true \| false	false	控制在選取選項時是否應模糊輸入框 `false` 輸入框不會模糊。 `true` 輸入框永遠會模糊。 `touch` 在觸控事件後，輸入框會模糊。 `mouse` 在滑鼠事件後，輸入框會模糊。
clearOnBlur	boolean	!props.freeSolo	若為 `true`，如果未選取任何值，則在失去焦點時清除輸入框的文字。如果您想要協助使用者輸入新值，請設定為 `true`。如果您想要協助使用者恢復搜尋，請設定為 `false`。
clearOnEscape	boolean	false	若為 `true`，當使用者按下 escape 鍵且彈出視窗關閉時，清除所有值。
componentName	string	-	正在使用此 hook 的元件名稱。用於警告。
defaultValue	AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>	props.multiple ? [] : null	預設值。當元件不受控制時使用。
disableClearable	DisableClearable	false	若為 `true`，則無法清除輸入框。
disableCloseOnSelect	boolean	false	若為 `true`，選取值時彈出視窗不會關閉。
disabled	boolean	false	若為 `true`，則元件會停用。
disabledItemsFocusable	boolean	false	若為 `true`，將允許焦點放在停用的項目上。
disableListWrap	boolean	false	若為 `true`，彈出視窗中的列表框將不會環繞焦點。
filterOptions	(options: Value[], state: FilterOptionsState<Value>) => Value[]	createFilterOptions()	一個函式，用於決定要在搜尋時呈現的篩選選項。
filterSelectedOptions	boolean	false	若為 `true`，從列表框中隱藏選取的選項。
freeSolo	FreeSolo	false	若為 `true`，Autocomplete 是自由單獨模式，表示使用者輸入不受提供的選項約束。
getOptionDisabled	(option: Value) => boolean	-	用於決定給定選項的停用狀態。
getOptionKey	(option: Value \| AutocompleteFreeSoloValueMapping<FreeSolo>) => string \| number	-	用於決定給定選項的索引鍵。當選項的標籤不唯一時，這會很有用（因為預設情況下標籤會用作索引鍵）。
getOptionLabel	(option: Value \| AutocompleteFreeSoloValueMapping<FreeSolo>) => string	(option) => option.label ?? option	用於決定給定選項的字串值。它用於填寫輸入框（以及在未提供 `renderOption` 時的列表框選項）。如果在自由單獨模式中使用，則必須接受選項類型和字串。
groupBy	(option: Value) => string	-	如果提供，選項將會分組在傳回的字串下。當未提供 `renderGroup` 時，groupBy 值也會用作群組標題的文字。
handleHomeEndKeys	boolean	!props.freeSolo	若為 `true`，當彈出視窗開啟時，元件會處理 "Home" 和 "End" 鍵。它應該分別將焦點移至第一個選項和最後一個選項。
id	string	-	此 prop 用於協助實作無障礙邏輯。如果您未提供 id，它將會回復為隨機產生的 id。
includeInputInList	boolean	false	若為 `true`，醒目提示可以移至輸入框。
inputValue	string	-	輸入值。
isOptionEqualToValue	(option: Value, value: Value) => boolean	-	用於決定選項是否代表給定的值。預設使用嚴格相等。⚠️ 需要處理兩個引數，一個選項只能與一個值相符。
multiple	Multiple	false	若為 `true`，`value` 必須是陣列，且選單將支援多重選取。
onChange	(event: React.SyntheticEvent, value: AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>, reason: AutocompleteChangeReason, details?: AutocompleteChangeDetails<Value>) => void	-	當值變更時觸發的回呼。
onClose	(event: React.SyntheticEvent, reason: AutocompleteCloseReason) => void	-	當彈出視窗要求關閉時觸發的回呼。在受控模式中使用（請參閱 open）。
onHighlightChange	(event: React.SyntheticEvent, option: Value \| null, reason: AutocompleteHighlightChangeReason) => void	-	當醒目提示選項變更時觸發的回呼。
onInputChange	(event: React.SyntheticEvent, value: string, reason: AutocompleteInputChangeReason) => void	-	當輸入值變更時觸發的回呼。
onOpen	(event: React.SyntheticEvent) => void	-	當彈出視窗要求開啟時觸發的回呼。在受控模式中使用（請參閱 open）。
open	boolean	-	若為 `true`，則會顯示元件。
openOnFocus	boolean	false	若為 `true`，則在輸入框取得焦點時彈出視窗將會開啟。
readOnly	boolean	false	若為 `true`，元件會變成唯讀。多個標籤也支援唯讀，其中標籤無法刪除。
selectOnFocus	boolean	!props.freeSolo	若為 `true`，輸入框的文字會在取得焦點時選取。這有助於使用者清除選取的值。
unstable_classNamePrefix	string	'Mui'
unstable_isActiveElementInListbox	(listbox: React.RefObject<HTMLElement \| null>) => boolean	-
value	AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>	-	自動完成的值。值必須與選項具有參考相等性才能被選取。您可以使用 `isOptionEqualToValue` prop 自訂相等行為。

回傳值

名稱	類型	描述
anchorEl	null \| HTMLElement	用於設定元件位置的 HTML 元素。
dirty	boolean	若為 `true`，元件輸入框有一些值。
expanded	boolean	若為 `true`，正在顯示列表框。
focused	boolean	若為 `true`，元件已取得焦點。
focusedTag	number	元件的焦點標籤索引。
getClearProps	() => React.HTMLAttributes<HTMLButtonElement>	`clear` 按鈕元素 props 的解析器。
getInputLabelProps	() => Omit<React.HTMLAttributes<HTMLLabelElement>, 'color'>	輸入標籤元素 props 的解析器。
getInputProps	() => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.Ref<HTMLInputElement> }	輸入元素 props 的解析器。
getListboxProps	() => React.HTMLAttributes<HTMLUListElement>	列表框元件 props 的解析器。
getOptionProps	(renderedOption: UseAutocompleteRenderedOption<Value>) => React.HTMLAttributes<HTMLLIElement> & { key: any }	呈現的選項元素 props 的解析器。
getPopupIndicatorProps	() => React.HTMLAttributes<HTMLButtonElement>	彈出視窗圖示 props 的解析器。
getRootProps	(externalProps?: any) => React.HTMLAttributes<HTMLDivElement>	根插槽 props 的解析器。
getTagProps	AutocompleteGetTagProps	標籤 props getter。
groupedOptions	Value[] \| Array<AutocompleteGroupedOption<Value>>	要呈現的選項。如果提供了 groupBy prop，則為 `Value[]` 或 `AutocompleteGroupedOption<Value>[]`。
id	string	Autocomplete 的 ID。
inputValue	string	輸入值。
popupOpen	boolean	若為 `true`，彈出視窗在元件上開啟。
setAnchorEl	() => void	元件 `anchorEl` 的 Setter。
value	AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>	自動完成的值。