Директива, отображающая список вариантов, из которого пользователи могут выбирать, с поддержкой навигации с клавиатуры, выбора одного или нескольких вариантов и программ чтения с экрана.
import {Listbox, Option} from '@angular/aria/listbox';
import {Component} from '@angular/core';
@Component({
selector: 'app-root',
templateUrl: './app.html',
styleUrl: './app.css',
imports: [Listbox, Option],
})
export class App {
/** The options available in the listbox. */
options = [
'Option 1',
'Option 2',
'Option 3',
'Option 4',
'Option 5',
'Option 6',
'Option 7',
'Option 8',
];
}
Список выбора — это базовая директива, используемая в шаблонах Select, Multiselect и Autocomplete. Для большинства задач, связанных с выпадающими списками, используйте описанные шаблоны.
Используйте список выбора напрямую в следующих случаях:
Создание пользовательских компонентов выбора — для создания специализированных интерфейсов с особым поведением
Видимые списки вариантов — для отображения вариантов непосредственно на странице, а не в выпадающем списке
Пользовательские сценарии интеграции — для интеграции с уникальными требованиями к всплывающим элементам или макету
Не используйте список выбора в следующих случаях:
Нужны меню навигации — используйте директиву Menu для действий и команд
Возможности
Список выбора Angular обеспечивает полностью доступную реализацию списка со следующими возможностями:
Навигация с клавиатуры — переход между вариантами с помощью клавиш со стрелками, выбор клавишей Enter или пробелом
Поддержка программ чтения с экрана — встроенные атрибуты ARIA, включая role="listbox"
Выбор одного или нескольких вариантов — атрибут multi задаёт режим выбора
Горизонтальная или вертикальная ориентация — атрибут orientation задаёт направление расположения элементов
Поиск по мере ввода — вводите символы, чтобы перейти к подходящим вариантам
Реактивность на основе сигналов — реактивное управление состоянием с помощью сигналов Angular
Примеры
Базовый список выбора
Иногда приложениям нужны списки вариантов, которые видны непосредственно на странице, а не скрыты в выпадающем списке. Отдельный список выбора обеспечивает навигацию с клавиатуры и выбор элементов в таких видимых списках.
import {Listbox, Option} from '@angular/aria/listbox';
import {Component} from '@angular/core';
@Component({
selector: 'app-root',
templateUrl: './app.html',
styleUrl: './app.css',
imports: [Listbox, Option],
})
export class App {
/** The options available in the listbox. */
options = [
'Option 1',
'Option 2',
'Option 3',
'Option 4',
'Option 5',
'Option 6',
'Option 7',
'Option 8',
];
}
Сигнал модели value обеспечивает двустороннюю привязку к выбранным элементам. В режиме selectionMode="explicit" пользователи нажимают пробел или Enter, чтобы выбрать варианты. О шаблонах выпадающих списков, объединяющих список выбора с комбинированным полем и позиционированием наложения, см. в разделе Select.
Горизонтальный список выбора
Иногда списки удобнее отображать горизонтально, например в интерфейсах, похожих на панели инструментов, или при выборе вариантов в виде вкладок. Атрибут orientation меняет и расположение элементов, и направление навигации с клавиатуры.
import {Listbox, Option} from '@angular/aria/listbox';
import {Component} from '@angular/core';
@Component({
selector: 'app-root',
templateUrl: './app.html',
styleUrl: './app.css',
imports: [Listbox, Option],
})
export class App {
/** The options available in the listbox. */
amenities = ['Washer / Dryer', 'Ramp access', 'Garden', 'Cats OK', 'Dogs OK', 'Smoke-free'];
}
В режиме orientation="horizontal" клавиши со стрелками влево и вправо перемещают фокус между вариантами вместо клавиш вверх и вниз. Список выбора автоматически учитывает языки с письмом справа налево (RTL), меняя направление навигации на противоположное.
Режимы выбора
Список выбора поддерживает два режима, определяющих, когда элементы становятся выбранными.
Режим 'follow' автоматически выбирает элемент, на котором находится фокус, что ускоряет взаимодействие при частом изменении выбора. В режиме 'explicit' для подтверждения выбора нужно нажать пробел или Enter, что предотвращает случайные изменения при навигации. В шаблонах выпадающих списков для выбора одного варианта обычно используется режим 'follow'.
Автоматически выбирает элемент, на котором находится фокус, что ускоряет взаимодействие при частом изменении выбора
'explicit'
Для подтверждения выбора нужно нажать пробел или Enter, что предотвращает случайные изменения при навигации
СОВЕТ: В шаблонах выпадающих списков для выбора одного варианта обычно используется режим 'follow'.
Тестирование
Angular Aria предоставляет компонентные стенды для тестирования компонентов списка выбора. Вот пример использования стендов в тесте компонента:
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
Директива списка выбора
Директива ngListbox создаёт доступный список выбираемых вариантов.
Входные параметры
Свойство
Тип
Значение по умолчанию
Описание
id
string
auto
Уникальный идентификатор списка выбора
multi
boolean
false
Включает множественный выбор
orientation
'vertical' | 'horizontal'
'vertical'
Направление расположения элементов списка
wrap
boolean
true
Определяет, зацикливается ли фокус у краёв списка
selectionMode
'follow' | 'explicit'
'follow'
Способ запуска выбора
focusMode
'roving' | 'activedescendant'
'roving'
Стратегия управления фокусом
softDisabled
boolean
true
Определяет, можно ли перемещать фокус на отключённые элементы
disabled
boolean
false
Отключает весь список выбора
readonly
boolean
false
Переводит список выбора в режим «только для чтения»
typeaheadDelay
number
500
Количество миллисекунд до сброса поиска по мере ввода
Модель
Свойство
Тип
Описание
value
V[]
Массив выбранных значений с двусторонней привязкой
Сигналы
Свойство
Тип
Описание
value
Signal<V[]>
Текущие выбранные значения в виде сигнала
Методы
Метод
Параметры
Описание
scrollActiveItemIntoView
options?: ScrollIntoViewOptions
Прокручивает страницу так, чтобы активный элемент оказался в области просмотра
gotoFirst
нет
Переходит к первому элементу списка выбора
Директива варианта
Директива ngOption помечает элемент внутри списка выбора.
Входные параметры
Свойство
Тип
Значение по умолчанию
Описание
id
string
auto
Уникальный идентификатор варианта
value
V
-
Значение, связанное с этим вариантом (обязательно)
label
string
-
Необязательная подпись для программ чтения с экрана
disabled
boolean
false
Определяет, отключён ли этот вариант
Сигналы
Свойство
Тип
Описание
selected
Signal<boolean>
Определяет, выбран ли этот вариант
active
Signal<boolean>
Определяет, находится ли этот вариант в фокусе
Связанные шаблоны
Этот список выбора используется в описанных шаблонах выпадающих списков:
Select — шаблон выпадающего списка с выбором одного варианта, использующий комбинированное поле только для чтения и список выбора
Multiselect — шаблон выпадающего списка с выбором нескольких вариантов, использующий комбинированное поле только для чтения и список выбора с multi
Autocomplete — фильтруемый шаблон выпадающего списка, использующий комбинированное поле и список выбора
Полные шаблоны выпадающих списков с триггером, всплывающим окном и позиционированием наложения описаны в соответствующих руководствах; используйте их вместо списка выбора в отдельности.
