自動完成 (Autocomplete)

Autocomplete 元件支援透過滑鼠、鍵盤和觸控進行選取。您可以使用 onSelectionChange 屬性來處理所有這些操作。Autocomplete 會將選取的鍵傳遞給 onSelectionChange 處理常式。此外，ComboBox 接受 onInputChange 屬性，當使用者編輯值時（無論是透過輸入還是選項選取）都會觸發該屬性。

下面的範例使用 onSelectionChange 和 onInputChange 來更新儲存在 React 狀態中的選取和輸入值。

受控

您可以使用 selectedKey 和 onSelectionChange 屬性來控制選取的值。

完全受控

透過將 inputValue、selectedKey 和 items 傳遞給 Autocomplete，您可以精確控制 Autocomplete 應顯示的內容。

下面的範例示範如何建立受控的 Autocomplete，從選取的值 selectedKey 到組合框選項 items，控制所有內容。

我們建議使用來自 @react-aria/i18n 的 useFilter hook 來管理項目的篩選。

注意：請務必注意，您不必控制 Autocomplete 的每個方面。如果您決定只控制 Autocomplete 的單一屬性，請務必也為該屬性提供變更處理常式，例如控制 selectedKey 將需要 onSelectionChange。

自訂項目

您可以透過修改 AutocompleteItem 子元素來自訂自動完成項目。

自訂空白內容訊息

預設情況下，如果沒有任何結果符合您的篩選條件，將會顯示訊息 找不到結果。。您可以透過修改 listboxProps 中的 emptyContent來自訂空白內容訊息。

自訂篩選

預設情況下，Autocomplete 使用來自 useFilter 的 "contains" 函式來篩選選項列表。這可以使用 defaultFilter 屬性覆蓋，或是使用 items 屬性來控制篩選後的列表。當提供 items 而非 defaultItems 時，Autocomplete 不會自行進行篩選。

以下範例使用 defaultFilter 屬性，使用自訂的篩選函式來篩選選項列表。

非同步篩選

Autocomplete 支援非同步篩選。在下面的範例中，我們使用來自 useAsyncList 函式，該函式來自 react-aria，用來處理從伺服器非同步載入和篩選資料。

非同步載入

Autocomplete 支援非同步載入。在下面的範例中，我們使用自訂的 Hook 來取得 Pokemon API 資料，並結合 useInfiniteScroll Hook，以便在使用者到達列表末端時載入更多資料。

當資料正在擷取時，會使用 isLoading 屬性來顯示載入指示器，而不是選取器圖示。

虛擬化

Autocomplete 支援虛擬化。在下面的範例中，我們使用 isVirtualized 屬性來啟用虛擬化。

注意：虛擬化策略基於 @tanstack/react-virtual 套件，該套件透過僅渲染視窗中可見的項目來提供大型列表的有效渲染。

base：自動完成的主要包裝器。它會包裝輸入和 popover 元件。
listboxWrapper：listbox 的包裝器。它會包裝 listbox 元件，此插槽用於捲軸陰影元件之上。
listbox：listbox 元件。此元件會包裝自動完成的項目。
popoverContent：popover 內容插槽。使用此插槽來修改 popover 內容樣式。
endContentWrapper：結束內容的包裝器。它會包裝清除按鈕和選擇器按鈕。
clearButton：清除按鈕插槽。
selectorButton：選擇器按鈕插槽。

資料屬性

Autocomplete 在 base 元素上具有以下屬性

data-invalid：當自動完成功能無效時。根據 isInvalid 屬性。
data-open：指示自動完成的 popover 是否開啟。

Autocomplete 在 selectorButton 元素上具有以下屬性

data-open：指示自動完成的 popover 是否開啟。

Autocomplete 在 clearButton 元素上具有以下屬性

data-visible：指示自動完成的清除按鈕是否可見。預設情況下，當滑鼠懸停在自動完成功能上且自動完成功能具有值（桌面版）時，或當自動完成功能具有值（行動版）時，它是可見的。

AutocompleteItem 在 base 元素上具有以下屬性

data-disabled：當自動完成項目停用時。根據自動完成 disabledKeys 屬性。
data-selected：當自動完成項目被選取時。根據自動完成 selectedKey 屬性。
data-hover：當自動完成項目懸停時。根據 useHover
data-pressed：當自動完成項目被按下時。根據 usePress
data-focus：當自動完成項目被聚焦時。根據 useFocusRing。
data-focus-visible：當使用鍵盤聚焦自動完成項目時。根據 useFocusRing。

輔助功能

