Dauerhafte App-Touren erstellen

Webfunktionen: Popover Ankerpositionierung

Für Onboarding-Touren sind Overlays erforderlich, die angezeigt bleiben, während Nutzer mit den hervorgehobenen Funktionen interagieren. Im Gegensatz zu automatischen Popovers werden manuelle Popovers nicht geschlossen, wenn der Nutzer auf eine andere Stelle der Seite klickt. Wenn Sie popover="manual" mit der CSS-Ankerpositionierung kombinieren, können Sie nicht modale, verankerte Tour-Schritte erstellen.

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

Implementierungsrichtlinien

  • OBLIGATORISCH: Verwenden Sie popover="manual", um zu verhindern, dass der Schritt der Tour während der Nutzerinteraktion versehentlich geschlossen wird.
  • OBLIGATORISCH: Kennzeichnen Sie den Container mit role="dialog" und verlinken Sie die Überschrift über aria-labelledby.
  • OBLIGATORISCH: Der programmatische Fokus muss sofort nach dem Öffnen des Popovers dorthin verschoben werden, um zu verhindern, dass der Fokus verloren geht.
  • DO: Verwenden Sie die CSS-Ankerpositionierung, um den Schritt der Tour mit der jeweiligen Funktion zu verknüpfen, die erklärt wird.
  • DO provide an explicit "Close" or "Next" button within the popover that uses popovertargetaction="hide".

Fallback-Strategien

Fallbacks und Browserunterstützung für Popover

Die Popover API ist größtenteils eine progressive Verbesserung, aber ihre definierenden Verhaltensweisen – die Hochstufung auf die oberste Ebene, das Schließen durch Klicken außerhalb des Popovers und der Aufruf von popovertarget – haben kein CSS-Äquivalent. Ältere Browser benötigen ein Polyfill oder ein manuelles Fallback, wenn Sie kein Polyfill bereitstellen möchten.

Polyfill: Damit das Attribut popover in älteren Browsern unterstützt wird, lade @oddbird/popover-polyfill bedingt. OBLIGATORISCH: Prüfe, ob die Funktion unterstützt wird, indem du nach der Property popover in HTMLElement.prototype suchst, und lade das Polyfill nur, wenn die native Unterstützung fehlt. Lade es NICHT bedingungslos.

Mit einem Bundler oder einer Importzuordnung:

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

Ohne Bundler importieren Sie aus einem CDN in einem <script type="module">:

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

Einschränkung beim Styling: Das Polyfill kann die echte Pseudoklasse :popover-open nicht definieren, daher wird stattdessen die Klasse .\:popover-open angewendet. OBLIGATORISCH: Kombinieren Sie die beiden mit :is() oder :where(). Andernfalls verwerfen Browser, die :popover-open nicht unterstützen, die gesamte Regel:

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

Alternativ können Sie für einen Legacy-Fallback ohne Polyfill position: fixed verwenden und die Koordinaten manuell über getBoundingClientRect() berechnen oder die Standardpositionierung mit inset: auto verwenden, wenn das für den Anwendungsfall akzeptabel ist.

anchor-positioning

Wenn Sie Browser ohne Ankerpositionierung unterstützen möchten, können Sie zwischen einem Polyfill und einem reinen CSS-Fallback wählen.

Option 1: Polyfill-Fallback

Mit dem @oddbird/css-anchor-positioning-Polyfill kann die Ankerpositionierung emuliert werden. Implizite Anker werden nicht unterstützt. Sie MÜSSEN dem Trigger also explizite Ankernamen hinzufügen. Außerdem wird position-area vom Polyfill nicht für Popovers unterstützt. Du MUSST also anchor() für die gewünschten Insets anstelle von position-area verwenden.

<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: CSS-Fallback ohne Polyfill

Wenn Sie kein Polyfill verwenden möchten, können Sie den Kurzinfo standardmäßig mit @supports not an einer festen Position am unteren Rand des Darstellungsbereichs platzieren.

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