自動完成

自動完成是文字輸入框的強化版本，當使用者開始輸入時，會顯示建議選項面板。

簡介

Autocomplete 是文字輸入框的強化版本，會在使用者輸入時顯示建議選項，並允許他們從列表中選取選項。

用法

在安裝後，您可以使用以下基本元素開始建構此元件

import Autocomplete from '@mui/joy/Autocomplete';
import Input from '@mui/joy/Input';

export default function App() {
  return <Autocomplete options={['Option 1', 'Option 2']} />;
}

基本

Autocomplete 元件需要一個 options 列表，以便在文字框獲得焦點後顯示。值必須從預先定義的允許值集合中選擇。

自訂

選項結構

預設情況下，options 接受 string 或 { label: string } 的陣列

const options = [
  { label: 'The Godfather', id: 1 },
  { label: 'Pulp Fiction', id: 2 },
];
// or
const options = ['The Godfather', 'Pulp Fiction'];

但是，您可以透過提供 getOptionLabel 屬性來使用不同的結構

const options = [
  { title: 'Pulp Fiction', id: 2 },
  // ...
];

<Autocomplete getOptionLabel={option => option.title}>

選項外觀

若要自訂選項的外觀，請將 renderOption 屬性與 AutocompleteOption 元件結合使用，作為選項容器。

變體

自動完成元件支援四種全域變體：outlined（預設）、soft、solid 和 plain。

變體和色彩值會傳播到 Autocomplete 的 input 和 listbox 插槽。

若要自訂特定插槽的變體和色彩，請使用 slotProps

<Autocomplete
  variant="plain"
  slotProps={{
    listbox: {
      variant: 'outlined',
    },
  }}
/>

標籤

將 Autocomplete、FormLabel 和 FormHelperText（選用）放在 FormControl 元件下，以建立可存取的自動完成。

裝飾器

使用 startDecorator 或 endDecorator 將裝飾器插入自動完成。

受控狀態

元件有兩種可以控制的狀態

1. 「值」狀態，使用 value/onChange 屬性組合。此狀態代表使用者選取的值，例如按下 Enter 時。
2. 「輸入值」狀態，使用 inputValue/onInputChange 屬性組合。此狀態代表文字框中顯示的值。

這兩個狀態是隔離的，應該獨立控制。

停用選項

使用 getOptionDisabled 屬性讀取選項，並傳回 true 以停用它們。

群組選項

您可以使用 groupBy 屬性將選項分組。如果您這樣做，請確保選項也使用與分組相同的維度排序，否則，您會注意到重複的標題。

載入中

只要網路請求處於擱置狀態，就會顯示進度狀態。

搜尋輸入框

使用 freeSolo 建立具有建議體驗的搜尋輸入框，例如 Google 搜尋或 react-autowhatever。

使用者建立的選項

如果您打算將 freeSolo 模式用於類似 組合框 的體驗（選取器元素的強化版本），我們建議設定

• selectOnFocus 以協助使用者清除選取的值。
• clearOnBlur 以協助使用者輸入新值。
• handleHomeEndKeys 以使用 Home 和 End 鍵在彈出視窗內移動焦點。
• 最後一個選項，例如：新增「您的搜尋」。

當使用者想要新增值時，您也可以顯示對話框。

驗證

若要顯示無效狀態，請在 FormControl 上設定 error 屬性。

多重選取

預設情況下，自動完成使用 Chip 元件來呈現使用者選取的選項。

當自動完成獲得焦點時，使用者可以按下退格鍵從列表中移除最新選取的選項。

已選取選項外觀

使用 renderTag 屬性自訂外觀。

限制顯示的已選取選項數量

當未獲得焦點時，您可以使用 limitTags 屬性來限制顯示的選項數量。

尺寸

自動完成元件隨附三種開箱即用的尺寸：sm、md（預設）和 lg。尺寸會傳播到內部元件，包括 Input、Chip 和 List。

size 也可以在 FormControl 中控制。

自訂篩選器

元件公開一個 factory 以建立篩選方法，該方法可以提供給 filterOptions 屬性。您可以使用它來變更預設選項篩選行為。

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

參數

1. config（物件 [選用]）

