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

Multiselect

Обзор

Паттерн multiselect сочетает read-only combobox-trigger с multi-select listbox popup для создания доступных dropdown с множественным выбором, клавиатурной навигацией и поддержкой screen reader.

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

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

Рассмотрите этот паттерн, когда:

  • Нужен множественный выбор — теги, категории, фильтры или метки, где применимо несколько вариантов
  • Список опций фиксирован (меньше 20 элементов) — пользователи могут просмотреть опции без поиска
  • Фильтрация контента — несколько критериев могут быть активны одновременно
  • Назначение атрибутов — метки, права или функции, где имеют смысл несколько значений
  • Связанные варианты — опции, которые логично работают вместе (например, выбор нескольких членов команды)

Избегайте этого паттерна, когда:

  • Нужен только одиночный выбор — используйте паттерн Select для более простых dropdown с одним выбором
  • В списке больше 20 элементов и нужен поиск — используйте паттерн Autocomplete с возможностью multiselect
  • Будут выбраны большинство или все опции — паттерн checklist даёт лучшую видимость
  • Варианты — независимые бинарные опции — отдельные checkboxes яснее сообщают о выборе

Возможности

Паттерн multiselect сочетает директивы Combobox и Listbox, предоставляя полностью доступный dropdown с:

  • Клавиатурной навигацией — перемещение по опциям стрелками, переключение Space, закрытие Escape
  • Поддержкой screen reader — встроенные ARIA-атрибуты, включая aria-multiselectable
  • Отображением числа выбранных — компактный паттерн «Item + 2 more» для нескольких выборов
  • Signal-based реактивностью — реактивное управление состоянием через сигналы Angular
  • Умным позиционированием — CDK Overlay обрабатывает края viewport и прокрутку
  • Сохраняемым выбором — выбранные опции остаются видимыми с галочками после выбора

Примеры

Базовый multiselect

Пользователям нужно выбрать несколько элементов из списка опций. Readonly combobox в паре с multi-enabled listbox даёт привычную функциональность multiselect с полной поддержкой accessibility.

Атрибут multi на ngListbox включает множественный выбор. Нажимайте Space для переключения опций — popup остаётся открытым для дополнительных выборов. Отображение показывает первый выбранный элемент плюс число оставшихся выборов.

Multiselect с кастомным отображением

Опциям часто нужны визуальные индикаторы — иконки или цвета — чтобы пользователи узнавали варианты. Кастомные шаблоны внутри опций позволяют rich-форматирование, а display value показывает компактную сводку.

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

Управляемый выбор

Формам иногда нужно ограничить число выборов или валидировать выбор пользователя. Программный контроль выбора позволяет эти ограничения с сохранением accessibility.

Этот пример ограничивает выбор двумя элементами. Когда лимит достигнут, невыбранные опции отключаются, чтобы предотвратить дальнейший выбор, а отображение combobox обновляется, отражая выбор.

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

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

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

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

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

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

  it('should allow selecting multiple options', async () => {
    const select = await loader.getHarness(ComboboxHarness);

    // Open the dropdown
    await select.open();

    // Get the listbox harness from the popup
    const listbox = await select.getPopupWidget(ListboxHarness);
    expect(await listbox.isMulti()).toBe(true);

    const options = await listbox.getOptions();

    // Select first and second options
    await options[0].click();
    await options[1].click();

    // Verify both options are selected
    expect(await options[0].isSelected()).toBe(true);
    expect(await options[1].isSelected()).toBe(true);

    // Close the dropdown
    await select.close();

    // Verify value is updated (e.g., comma separated list or count)
    expect(await (await select.host()).text()).toContain('Option 1, Option 2');
  });
});

API reference

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