跳到主要內容跳到主要內容
🚀 影響 Joy UI 2025 年的藍圖！參與最新的開發者調查

自動完成 (Autocomplete)API

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

範例

匯入

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

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

Props

原生元件的 Props 也可用。

名稱類型預設描述
options*陣列-

選項陣列。

aria-describedby字串-

識別描述物件的元素（或多個元素）。

aria-label字串-

定義標記目前元素的字串值。

aria-labelledby字串-

識別標記目前元素的元素（或多個元素）。

autoComplete布林值false

若為 true，使用者尚未輸入的選取建議部分（稱為完成字串）會以内嵌方式顯示在文字框中輸入游標之後。内嵌完成字串會以視覺方式醒目提示，並具有選取狀態。

autoFocus布林值-

若為 true，則在首次掛載期間會聚焦 input 元素。

autoHighlight布林值false

若為 true，則會自動醒目提示第一個選項。

autoSelect布林值false

若為 true，當 Autocomplete 失去焦點時，選取的選項會變成輸入值，除非使用者選擇不同的選項或變更輸入中的字元字串。
當使用 freeSolo 模式時，如果 Autocomplete 失去焦點且未醒目提示選項，則輸入的值將會是輸入值。

blurOnSelect'mouse'
| 'touch'
| 布林值		false

控制在選取選項時是否應模糊輸入

  • false 輸入不會模糊。
  • true 輸入一律模糊。
  • touch 在觸控事件後輸入會模糊。
  • mouse 在滑鼠事件後輸入會模糊。
clearIcon節點<ClearIcon fontSize="md" />

要顯示以取代預設清除圖示的圖示。

clearOnBlur布林值!props.freeSolo

若為 true，如果未選取任何值，則在模糊時會清除輸入的文字。
如果您想要協助使用者輸入新值，請將其設定為 true。如果您想要協助使用者恢復搜尋，請將其設定為 false。

clearOnEscape布林值false

若為 true，當使用者按下 Escape 鍵且彈出視窗關閉時，會清除所有值。

clearText字串'清除'

覆寫清除圖示按鈕的預設文字。
基於本地化目的，您可以使用提供的翻譯。

closeText字串'關閉'

覆寫關閉彈出視窗圖示按鈕的預設文字。
基於本地化目的，您可以使用提供的翻譯。

color'danger'
| 'neutral'
| 'primary'
| 'success'
| 'warning'		'neutral'

元件的顏色。它支援對此元件有意義的那些主題顏色。

若要了解如何新增自己的顏色，請查看主題元件—擴充顏色。

defaultValueanyprops.multiple ? [] : null

預設值。當元件不受控制時使用。

disableClearable布林值false

若為 true，則無法清除輸入。

disableCloseOnSelect布林值false

若為 true，則在選取值時不會關閉彈出視窗。

disabled布林值false

若為 true，則停用元件。

disabledItemsFocusable布林值false

若為 true，則允許聚焦在停用的項目上。

disableListWrap布林值false

若為 true，則彈出視窗中的列表框不會包裝焦點。

endDecorator節點-

此輸入的尾隨裝飾。

error布林值false

若為 true，則 input 將指示錯誤。此 prop 預設為從父 FormControl 元件繼承的值 (false)。

filterOptions函式createFilterOptions()

一個函式，用於判斷要在搜尋時呈現的篩選選項。

簽名：function(options: Array<value>, state: object) => Array<value>
  • options 要呈現的選項。
  • state 元件的狀態。
filterSelectedOptions布林值false

若為 true，則從列表框中隱藏選取的選項。

forcePopupIcon'auto'
| 布林值		'auto'

強制彈出視窗圖示的顯示可見性。

freeSolo布林值false

若為 true，則 Autocomplete 為 free solo，表示使用者輸入不受提供的選項約束。

getLimitTagsText函式(more: string | number) => `+${more}`

當標籤被截斷 (limitTags) 時要顯示的標籤。

簽名：function(more: string | number) => ReactNode
  • more 截斷的標籤數量。
getOptionDisabled函式-

用於判斷給定選項的停用狀態。

簽名：function(option: Value) => boolean
  • option 要測試的選項。
getOptionKey函式-

用於判斷給定選項的索引鍵。當選項的標籤不是唯一的時，這會很有用（因為預設會使用標籤作為索引鍵）。

簽名：function(option: Value) => string | number
  • option 要取得索引鍵的選項。
getOptionLabel函式(option) => option.label ?? option

