Persistente app-rondleidingen maken

Voor introductierondleidingen zijn overlays vereist die blijven bestaan terwijl gebruikers interactie hebben met de gemarkeerde functies. In tegenstelling tot automatische pop-overs worden handmatige pop-overs niet gesloten als de gebruiker ergens anders op de pagina klikt. Als je popover="manual" combineert met CSS-ankerpositionering, kun je niet-modale, gekoppelde rondleidingsstappen maken.

Aanbevolen implementatie

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

Implementatierichtlijnen

• VERPLICHT: Gebruik popover="manual" om te voorkomen dat de rondleidingsstap per ongeluk wordt gesloten tijdens gebruikersinteractie.
• VERPLICHT: Markeer de container met role="dialog" en koppel de kop via aria-labelledby.
• VERPLICHT: Verplaats de programmatische focus onmiddellijk na het openen naar de popover om te voorkomen dat de focus wordt verlaten.
• WEL: Gebruik CSS-ankerpositionering om de rondleidingsstap te koppelen aan de specifieke functie die wordt uitgelegd.
• WEL: Zorg voor een expliciete knop Sluiten of Volgende in de pop-over die popovertargetaction="hide" gebruikt.

Reservestrategieën

Fallbacks en browserondersteuning voor Popover

De Popover API is voornamelijk progressive enhancement, maar de bepalende gedragingen (promotie van de bovenste laag, licht sluiten en aanroepen van popovertarget) hebben geen equivalent dat alleen CSS gebruikt. Oudere browsers hebben een polyfill nodig, of een handmatige fallback als je er liever geen verzendt.

Polyfill: Als je het kenmerk popover wilt ondersteunen in oudere browsers, laad je @oddbird/popover-polyfill voorwaardelijk. VERPLICHT: Voer een functiedetectie uit door te controleren op de property popover op HTMLElement.prototype en laad de polyfill alleen als systeemeigen ondersteuning ontbreekt. Laad de polyfill NIET onvoorwaardelijk.

Met een bundler of importtoewijzing:

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

Zonder bundler importeer je vanuit een CDN in een <script type="module">:

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

Opmerking over de stijl: De polyfill kan de echte pseudoklasse :popover-open niet definiëren, dus wordt in plaats daarvan de klasse .\:popover-open toegepast. VERPLICHT: Combineer de 2 met :is() of :where(), anders negeren browsers zonder :popover-open de hele regel:

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

Als alternatief kun je voor een verouderde fallback zonder polyfill position: fixed gebruiken en de coördinaten handmatig berekenen via getBoundingClientRect() of vertrouwen op de standaardpositionering met inset: auto als dat acceptabel is voor de use case.

ankerpositionering

Als je browsers zonder ankerpositionering wilt ondersteunen, kun je kiezen tussen een polyfill of een pure CSS-fallback.

Optie 1: Polyfill-reserveoptie

De polyfill @oddbird/css-anchor-positioning kan worden gebruikt om ankerpositionering te emuleren. Impliciete ankers worden niet ondersteund, dus je MOET expliciete ankernamen toevoegen aan de trigger. Daarnaast wordt position-area niet ondersteund voor pop-overs door de polyfill. Je MOET dus anchor() gebruiken voor de gewenste insets in plaats van 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);
}

Optie 2: Niet-polyfill CSS-terugval

Als je liever geen polyfill gebruikt, kun je de tooltip standaard op een vaste positie onderaan de viewport zetten met @supports not.

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