自动完成API

React Autocomplete 组件的 API 参考文档。了解此导出模块的 props、CSS 和其他 API。

演示

有关此 React 组件的用法示例和详细信息，请访问组件演示页面

自动完成

导入

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

通过阅读关于最小化 bundle size 的指南，了解它们之间的区别。

Props

原生组件的 Props 也可用。

名称	类型	默认值	描述
options*	array	-	将在 Autocomplete 中显示的选项列表。
renderInput*	func	-	渲染输入框。签名：`function(params: object) => ReactNode`
autoComplete	bool	false	如果 `true`，用户尚未键入的所选建议部分（称为完成字符串）将以内联方式显示在文本框中输入光标之后。内联完成字符串在视觉上突出显示并具有选定状态。
autoHighlight	bool	false	如果 `true`，则自动高亮显示第一个选项。
autoSelect	bool	false	如果 `true`，则当 Autocomplete 失去焦点时，所选选项将成为输入框的值，除非用户选择其他选项或更改输入框中的字符串。当使用 `freeSolo` 模式时，如果 Autocomplete 失去焦点且未高亮显示任何选项，则键入的值将作为输入值。
blurOnSelect	'mouse' \| 'touch' \| bool	false	控制在选择选项时是否应模糊输入框 `false` 输入框不会被模糊。 `true` 输入框始终被模糊。 `touch` 在触摸事件后输入框被模糊。 `mouse` 在鼠标事件后输入框被模糊。
ChipProps	object	-	应用于 `Chip` 元素的 Props。已弃用－请改用 `slotProps.chip`。此 prop 将在 v7 中移除。有关更多详细信息，请参阅从已弃用的 API 迁移。
classes	object	-	覆盖或扩展应用于组件的样式。有关更多详细信息，请参阅下面的CSS 类 API。
clearIcon	node	<ClearIcon fontSize="small" />	用于替换默认清除图标的图标。
clearOnBlur	bool	!props.freeSolo	如果 `true`，则在未选择任何值的情况下，输入框的文本在失去焦点时被清除。如果您想帮助用户输入新值，请将其设置为 `true`。如果您想帮助用户恢复搜索，请将其设置为 `false`。
clearOnEscape	bool	false	如果 `true`，则在用户按下 escape 键并且弹出窗口关闭时，清除所有值。
clearText	string	'Clear'	覆盖清除图标按钮的默认文本。出于本地化目的，您可以使用提供的翻译。
closeText	string	'Close'	覆盖关闭弹出窗口图标按钮的默认文本。出于本地化目的，您可以使用提供的翻译。
componentsProps	{ clearIndicator?: object, paper?: object, popper?: object, popupIndicator?: object }	-	用于内部每个插槽的 props。已弃用－请改用 `slotProps` prop。此 prop 将在 v7 中移除。有关更多详细信息，请参阅从已弃用的 API 迁移。
defaultValue	any	props.multiple ? [] : null	默认值。当组件不受控制时使用。
disableClearable	bool	false	如果 `true`，则无法清除输入框。
disableCloseOnSelect	bool	false	如果 `true`，则在选择值时弹出窗口不会关闭。
disabled	bool	false	如果 `true`，则组件被禁用。
disabledItemsFocusable	bool	false	如果 `true`，则允许聚焦在禁用的项目上。
disableListWrap	bool	false	如果 `true`，则弹出窗口中的列表框不会循环聚焦。
disablePortal	bool	false	如果 `true`，则 `Popper` 内容将位于父组件的 DOM 层次结构下。
filterOptions	func	createFilterOptions()	确定要在搜索时渲染的已过滤选项的函数。签名：`function(options: Array, state: object) => Array` `options` 要渲染的选项。 `state` 组件的状态。
filterSelectedOptions	bool	false	如果 `true`，则从列表框中隐藏已选定的选项。
forcePopupIcon	'auto' \| bool	'auto'	强制弹出图标的可见性显示。
freeSolo	bool	false	如果 `true`，则 Autocomplete 处于 free solo 模式，这意味着用户输入不受提供的选项的约束。
fullWidth	bool	false	如果 `true`，则输入框将占据其容器的全部宽度。
getLimitTagsText	func	(more) => `+${more}`	当标签被截断 (`limitTags`) 时显示的标签。签名：`function(more: number) => ReactNode` `more` 截断标签的数量。
getOptionDisabled	func	-	用于确定给定选项的禁用状态。签名：`function(option: Value) => boolean` `option` 要测试的选项。
getOptionKey	func	-	用于确定给定选项的键。当选项的标签不是唯一的（因为默认情况下标签用作键）时，这可能很有用。签名：`function(option: Value) => string \| number` `option` 要获取键的选项。
getOptionLabel	func	(option) => option.label ?? option	用于确定给定选项的字符串值。它用于填充输入框（以及列表框选项，如果未提供 `renderOption`）。如果在 free solo 模式下使用，它必须接受选项类型和字符串。签名：`function(option: Value) => string`
groupBy	func	-	如果提供，选项将分组在返回的字符串下。当未提供 `renderGroup` 时，groupBy 值也用作组标题的文本。签名：`function(option: Value) => string` `option` Autocomplete 选项。
handleHomeEndKeys	bool	!props.freeSolo	如果 `true`，则当弹出窗口打开时，组件处理 "Home" 和 "End" 键。它应分别将焦点移动到第一个选项和最后一个选项。
id	string	-	此 prop 用于帮助实现可访问性逻辑。如果您不提供 id，它将回退到随机生成的 id。
includeInputInList	bool	false	如果 `true`，则高亮显示可以移动到输入框。
inputValue	string	-	输入值。
isOptionEqualToValue	func	-	用于确定选项是否表示给定的值。默认情况下使用严格相等。⚠️ 需要处理两个参数，一个选项只能与一个值匹配。签名：`function(option: Value, value: Value) => boolean` `option` 要测试的选项。 `value` 要测试的值。
limitTags	integer	-1	未聚焦时将可见的最大标签数。设置 `-1` 以禁用限制。
ListboxComponent	elementType	'ul'	用于渲染列表框的组件。已弃用－请改用 `slotProps.listbox.component`。此 prop 将在 v7 中移除。有关更多详细信息，请参阅从已弃用的 API 迁移。
ListboxProps	object	-	应用于 Listbox 元素的 Props。已弃用－请改用 `slotProps.listbox`。此 prop 将在 v7 中移除。有关更多详细信息，请参阅从已弃用的 API 迁移。
loading	bool	false	如果 `true`，则组件处于加载状态。这会在没有建议显示时（仅当没有建议显示时，例如 `options` 为空）显示 `loadingText`。
loadingText	node	'Loading…'	在加载状态下显示的文本。出于本地化目的，您可以使用提供的翻译。
multiple	bool	false	如果 `true`，则 `value` 必须是一个数组，并且菜单将支持多选。
noOptionsText	node	'No options'	在没有选项时显示的文本。出于本地化目的，您可以使用提供的翻译。
onChange	func	-	当值更改时触发的回调。签名：`function(event: React.SyntheticEvent, value: Value \| Array, reason: string, details?: string) => void` `event` 回调的事件源。 `value` 组件的新值。 `reason` "createOption"、"selectOption"、"removeOption"、"blur" 或 "clear" 之一。
onClose	func	-	当弹出窗口请求关闭时触发的回调。在受控模式下使用（请参阅 open）。签名：`function(event: React.SyntheticEvent, reason: string) => void` `event` 回调的事件源。 `reason` 可以是：`"toggleInput"`、`"escape"`、`"selectOption"`、`"removeOption"`、`"blur"`。
onHighlightChange	func	-	当高亮显示选项更改时触发的回调。签名：`function(event: React.SyntheticEvent, option: Value, reason: string) => void` `event` 回调的事件源。 `option` 高亮显示的选项。 `reason` 可以是：`"keyboard"`、`"mouse"`、`"touch"`。
onInputChange	func	-	当输入值更改时触发的回调。签名：`function(event: React.SyntheticEvent, value: string, reason: string) => void` `event` 回调的事件源。 `value` 文本输入框的新值。 `reason` 可以是：`"input"`（用户输入）、`"reset"`（程序化更改）、`"clear"`、`"blur"`、`"selectOption"`、`"removeOption"`
onOpen	func	-	当弹出窗口请求打开时触发的回调。在受控模式下使用（请参阅 open）。签名：`function(event: React.SyntheticEvent) => void` `event` 回调的事件源。
open	bool	-	如果 `true`，则组件显示。
openOnFocus	bool	false	如果 `true`，则弹出窗口将在输入框聚焦时打开。
openText	string	'Open'	覆盖打开弹出窗口图标按钮的默认文本。出于本地化目的，您可以使用提供的翻译。
PaperComponent	elementType	纸张	用于渲染弹出窗口主体的组件。已弃用－请改用 `slots.paper`。此 prop 将在 v7 中移除。有关更多详细信息，请参阅从已弃用的 API 迁移。
PopperComponent	elementType	Popper	用于定位弹出窗口的组件。已弃用－请改用 `slots.popper`。此 prop 将在 v7 中移除。有关更多详细信息，请参阅从已弃用的 API 迁移。
popupIcon	node	<ArrowDropDownIcon />	用于替换默认弹出图标的图标。
readOnly	bool	false	如果 `true`，则组件变为只读。多标签也支持此属性，其中标签无法删除。
renderGroup	func	-	渲染组。签名：`function(params: AutocompleteRenderGroupParams) => ReactNode` `params` 要渲染的组。
renderOption	func	-	渲染选项，默认使用 `getOptionLabel`。签名：`function(props: object, option: Value, state: object, ownerState: object) => ReactNode` `props` 要应用于 li 元素的 props。 `option` 要渲染的选项。 `state` 每个选项的状态。 `ownerState` Autocomplete 组件的状态。
renderTags	func	-	渲染选定的值。签名：`function(value: Array, getTagProps: function, ownerState: object) => ReactNode` `value` 提供给组件的 `value`。 `getTagProps` 标签 props 获取器。 `ownerState` Autocomplete 组件的状态。
selectOnFocus	bool	!props.freeSolo	如果 `true`，则输入框的文本在聚焦时被选中。这有助于用户清除选定的值。
size	'small' \| 'medium' \| string	'medium'	组件的尺寸。
slotProps	{ chip?: func \| object, clearIndicator?: func \| object, listbox?: func \| object, paper?: func \| object, popper?: func \| object, popupIndicator?: func \| object }	{}	用于内部每个插槽的 props。
slots	{ listbox?: elementType, paper?: elementType, popper?: elementType }	{}	用于内部每个插槽的组件。
sx	Array<func \| object \| bool> \| func \| object	-	允许定义系统覆盖以及其他 CSS 样式的系统 prop。有关更多详细信息，请参阅`sx` 页面。
value	any	-	autocomplete 的值。该值必须与选项具有引用相等性才能被选中。您可以使用 `isOptionEqualToValue` prop 自定义相等行为。

