Dokument: startViewTransition()-Methode

Baseline 2025 *

Newly available

Since ⁨October 2025⁩, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

* Some parts of this feature may have varying levels of support.

Die startViewTransition()-Methode der Document-Schnittstelle startet eine neue gleiche-Dokument (SPA) Ansichtstransition und gibt ein ViewTransition-Objekt zurück, um sie darzustellen.

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

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

options Optional

Ein Objekt mit Optionen zur Konfiguration der Ansichtstransition. Es kann die folgenden Eigenschaften enthalten:

update Optional: Die gleiche oben beschriebene updateCallback-Funktion. Standardmäßig null.
types Optional: Ein Array von Zeichenfolgen, das die Arten darstellt, die auf die Ansichtstransition angewendet werden. Ansichtstransitionstypen ermöglichen die selektive Anwendung von CSS-Stilen oder JavaScript-Logik basierend auf dem Übergangstyp. Standardmäßig eine leere Sequenz.

Rückgabewert

Eine ViewTransition-Objektinstanz.

Beispiele

Siehe View Transition API > Beispiele für eine Liste vollständiger Beispiele.

Grundlegende Verwendung

In dieser gleichen-Dokument-Ansichtstransition überprüfen wir, ob der Browser Ansichtsübergänge unterstützt. Falls keine Unterstützung vorhanden ist, setzen wir die Hintergrundfarbe mit einer Fallback-Methode, die sofort angewandt 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 mithilfe des ::view-transition-group-Pseudoelements.

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 updateColor = () => {
  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) {
    updateColor();
    return;
  }

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

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