ContentVisibilityAutoStateChangeEvent.skipped — Eigenschaft · JavaScript-Referenz

Signatur

ContentVisibilityAutoStateChangeEvent.skipped

Beschreibung

Die Eigenschaft skipped gehört zum Ereignis contentvisibilityautostatechange. Das Ereignis wird auf einem Element mit der CSS-Eigenschaft content-visibility: auto ausgelöst, wenn der Browser anfängt oder aufhört, die Inhalte des Elements zu überspringen. „Überspringen“ heißt: Layout, Zeichnen und Hit-Testing der Kindelemente fallen weg, weil das Element nicht relevant ist, also etwa außerhalb des Viewports liegt, keinen Fokus hat und keine Auswahl enthält.

Der Wert ist true, wenn die Inhalte ab jetzt übersprungen werden, und false, wenn sie wieder gerendert werden. So kannst du teure Arbeit an die Sichtbarkeit koppeln: Canvas-Animationen anhalten, Polling beenden, Videos pausieren oder Inhalte erst dann nachladen, wenn sie gerendert werden.

Anders als ein IntersectionObserver richtet sich das Ereignis nach dem Rendering-Zustand des Browsers. Es berücksichtigt also auch Fokus und Textauswahl und nicht nur die geometrische Überschneidung mit dem Viewport.

Beispiele

Zustandswechsel protokollieren

// CSS: .section { content-visibility: auto; contain-intrinsic-size: auto 500px; }
const section = document.querySelector('.section');

section.addEventListener('contentvisibilityautostatechange', (event) => {
  console.log(event.skipped ? 'Inhalte übersprungen' : 'Inhalte werden gerendert');
});

Inhalte werden gerendert Inhalte übersprungen

Canvas-Animation nur bei gerenderten Inhalten laufen lassen

const container = document.querySelector('#chart-container');
const canvas = container.querySelector('canvas');
const ctx = canvas.getContext('2d');
let frameId = null;
let angle = 0;

const draw = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.fillRect(100 + Math.cos(angle) * 50, 75, 10, 10);
  angle += 0.05;
  frameId = requestAnimationFrame(draw);
};

container.addEventListener('contentvisibilityautostatechange', ({ skipped }) => {
  if (skipped) {
    cancelAnimationFrame(frameId);
    frameId = null;
  } else if (frameId === null) {
    frameId = requestAnimationFrame(draw);
  }
});

Inhalte nachladen, sobald sie gerendert werden, mit Fallback

const cards = document.querySelectorAll('.lazy-card');
const supported = 'ContentVisibilityAutoStateChangeEvent' in window;

const loadContent = async (card) => {
  if (card.dataset.loaded) return;
  card.dataset.loaded = 'true';
  const res = await fetch(card.dataset.src);
  card.textContent = await res.text();
};

cards.forEach((card) => {
  if (!supported) {
    loadContent(card); // Fallback: sofort laden
    return;
  }
  const onChange = (event) => {
    if (!event.skipped) {
      loadContent(card);
      card.removeEventListener('contentvisibilityautostatechange', onChange);
    }
  };
  card.addEventListener('contentvisibilityautostatechange', onChange);
});

// Wichtig · Fallstricke

Das Ereignis wird nur auf Elementen mit content-visibility: auto ausgelöst. Bei visible oder hidden gibt es kein Ereignis.
Es gibt keine on-Eigenschaft wie oncontentvisibilityautostatechange. Nutze immer addEventListener().
Das Ereignis wird asynchron ausgelöst und blubbert nicht (bubbles: false). Delegation über ein Elternelement funktioniert daher nicht, der Listener muss am Element selbst hängen.
Der Browser kann das Überspringen jederzeit aufheben, etwa bei Fokus, Textauswahl oder der Suche im Seitentext (Strg+F). Verlass dich deshalb nicht darauf, dass skipped === true „unsichtbar für immer“ bedeutet.
Nutze die Unterstützung erst nach einer Feature-Prüfung mit 'ContentVisibilityAutoStateChangeEvent' in window. Ältere Browser brauchen einen Fallback, z. B. IntersectionObserver.
Setze zusätzlich contain-intrinsic-size, damit übersprungene Elemente eine Platzhaltergröße haben und die Scrollleiste nicht springt.

Siehe auch

WindowControlsOverlayGeometryChangeEvent.visible XRVisibilityMaskChangeEvent.session XRVisibilityMaskChangeEvent.index XRVisibilityMaskChangeEvent.eye XRVisibilityMaskChangeEvent.indices