自动完成API

React 自动完成组件的 API 参考文档。了解此导出模块的属性、CSS 和其他 API。

演示

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

自动完成

导入

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

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

属性

也可使用原生组件的属性。

名称	类型	默认值	描述
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'	组件的颜色。它支持那些对此组件有意义的主题颜色。要了解如何添加自己的颜色，请查看主题组件—扩展颜色。
defaultValue	任意类型	props.multiple ? [] : null	默认值。当组件不受控制时使用。
disableClearable	布尔值	false	如果为 `true`，则无法清除输入。
disableCloseOnSelect	布尔值	false	如果为 `true`，则在选择值时弹出窗口不会关闭。
disabled	布尔值	false	如果为 `true`，则组件被禁用。
disabledItemsFocusable	布尔值	false	如果为 `true`，则允许聚焦在禁用的项目上。
disableListWrap	布尔值	false	如果为 `true`，则弹出窗口中的列表框不会循环焦点。
endDecorator	节点	-	此输入的尾随装饰。
error	布尔值	false	如果为 `true`，则 `input` 将指示错误。该属性默认为从父 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	字符串	-	此属性用于帮助实现可访问性逻辑。如果您不提供 id，它将回退到随机生成的 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 元素的属性。 `option` 要渲染的选项。 `state` 组件的状态。
renderTags	函数	-	渲染选定的值。签名:`function(value: Array<t>, getTagProps: function, ownerState: object) => ReactNode` `value` 提供给组件的 `value`。 `getTagProps` 标签属性 getter。 `ownerState` Autocomplete 组件的状态。
required	布尔值	-	如果为 `true`，则 `input` 元素是必需的。该属性默认为从父 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 }	{}	用于每个内部插槽的属性。
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 }	{}	用于每个内部插槽的组件。有关更多详细信息，请参阅下面的 Slots API。
startDecorator	节点	-	此输入的前导装饰。
sx	Array<func \| object \| bool> \| func \| object	-	允许定义系统覆盖以及其他 CSS 样式的系统属性。有关更多详细信息，请参阅 `sx` 页面。
type	字符串	-	`input` 元素的类型。它应该是有效的 HTML5 输入类型。
value	任意类型	-	自动完成的值。该值必须与选项具有引用相等性才能被选中。您可以使用 `isOptionEqualToValue` 属性自定义相等行为。
variant	'outlined' \| 'plain' \| 'soft' \| 'solid'	'outlined'	要使用的全局变体。要了解如何添加自己的变体，请查看主题组件—扩展变体。

ref 被转发到根元素。

主题默认属性

您可以使用 JoyAutocomplete 通过主题更改此组件的默认属性。

插槽

要了解如何自定义插槽，请查看覆盖组件结构指南。

插槽名称	类名	默认组件	描述
root	.MuiAutocomplete-root	`'div'`	渲染根的组件。
wrapper	.MuiAutocomplete-wrapper	`'div'`	渲染 wrapper 的组件。
input	.MuiAutocomplete-input	`'input'`	渲染 input 的组件。
startDecorator	.MuiAutocomplete-startDecorator	`'div'`	渲染 start decorator 的组件。
endDecorator	.MuiAutocomplete-endDecorator	`'div'`	渲染 end decorator 的组件。
clearIndicator	.MuiAutocomplete-clearIndicator	`'button'`	渲染 clear indicator 的组件。
popupIndicator	.MuiAutocomplete-popupIndicator	`'button'`	渲染 popup indicator 的组件。
listbox	.MuiAutocomplete-listbox	`'ul'`	渲染 listbox 的组件。
option	.MuiAutocomplete-option	`'li'`	渲染 option 的组件。
loading	.MuiAutocomplete-loading	`'li'`	渲染 loading 的组件。
noOptions	.MuiAutocomplete-noOptions	`'li'`	渲染 no-options 的组件。
limitTag	.MuiAutocomplete-limitTag	`'div'`	渲染 limit tag 的组件。

CSS 类

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

类名	规则名称	描述
.Mui-disabled		如果 `disabled={true}`，则应用于根元素的类名。
.Mui-error		如果 `error={true}`，则应用于根元素的状态类。
.Mui-focused		如果组件获得焦点，则应用于根元素的类名。
.MuiAutocomplete-colorContext	colorContext	当颜色反转被触发时应用于根元素的类名。
.MuiAutocomplete-colorDanger	colorDanger	如果 `color="danger"`，则应用于根元素的类名。
.MuiAutocomplete-colorNeutral	colorNeutral	如果 `color="neutral"`，则应用于根元素的类名。
.MuiAutocomplete-colorPrimary	colorPrimary	如果 `color="primary"`，则应用于根元素的类名。
.MuiAutocomplete-colorSuccess	colorSuccess	如果 `color="success"`，则应用于根元素的类名。
.MuiAutocomplete-colorWarning	colorWarning	如果 `color="warning"`，则应用于根元素的类名。
.MuiAutocomplete-formControl	formControl	如果组件是 `FormControl` 的后代，则应用于根元素的类名。
.MuiAutocomplete-hasClearIcon	hasClearIcon	当渲染清除图标时应用的类名。
.MuiAutocomplete-hasPopupIcon	hasPopupIcon	当渲染弹出图标时应用的类名。
.MuiAutocomplete-multiple	multiple	如果 `multiple={true}`，则应用于 wrapper 元素的类名。
.MuiAutocomplete-popupIndicatorOpen	popupIndicatorOpen	如果弹出窗口打开，则应用于弹出指示器的类名。
.MuiAutocomplete-sizeLg	sizeLg	如果 `size="lg"`，则应用于根元素的类名。
.MuiAutocomplete-sizeMd	sizeMd	如果 `size="md"`，则应用于根元素的类名。
.MuiAutocomplete-sizeSm	sizeSm	如果 `size="sm"`，则应用于根元素的类名。
.MuiAutocomplete-variantOutlined	variantOutlined	如果 `variant="outlined"`，则应用于根元素的类名。
.MuiAutocomplete-variantPlain	variantPlain	如果 `variant="plain"`，则应用于根元素的类名。
.MuiAutocomplete-variantSoft	variantSoft	如果 `variant="soft"`，则应用于根元素的类名。
.MuiAutocomplete-variantSolid	variantSolid	如果 `variant="solid"`，则应用于根元素的类名。

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

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

源代码

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