ContentVisibilityAutoStateChangeEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface ContentVisibilityAutoStateChangeEvent extends Event

Beschreibung

Die CSS-Eigenschaft content-visibility: auto sorgt dafür, dass der Browser das Rendern (Layout, Stil, Zeichnen) der Kindelemente überspringt, solange das Element für den Nutzer nicht relevant ist, etwa weil es weit außerhalb des sichtbaren Bereichs liegt. Beginnt oder endet dieses Überspringen, feuert der Browser am Element das Ereignis contentvisibilityautostatechange. Das zugehörige Ereignisobjekt ist ein ContentVisibilityAutoStateChangeEvent.

Die wichtigste Eigenschaft ist skipped (boolean). Bei true werden die Inhalte gerade übersprungen, bei false werden sie wieder gerendert. So kannst du aufwendige Arbeit an den Renderzustand koppeln, zum Beispiel Canvas-Animationen, requestAnimationFrame-Schleifen, Polling, WebSocket-Updates oder das nachträgliche Laden von Daten. Diese Arbeit läuft dann nur, wenn der Nutzer das Element tatsächlich sehen kann.

Du lauschst entweder mit element.addEventListener("contentvisibilityautostatechange", handler) oder über die Eigenschaft element.oncontentvisibilityautostatechange. Das Ereignis steigt nicht im DOM auf (kein Bubbling). Den Listener musst du deshalb direkt am Element mit content-visibility: auto registrieren. Den Konstruktor new ContentVisibilityAutoStateChangeEvent(type, options) brauchst du vor allem für Tests oder eigene Auslöser.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, normalerweise `"contentvisibilityautostatechange"` (nur beim Konstruktor).
$options	{ skipped?: boolean, bubbles?: boolean, cancelable?: boolean, composed?: boolean }	{ skipped: false }	Optionales Objekt mit den Event-Optionen. `skipped` legt den Wert der gleichnamigen Eigenschaft fest.

Rückgabewert

Typ

ContentVisibilityAutoStateChangeEvent

Beschreibung

Eine neue Event-Instanz. Die schreibgeschützte Eigenschaft skipped (boolean) gibt an, ob der Browser das Rendern der Elementinhalte gerade überspringt.

Beispiele

Canvas-Animation nur bei gerenderten Inhalten ausführen

// CSS: .panel { content-visibility: auto; contain-intrinsic-size: auto 400px; }
const panel = document.querySelector('.panel');
const canvas = panel.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, 100 + Math.sin(angle) * 50, 10, 10);
  angle += 0.05;
  frameId = requestAnimationFrame(draw);
};

panel.addEventListener('contentvisibilityautostatechange', (event) => {
  if (event.skipped) {
    cancelAnimationFrame(frameId);
    frameId = null;
    console.log('Animation pausiert');
  } else if (frameId === null) {
    draw();
    console.log('Animation gestartet');
  }
});

Animation gestartet Animation pausiert

Daten erst beim Rendern nachladen (on-Property)

const section = document.querySelector('#kommentare');
section.style.contentVisibility = 'auto';
section.style.containIntrinsicSize = 'auto 600px';

section.oncontentvisibilityautostatechange = async (event) => {
  if (event.skipped || section.dataset.loaded) return;
  section.dataset.loaded = 'true';
  const res = await fetch('/api/kommentare');
  const kommentare = await res.json();
  section.textContent = `${kommentare.length} Kommentare geladen`;
  // Einmalige Aufgabe erledigt – Handler entfernen
  section.oncontentvisibilityautostatechange = null;
};

Event manuell erzeugen (z. B. für Tests)

const el = document.createElement('div');

const onChange = (e) => {
  console.log(e instanceof ContentVisibilityAutoStateChangeEvent, e.skipped);
};
el.addEventListener('contentvisibilityautostatechange', onChange);

el.dispatchEvent(new ContentVisibilityAutoStateChangeEvent(
  'contentvisibilityautostatechange',
  { skipped: true }
));

el.removeEventListener('contentvisibilityautostatechange', onChange);

true true

// Wichtig · Fallstricke

Nur bei content-visibility: auto: Bei hidden oder visible feuert das Ereignis nicht.
Kein Bubbling: Event-Delegation über einen Elternknoten funktioniert nicht. Registriere den Listener direkt am Element.
Übersprungen heißt nicht unsichtbar: Der Browser rendert auch Inhalte knapp außerhalb des sichtbaren Bereichs, und fokussierte oder ausgewählte Inhalte werden nie übersprungen. Für exakte Sichtbarkeitsprüfungen nimm IntersectionObserver.
Erstes Ereignis: Ein erstes Ereignis kommt, sobald der Browser den Anfangszustand festlegt. Initialisiere Logik deshalb nicht doppelt.
Nutze zusätzlich contain-intrinsic-size, damit die Scrollbar nicht springt.
Kompatibilität: Chromium 108+, Firefox 130+, Safari 18+. Prüfe die Unterstützung mit 'ContentVisibilityAutoStateChangeEvent' in window und sieh sonst einen Ersatz mit IntersectionObserver vor.

Siehe auch

Event XRVisibilityMaskChangeEvent ExtendableCookieChangeEvent ClipboardChangeEvent PaymentMethodChangeEvent