Creazione di tour delle app permanenti

I tour di onboarding richiedono overlay che rimangono visibili mentre gli utenti interagiscono con le funzionalità evidenziate. A differenza dei popover automatici, i popover manuali non si chiudono quando l'utente fa clic in un altro punto della pagina. La combinazione di popover="manual" con il posizionamento degli ancoraggi CSS ti consente di creare passaggi del tour non modali e ancorati.

Implementazione consigliata

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();

Linee guida per l'implementazione

• OBBLIGATORIO: utilizza popover="manual" per evitare che il passaggio del tour si chiuda accidentalmente durante l'interazione dell'utente.
• OBBLIGATORIO: contrassegna il contenitore con role="dialog" e collega la relativa intestazione tramite aria-labelledby.
• OBBLIGATORIO: sposta lo stato attivo programmatico all'interno del popover immediatamente dopo l'apertura per evitare l'abbandono dello stato attivo.
• SÌ: utilizza il posizionamento degli ancoraggi CSS per collegare il passaggio del tour alla funzionalità specifica che viene spiegata.
• SÌ: fornisci un pulsante "Chiudi" o "Avanti" esplicito all'interno del popover che utilizza popovertargetaction="hide".

Strategie di riserva

Alternative e supporto del browser per Popover

L'API Popover è per lo più un potenziamento progressivo, ma i suoi comportamenti distintivi (promozione al livello superiore, chiusura con un clic e attivazione di popovertarget) non hanno un equivalente solo CSS. I browser meno recenti richiedono un polyfill o un fallback manuale se preferisci non fornirne uno.

Polyfill: per supportare l'attributo popover nei browser meno recenti, carica @oddbird/popover-polyfill in modo condizionale. OBBLIGATORIO: esegui il rilevamento delle funzionalità controllando la proprietà popover su HTMLElement.prototype e carica il polyfill solo quando manca il supporto nativo; NON caricarlo incondizionatamente.

Con un bundler o una mappa di importazione:

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

Senza un bundler, importa da una CDN all'interno di 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>

Avvertenza sullo stile: il polyfill non può definire la pseudo-classe :popover-open reale, quindi applica una classe .\:popover-open. OBBLIGATORIO: combina i due elementi con :is() o :where(), altrimenti i browser che non dispongono di :popover-open ignorano l'intera regola:

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

In alternativa, per un fallback legacy senza un polyfill, utilizza position: fixed e calcola manualmente le coordinate tramite getBoundingClientRect() o affidati al posizionamento predefinito con inset: auto se è accettabile per il caso d'uso.

anchor-positioning

Per supportare i browser senza posizionamento degli ancoraggi, puoi scegliere di utilizzare un polyfill o un fallback CSS puro.

Opzione 1: polyfill di riserva

Il polyfill @oddbird/css-anchor-positioning può essere utilizzato per emulare il posizionamento degli ancoraggi. Non supporta gli ancoraggi impliciti, quindi DEVI aggiungere nomi di ancoraggio espliciti all'attivatore. Inoltre, position-area non è supportato sui popover dal polyfill, quindi DEVI utilizzare anchor() sugli inset desiderati anziché 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);
}

Opzione 2: CSS di riserva non polyfill

Se preferisci non utilizzare un polyfill, puoi impostare il tooltip in una posizione fissa nella parte inferiore dell'area visibile utilizzando @supports not.

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