支援透過輸入來篩選選項列表
支援選取單一選項
支援停用選項
支援區段中的項目群組
支援自訂使用者輸入值
支援控制和不受控制的選項、選取、輸入值和開啟狀態
支援自訂篩選函數
支援非同步載入和無限滾動
支援虛擬化滾動，以便在長列表時提升效能
以具有 ARIA 的組合框形式呈現給輔助技術
為輔助功能提供標籤支援
透過 ARIA 將必要和無效狀態呈現給輔助技術
支援滑鼠、觸控和鍵盤互動
鍵盤支援使用方向鍵開啟組合框列表框，包括自動聚焦第一個或最後一個項目
支援在輸入時、聚焦時或手動開啟列表框
處理觸控螢幕閱讀器上輸入的虛擬點擊以切換列表框
用於組合框列表框選項導覽的虛擬焦點管理
在入口網站中開啟列表框時，將輸入和列表框外的元素從輔助技術中隱藏
為選項聚焦、篩選和選取使用 ARIA 即時區域的自訂本地化公告，以解決 VoiceOver 的錯誤
支援透過 ARIA 連結至輸入的描述和錯誤訊息說明文字

API

自動完成屬性 (Autocomplete Props)

屬性 (Prop)	類型 (Type)	預設值 (Default)
`children*`	`ReactNode[]`
`label`	`ReactNode`
`name`	`string`
`variant`	`flat \| bordered \| faded \| underlined`	`"flat"`
`color`	`default \| primary \| secondary \| success \| warning \| danger`	`"default"`
`size`	`sm \| md \| lg`	`"md"`
`radius`	`none \| sm \| md \| lg \| full`
`items`	`Iterable<T>`
`defaultItems`	`Iterable<T>`
`inputValue`	`string`
`defaultInputValue`	`string`
`allowsCustomValue`	`boolean`	`false`
`allowsEmptyCollection`	`boolean`	`true`
`shouldCloseOnBlur`	`boolean`	`true`
`placeholder`	`string`
`description`	`ReactNode`
`menuTrigger`	`focus \| input \| manual`	`"focus"`
`labelPlacement`	`inside \| outside \| outside-left`	`"inside"`
`selectedKey`	`React.Key`
`defaultSelectedKey`	`React.Key`
`disabledKeys`	`all \| React.Key[]`
`errorMessage`	`ReactNode \| ((v: ValidationResult) => ReactNode)`
`validate`	`(value: { inputValue: string, selectedKey: React.Key }) => ValidationError \| true \| null \| undefined`
`validationBehavior`	`native \| aria`	`"native"`
`startContent`	`ReactNode`
`endContent`	`ReactNode`
`autoFocus`	`boolean`	`false`
`defaultFilter`	`(textValue: string, inputValue: string) => boolean`
`filterOptions`	`Intl.CollatorOptions`	`"{ sensitivity: 'base'}"`
`maxListboxHeight`	`number`	`"256"`
`itemHeight`	`number`	`"32"`
`isVirtualized`	`boolean`	`"undefined"`
`isReadOnly`	`boolean`	`false`
`isRequired`	`boolean`	`false`
`isInvalid`	`boolean`	`false`
`isDisabled`	`boolean`	`false`
`fullWidth`	`boolean`	`true`
`selectorIcon`	`ReactNode`
`clearIcon`	`ReactNode`
`showScrollIndicators`	`boolean`	`true`
`scrollRef`	`React.RefObject<HTMLElement>`
`inputProps`	`InputProps`
`popoverProps`	`PopoverProps`
`listboxProps`	`ListboxProps`
`scrollShadowProps`	`ScrollShadowProps`
`selectorButtonProps`	`ButtonProps`
`clearButtonProps`	`ButtonProps`
`isClearable`	`boolean`	`true`
`disableClearable`	`boolean`	`false`
`disableAnimation`	`boolean`	`true`
`disableSelectorIconRotation`	`boolean`	`false`
`classNames`	`Partial<Record<'base' \| 'listboxWrapper' \| 'listbox' \| 'popoverContent' \| 'endContentWrapper' \| 'clearButton' \| 'selectorButton', string>>`

自動完成事件 (Autocomplete Events)

屬性 (Prop)	類型 (Type)	預設值 (Default)
`onOpenChange`	`(isOpen: boolean, menuTrigger?: MenuTriggerAction) => void`
`onInputChange`	`(value: string) => void`
`onSelectionChange`	`(key: React.Key) => void`
`onFocus`	`(e: FocusEvent<HTMLInputElement>) => void`
`onBlur`	`(e: FocusEvent<HTMLInputElement>) => void`
`onFocusChange`	`(isFocused: boolean) => void`
`onKeyDown`	`(e: KeyboardEvent) => void`
`onKeyUp`	`(e: KeyboardEvent) => void`
`onClose`	`() => void`