Dokument: startViewTransition()-Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Die startViewTransition()-Methode des Document-Interfaces startet eine neue Ansichtstransition im selben Dokument (SPA) und gibt ein ViewTransition-Objekt zurück, das diese darstellt.

Wenn startViewTransition() aufgerufen wird, wird eine Abfolge von Schritten befolgt, wie im Abschnitt Der Ansichtstransitionsprozess erklärt.

Eine optionale Callback-Funktion, die typischerweise während des SPA-Ansichtstransitionsprozesses aufgerufen wird, um das DOM zu aktualisieren und ein Promise zurückgibt. Der Callback wird aufgerufen, nachdem die API einen Schnappschuss der aktuellen Seite erstellt hat. Wenn das von dem Callback zurückgegebene Promise erfüllt wird, beginnt die Ansichtstransition im nächsten Frame. Wenn das Promise abgelehnt wird, wird die Transition abgebrochen.

options Optional

Ein Objekt, das Optionen zur Konfiguration der Ansichtstransition enthält. Es kann die folgenden Eigenschaften umfassen:

update Optional: Dieselbe updateCallback-Funktion, wie oben beschrieben. Standardwert ist null.
types Optional: Ein Array von Zeichenfolgen. Diese Zeichenfolgen dienen als Klassennamen oder Bezeichner für die Transition, sodass Sie selektiv CSS-Stile anwenden oder unterschiedliche JavaScript-Logik basierend auf dem Übergangstyp ausführen können. Der Standardwert ist eine leere Sequenz.

Rückgabewert

Eine Instanz des ViewTransition-Objekts.

Beispiele

Verwendung einer Ansichtstransition im selben Dokument

In dieser Ansichtstransition im selben Dokument überprüfen wir, ob der Browser Ansichtstransitionen unterstützt. Wenn es keine Unterstützung gibt, setzen wir die Hintergrundfarbe mit einer Fallback-Methode, die sofort angewendet wird. Andernfalls können wir sicher document.startViewTransition() mit Animationsregeln aufrufen, die wir in CSS definieren.

html

<main>
  <section></section>
  <button id="change-color">Change color</button>
</main>

Wir setzen die animation-duration auf 2 Sekunden unter Verwendung des ::view-transition-group Pseudo-Elements.

css

html {
  --bg: indigo;
}
main {
  display: flex;
  flex-direction: column;
  gap: 5px;
}
section {
  background-color: var(--bg);
  height: 60px;
  border-radius: 5px;
}
::view-transition-group(root) {
  animation-duration: 2s;
}

const colors = ["darkred", "darkslateblue", "darkgreen"];
const colBlock = document.querySelector("section");
let count = 0;
const updateColour = () => {
  colBlock.style = `--bg: ${colors[count]}`;
  count = count !== colors.length - 1 ? ++count : 0;
};
const changeColor = () => {
  // Fallback for browsers that don't support View Transitions:
  if (!document.startViewTransition) {
    updateColour();
    return;
  }

  // With View Transitions:
  const transition = document.startViewTransition(() => {
    updateColour();
  });
};
const changeColorButton = document.querySelector("#change-color");
changeColorButton.addEventListener("click", changeColor);
changeColorButton.addEventListener("keypress", changeColor);

Wenn Ansichtstransitionen unterstützt werden, wird durch Klicken auf die Schaltfläche die Farbe über 2 Sekunden hinweg von einer zur anderen wechseln. Andernfalls wird die Hintergrundfarbe ohne Animation mit einer Fallback-Methode gesetzt.