用於判斷給定選項的字串值。它用於填寫輸入（以及列表框選項，如果未提供 renderOption）。
如果在 free solo 模式中使用，則必須接受選項類型和字串。

簽名：function(option: Value) => string
    groupBy函式-

    如果提供，選項將在傳回的字串下分組。當未提供 renderGroup 時，groupBy 值也用作群組標題的文字。

    簽名：function(options: Value) => string
    • options 要分組的選項。
    handleHomeEndKeys布林值!props.freeSolo

    若為 true，當彈出視窗開啟時，元件會處理 "Home" 和 "End" 鍵。它應分別將焦點移至第一個選項和最後一個選項。

    id字串-

    此 prop 用於協助實作可存取性邏輯。如果您未提供 id，它將回復為隨機產生的一個。

    includeInputInList布林值false

    若為 true，則醒目提示可以移至輸入。

    inputValue字串-

    輸入值。

    isOptionEqualToValue函式-

    用於判斷選項是否代表給定的值。預設使用嚴格相等。⚠️ 需要處理兩個引數，一個選項只能與一個值相符。

    簽名：function(option: Value, value: Value) => boolean
    • option 要測試的選項。
    • value 要測試的值。
    limitTags整數-1

    未聚焦時將可見的標籤最大數量。設定 -1 以停用限制。

    loading布林值false

    若為 true，則元件處於載入狀態。這會顯示 loadingText 以取代建議（僅當沒有建議要顯示時，例如 options 為空）。

    loadingText節點'載入中…'

    在載入狀態時要顯示的文字。
    基於本地化目的，您可以使用提供的翻譯。

    multiple布林值false

    若為 true，則 value 必須是陣列，且選單將支援多重選取。

    name字串-

    input 元素的 Name 屬性。

    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"、"auto"、"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布林值false

    若為 true，則彈出視窗將在輸入聚焦時開啟。

    openText字串'開啟'

    覆寫開啟彈出視窗圖示按鈕的預設文字。
    基於本地化目的，您可以使用提供的翻譯。

    placeholder字串-

    輸入預留位置

    popupIcon節點<ArrowDropDownIcon />

    要顯示以取代預設彈出視窗圖示的圖示。

    readOnly布林值false

    若為 true，則元件變為唯讀。多個標籤也支援此功能，其中標籤無法刪除。

    renderGroup函式-

    呈現群組。

    簽名：function(params: AutocompleteRenderGroupParams) => ReactNode
    • params 要呈現的群組。
    renderOption函式-

    呈現選項，預設使用 getOptionLabel。

    簽名：function(props: object, option: T, state: object) => ReactNode
    • props 要套用在 li 元素上的 props。
    • option 要呈現的選項。
    • state 元件的狀態。
    renderTags函式-

    呈現選取的值。

    簽名：function(value: Array<T>, getTagProps: function, ownerState: object) => ReactNode
    • value 提供給元件的 value。
    • getTagProps 標籤 props getter。
    • ownerState Autocomplete 元件的狀態。
    required布林值-

    若為 true，則 input 元素為必要項。此 prop 預設為從父 FormControl 元件繼承的值 (false)。

    selectOnFocus布林值!props.freeSolo

    若為 true，則在聚焦時會選取輸入的文字。這有助於使用者清除選取的值。

    size'sm'
    | 'md'
    | 'lg'
    | 字串    		'md'

    元件的大小。

    若要了解如何將自訂大小新增至元件，請查看主題元件—擴充大小。

    slotProps{ clearIndicator?: func
    | object, endDecorator?: func
    | object, input?: func
    | object, limitTag?: func
    | object, listbox?: func
    | object, loading?: func
    | object, noOptions?: func
    | object, option?: func
    | object, popupIndicator?: func
    | object, root?: func
    | object, startDecorator?: func
    | object, wrapper?: func
    | object }    		{}

    用於每個插槽內部的 props。

    slots{ clearIndicator?: elementType, endDecorator?: elementType, input?: elementType, limitTag?: elementType, listbox?: elementType, loading?: elementType, noOptions?: elementType, option?: elementType, popupIndicator?: elementType, root?: elementType, startDecorator?: elementType, wrapper?: elementType }{}

    用於每個插槽內部的元件。

    請參閱下方的插槽 API 以取得更多詳細資訊。

    startDecorator節點-

    此輸入的前導裝飾。

    sxArray<func
    | object
    | bool>
    | func
    | object    		-

    系統 prop，允許定義系統覆寫以及其他 CSS 樣式。

    請參閱 `sx` 頁面 以取得更多詳細資訊。

    type字串-

    input 元素的類型。它應該是有效的 HTML5 輸入類型。

    valueany-

    自動完成的值。
    值必須與選項具有參考相等性，才能被選取。您可以使用 isOptionEqualToValue prop 自訂相等行為。

    variant'outlined'
    | 'plain'
    | 'soft'
    | 'solid'    		'outlined'

    要使用的全域變體。

    若要了解如何新增自己的變體，請查看主題元件—擴充變體。

    ref 會轉發到根元素。

    主題預設 Props

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

    插槽 (Slots)

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

    插槽名稱類別名稱預設元件描述
    root.MuiAutocomplete-root'div'呈現根的元件。
    wrapper.MuiAutocomplete-wrapper'div'呈現包裝器的元件。
    input.MuiAutocomplete-input'input'呈現輸入的元件。
    startDecorator.MuiAutocomplete-startDecorator'div'呈現開始裝飾器的元件。
    endDecorator.MuiAutocomplete-endDecorator'div'呈現結束裝飾器的元件。
    clearIndicator.MuiAutocomplete-clearIndicator'button'呈現清除指示器的元件。
    popupIndicator.MuiAutocomplete-popupIndicator'button'呈現彈出視窗指示器的元件。
    listbox.MuiAutocomplete-listbox'ul'呈現列表框的元件。
    option.MuiAutocomplete-option'li'呈現選項的元件。
    loading.MuiAutocomplete-loading'li'呈現載入中的元件。
    noOptions.MuiAutocomplete-noOptions'li'呈現無選項的元件。
    limitTag.MuiAutocomplete-limitTag'div'呈現限制標籤的元件。

    CSS 類別

    這些類別名稱對於使用 CSS 設定樣式很有用。當觸發特定狀態時，它們會套用至元件的插槽。

    類別名稱規則名稱描述
    .Mui-disabled若 disabled={true}，則套用至根元素的類別名稱。
    .Mui-error若 error={true}，則套用至根元素的狀態類別。
    .Mui-focused若元件已聚焦，則套用至根元素的類別名稱。
    .MuiAutocomplete-colorContextcolorContext當觸發色彩反轉時，套用至根元素的類別名稱。
    .MuiAutocomplete-colorDangercolorDanger若 color="danger"，則套用至根元素的類別名稱。
    .MuiAutocomplete-colorNeutralcolorNeutral若 color="neutral"，則套用至根元素的類別名稱。
    .MuiAutocomplete-colorPrimarycolorPrimary若 color="primary"，則套用至根元素的類別名稱。
    .MuiAutocomplete-colorSuccesscolorSuccess若 color="success"，則套用至根元素的類別名稱。
    .MuiAutocomplete-colorWarningcolorWarning若 color="warning"，則套用至根元素的類別名稱。
    .MuiAutocomplete-formControlformControl若元件是 FormControl 的後代，則套用至根元素的類別名稱。
    .MuiAutocomplete-hasClearIconhasClearIcon當呈現清除圖示時套用的類別名稱。
    .MuiAutocomplete-hasPopupIconhasPopupIcon當呈現彈出視窗圖示時套用的類別名稱。
    .MuiAutocomplete-multiplemultiple若 multiple={true}，則套用至包裝器元素的類別名稱。
    .MuiAutocomplete-popupIndicatorOpenpopupIndicatorOpen若彈出視窗開啟，則套用至彈出視窗指示器的類別名稱。
    .MuiAutocomplete-sizeLgsizeLg若 size="lg"，則套用至根元素的類別名稱。
    .MuiAutocomplete-sizeMdsizeMd若 size="md"，則套用至根元素的類別名稱。
    .MuiAutocomplete-sizeSmsizeSm若 size="sm"，則套用至根元素的類別名稱。
    .MuiAutocomplete-variantOutlinedvariantOutlined若 variant="outlined"，則套用至根元素的類別名稱。
    .MuiAutocomplete-variantPlainvariantPlain若 variant="plain"，則套用至根元素的類別名稱。
    .MuiAutocomplete-variantSoftvariantSoft若 variant="soft"，則套用至根元素的類別名稱。
    .MuiAutocomplete-variantSolidvariantSolid若 variant="solid"，則套用至根元素的類別名稱。

    您可以使用下列其中一種自訂選項覆寫元件的樣式

    原始碼

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