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

Combobox

Обзор

Директива, координирующая trigger-элемент (текстовый input, кнопку или div) с popup — примитивная директива для паттернов autocomplete, select и multiselect.

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

Combobox — примитивная директива, координирующая интерактивный trigger-элемент (текстовый input, кнопку или div) с popup. Она даёт основу для паттернов autocomplete, select и multiselect. Рассмотрите прямое использование combobox, когда:

  • Строите кастомные паттерны autocomplete — специализированная фильтрация или поведение подсказок
  • Создаёте кастомные компоненты выбора — dropdown с уникальными требованиями
  • Координируете input с popup — связываете текстовый ввод с контентом listbox, tree или dialog
  • Реализуете кастомную фильтрацию — фильтрация и оркестрация совпадающих опций в user space

Используйте задокументированные паттерны, когда:

  • Нужен стандартный autocomplete с фильтрацией — см. паттерн Autocomplete для готовых примеров
  • Нужны dropdown с одиночным выбором — см. паттерн Select для полной реализации dropdown
  • Нужны dropdown с множественным выбором — см. паттерн Multiselect для multi-select с компактным отображением

ПРИМЕЧАНИЕ: Руководства Autocomplete, Select и Multiselect показывают задокументированные паттерны, сочетающие эту директиву с Listbox для конкретных сценариев.

Возможности

Combobox Angular предоставляет полностью доступную систему координации input-popup с:

  • Trigger-элементом с popup — координация trigger-элемента с контентом popup
  • Гибкой координацией — бесшовная интеграция со стандартными layout (listbox, tree, grid или dialog)
  • Клавиатурной навигацией — обработка стрелок, Enter, Escape
  • Поддержкой screen reader — встроенные ARIA-атрибуты, включая role="combobox" и aria-expanded
  • Управлением popup — автоматический показ/скрытие на основе взаимодействия пользователя
  • Signal-based реактивностью — реактивное управление состоянием через сигналы Angular

Примеры

Autocomplete

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

Фильтрация управляется в user space обновлением сигнала, который реактивно фильтрует список опций. Пользователи перемещаются стрелками и выбирают Enter или кликом. Это даёт полный контроль и максимальную гибкость для кастомной логики выбора. Полные паттерны фильтрации и примеры — в руководстве Autocomplete.

Режим readonly

Паттерн, сочетающий readonly combobox с listbox для создания dropdown с одиночным выбором, клавиатурной навигацией и поддержкой screen reader.

Запуск dropdown без текстового ввода достигается использованием кнопки как host trigger или применением нативного HTML-атрибута readonly к input trigger. Popup открывается по клику или стрелкам.

Эта конфигурация даёт основу для паттернов Select и Multiselect. Полные реализации dropdown с triggers и позиционированием overlay — в этих руководствах.

Datepicker grid

Combobox может координироваться с двумерным grid для создания доступных datepickers. Пользователи перемещаются по датам внутри таблицы calendar grid стрелками и подтверждают выбор кликом, Enter или Spacebar.

Dialog popup

Dialog popups сочетают combobox trigger со стандартными dialog layout и focus traps (например, cdkTrapFocus CDK). Используйте dialog popups, когда overlay требует modal-поведения или взаимодействия с backdrop.

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

Angular Aria предоставляет ComboboxHarness для тестирования компонентов combobox. Пример использования harness в тесте компонента:

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 {MyComboboxComponent} from './my-combobox'; // Your component

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

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

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

  it('should allow opening and closing the popup', async () => {
    const combobox = await loader.getHarness(ComboboxHarness);

    // Verify initial state
    expect(await combobox.isOpen()).toBe(false);

    // Open the popup
    await combobox.open();
    expect(await combobox.isOpen()).toBe(true);

    // Close the popup
    await combobox.close();
    expect(await combobox.isOpen()).toBe(false);
  });
});

API reference

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

Combobox — примитивная директива для этих задокументированных паттернов:

  • Autocomplete — паттерн фильтрации и подсказок (координирует ввод с списком опций)
  • Select — паттерн dropdown с одиночным выбором (применяется напрямую к нередактируемым button triggers)
  • Multiselect — паттерн множественного выбора (применяется к нередактируемым triggers с multi-enabled Listbox)

Combobox обычно сочетается с:

  • Listbox — самый частый контент popup
  • Tree — иерархический контент popup (примеры — в руководстве Tree)