CSSViewTransitionRule — Schnittstelle · JavaScript-Referenz

Signatur

interface CSSViewTransitionRule extends CSSRule

Beschreibung

CSSViewTransitionRule ist die CSSOM-Darstellung der At-Regel @view-transition. Mit dieser Regel schaltet ein Dokument dokumentübergreifende View Transitions ein, also animierte Übergänge beim Navigieren zwischen zwei Seiten desselben Ursprungs (same-origin). Beide Seiten müssen dafür @view-transition { navigation: auto; } angeben.

Die Schnittstelle erbt von CSSRule und hat zwei eigene, schreibgeschützte Eigenschaften:

navigation: ein String mit dem Wert des Deskriptors navigation, nämlich "auto" oder "none". Gibt es keinen gültigen Wert, liefert die Eigenschaft einen leeren String.
types: ein eingefrorenes Array von Strings mit den Übergangstypen aus dem Deskriptor types. Mit diesen Typen kannst du per :active-view-transition-type() unterschiedliche Animationen auswählen.

Die Schnittstelle erzeugst du nicht selbst. Du bekommst sie, wenn du CSSStyleSheet.cssRules durchläufst. Nützlich ist sie vor allem für Diagnose-Werkzeuge, für Tests und für Feature-Erkennung, zum Beispiel um herauszufinden, ob eine Seite dokumentübergreifende Übergänge aktiviert hat. Um das Verhalten zur Laufzeit zu ändern, bearbeitest du das Stylesheet, etwa mit insertRule() oder deleteRule().

Parameter

Name	Typ	Default	Beschreibung
$navigation	string	""	Schreibgeschützt. Wert des Deskriptors `navigation`: `"auto"` (Übergänge bei Navigation aktiv) oder `"none"` (inaktiv).
$types	ReadonlyArray<string>	[]	Schreibgeschützt. Liste der Übergangstypen aus dem Deskriptor `types`, z. B. `["slide", "forwards"]`.
$cssText	string		Geerbt von `CSSRule`. Die komplette Regel als Text.
$parentStyleSheet	CSSStyleSheet \| null		Geerbt von `CSSRule`. Das Stylesheet, zu dem die Regel gehört.

Rückgabewert

Typ

CSSViewTransitionRule

Beschreibung

Ein Regelobjekt aus CSSStyleSheet.cssRules. Es entspricht einer @view-transition-Regel.

Beispiele

@view-transition-Regeln im Dokument finden

// CSS: @view-transition { navigation: auto; types: slide forwards; }
const findViewTransitionRules = () => {
  const result = [];
  for (const sheet of document.styleSheets) {
    let rules;
    try {
      rules = sheet.cssRules; // bei fremden Ursprüngen: SecurityError
    } catch {
      continue;
    }
    for (const rule of rules) {
      if (typeof CSSViewTransitionRule !== 'undefined' && rule instanceof CSSViewTransitionRule) {
        result.push(rule);
      }
    }
  }
  return result;
};

for (const rule of findViewTransitionRules()) {
  console.log(rule.navigation, rule.types);
}

auto ["slide", "forwards"]

Prüfen, ob dokumentübergreifende Übergänge aktiv sind

const crossDocumentTransitionsEnabled = () =>
  [...document.styleSheets].some((sheet) => {
    try {
      return [...sheet.cssRules].some(
        (rule) => rule instanceof CSSViewTransitionRule && rule.navigation === 'auto'
      );
    } catch {
      return false;
    }
  });

if ('CSSViewTransitionRule' in window) {
  console.log('Cross-Document-Transitions:', crossDocumentTransitionsEnabled());
} else {
  console.log('@view-transition wird nicht unterstützt');
}

Cross-Document-Transitions: true

Regel zur Laufzeit einfügen und wieder entfernen

const sheet = new CSSStyleSheet();
document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];

const index = sheet.insertRule('@view-transition { navigation: auto; }');
const rule = sheet.cssRules[index];

console.log(rule.constructor.name); // CSSViewTransitionRule
console.log(rule.navigation);       // auto
console.log(rule.cssText);

// Übergänge z. B. bei aktivierter Einstellung „Bewegung reduzieren“ abschalten
if (matchMedia('(prefers-reduced-motion: reduce)').matches) {
  sheet.deleteRule(index);
}

CSSViewTransitionRule auto @view-transition { navigation: auto; }

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser unterstützen die Schnittstelle ab Version 126, Safari ab 18.2. Firefox unterstützt dokumentübergreifende View Transitions noch nicht (Stand der Erstellung). Prüfe deshalb vorher mit 'CSSViewTransitionRule' in window. Die Eigenschaft types kann in älteren Versionen fehlen.
Die Eigenschaften navigation und types sind schreibgeschützt. Um eine Regel zu ändern, entfernst du sie mit deleteRule() und fügst sie mit insertRule() neu ein.
Dokumentübergreifende Übergänge funktionieren nur bei Navigationen auf demselben Ursprung. Beide Seiten müssen navigation: auto angeben.
Bei Stylesheets von fremden Ursprüngen ohne CORS löst der Zugriff auf cssRules einen SecurityError aus. Fange den Fehler deshalb mit try/catch ab.
Im Prüfer-Modus der Media Query prefers-reduced-motion nicht vergessen: Nutzer sollen Animationen abschalten können.

Siehe auch

ViewTransition CSSConditionRule CSSTransition CSSFunctionRule ViewTransitionTypeSet