Guides approfondis
Angular Aria

Autocomplete

Vue d'ensemble

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.

Utilisation

L'autocomplete est idéal lorsque les utilisateurs doivent choisir parmi un grand nombre d'options et que taper est plus rapide que faire défiler. Envisagez l'autocomplete lorsque :

  • La liste d'options est longue (plus de 20 éléments) - Taper affine les choix plus vite que de faire défiler une liste déroulante
  • Les utilisateurs savent ce qu'ils cherchent - Ils peuvent taper une partie de la valeur attendue (comme un nom d'État, un produit ou un nom d'utilisateur)
  • Les options suivent des schémas prévisibles - Les utilisateurs peuvent deviner des correspondances partielles (comme des codes pays, des domaines d'e-mail ou des catégories)
  • La rapidité compte - Les formulaires bénéficient d'une sélection rapide sans navigation fastidieuse

Évitez l'autocomplete lorsque :

  • La liste compte moins de 10 options - Une liste déroulante classique ou un groupe de boutons radio offre une meilleure visibilité
  • Les utilisateurs doivent parcourir les options - Si la découverte est importante, affichez toutes les options d'emblée
  • Les options ne sont pas familières - Les utilisateurs ne peuvent pas taper ce dont ils ignorent la présence dans la liste

Fonctionnalités

L'autocomplete d'Angular fournit une implémentation de combobox entièrement accessible avec :

  • Navigation au clavier - Parcourez les options avec les touches fléchées, sélectionnez avec Entrée, fermez avec Échap
  • Prise en charge des lecteurs d'écran - Attributs ARIA intégrés pour les technologies d'assistance
  • Comportement de mise en surbrillance dynamique - Prise en charge intégrée des suggestions de sélection en ligne
  • Réactivité basée sur les signals - Gestion d'état réactive avec les signals d'Angular
  • Intégration de l'API Popover - Exploite l'API Popover native du HTML pour un positionnement optimal
  • Prise en charge du texte bidirectionnel - Gère automatiquement les langues de droite à gauche (RTL)

Exemples

Mode de sélection automatique

Les utilisateurs qui tapent un texte partiel attendent une confirmation immédiate que leur saisie correspond à une option disponible. Le mode de sélection automatique met à jour la valeur du champ pour qu'elle corresponde à la première option filtrée pendant la frappe, ce qui réduit le nombre de frappes nécessaires et indique instantanément que la recherche est sur la bonne voie.

Mode de sélection manuelle

Le mode de sélection manuelle conserve le texte tapé inchangé pendant que les utilisateurs parcourent la liste de suggestions, ce qui évite la confusion due aux mises à jour automatiques. Le champ ne change que lorsque les utilisateurs confirment explicitement leur choix avec Entrée ou un clic.

Mode de mise en surbrillance

Le mode de mise en surbrillance permet à l'utilisateur de parcourir les options avec les touches fléchées sans modifier la valeur du champ pendant la navigation, jusqu'à ce qu'il sélectionne explicitement une nouvelle option avec Entrée ou un clic.

Intégration dans un formulaire Signal Forms

Angular Aria s'intègre parfaitement avec l'API Signal Forms, basée sur les signals. Vous pouvez encapsuler des champs complexes dans des composants de contrôle personnalisé réutilisables qui implémentent FormValueControl.

L'exemple suivant montre un composant de sélection de pays (country selector) qui implémente FormValueControl<string>, lié au formulaire parent avec [formField] et protégé par des règles de validation de schéma.

Tests

Le pattern autocomplete peut être testé en combinant ComboboxHarness et ListboxHarness depuis @angular/aria/combobox/testing et @angular/aria/listbox/testing. Voici un exemple d'utilisation des harnais pour tester un composant autocomplete :

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

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

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

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

  it('should filter options based on input', async () => {
    const combobox = await loader.getHarness(ComboboxHarness);

    // Type in the input to trigger filtering
    await combobox.setValue('ap');
    expect(await combobox.isOpen()).toBe(true);

    // Get the listbox harness from the popup
    const listbox = await combobox.getPopupWidget(ListboxHarness);
    const options = await listbox.getOptions();

    // Verify options are filtered (e.g., 'Apple', 'Apricot')
    expect(options.length).toBe(2);
    expect(await options[0].getText()).toBe('Apple');

    // Select the first option
    await options[0].click();

    // Verify the input value is updated and popup is closed
    expect(await combobox.isOpen()).toBe(false);
    expect(await combobox.getValue()).toBe('Apple');
  });
});

Référence de l'API

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