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

Listbox

Обзор

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

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

Listbox — базовая директива, используемая паттернами Select, Multiselect и Autocomplete. Для большинства нужд dropdown используйте эти задокументированные паттерны.

Рассмотрите прямое использование listbox, когда:

  • Создаёте кастомные компоненты выбора — специализированные интерфейсы с конкретным поведением
  • Видимые списки выбора — отображение выбираемых элементов прямо на странице (не в dropdown)
  • Кастомные паттерны интеграции — интеграция с уникальными требованиями popup или layout

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

  • Нужны навигационные меню — используйте директиву Menu для действий и команд

Возможности

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

  • Клавиатурной навигацией — перемещение по опциям стрелками, выбор Enter или Space
  • Поддержкой screen reader — встроенные ARIA-атрибуты, включая role="listbox"
  • Одиночным или множественным выбором — атрибут multi управляет режимом выбора
  • Горизонтальной или вертикальной ориентацией — атрибут orientation для направления layout
  • Type-ahead поиском — ввод символов для перехода к совпадающим опциям
  • Signal-based реактивностью — реактивное управление состоянием через сигналы Angular

Примеры

Базовый listbox

Иногда приложениям нужны выбираемые списки, видимые прямо на странице, а не скрытые в dropdown. Standalone listbox обеспечивает клавиатурную навигацию и выбор для таких видимых списковых интерфейсов.

Model-сигнал value обеспечивает двустороннюю привязку к выбранным элементам. С selectionMode="explicit" пользователи нажимают Space или Enter для выбора опций. Для паттернов dropdown, сочетающих listbox с combobox и позиционированием overlay, см. паттерн Select.

Горизонтальный listbox

Иногда списки лучше работают горизонтально — например, интерфейсы в стиле toolbar или выбор в стиле вкладок. Атрибут orientation меняет и layout, и направление клавиатурной навигации.

С orientation="horizontal" клавиши влево и вправо перемещают между опциями вместо вверх и вниз. Listbox автоматически обрабатывает языки справа налево (RTL), меняя направление навигации.

Режимы выбора

Listbox поддерживает два режима выбора, управляющих тем, когда элементы становятся выбранными.

Режим 'follow' автоматически выбирает элемент в фокусе, обеспечивая более быстрое взаимодействие при частой смене выбора. Режим 'explicit' требует Space или Enter для подтверждения выбора, предотвращая случайные изменения при навигации. Паттерны dropdown обычно используют режим 'follow' для одиночного выбора.

Explicit

Follow

Режим Описание
'follow' Автоматически выбирает элемент в фокусе — быстрее при частой смене выбора
'explicit' Требует Space или Enter для подтверждения выбора, предотвращая случайные изменения при навигации

СОВЕТ: Паттерны dropdown обычно используют режим 'follow' для одиночного выбора.

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

Angular Aria предоставляет component harnesses для тестирования компонентов listbox. Пример использования harnesses в тесте компонента:

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

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

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

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

  it('should allow selecting options', async () => {
    const listbox = await loader.getHarness(ListboxHarness);

    // Verify listbox properties
    expect(await listbox.isMulti()).toBe(true);

    // Get all options
    const options = await listbox.getOptions();
    expect(options.length).toBe(2);

    // Click an option
    await options[0].click();

    // Verify option is selected
    expect(await options[0].isSelected()).toBe(true);

    // Filter options by text
    const bananaOption = await listbox.getOptions({text: 'Banana'});
    expect(bananaOption.length).toBe(1);
  });
});

API reference

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

Listbox используется этими задокументированными паттернами dropdown:

  • Select — паттерн dropdown с одиночным выбором: readonly combobox + listbox
  • Multiselect — паттерн dropdown с множественным выбором: readonly combobox + listbox с multi
  • Autocomplete — паттерн filterable dropdown: combobox + listbox

Для полных паттернов dropdown с trigger, popup и позиционированием overlay см. руководства по этим паттернам вместо использования listbox отдельно.