Créer des visites guidées persistantes de l'application

Fonctionnalités Web : Popover Positionnement des ancres

Les visites d'intégration nécessitent des superpositions qui persistent pendant que les utilisateurs interagissent avec les fonctionnalités mises en évidence. Contrairement aux popovers automatiques, les popovers manuels ne se ferment pas lorsque l'utilisateur clique ailleurs sur la page. En combinant popover="manual" avec le positionnement d'ancrage CSS, vous pouvez créer des étapes de visite non modales et ancrées.

HTML

<div id="feature-target">Highlight this feature</div>

<!-- MANDATORY: Enforce overlay dialog semantics and accessible name bindings -->
<div id="tour-step" popover="manual" role="dialog" aria-labelledby="tour-title">
  <!-- Assume an <h1> precedes this element in the full document outline -->
  <h2 id="tour-title">Step 1</h2>
  <p>Learn how to use this feature.</p>
  <button popovertarget="tour-step" popovertargetaction="hide">Got it</button>
</div>

CSS

#feature-target {
  anchor-name: --feature-target;
}

#tour-step {
  popover: manual;
  position-anchor: --feature-target;
  position-area: right center;
  inset: auto;
  margin: 1rem;
  padding: 1rem;
  border: 1px solid blue;
  border-radius: 0.5rem;
  background: aliceblue;
}

JavaScript

const tourStep = document.getElementById('tour-step');
tourStep.showPopover();
// MANDATORY: Programmatically route focus into the non-modal popover so keyboard/assistive technology users immediately perceive the new context
tourStep.querySelector('button').focus();

Consignes de mise en œuvre

  • OBLIGATOIRE : Utilisez popover="manual" pour éviter que l'étape de la visite ne se ferme accidentellement lors de l'interaction de l'utilisateur.
  • OBLIGATOIRE : Marquez le conteneur avec role="dialog" et associez son titre via aria-labelledby.
  • OBLIGATOIRE : Déplacez le curseur de sélection de manière programmatique à l'intérieur du popover immédiatement après l'ouverture pour éviter qu'il ne soit perdu.
  • À FAIRE : Utilisez le positionnement des ancres CSS pour lier l'étape de la visite à la fonctionnalité spécifique expliquée.
  • À FAIRE : Fournissez un bouton "Fermer" ou "Suivant" explicite dans le popover qui utilise popovertargetaction="hide".

Stratégies de remplacement

Solutions de remplacement et compatibilité des navigateurs pour Popover

L'API Popover est principalement une amélioration progressive, mais ses comportements déterminants (promotion de la couche supérieure, fermeture par clic en dehors de l'élément et appel de popovertarget) n'ont pas d'équivalent CSS uniquement. Les anciens navigateurs ont besoin d'un polyfill ou d'un remplacement manuel si vous préférez ne pas en fournir.

Polyfill : pour que l'attribut popover soit compatible avec les anciens navigateurs, chargez @oddbird/popover-polyfill de manière conditionnelle. OBLIGATOIRE : Détectez la fonctionnalité en vérifiant la propriété popover sur HTMLElement.prototype, et chargez le polyfill uniquement lorsque la compatibilité native est manquante. Ne le chargez PAS de manière inconditionnelle.

Avec un bundler ou une carte d'importation :

// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
if (!("popover" in HTMLElement.prototype)) {
  import("@oddbird/popover-polyfill");
}

Sans bundler, importez depuis un CDN dans un <script type="module"> :

<script type="module">
  if (!("popover" in HTMLElement.prototype)) {
    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
  }
</script>

Mise en garde concernant l'application de styles : le polyfill ne peut pas définir la véritable pseudo-classe :popover-open. Il applique donc une classe .\:popover-open à la place. OBLIGATOIRE : Combinez les deux avec :is() ou :where(), sinon les navigateurs qui ne disposent pas de :popover-open ignorent l'intégralité de la règle :

[popover]:is(:popover-open, .\:popover-open) {
  display: block;
}

Vous pouvez également utiliser position: fixed pour une solution de remplacement sans polyfill et calculer manuellement les coordonnées via getBoundingClientRect(), ou vous appuyer sur le positionnement par défaut avec inset: auto si cela convient à votre cas d'utilisation.

anchor-positioning

Pour prendre en charge les navigateurs sans positionnement d'ancrage, vous pouvez choisir d'utiliser un polyfill ou une solution de remplacement CSS pure.

Option 1 : Polyfill de remplacement

Le polyfill @oddbird/css-anchor-positioning peut être utilisé pour émuler le positionnement des ancres. Il n'est pas compatible avec les ancres implicites. Vous DEVEZ donc ajouter des noms d'ancres explicites au déclencheur. De plus, position-area n'est pas compatible avec les popovers par le polyfill. Vous DEVEZ donc utiliser anchor() sur les encarts souhaités au lieu de position-area.

<script type="module">
  if (!CSS.supports('anchor-name: --foo')) {
    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
  }
</script>

#tour-step {
  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions instead of `position-area`. */
  left: anchor(right);
  top: anchor(top);
}
Option 2 : Solution de remplacement CSS sans polyfill

Si vous préférez ne pas utiliser de polyfill, vous pouvez définir par défaut l'info-bulle sur une position fixe en bas de la fenêtre d'affichage à l'aide de @supports not.

@supports not (anchor-name: --foo) {
  #tour-step {
    position: fixed;
    bottom: 0;
    left: 0;
    right: 0;
    width: 100%;
    margin: 0;
    border-radius: 0;
  }
}