Autocomplete

自动完成组件是一个文本输入框，通过建议选项面板进行增强。

useAutocomplete API

导入

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	-	正在使用此钩子的组件名称。用于警告。
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	-	此属性用于帮助实现可访问性逻辑。如果您不提供 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>	-	autocomplete 的值。该值必须与选项具有引用相等性才能被选中。您可以使用 `isOptionEqualToValue` 属性自定义相等性行为。

返回值

名称	类型	描述
anchorEl	null \| HTMLElement	用于设置组件位置的 HTML 元素。
dirty	boolean	如果 `true`，则组件输入框有一些值。
expanded	boolean	如果 `true`，则列表框正在显示。
focused	boolean	如果 `true`，则组件已聚焦。
focusedTag	number	组件的聚焦标签的索引。
getClearProps	() => React.HTMLAttributes<HTMLButtonElement>	清除按钮元素属性的解析器。
getInputLabelProps	() => Omit<React.HTMLAttributes<HTMLLabelElement>, 'color'>	输入标签元素属性的解析器。
getInputProps	() => React.InputHTMLAttributes<HTMLInputElement> & { ref: React.Ref<HTMLInputElement> }	输入元素属性的解析器。
getListboxProps	() => React.HTMLAttributes<HTMLUListElement>	列表框组件属性的解析器。
getOptionProps	(renderedOption: UseAutocompleteRenderedOption<Value>) => React.HTMLAttributes<HTMLLIElement> & { key: any }	渲染选项元素属性的解析器。
getPopupIndicatorProps	() => React.HTMLAttributes<HTMLButtonElement>	弹出窗口图标属性的解析器。
getRootProps	(externalProps?: any) => React.HTMLAttributes<HTMLDivElement>	根槽属性的解析器。
getTagProps	AutocompleteGetTagProps	标签属性 getter。
groupedOptions	Value[] \| Array<AutocompleteGroupedOption<Value>>	要渲染的选项。如果提供了 groupBy 属性，则为 `Value[]` 或 `AutocompleteGroupedOption<Value>[]`。
id	string	Autocomplete 的 ID。
inputValue	string	输入值。
popupOpen	boolean	如果 `true`，则弹出窗口在组件上打开。
setAnchorEl	() => void	组件 `anchorEl` 的设置器。
value	AutocompleteValue<Value, Multiple, DisableClearable, FreeSolo>	autocomplete 的值。