Une directive qui affiche une liste d'options parmi lesquelles les utilisateurs peuvent choisir, avec la navigation au clavier, la sélection simple ou multiple et la prise en charge des lecteurs d'écran.
app.ts
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', ];}
La listbox est une directive de base utilisée par les patterns Select, Multiselect et Autocomplete. Pour la plupart des besoins de liste déroulante, utilisez plutôt ces patterns documentés.
Envisagez d'utiliser directement une listbox pour :
Construire des composants de sélection personnalisés - Créer des interfaces spécialisées avec un comportement spécifique
Des listes de sélection visibles - Afficher des éléments sélectionnables directement sur la page (pas dans des listes déroulantes)
Des patterns d'intégration personnalisés - S'intégrer à des exigences particulières de popup ou de mise en page
Évitez la listbox quand :
Vous avez besoin de menus de navigation - Utilisez la directive Menu pour les actions et les commandes
Les applications ont parfois besoin de listes sélectionnables visibles directement sur la page plutôt que cachées dans une liste déroulante. Une listbox standalone fournit la navigation au clavier et la sélection pour ces interfaces de liste visibles.
app.ts
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', ];}
Le signal model value fournit un two-way binding vers les éléments sélectionnés. Avec selectionMode="explicit", les utilisateurs appuient sur Espace ou Entrée pour sélectionner des options. Pour les patterns de liste déroulante qui combinent une listbox avec une combobox et un positionnement en overlay, consultez le pattern Select.
Les listes fonctionnent parfois mieux à l'horizontale, par exemple pour des interfaces de type toolbar ou des sélections de type onglets. L'attribute orientation modifie à la fois la mise en page et la direction de la navigation au clavier.
app.ts
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'];}
Avec orientation="horizontal", les touches fléchées gauche et droite permettent de naviguer entre les options au lieu des touches haut et bas. La listbox gère automatiquement les langues de droite à gauche (RTL) en inversant la direction de navigation.
La listbox prend en charge deux modes de sélection qui déterminent à quel moment les éléments sont sélectionnés.
Le mode 'follow' sélectionne automatiquement l'élément qui a le focus, ce qui accélère l'interaction lorsque la sélection change fréquemment. Le mode 'explicit' exige Espace ou Entrée pour confirmer la sélection, ce qui évite les changements accidentels pendant la navigation. Les patterns de liste déroulante utilisent généralement le mode 'follow' pour la sélection simple.
Angular Aria fournit des harnais de composant pour tester les composants listbox.
Voici un exemple d'utilisation des harnais dans un test de composant :
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 componentdescribe('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); });});
La listbox est utilisée par ces patterns de liste déroulante documentés :
Select - Pattern de liste déroulante à sélection simple utilisant une combobox en lecture seule + une listbox
Multiselect - Pattern de liste déroulante à sélection multiple utilisant une combobox en lecture seule + une listbox avec multi
Autocomplete - Pattern de liste déroulante filtrable utilisant une combobox + une listbox
Pour des patterns de liste déroulante complets avec déclencheur, popup et positionnement en overlay, consultez ces guides de patterns plutôt que d'utiliser la listbox seule.