new ContentVisibilityAutoStateChangeEvent() — Methode · JavaScript-Referenz

Signatur

new ContentVisibilityAutoStateChangeEvent(type, options)

Beschreibung

Der Konstruktor ContentVisibilityAutoStateChangeEvent() erzeugt eine neue Instanz des Ereignistyps, den der Browser normalerweise selbst auslöst: Er feuert contentvisibilityautostatechange auf Elementen mit content-visibility: auto, sobald der Browser mit dem Rendern des Inhalts beginnt oder aufhört (Relevanz bzw. Skipping).

Im Alltag erstellt man dieses Objekt selten selbst. Sinnvoll ist der Konstruktor vor allem für Unit-Tests, in denen man Listener prüfen will, ohne auf echtes Scrollen oder Layout zu warten. Auch zum Simulieren von Zustandswechseln ist er brauchbar, etwa um Logik anzustoßen, die rechenintensive Arbeiten (Canvas-Animationen, Datenabrufe) pausiert oder fortsetzt.

Der entscheidende Wert ist die Eigenschaft skipped. true heißt, dass der Inhalt des Elements gerade übersprungen wird, also nicht gerendert wird. false heißt, dass er relevant ist und gerendert wird. Diese Eigenschaft setzt man über das Options-Objekt. Das so erzeugte Ereignis löst man anschließend mit dispatchEvent() aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, üblicherweise `"contentvisibilityautostatechange"`. Groß- und Kleinschreibung wird beachtet.
$options	Object	{}	Optionales Objekt mit den Feldern von `EventInit` (`bubbles`, `cancelable`, `composed`, alle standardmäßig `false`) und zusätzlich `skipped`.
$options.skipped	boolean	false	`true`, wenn der Inhalt des Elements übersprungen (nicht gerendert) wird, sonst `false`.

Rückgabewert

Typ

ContentVisibilityAutoStateChangeEvent

Beschreibung

Ein neues Ereignisobjekt, dessen Eigenschaft skipped nur gelesen werden kann.

Beispiele

Ereignis erzeugen und Eigenschaften prüfen

const event = new ContentVisibilityAutoStateChangeEvent(
  'contentvisibilityautostatechange',
  { skipped: true }
);

console.log(event.type);
console.log(event.skipped);
console.log(event.bubbles);

contentvisibilityautostatechange true false

Zustandswechsel simulieren, um einen Listener zu testen

const section = document.createElement('section');
section.style.contentVisibility = 'auto';
document.body.append(section);

section.addEventListener('contentvisibilityautostatechange', (e) => {
  console.log(e.skipped ? 'Arbeit pausieren' : 'Arbeit fortsetzen');
});

// Zustandswechsel künstlich auslösen
section.dispatchEvent(new ContentVisibilityAutoStateChangeEvent(
  'contentvisibilityautostatechange', { skipped: false }
));
section.dispatchEvent(new ContentVisibilityAutoStateChangeEvent(
  'contentvisibilityautostatechange', { skipped: true }
));

Arbeit fortsetzen Arbeit pausieren

Canvas-Animation abhängig von der Sichtbarkeit steuern (mit Feature-Erkennung)

const canvas = document.querySelector('#chart');
let frameId = null;

const draw = () => {
  // ... Zeichenlogik ...
  frameId = requestAnimationFrame(draw);
};

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

// Anfangszustand nur setzen, wenn die API vorhanden ist
if ('ContentVisibilityAutoStateChangeEvent' in window) {
  canvas.parentElement.dispatchEvent(
    new ContentVisibilityAutoStateChangeEvent('contentvisibilityautostatechange', { skipped: false })
  );
}

// Wichtig · Fallstricke

Browser-Kompatibilität: Chromium-Browser unterstützen die API ab Version 108, Firefox ab 125 und Safari ab 18. In älteren Browsern führt der Konstruktoraufruf zu einem ReferenceError. Deshalb vorher mit 'ContentVisibilityAutoStateChangeEvent' in window prüfen.
Ein selbst erzeugtes Ereignis hat isTrusted === false und beeinflusst das Rendering nicht. Es ruft nur die registrierten Listener auf.
Ohne bubbles: true steigt das Ereignis nicht im DOM auf. Auch das vom Browser ausgelöste Original-Ereignis steigt nicht auf, deshalb muss der Listener direkt am Element mit content-visibility: auto registriert werden.
skipped ist nach dem Erzeugen schreibgeschützt. Für einen anderen Wert muss ein neues Ereignis erzeugt werden.
Den Konstruktor ohne new aufzurufen, löst einen TypeError aus.

Siehe auch

Event new GravitySensor() new Gyroscope() new XRVisibilityMaskChangeEvent() new ExtendableCookieChangeEvent()