Crea visitas guiadas persistentes por la app

Funciones web: Popover Posicionamiento de anclaje

Los recorridos de integración requieren superposiciones que persistan mientras los usuarios interactúan con las funciones destacadas. A diferencia de los popovers automáticos, los manuales no se cierran cuando el usuario hace clic en otro lugar de la página. La combinación de popover="manual" con el posicionamiento de anclaje de CSS te permite crear pasos de visita guiada vinculados no modales.

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

Lineamientos de implementación

  • OBLIGATORIO: Usa popover="manual" para evitar que el paso de la visita guiada se cierre accidentalmente durante la interacción del usuario.
  • OBLIGATORIO: Marca el contenedor con role="dialog" y vincula su encabezado con aria-labelledby.
  • OBLIGATORIO: Cambia el enfoque programático dentro del cuadro emergente inmediatamente después de abrirlo para evitar que se pierda el enfoque.
  • SÍ uses el posicionamiento de anclaje de CSS para vincular el paso de la visita guiada a la función específica que se explica.
  • SÍ proporciona un botón explícito "Cerrar" o "Siguiente" dentro del cuadro emergente que usa popovertargetaction="hide".

Estrategias de resguardo

Resguardos y compatibilidad de navegadores para Popover

La API de Popover es, en su mayor parte, una mejora progresiva, pero sus comportamientos definitorios (promoción de la capa superior, cierre rápido y la invocación de popovertarget) no tienen un equivalente solo de CSS. Los navegadores más antiguos necesitan un polyfill o un resguardo manual si prefieres no enviar uno.

Polyfill: Para admitir el atributo popover en navegadores más antiguos, carga @oddbird/popover-polyfill de forma condicional. OBLIGATORIO: Detecta la función verificando la propiedad popover en HTMLElement.prototype y carga el polyfill solo cuando no haya compatibilidad nativa. NO lo cargues de forma incondicional.

Con un empaquetador o un mapa de importación:

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

Sin un empaquetador, importa desde una CDN dentro de 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>

Advertencia de diseño: El polyfill no puede definir la pseudoclase :popover-open real, por lo que aplica una clase .\:popover-open en su lugar. OBLIGATORIO: Combina las dos con :is() o :where(); de lo contrario, los navegadores que no tengan :popover-open descartarán toda la regla:

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

Como alternativa, para un resguardo heredado sin un polyfill, usa position: fixed y calcula manualmente las coordenadas a través de getBoundingClientRect() o confía en el posicionamiento predeterminado con inset: auto si eso es aceptable para el caso de uso.

anchor-positioning

Para admitir navegadores sin posicionamiento de fijación, puedes elegir entre usar un polyfill o un resguardo de CSS puro.

Opción 1: Resguardo de polyfill

El polyfill @oddbird/css-anchor-positioning se puede usar para emular el posicionamiento de las anclas. No admite anclas implícitas, por lo que DEBES agregar nombres de anclas explícitos al activador. Además, el polyfill no admite position-area en los popovers, por lo que DEBES usar anchor() en las inserciones deseadas en lugar 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);
}
Opción 2: Resguardo de CSS sin polyfill

Si prefieres no usar un polyfill, puedes establecer la información sobre la herramienta en una posición fija en la parte inferior del viewport con @supports not.

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