Автозаполнение (Autocomplete)

Автозаполнение - это обычный текстовый ввод, дополненный панелью предлагаемых вариантов.

Виджет полезен для установки значения однострочного текстового поля в одном из двух типов сценариев:

Значение для текстового поля должно быть выбрано из заранее определенного набора допустимых значений, например, поле местоположения должно содержать допустимое имя местоположения: комбобокс.
Текстовое поле может содержать любое произвольное значение, но выгодно предложить пользователю возможные значения, например, поле поиска может предложить похожие или предыдущие поиски, чтобы сэкономить время пользователя: свободное соло.

Он должен стать улучшенной версией пакетов "react-select" и "downshift".

Комбобокс

Значение должно быть выбрано из заранее определенного набора допустимых значений.

Movie

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

Press Enter to start editing

Структура опций

По умолчанию компонент принимает следующие структуры опций:

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.

Игровая площадка

Каждый из следующих примеров демонстрирует одну из возможностей компонента Autocomplete.

disableCloseOnSelect

clearOnEscape

disableClearable

includeInputInList

flat

controlled

autoComplete

disableListWrap

openOnFocus

autoHighlight

autoSelect

disabled

disablePortal

blurOnSelect

clearOnBlur

selectOnFocus

readOnly

Выбор страны

Выберите одну из 248 стран.

Choose a country

Управляемые состояния

Компонент имеет два состояния, которыми можно управлять:

состояние "значение" с помощью комбинации свойств value/onChange. Это состояние представляет собой значение, выбранное пользователем, например, при нажатии Enter.
состояние "введенное значение" с помощью комбинации реквизитов inputValue/onInputChange. Это состояние представляет собой значение, отображаемое в текстовом поле.

value: 'Option 1'

inputValue: ''

Controllable

Свободное соло

Установите freeSolo в true, чтобы текстовое поле могло содержать любое произвольное значение.

Поле поиска

Этот реквизит предназначен для основного случая использования поискового ввода с предложениями, например, поиск Google или react-autowhatever.

freeSolo

Search input

С созданием опций

Если вы планируете использовать этот режим для комбобокса (расширенная версия элемента select), мы рекомендуем установить следующие параметры

selectOnFocus, чтобы помочь пользователю очистить выбранное значение.
clearOnBlur, чтобы помочь пользователю ввести новое значение.
handleHomeEndKeys для перемещения фокуса внутри всплывающего окна с помощью клавиш Home и End.
Последний вариант, например: Добавить "ВВЕДЕННОЕ ЗНАЧЕНИЕ".

Free solo with text demo

Можно также вывести диалоговое окно, когда пользователь хочет добавить новое значение.

Free solo dialog

Сгруппированные

Вы можете сгруппировать параметры с помощью атрибута groupBy. Если вы это сделаете, убедитесь, что опции также отсортированы по тому же измерению, по которому они сгруппированы, в противном случае вы увидите дублирующиеся заголовки.

With categories

<Autocomplete
  id="grouped-demo"
  options={options.sort((a, b) => -b.firstLetter.localeCompare(a.firstLetter))}
  groupBy={(option) => option.firstLetter}
  getOptionLabel={(option) => option.title}
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="With categories" />}
/>
<Autocomplete
  id="grouped-demo"
  options={options.sort((a, b) => -b.firstLetter.localeCompare(a.firstLetter))}
  groupBy={(option) => option.firstLetter}
  getOptionLabel={(option) => option.title}
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="With categories" />}
/>

Press Enter to start editing

Чтобы управлять отображением групп, предоставьте атрибут renderGroup. Это функция, которая принимает объект с двумя полями:

group - строка, представляющая имя группы
children - коллекция элементов списка, которые принадлежат группе.

Следующая демонстрация показывает, как использовать этот атрибут для определения пользовательской разметки и переопределения стилей групп по умолчанию:

With categories

<Autocomplete
  id="grouped-demo"
  options={options.sort((a, b) => -b.firstLetter.localeCompare(a.firstLetter))}
  groupBy={(option) => option.firstLetter}
  getOptionLabel={(option) => option.title}
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="With categories" />}
  renderGroup={(params) => (
    <li>
      <GroupHeader>{params.group}</GroupHeader>
      <GroupItems>{params.children}</GroupItems>
    </li>
  )}
/>
<Autocomplete
  id="grouped-demo"
  options={options.sort((a, b) => -b.firstLetter.localeCompare(a.firstLetter))}
  groupBy={(option) => option.firstLetter}
  getOptionLabel={(option) => option.title}
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="With categories" />}
  renderGroup={(params) => (
    <li>
      <GroupHeader>{params.group}</GroupHeader>
      <GroupItems>{params.children}</GroupItems>
    </li>
  )}
/>

Press Enter to start editing

