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, gleichbleibende Dokumentansicht (SPA) view transition und gibt ein ViewTransition-Objekt zurück, das diese repräsentiert.

Wenn startViewTransition() aufgerufen wird, folgt eine Abfolge von Schritten, wie sie im Prozess der View Transition erklärt werden.

Syntax

js
startViewTransition()
startViewTransition(updateCallback)

Parameter

updateCallback Optional

Eine optionale Callback-Funktion, die typischerweise aufgerufen wird, um das DOM während des SPA-View-Transition-Prozesses zu aktualisieren und die ein Promise zurückgibt. Der Callback wird aufgerufen, sobald die API einen Schnappschuss der aktuellen Seite erstellt hat. Wenn das durch den Callback zurückgegebene Promise erfüllt wird, beginnt die View Transition im nächsten Frame. Wenn das Promise zurückgewiesen wird, wird die Transition abgebrochen.

Rückgabewert

Eine Instanz des ViewTransition-Objekts.

Beispiele

Verwendung einer gleichen Dokument-View-Transition

In dieser gleichen Dokument-View-Transition prüfen wir, ob der Browser View Transitions unterstützt. Falls keine Unterstützung vorhanden ist, setzen wir die Hintergrundfarbe mit einer Ersatzmethode, die sofort angewendet wird. Andernfalls kann document.startViewTransition() mit Animationsregeln, die wir in CSS definieren, sicher aufgerufen werden.

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;
}
js
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 View Transitions unterstützt werden, wird durch Klicken auf den Button die Farbe von einer zur anderen über 2 Sekunden hinweg übergehen. Andernfalls wird die Hintergrundfarbe ohne Animation mit einer Ersatzmethode gesetzt.

Spezifikationen

Specification
CSS View Transitions Module Level 1
# dom-document-startviewtransition
CSS View Transitions Module Level 2
# dom-document-startviewtransition

Browser-Kompatibilität

Siehe auch