Внести вклад
Подробные руководства
Angular Aria

Autocomplete

Обзор

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

Использование

Autocomplete лучше всего подходит, когда пользователям нужно выбрать из большого набора опций, где ввод быстрее прокрутки. Рассмотрите autocomplete, когда:

  • Список опций длинный (больше 20 элементов) — ввод сужает выбор быстрее, чем прокрутка dropdown
  • Пользователи знают, что ищут — могут ввести часть ожидаемого значения (имя штата, продукт, username)
  • Опции следуют предсказуемым паттернам — пользователи могут угадать частичные совпадения (коды стран, email-домены, категории)
  • Важна скорость — формы выигрывают от быстрого выбора без обширной навигации

Избегайте autocomplete, когда:

  • В списке меньше 10 опций — обычный dropdown или radio group даёт лучшую видимость
  • Пользователям нужно просматривать опции — если важен discovery, покажите все опции сразу
  • Опции незнакомы — пользователи не могут ввести то, о чём не знают, что оно есть в списке

Возможности

Autocomplete Angular предоставляет полностью доступную реализацию combobox с:

  • Клавиатурной навигацией — перемещение по опциям стрелками, выбор Enter, закрытие Escape
  • Поддержкой screen reader — встроенные ARIA-атрибуты для вспомогательных технологий
  • Динамическим highlight-поведением — встроенная поддержка inline-предложений выбора
  • Signal-based реактивностью — реактивное управление состоянием через сигналы Angular
  • Интеграцией Popover API — использует нативный HTML Popover API для оптимального позиционирования
  • Поддержкой двунаправленного текста — автоматическая обработка языков справа налево (RTL)

Примеры

Режим auto-select

Пользователи, вводящие частичный текст, ожидают немедленного подтверждения, что их ввод совпадает с доступной опцией. Режим auto-select обновляет значение input, чтобы оно совпадало с первой отфильтрованной опцией по мере ввода, сокращая число нажатий клавиш и давая мгновенную обратную связь, что поиск идёт в верном направлении.

Режим ручного выбора

Режим ручного выбора сохраняет введённый текст без изменений, пока пользователи перемещаются по списку предложений, предотвращая путаницу от автоматических обновлений. Input меняется только когда пользователи явно подтверждают выбор Enter или кликом.

Режим highlight

Режим highlight позволяет пользователю перемещаться по опциям стрелками без изменения значения input при просмотре, пока явно не выберут новую опцию Enter или кликом.

Интеграция с Signal Forms

Angular Aria бесшовно интегрируется с signal-based API Signal Forms. Сложные inputs можно инкапсулировать в переиспользуемые кастомные control-компоненты, реализующие FormValueControl.

Следующий пример демонстрирует компонент выбора страны, реализующий FormValueControl<string>, привязанный к родительской форме через [formField] и защищённый правилами валидации схемы.

Тестирование

Паттерн autocomplete можно тестировать комбинацией ComboboxHarness и ListboxHarness из @angular/aria/combobox/testing и @angular/aria/listbox/testing. Пример использования harnesses для тестирования компонента autocomplete:

import {ComponentFixture, TestBed} from '@angular/core/testing';
import {HarnessLoader} from '@angular/cdk/testing';
import {TestbedHarnessEnvironment} from '@angular/cdk/testing/testbed';
import {ComboboxHarness} from '@angular/aria/combobox/testing';
import {ListboxHarness} from '@angular/aria/listbox/testing';
import {MyAutocompleteComponent} from './my-autocomplete'; // Your component

describe('MyAutocompleteComponent', () => {
  let fixture: ComponentFixture<MyAutocompleteComponent>;
  let loader: HarnessLoader;

  beforeEach(async () => {
    TestBed.configureTestingModule({
      imports: [MyAutocompleteComponent],
    });

    fixture = TestBed.createComponent(MyAutocompleteComponent);
    await fixture.whenStable();
    loader = TestbedHarnessEnvironment.loader(fixture);
  });

  it('should filter options based on input', async () => {
    const combobox = await loader.getHarness(ComboboxHarness);

    // Type in the input to trigger filtering
    await combobox.setValue('ap');
    expect(await combobox.isOpen()).toBe(true);

    // Get the listbox harness from the popup
    const listbox = await combobox.getPopupWidget(ListboxHarness);
    const options = await listbox.getOptions();

    // Verify options are filtered (e.g., 'Apple', 'Apricot')
    expect(options.length).toBe(2);
    expect(await options[0].getText()).toBe('Apple');

    // Select the first option
    await options[0].click();

    // Verify the input value is updated and popup is closed
    expect(await combobox.isOpen()).toBe(false);
    expect(await combobox.getValue()).toBe('Apple');
  });
});

API reference

Подробную API-документацию смотрите в следующих API reference: