自动完成

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

这个小部件在两种类型的场景中用于设置单行文本框的值非常有用

文本框的值必须从预定义的允许值集中选择，例如，位置字段必须包含有效的地点名称：组合框。
文本框可以包含任何任意值，但建议向用户提供可能的值是有利的，例如，搜索字段可以建议相似或以前的搜索，以节省用户时间：自由独奏。

它旨在成为 "react-select" 和 "downshift" 包的改进版本。

组合框

值必须从预定义的允许值集中选择。

电影

<Autocomplete
  disablePortal
  options={top100Films}
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="Movie" />}
/>

<Autocomplete
  disablePortal
  options={top100Films}
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="Movie" />}
/>

按 Enter 开始编辑

选项结构

默认情况下，组件接受以下选项结构

interface AutocompleteOption {
  label: string;
}
// or
type AutocompleteOption = string;

例如

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

但是，您可以通过提供 getOptionLabel 属性来使用不同的结构。

如果您的选项是对象，您必须提供 isOptionEqualToValue 属性以确保正确的选择和高亮显示。默认情况下，它使用严格相等性来比较选项与当前值。

演示

以下每个示例都演示了 Autocomplete 组件的一个功能。

disableCloseOnSelect

clearOnEscape

disableClearable

includeInputInList

flat

受控

autoComplete

disableListWrap

openOnFocus

autoHighlight

autoSelect

禁用

disablePortal

blurOnSelect

clearOnBlur

selectOnFocus

只读

受控状态

该组件有两种状态可以被控制

“value” 状态，使用 value/onChange 属性组合。此状态表示用户选择的值，例如在按下 Enter 时。
“input value” 状态，使用 inputValue/onInputChange 属性组合。此状态表示文本框中显示的值。

这两个状态是隔离的，应该独立控制。

value: '选项 1'

inputValue: ''

可控

如果您控制 value，请确保它在渲染之间是引用稳定的。换句话说，如果值本身没有更改，则对值的引用不应更改。

// ⚠️ BAD
return <Autocomplete multiple value={allValues.filter((v) => v.selected)} />;

// 👍 GOOD
const selectedValues = React.useMemo(
  () => allValues.filter((v) => v.selected),
  [allValues],
);
return <Autocomplete multiple value={selectedValues} />;

在第一个示例中，allValues.filter 被调用，并在每次渲染时返回一个新数组。修复方法包括记忆值，以便仅在需要时才更改它。

自由独奏

将 freeSolo 设置为 true，以便文本框可以包含任何任意值。

搜索输入

此属性旨在涵盖带有建议的搜索输入的主要用例，例如 Google 搜索或 react-autowhatever。

freeSolo

搜索输入

可创建

如果您打算将此模式用于类似组合框的体验（select 元素的增强版本），我们建议设置

selectOnFocus 以帮助用户清除所选值。
clearOnBlur 以帮助用户输入新值。
handleHomeEndKeys 以使用 Home 和 End 键将焦点移动到弹出窗口内。
最后一个选项，例如：添加 “您的搜索”。

带有文本演示的自由独奏

当用户想要添加新值时，您也可以显示一个对话框。

自由独奏对话框

`useAutocomplete`

对于高级自定义用例，公开了一个无头的 useAutocomplete() 钩子。它接受与 Autocomplete 组件几乎相同的选项，减去所有与 JSX 渲染相关的属性。Autocomplete 组件是基于此钩子构建的。

import { useAutocomplete } from '@mui/base/useAutocomplete';

为了方便和向后兼容性，useAutocomplete 钩子也从 @mui/material 重新导出。

import useAutocomplete from '@mui/material/useAutocomplete';

📦 4.6 kB gzipped。

useAutocomplete

异步请求

该组件支持两种不同的异步用例

打开时加载：它等待组件被交互以加载选项。
边输入边搜索：每次击键都会发出新请求。

边输入边搜索

如果您的逻辑是在每次击键时获取新选项并使用文本框的当前值在服务器上进行过滤，您可能需要考虑限制请求。

此外，您将需要通过覆盖 filterOptions 属性来禁用 Autocomplete 组件的内置过滤。

<Autocomplete filterOptions={(x) => x} />

Google 地图地点

Google 地图地点自动完成的自定义 UI。对于此演示，我们需要加载 Google Maps JavaScript 和 Google Places API。