Отключенные опции

Disabled options

<Autocomplete
  id="disabled-options-demo"
  options={timeSlots}
  getOptionDisabled={(option) =>
    option === timeSlots[0] || option === timeSlots[2]
  }
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="Disabled options" />}
/>
<Autocomplete
  id="disabled-options-demo"
  options={timeSlots}
  getOptionDisabled={(option) =>
    option === timeSlots[0] || option === timeSlots[2]
  }
  sx={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="Disabled options" />}
/>

Press Enter to start editing

`useAutocomplete`.

Для расширенной настройки используется headless хук useAutocomplete(). Он принимает почти те же параметры, что и компонент Autocomplete, за вычетом всех реквизитов. связанные с рендерингом JSX. Компонент Autocomplete построен на этом хуке.

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

Хук useAutocomplete также реэкспортирован из @mui/material для удобства и обратной совместимости.

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

📦 4.5 kB в сжатом виде.

useAutocomplete

Хук с настройками

Customized hook

The Godfather

Перейдите в раздел Кастомизация для примера с компонентом Autocomplete вместо хука.

Асинхронные запросы

Компонент поддерживает два различных случая асинхронного использования:

Загрузка при открытии: он ждет, пока компонент, с которым взаимодействуют, загрузит опции.
Поиск по мере ввода текста: при каждом нажатии клавиши выполняется новый запрос.

Загрузка при открытии

Он отображает состояние выполнения, пока запрос сети находится на рассмотрении.

Asynchronous

Поиск по мере ввода

Если ваша логика заключается в получении новых вариантов при каждом нажатии клавиши и использовании текущего значения текстового поля для фильтрации на сервере, вам стоит подумать о дросселировании запросов.

Кроме того, вам нужно отключить встроенную фильтрацию компонента Autocomplete путем переопределив атрибут filterOptions:

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

Google Maps

Настроенный интерфейс для автозаполнения мест из Google Maps. Для этого демо нам необходимо загрузить Google Maps JavaScript и Google Places API.

Add a location

Множественные значения

Также известны как теги, пользователю разрешается вводить более одного значения.

Multiple values

Inception

filterSelectedOptions

Inception

freeSolo

Inception

readOnly

Forrest Gump

Inception

Фиксированные опции

В случае, если вам нужно заблокировать определенные теги, чтобы их нельзя было удалить, вы можете установить отключение фишек.

Fixed tag

Pulp Fiction

Inception

Галочки

Checkboxes

Ограничение тегов

Вы можете использовать параметр limitTags, чтобы ограничить количество отображаемых опций, когда они не сфокусированы.

limitTags

Inception

Forrest Gump

<Autocomplete
  multiple
  limitTags={2}
  id="multiple-limit-tags"
  options={top100Films()}
  getOptionLabel={(option) => option.title}
  defaultValue={[top100Films()[13], top100Films()[12], top100Films()[11]]}
  renderInput={(params) => (
    <TextField {...params} label="limitTags" placeholder="Favorites" />
  )}
  sx={{ width: '500px' }}
/>
<Autocomplete
  multiple
  limitTags={2}
  id="multiple-limit-tags"
  options={top100Films()}
  getOptionLabel={(option) => option.title}
  defaultValue={[top100Films()[13], top100Films()[12], top100Films()[11]]}
  renderInput={(params) => (
    <TextField {...params} label="limitTags" placeholder="Favorites" />
  )}
  sx={{ width: '500px' }}
/>

Press Enter to start editing

Размеры

Вам нравятся маленькие поля для ввода? Используйте параметр size.

Size small

Inception

Size small

Inception

Size small

Inception

Кастомизация

Выбор элемента для поля ввода

Реквизит renderInput позволяет вам настраивать отображаемое поле для ввода. Первый аргумент этого реквизита render содержит реквизиты, которые вам необходимо переслать. Обратите особое внимание на ключи ref и inputProps.

Value:

Ярлыки как на GitHub

Эта демонстрация воспроизводит подборщик ярлыков GitHub:

help wanted

type: bug

Перейдите в раздел Customized hook для примера настройки с хуком useAutocomplete вместо компонента.

Выделение

Следующая демонстрация основана на autosuggest-highlight, небольшой (1 кБ) утилите для выделения текста в компонентах autosuggest и autocomplete.

Highlights

Пользовательский фильтр

Компонент предоставляет фабрику для создания метода фильтра, который может быть предоставлен в свойстве filterOptions. Вы можете использовать его для изменения поведения фильтра опций по умолчанию.

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

TODOTRAN доперевести

`createFilterOptions(config) => filterOptions`

Arguments

config (object [optional]):

