Documentation
Version de développement
Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.
Développeurs

Composant Stepper (frappe.ui.Stepper)

Référence développeur du composant frappe.ui.Stepper : parcours d'étapes horizontal ou vertical, contenu par étape, options, états et méthodes.

Composant Stepper (frappe.ui.Stepper)

frappe.ui.Stepper affiche un parcours sous forme d'étapes reliées par une ligne : assistant de configuration, checklist, onboarding. C'est un composant Espresso du desk, comme ceux de la référence des composants Espresso. Il s'utilise depuis n'importe quelle application.

Des exemples interactifs sont disponibles dans l'explorateur de composants de l'interface Desk (page Component Explorer, section Stepper).

Créer un stepper

const stepper = new frappe.ui.Stepper({
    steps: [
        { label: __("Compte") },
        { label: __("Configuration") },
        { label: __("Mise en service") },
    ],
    current: 0,
    is_locked: (index) => index > 1,
    on_step_click: (i) => stepper.set_current(i),
});

$(".wizard-head").append(stepper.$el);

La fabrique frappe.ui.stepper(options) renvoie l'élément enveloppé par jQuery ; l'instance se lit ensuite avec .data("es-stepper") :

const $stepper = frappe.ui
    .stepper({
        steps: [{ label: __("Étape 1") }, { label: __("Étape 2") }],
    })
    .appendTo("body");
const stepper = $stepper.data("es-stepper");

Options

OptionTypeDéfautDescription
stepsStepperStep[]—Liste des étapes (obligatoire).
currentnumber0Index de l'étape active.
labelstring« Steps »Nom accessible du <nav> (aria-label).
is_locked(index: number) => boolean—Verrouille une étape. Une étape verrouillée porte aria-disabled="true" et non disabled : elle reste dans l'ordre de tabulation, mais le clic est bloqué et appelle on_locked_click.
is_completed(index: number) => boolean—Indique si une étape est terminée. Sans cette fonction, toutes les étapes situées avant l'étape active sont considérées comme terminées.
on_step_click(index: number) => void—Appelée au clic sur une étape déverrouillée. Appelez set_current pour déplacer l'étape active.
on_locked_click(index: number) => void—Appelée au clic sur une étape verrouillée.
compactbooleanfalseAffiche une barre de progression avec un indice « Step x of y » à la place des étapes, pour les mises en page étroites. Horizontal uniquement : l'option est ignorée en orientation verticale.
hint(done: number, count: number) => string« Step {0} of {1} »Texte de progression en mode compact. done est le numéro de l'étape en cours, count le nombre d'étapes. Le formulaire web l'utilise pour afficher « 2 of 3 » : hint: (done, count) => __("{0} of {1}", [done, count]).
orientation"horizontal" ou "vertical""horizontal"En vertical, les étapes s'empilent avec leur contenu, pour une checklist qui reste ouverte.
label_position"right", "left", "top" ou "bottom""right"Position du libellé par rapport au marqueur. Horizontal uniquement.
css_classstring—Classes supplémentaires ajoutées au <nav> racine.

Définition d'une étape (StepperStep)

PropriétéTypeDescription
labelstringNom de l'étape, passé par __() pour la traduction. Le libellé complet est aussi placé dans l'attribut title de l'étape.
contentstring, Element, JQuery ou (index: number) => string | Element | JQueryContenu affiché à côté de la ligne de marqueurs en orientation verticale. Une chaîne reste du texte : elle n'est jamais interprétée comme du HTML. Le contenu est reconstruit à chaque rendu : à la création, puis à chaque changement d'étape active ou d'état d'une étape.

Étape cliquable ou lecture seule

Quelle que soit l'orientation, une étape est rendue comme un <button type="button"> uniquement si on_step_click ou on_locked_click est fournie. Sans gestionnaire de clic, l'étape est un simple <div> non focusable : un stepper en lecture seule n'ajoute aucune halte morte dans l'ordre de tabulation.

Orientation verticale

frappe.ui.stepper({
    orientation: "vertical",
    steps: [
        { label: __("Plan comptable"), content: $actions_comptes },
        {
            label: __("Soldes d'ouverture"),
            content: () =>
                $("<p>Reprenez les soldes de clôture de vos anciens livres.</p>"),
        },
        { label: __("Mise en ligne") },
    ],
});

En orientation verticale :

  • les étapes forment une liste ordonnée : un <ol class="es-stepper__list"> contenant un <li class="es-stepper__item"> par étape, pour que les technologies d'assistance annoncent le nombre et l'ordre des étapes ;
  • chaque élément contient l'étape, un connecteur <span class="es-stepper__connector"> (absent après la dernière étape) et, si l'étape définit un content, un bloc <div class="es-stepper__content"> affiché sous le libellé, à côté de la ligne de marqueurs ;
  • une étape sans content n'a pas de bloc de contenu ;
  • le contenu de chaque étape reste visible : le composant sert de checklist ouverte, pas de parcours à révéler étape par étape ;
  • le focus est conservé : les nœuds de contenu sont réutilisés à chaque rendu, donc un champ situé dans un contenu retrouve sa valeur et son focus après refresh() ou set_current() ;
  • compact et label_position ne s'appliquent pas.

Le <nav> racine porte les classes es-stepper et es-stepper--vertical (ainsi que es-stepper--label-<position> en horizontal, quand label_position est défini).

États et accessibilité

  • L'étape active porte data-state="active" et aria-current="step".
  • Une étape terminée porte data-state="completed" et data-completed="true". L'attribut data-completed est distinct de data-state, pour qu'une étape terminée revisitée puisse rester active.
  • Une étape verrouillée porte data-state="locked" et aria-disabled="true".
  • Les connecteurs sont masqués aux technologies d'assistance (aria-hidden="true") et portent data-completed="true" lorsqu'ils suivent une étape terminée.

Méthodes et propriétés

MembreDescription
set_current(index)Déplace l'étape active et provoque un nouveau rendu de toutes les étapes. Un index hors limites est ramené à la première ou à la dernière étape.
next_step(), prev_step()Passe à l'étape suivante ou précédente. Le verrouillage n'est pas vérifié : validez avant l'appel.
refresh()Rend à nouveau les étapes, par exemple après un changement d'état externe (verrouillage, contenu).
$elÉlément <nav> racine du composant, à insérer dans le DOM.