• config.ignoreAccents（bool [選用]）：預設為 true。移除變音符號。
• config.ignoreCase（bool [選用]）：預設為 true。將所有內容轉換為小寫。
• config.limit（number [選用]）：預設為 null。限制要顯示的建議選項數量。例如，如果 config.limit 為 100，則只會顯示前 100 個相符選項。如果有很多選項符合且未設定虛擬化，則這會很有用。
• config.matchFrom（'any' | 'start' [選用]）：預設為 'any'。
• config.stringify（func [選用]）：控制如何將選項轉換為字串，以便可以與輸入文字片段比對。
• config.trim（bool [選用]）：預設為 false。移除尾隨空格。

回傳

filterOptions：傳回的篩選方法可以直接提供給 Autocomplete 元件的 filterOptions 屬性，或用於 Hook 的同名參數。

在以下示範中，選項需要以查詢字首開頭

const filterOptions = createFilterOptions({
  matchFrom: 'start',
  stringify: (option) => option.title,
});

<Autocomplete filterOptions={filterOptions} />;

進階篩選器

對於更豐富的篩選機制，例如模糊比對，建議查看 match-sorter。例如

import { matchSorter } from 'match-sorter';

const filterOptions = (options, { inputValue }) => matchSorter(options, inputValue);

<Autocomplete filterOptions={filterOptions} />;

CSS 變數遊樂場

Autocomplete 元件重複使用 Input 元件中的 CSS 變數，為您提供一致的自訂體驗。

常見範例

提示

以下示範說明如何使用 filterOptions 屬性將提示功能新增至 Autocomplete

醒目提示選項

以下示範依賴 autosuggest-highlight，這是一個小巧 (1 kB) 的公用程式，用於在自動建議和自動完成元件中醒目提示文字。

GitHub 的選取器

若要重現 GitHub 的標籤選取器，Autocomplete 會在 MUI Base Popper 內呈現。若要從自動完成中移除彈出視窗行為，請將 listbox 插槽取代為 AutocompleteListbox 元件。

虛擬化

在 10,000 個隨機產生的選項中搜尋。列表已透過 react-window 虛擬化。

事件

如果您想要防止預設的按鍵處理常式行為，您可以將事件的 defaultMuiPrevented 屬性設定為 true

<Autocomplete
  onKeyDown={(event) => {
    if (event.key === 'Enter') {
      // Prevent's default 'Enter' behavior.
      event.defaultMuiPrevented = true;
      // your handler code
    }
  }}
/>

限制

自動完成/自動填入

預設情況下，元件會使用 autoComplete="off" 屬性停用輸入自動完成功能（記住使用者在先前的會話中針對給定欄位輸入的內容）。Google Chrome 目前不支援此屬性設定 (Issue 41239842)。可能的解決方法是移除 id 以讓元件產生隨機的 id。

除了記住過去輸入的值之外，瀏覽器也可能會建議自動填入建議（已儲存的登入、地址或付款詳細資料）。如果您想要避免自動填入，您可以嘗試以下方法

• 命名輸入框時，請勿洩漏瀏覽器可以使用的任何資訊。例如 id="field1" 而不是 id="country"。如果您將 id 留空，元件會使用隨機 id。

• 設定 autoComplete="new-password"（某些瀏覽器會針對具有此屬性設定的輸入框建議強式密碼）

  <Autocomplete
    slotProps={{
      input: {
        autoComplete: 'new-password',
      },
    }}
  />
  

  複製已複製（或 $keyC）

閱讀 MDN 上的指南以瞭解更多詳細資訊。

iOS VoiceOver

iOS Safari 上的 VoiceOver 不太支援 aria-owns 屬性。您可以使用 disablePortal 屬性來解決此問題。

<Autocomplete
  slotProps={{
    listbox: {
      disablePortal: true,
    },
  }}
/>

協助工具

（WAI-ARIA：https://www.w3.org/WAI/ARIA/apg/patterns/combobox/）

我們鼓勵為文字框使用標籤。元件實作 WAI-ARIA 撰寫實務。

API

請參閱以下文件，以取得此處提及之元件的所有屬性和類別的完整參考。

• <Autocomplete />
• <AutocompleteListbox />
• <AutocompleteOption />