该组件不能持有 ref。

主题默认 Props

您可以使用 MuiAutocomplete 通过主题更改此组件的默认 props。

插槽

插槽名称	类名	默认组件	描述
listbox	.MuiAutocomplete-listbox	`'ul'`	用于渲染列表框的组件。
paper	.MuiAutocomplete-paper	`纸张`	用于渲染弹出窗口主体的组件。
popper	.MuiAutocomplete-popper	`Popper`	用于定位弹出窗口的组件。

CSS 类

这些类名对于使用 CSS 设置样式很有用。当触发特定状态时，它们将应用于组件的插槽。

类名	规则名称	描述
.Mui-expanded		如果显示列表框，则应用于根元素的状态类。
.Mui-focused		如果聚焦，则应用于根元素的状态类。
.Mui-focusVisible		如果选项元素通过键盘聚焦，则应用于选项元素的样式。
.MuiAutocomplete-clearIndicator	clearIndicator	应用于清除指示器的样式。
.MuiAutocomplete-endAdornment	endAdornment	应用于 endAdornment 元素的样式。
.MuiAutocomplete-fullWidth	fullWidth	如果 `fullWidth={true}`，则应用于根元素的样式。
.MuiAutocomplete-groupLabel	groupLabel	应用于组标签元素的样式。
.MuiAutocomplete-groupUl	groupUl	应用于组 ul 元素的样式。
.MuiAutocomplete-hasClearIcon	hasClearIcon	当渲染清除图标时应用的样式。
.MuiAutocomplete-hasPopupIcon	hasPopupIcon	当渲染弹出图标时应用的样式。
.MuiAutocomplete-input	input	应用于输入框元素的样式。
.MuiAutocomplete-inputFocused	inputFocused	如果输入框聚焦，则应用于输入框元素的样式。
.MuiAutocomplete-inputRoot	inputRoot	应用于 Input 元素的样式。
.MuiAutocomplete-loading	loading	应用于加载包装器的样式。
.MuiAutocomplete-noOptions	noOptions	应用于无选项包装器的样式。
.MuiAutocomplete-option	option	应用于选项元素的样式。
.MuiAutocomplete-popperDisablePortal	popperDisablePortal	如果 `disablePortal={true}`，则应用于 popper 元素的样式。
.MuiAutocomplete-popupIndicator	popupIndicator	应用于弹出指示器的样式。
.MuiAutocomplete-popupIndicatorOpen	popupIndicatorOpen	如果弹出窗口打开，则应用于弹出指示器的样式。
.MuiAutocomplete-root	root	应用于根元素的样式。
.MuiAutocomplete-tag	tag	应用于标签元素的样式，例如纸片。
.MuiAutocomplete-tagSizeMedium	tagSizeMedium	应用于标签元素的样式，例如纸片，如果 `size="medium"`。
.MuiAutocomplete-tagSizeSmall	tagSizeSmall	应用于标签元素的样式，例如纸片，如果 `size="small"`。

您可以使用以下自定义选项之一覆盖组件的样式

使用全局类名。
使用规则名称作为自定义主题中组件的 styleOverrides 属性的一部分。

源代码

如果您在此页面中找不到信息，请考虑查看组件的实现以获取更多详细信息。