添加位置

该演示依赖于 autosuggest-highlight，一个小的 (1 kB) 实用程序，用于突出显示自动建议和自动完成组件中的文本。

尺寸

想要更小的输入框？使用 size 属性。

小尺寸

盗梦空间

小尺寸

盗梦空间

小尺寸

盗梦空间

自定义

自定义输入

renderInput 属性允许您自定义渲染的输入。此渲染属性的第一个参数包含您需要转发的属性。请特别注意 ref 和 inputProps 键。

值

要全局自定义应用程序中所有组件的 Autocomplete 选项，您可以使用主题默认属性并在 defaultProps 键中设置 renderOption 属性。renderOption 属性将 ownerState 作为第四个参数，其中包括属性和内部组件状态。要显示标签，您可以使用来自 ownerState 的 getOptionLabel 属性。这种方法可以为每个 Autocomplete 组件启用不同的选项，同时保持选项样式的一致性。

选择一部电影

选择一个国家/地区

<ThemeProvider theme={customTheme(outerTheme)}>
  <Stack spacing={5} sx={{ width: 300 }}>
    <MovieSelect />
    <CountrySelect />
  </Stack>
</ThemeProvider>

<ThemeProvider theme={customTheme(outerTheme)}>
  <Stack spacing={5} sx={{ width: 300 }}>
    <MovieSelect />
    <CountrySelect />
  </Stack>
</ThemeProvider>

按 Enter 开始编辑

GitHub 的选择器

此演示重现了 GitHub 的标签选择器

需要帮助

类型: 缺陷

前往自定义钩子部分，查看使用 useAutocomplete 钩子而不是组件的自定义示例。

提示

以下演示展示了如何向 Autocomplete 添加提示功能

电影

高亮

以下演示依赖于 autosuggest-highlight，一个小的 (1 kB) 实用程序，用于突出显示自动建议和自动完成组件中的文本。

高亮

自定义过滤器

该组件公开了一个工厂来创建一个过滤器方法，该方法可以提供给 filterOptions 属性。您可以使用它来更改默认选项过滤器行为。

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

参数

config (对象 [可选])

config.ignoreAccents (布尔值 [可选])：默认为 true。移除变音符号。
config.ignoreCase (布尔值 [可选])：默认为 true。将所有内容转换为小写。
config.limit (数字 [可选])：默认为 null。限制要显示的建议选项的数量。例如，如果 config.limit 为 100，则仅显示前 100 个匹配选项。如果有很多选项匹配并且未设置虚拟化，则它可能很有用。
config.matchFrom ('any' | 'start' [可选])：默认为 'any'。
config.stringify (函数 [可选])：控制如何将选项转换为字符串，以便可以将其与输入文本片段进行匹配。
config.trim (布尔值 [可选])：默认为 false。移除尾随空格。

返回值

filterOptions：返回的过滤器方法可以直接提供给 Autocomplete 组件的 filterOptions 属性，或者提供给钩子的同名参数。

在以下演示中，选项需要以查询前缀开头

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} />;

虚拟化

在 10,000 个随机生成的选项中搜索。列表通过 react-window 实现虚拟化。

10,000 个选项

事件

如果您想阻止默认的按键处理程序行为，您可以将事件的 defaultMuiPrevented 属性设置为 true

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

限制

autocomplete/autofill

浏览器具有启发式方法来帮助用户填写表单输入。但是，这可能会损害组件的 UX。

默认情况下，组件使用 autoComplete="off" 属性禁用输入自动完成功能（记住用户在前一个会话中为给定字段键入的内容）。Google Chrome 目前不支持此属性设置 (Issue 41239842)。一种可能的解决方法是删除 id 以使组件生成一个随机的 id。

除了记住过去输入的值之外，浏览器还可能提出自动填充建议（保存的登录名、地址或付款详细信息）。如果您想避免自动填充，可以尝试以下方法

命名输入时不要泄露浏览器可以使用的任何信息。例如，使用 id="field1" 而不是 id="country"。如果将 id 留空，组件将使用随机 id。
设置 autoComplete="new-password"（某些浏览器会为此属性设置的输入建议使用强密码）
```
<TextField
  {...params}
  inputProps={{
    ...params.inputProps,
    autoComplete: 'new-password',
  }}
/>
```

阅读 MDN 上的指南以了解更多详细信息。