Guides approfondis
Angular Aria

Combobox

Vue d'ensemble

Une directive qui coordonne un élément déclencheur (comme un champ de saisie, un bouton ou une div) avec une popup, et qui fournit la directive primitive des patterns autocomplete, select et multiselect.

Utilisation

La combobox est la directive primitive qui coordonne un élément déclencheur interactif (comme un champ de saisie, un bouton ou une div) avec une popup. Elle sert de base aux patterns autocomplete, select et multiselect. Envisagez d'utiliser directement la combobox pour :

  • Créer des patterns autocomplete personnalisés - Concevoir un comportement de filtrage ou de suggestion spécialisé
  • Créer des composants de sélection personnalisés - Développer des listes déroulantes aux exigences particulières
  • Coordonner un champ de saisie avec une popup - Associer un champ de saisie à un contenu listbox, tree ou dialog
  • Implémenter un filtrage personnalisé - Filtrer et orchestrer les options correspondantes dans votre propre code

Utilisez plutôt les patterns documentés lorsque :

  • Vous avez besoin d'une autocomplete standard avec filtrage - Consultez le pattern Autocomplete pour des exemples prêts à l'emploi
  • Vous avez besoin de listes déroulantes à sélection simple - Consultez le pattern Select pour une implémentation complète de liste déroulante
  • Vous avez besoin de listes déroulantes à sélection multiple - Consultez le pattern Multiselect pour une sélection multiple avec affichage compact

Note : Les guides Autocomplete, Select et Multiselect présentent des patterns documentés qui combinent cette directive avec Listbox pour des cas d'usage spécifiques.

Fonctionnalités

La combobox d'Angular fournit un système de coordination entre champ de saisie et popup entièrement accessible, avec :

  • Élément déclencheur avec popup - Coordonne l'élément déclencheur avec le contenu de la popup
  • Coordination flexible - S'intègre parfaitement aux mises en page standard (listbox, tree, grid ou dialog)
  • Navigation au clavier - Gestion des touches fléchées, d'Entrée et d'Échap
  • Prise en charge des lecteurs d'écran - Attributs ARIA intégrés, notamment role="combobox" et aria-expanded
  • Gestion de la popup - Affichage et masquage automatiques selon les interactions de l'utilisateur
  • Réactivité basée sur les signals - Gestion d'état réactive avec les signals d'Angular

Exemples

Autocomplete

Un champ de saisie accessible qui filtre et suggère des options pendant la frappe, pour aider les utilisateurs à trouver et sélectionner des valeurs dans une liste.

Le filtrage est géré dans votre propre code en mettant à jour un signal qui filtre la liste d'options de manière réactive. Les utilisateurs naviguent avec les touches fléchées et sélectionnent avec Entrée ou un clic. Cela offre un contrôle total et une flexibilité maximale pour une logique de sélection personnalisée. Consultez le guide Autocomplete pour des patterns de filtrage et des exemples complets.

Mode en lecture seule

Un pattern qui combine une combobox en lecture seule avec une listbox pour créer des listes déroulantes à sélection simple, avec navigation au clavier et prise en charge des lecteurs d'écran.

Pour ouvrir une liste déroulante sans saisie de texte, vous pouvez utiliser un bouton comme déclencheur host, ou appliquer l'attribut HTML natif readonly au champ de saisie déclencheur. La popup s'ouvre au clic ou avec les touches fléchées.

Cette configuration sert de base aux patterns Select et Multiselect. Consultez ces guides pour des implémentations complètes de listes déroulantes avec déclencheurs et positionnement de l'overlay.

Grid de sélecteur de date

La combobox peut se coordonner avec une grid à deux dimensions pour créer des sélecteurs de date accessibles. Les utilisateurs parcourent les dates dans le tableau de la grid du calendrier avec les touches fléchées directionnelles et confirment la sélection par un clic, Entrée ou la barre d'espace.

Popup dialog

Les popups dialog combinent le déclencheur de la combobox avec des mises en page de dialog standard et des pièges à focus (comme cdkTrapFocus du CDK). Utilisez des popups dialog lorsque l'overlay nécessite un comportement modal ou une interaction avec l'arrière-plan (backdrop).

Tests

Angular Aria fournit un ComboboxHarness pour tester les composants combobox. Voici un exemple d'utilisation du 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 {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);
  });
});

Référence de l'API

Pour une documentation détaillée de l'API, consultez les références d'API suivantes :

La combobox est la directive primitive de ces patterns documentés :

  • Autocomplete - Pattern de filtrage et de suggestions (coordonne la saisie dans le champ avec la liste d'options)
  • Select - Pattern de liste déroulante à sélection simple (appliqué directement sur des boutons déclencheurs non modifiables)
  • Multiselect - Pattern de sélection multiple (appliqué sur des déclencheurs non modifiables avec une Listbox multi-sélection)

La combobox se combine généralement avec :

  • Listbox - Contenu de popup le plus courant
  • Tree - Contenu de popup hiérarchique (consultez le guide Tree pour des exemples)