config.ignoreAccents (bool [optional]): Defaults to true. Remove diacritics.
config.ignoreCase (bool [optional]): Defaults to true. Lowercase everything.
config.limit (number [optional]): Default to null. Limit the number of suggested options to be shown. For example, if config.limit is 100, only the first 100 matching options are shown. It can be useful if a lot of options match and virtualization wasn't set up.
config.matchFrom ('any' | 'start' [optional]): Defaults to 'any'.
config.stringify (func [optional]): Controls how an option is converted into a string so that it can be matched against the input text fragment.
config.trim (bool [optional]): Defaults to false. Remove trailing spaces.

Returns

filterOptions: the returned filter method can be provided directly to the filterOptions prop of the Autocomplete component, or the parameter of the same name for the hook.

In the following demo, the options need to start with the query prefix:

const filterOptions = createFilterOptions({
  matchFrom: 'start',
  stringify: (option) => option.title,
});

<Autocomplete filterOptions={filterOptions} />;

Custom filter

Advanced

For richer filtering mechanisms, like fuzzy matching, it's recommended to look at match-sorter. For instance:

import { matchSorter } from 'match-sorter';

const filterOptions = (options, { inputValue }) => matchSorter(options, inputValue);

<Autocomplete filterOptions={filterOptions} />;

Virtualization

Search within 10,000 randomly generated options. The list is virtualized thanks to react-window.

10,000 options

<Autocomplete
  id="virtualize-demo"
  sx={{ width: 300 }}
  disableListWrap
  PopperComponent={StyledPopper}
  ListboxComponent={ListboxComponent}
  options={OPTIONS}
  groupBy={(option) => option[0].toUpperCase()}
  renderInput={(params) => <TextField {...params} label="10,000 options" />}
  renderOption={(props, option) => [props, option] as React.ReactNode}
  // TODO: Post React 18 update - validate this conversion, look like a hidden bug
  renderGroup={(params) => params as unknown as React.ReactNode}
/>
<Autocomplete
  id="virtualize-demo"
  sx={{ width: 300 }}
  disableListWrap
  PopperComponent={StyledPopper}
  ListboxComponent={ListboxComponent}
  options={OPTIONS}
  groupBy={(option) => option[0].toUpperCase()}
  renderInput={(params) => <TextField {...params} label="10,000 options" />}
  renderOption={(props, option) => [props, option] as React.ReactNode}
  // TODO: Post React 18 update - validate this conversion, look like a hidden bug
  renderGroup={(params) => params as unknown as React.ReactNode}
/>

Press Enter to start editing

Events

If you would like to prevent the default key handler behavior, you can set the event's defaultMuiPrevented property to true:

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

Limitations

autocomplete/autofill

Browsers have heuristics to help the user fill in form inputs. However, this can harm the UX of the component.

By default, the component disables the input autocomplete feature (remembering what the user has typed for a given field in a previous session) with the autoComplete="off" attribute. Google Chrome does not currently support this attribute setting (Issue 587466). A possible workaround is to remove the id to have the component generate a random one.

In addition to remembering past entered values, the browser might also propose autofill suggestions (saved login, address, or payment details). In the event you want the avoid autofill, you can try the following:

Name the input without leaking any information the browser can use. e.g. id="field1" instead of id="country". If you leave the id empty, the component uses a random id.

Set autoComplete="new-password" (some browsers will suggest a strong password for inputs with this attribute setting):

<TextField
  {...params}
  inputProps={{
    ...params.inputProps,
    autoComplete: 'new-password',
  }}
/>

Read the guide on MDN for more details.

iOS VoiceOver

VoiceOver on iOS Safari doesn't support the aria-owns attribute very well. You can work around the issue with the disablePortal prop.

ListboxComponent

If you provide a custom ListboxComponent prop, you need to make sure that the intended scroll container has the role attribute set to listbox. This ensures the correct behavior of the scroll, for example when using the keyboard to navigate.

Accessibility

(WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)

We encourage the usage of a label for the textbox. The component implements the WAI-ARIA authoring practices.

Автозаполнение (Autocomplete)

Комбобокс

Структура опций

Игровая площадка

Выбор страны

Управляемые состояния

Свободное соло

Поле поиска

С созданием опций

Сгруппированные

Отключенные опции

useAutocomplete.

Хук с настройками

Асинхронные запросы

Загрузка при открытии

Поиск по мере ввода

Google Maps

Множественные значения

Фиксированные опции

Галочки

Ограничение тегов

Размеры

Кастомизация

Выбор элемента для поля ввода

Ярлыки как на GitHub

Выделение

Пользовательский фильтр

createFilterOptions(config) => filterOptions

Arguments

Returns

Advanced

Virtualization

Events

Limitations

autocomplete/autofill

iOS VoiceOver

ListboxComponent

Accessibility

API

`useAutocomplete`.

`createFilterOptions(config) => filterOptions`