Перейти к контенту

🎉 Material UI v5 is out! Head to the migration guide to get started.

Редактировать эту страницу

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

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

Этот виджет используется для установки значения однострочного текстового поля. Он полезен в одном из двух случев:

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

It's meant to be an improved version of the "react-select" and "downshift" packages.

Комбо-Бокс

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

<Autocomplete
  id="combo-box-demo"
  options={top100Films}
  getOptionLabel={(option) => option.title}
  style={{ width: 300 }}
  renderInput={(params) => <TextField {...params} label="Combo box" variant="outlined" />}
/>

Песочница

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

Выбор страны

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

Controllable states

The component has two states that can be controlled:

  1. the "value" state with the value/onChange props combination. This state represents the value selected by the user, for instance when pressing Enter.
  2. the "input value" state with the inputValue/onInputChange props combination. This state represents the value displayed in the textbox.

⚠️ These two state are isolated, they should be controlled independently.

value: 'Option 1'
inputValue: ''

Произвольное значение

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

Ввод для поиска

The prop is designed to cover the primary use case of a search input with suggestions, e.g. Google search or react-autowhatever.

Создаваемый

If you intend to use this mode for a combo box like experience (an enhanced version of a select element) we recommend setting:

  • selectOnFocus to helps the user clear the selected value.
  • clearOnBlur to helps the user to enter a new value.
  • handleHomeEndKeys to move focus inside the popup with the Home and End keys.
  • A last option, for instance Add "YOUR SEARCH".

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

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

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

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

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

useAutocomplete

Для продвинутой кастомизации используйте хук useAutocomplete(). It accepts almost the same options as the Autocomplete component minus all the props related to the rendering of JSX. The Autocomplete component uses this hook internally.

import useAutocomplete from '@material-ui/lab/useAutocomplete';

Customized hook

Head to the Customized Autocomplete section for a customization example with the Autocomplete component instead of the hook.

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

Места Google Maps

A customized UI for Google Maps Places Autocomplete.

For this demo, we need to load the Google Maps JavaScript API.

⚠️ Перед началом использования API карт Google, JavaScript необходимо зарегистрировать и создать учетную запись для выставления счетов.

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

Also known as tags, the user is allowed to enter more than one value.

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

В случае, если вам нужно зафиксировать определенный тег (так что он не мог быть удалён через интерфейс), вы можете установить chips в состояние disabled.

Чекбоксы

Limit tags

You can use the limitTags prop to limit the number of displayed options when not focused.

<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} variant="outlined" label="limitTags" placeholder="Favorites" />
  )}
/>

Размеры

Fancy smaller inputs? Use the size prop.

Customizations

Custom input

The renderInput prop allows you to customize the rendered input. The first argument of this render prop contains props that you need to forward. Pay specific attention to the ref and inputProps keys.

<Autocomplete
  id="custom-input-demo"
  options={options}
  renderInput={(params) => (
    <div ref={params.InputProps.ref}>
      <input style={{ width: 200 }} type="text" {...params.inputProps} />
    </div>
  )}
/>

GitHub's picker

Эта демо-версия показывает label picker с сайта GitHub:

help wanted
type: bug

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

Основные моменты

The following demo relies on autosuggest-highlight, a small (1 kB) utility for highlighting text in autosuggest and autocomplete components.

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

The component exposes a factory to create a filter method that can provided to the filterOptions prop. You can use it to change the default option filter behavior.

import { createFilterOptions } from '@material-ui/lab/Autocomplete';

createFilterOptions(config) => filterOptions

Аргументы

  1. config (Object [optional]):
    • config.ignoreAccents (Boolean [optional]): Defaults to true. Remove diacritics.
    • config.ignoreCase (Boolean [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 (Boolean [optional]): По умолчанию - false. Remove trailing spaces.

Возвращает

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

Дополнительные параметры

For richer filtering mechanisms, like fuzzy matching, it's recommended to look at match-sorter. Например:

import matchSorter from 'match-sorter';

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

<Autocomplete filterOptions={filterOptions} />

Виртуализация

Поиск в 10000 случайно сгенерированных опций. Список виртуализирован благодаря реагирующему окну.

<Autocomplete
  id="virtualize-demo"
  style={{ width: 300 }}
  disableListWrap
  classes={classes}
  ListboxComponent={ListboxComponent}
  renderGroup={renderGroup}
  options={OPTIONS}
  groupBy={(option) => option[0].toUpperCase()}
  renderInput={(params) => <TextField {...params} variant="outlined" label="10,000 options" />}
  renderOption={(option) => <Typography noWrap>{option}</Typography>}
/>

Ограничения

Автозаполнение

The browsers have heuristics to help the users fill the form inputs. However, it can harm the UX of the component.

By default, the component disable the autocomplete feature (remembering what the user has typed for a given field in a previous session) with the autoComplete="off" attribute.

Однако, помимо запоминания введенных ранее значений браузер может также предложить автозаполнение (сохраненный логин, адрес или платежная информация). 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": jsx Set autoComplete="new-password": jsx Set autoComplete="new-password": jsx Set autoComplete="new-password": jsx Set `autoComplete="new-password": 
      jsx` 
  Set <code>autoComplete="new-password": 
      jsx</code>

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.

Доступность

(WAI-ARIA: https://www.w3.org/TR/wai-aria-practices/#combobox)

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

API