Navigator: getAutoplayPolicy() Methode

Die Methode muss mit einem (und nur einem) der folgenden drei Parameter aufgerufen werden:

type Optional

Ein String, der das Medienwiedergabe-Feature angibt, für das die allgemeine Autoplay-Richtlinie erforderlich ist.

Die unterstützten Werte sind:

mediaelement

Ermittelt die allgemeine Autoplay-Richtlinie für Medienelemente im Dokument. Medienelemente sind von HTMLMediaElement abgeleitete Objekte wie HTMLAudioElement und HTMLVideoElement und ihre entsprechenden Tags <audio> und <video>.

audiocontext

Holt die allgemeine Autoplay-Richtlinie für Web Audio API-Player im Dokument.

element Optional

Ein spezifisches Medienelement. Dies muss ein HTMLMediaElement sein, einschließlich abgeleiteter Elemente wie HTMLVideoElement und HTMLAudioElement.

context Optional

Ein spezifischer AudioContext.

Ein String, der die Autoplay-Richtlinie für den angegebenen Medienelementtyp, das Element oder den Kontext angibt. Dies wird ein String sein, der einen der folgenden Werte enthält:

allowed

Autoplay ist erlaubt.

allowed-muted

Autoplay ist nur für nicht hörbare Medien erlaubt. Dazu gehören Medien ohne Tonspur oder bei denen der Ton stummgeschaltet wurde.

disallowed

Autoplay ist nicht erlaubt.

Beachten Sie, dass die Autoplay-Richtlinie, die für einen type-Parameter zurückgegeben wird, die allgemeine Richtlinie für Elemente des angegebenen Typs ist. Beim Laden der Seite haben alle Elemente eines Typs dieselbe Richtlinie wie der Typ. Nachdem der Benutzer mit der Seite/Site interagiert hat, kann es bei einigen Browsern passieren, dass einzelne Elemente eine andere Richtlinie als der entsprechende Typ haben.

TypeError

Das an die Methode übergebene Objekt ist kein erlaubter Typ. Zu den erlaubten Typen gehören HTMLMediaElement (oder ein abgeleitetes Element wie HTMLVideoElement und HTMLAudioElement), oder AudioContext.

"Autoplay" bezieht sich auf alle Funktionen, die dazu führen, dass Inhalte abgespielt werden, ohne dass der Benutzer dies explizit angefordert hat. Dies umfasst das autoplay Attribut in den HTML <video> und <audio> Elementen sowie die Verwendung von JavaScript-Code, um die Wiedergabe ohne Benutzerinteraktion zu starten.

Benutzeragenten blockieren häufig das automatische Abspielen oder erlauben nur das automatische Abspielen von nicht hörbarem Inhalt, da unerwartete Geräusche beim erstmaligen Laden einer Seite zu einem erschreckenden und unangenehmen Benutzererlebnis führen können. Die Mechanismen, die verwendet werden, um zu bestimmen, ob Inhalte automatisch wiedergegeben werden können oder nicht, oder nur für nicht hörbare Inhalte, unterscheiden sich zwischen Benutzeragenten.

Die getAutoplayPolicy() Methode bietet einen standardisierten Mechanismus, um die Richtlinie eines bestimmten Benutzeragenten für das automatische Abspielen eines bestimmten Typs oder Inhaltsgegenstands zu ermitteln. Dies ermöglicht Anpassungen der Anwendung, wie z. B. das automatische Stummschalten von Videos auf Websites, auf denen das automatische Abspielen von hörbarem Inhalt nicht erlaubt ist, oder das Ändern des Verhaltens der Anwendung ohne automatisches Abspielen.

Die empfohlene Verwendung der Methode besteht darin, sie beim Laden der Seite (oder bevor die Inhaltelemente erstellt werden) mit Angabe des zu prüfenden Features aufzurufen und dann das automatische Abspielen der Medienelemente basierend auf dem Ergebnis zu konfigurieren. Beispielsweise können Sie den folgenden Code verwenden, um Videos stummzuschalten, wenn nur das automatische Abspielen von nicht hörbarem Inhalt erlaubt ist.

if (navigator.getAutoplayPolicy("mediaelement") === "allowed") {
  // Do nothing. The content can autoplay.
} else if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
  // Mute the video so it can autoplay.
} else {
  // Autoplay disallowed.
  // Add a play button to the video element.
}

Die Methode kann auch verwendet werden, um die Autoplay-Richtlinie für ein bestimmtes Medienelement oder einen bestimmten Audiokontext zu überprüfen. Wie unten gezeigt, sieht der Code genau gleich aus, außer dass Sie das spezifische Element anstelle des type-Strings übergeben.

const video = document.getElementById("video_element_id");
if (navigator.getAutoplayPolicy(video) === "allowed") {
  // Do nothing. The content can autoplay.
} else if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
  // Mute the video so it can autoplay.
} else {
  // Autoplay disallowed.
  // Add a play button to the video element.
}

Beim Laden der Seite, bevor der Benutzer mit der Seite oder Site interagiert hat, werden die Autoplay-Richtlinie für den Typ und die einzelnen Elemente dieselbe sein. Nachdem der Benutzer mit der Site, der Seite oder spezifischen Elementen interagiert hat, kann sich die Autoplay-Richtlinie für den gesamten type ändern. Es ist auch möglich, dass sich die Richtlinie für ein bestimmtes Element ändert, selbst wenn sich die allgemeine Richtlinie für den type nicht ändert.

Es gibt keine Möglichkeit, benachrichtigt zu werden, dass sich die Autoplay-Richtlinie geändert hat. Aus diesem Grund, obwohl Sie die Richtlinie für einen Typ oder ein Element jederzeit überprüfen können, werden Sie dies normalerweise nur beim Laden der Seite oder bevor Sie versuchen, Inhalte abzuspielen, tun.

Der untenstehende Code zeigt, wie Sie überprüfen können, ob navigator.getAutoplayPolicy() unterstützt wird:

<div id="reportResult"></div>

const log = document.getElementById("reportResult");

if (!navigator.getAutoplayPolicy) {
  log.textContent = "navigator.getAutoplayPolicy() not supported.";
} else {
  log.textContent = "navigator.getAutoplayPolicy() is supported.";
}

Das Ergebnis der Ausführung des Codes auf dieser Seite ist:

Dieses Beispiel zeigt, wie Sie die Autoplay-Richtlinie für den Medienelementtyp überprüfen können.

Der Code erzeugt ein Videoelement, das das autoplay Attribut hat und standardmäßig nicht stummgeschaltet ist. Wenn die Autoplay-Richtlinie "allowed-muted" ist, wird das Video stummgeschaltet, um es abspielen zu können.

HTML

Das untenstehende HTML hat ein div Element, das als Berichtprotokoll verwendet wird und auch ein <video> anzeigt, das das autoplay Attribut hat. Dieses sollte standardmäßig nicht stummgeschaltet werden und automatisch abspielen, wenn das automatische Abspielen nicht blockiert ist.

<div id="reportResult"></div>
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  id="bunny_vid"
  autoplay
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a> and
  watch it with your favorite video player!
</video>

JavaScript

Der Code meldet, ob die getAutoplayPolicy() Methode unterstützt wird, und wenn ja, die Richtlinie für Medienelemente.

Wenn die Richtlinie allowed-muted ist, können nur stummgeschaltete Videos abgespielt werden. In diesem Fall fügen wir einen Text hinzu, der erklärt, was passiert, und schalten das Video stumm.

const log = document.getElementById("reportResult");
const video = document.getElementById("bunny_vid");

if (!navigator.getAutoplayPolicy) {
  log.textContent =
    "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!";
} else {
  log.textContent = `Autoplay policy for media elements is: ${navigator.getAutoplayPolicy(
    "mediaelement",
  )}. `;

  if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
    // Mute the video so it can autoplay
    video.muted = true;
    log.textContent += "Video has been muted to allow it to autoplay.";
  }
}

Beachten Sie, dass Sie ähnlich für allowed und disallowed prüfen könnten.

Ergebnis

Das Video wird unten zusammen mit Informationen darüber angezeigt, ob die getAutoplayPolicy() Methode unterstützt wird, und falls ja, die Richtlinie.

Wenn getAutoplayPolicy() unterstützt wird und die Richtlinie allowed ist, wird das Video automatisch mit Ton abgespielt. Wenn die Richtlinie allowed-muted ist, wird das Video ohne Ton abgespielt.

Beachten Sie, dass das Video, wenn getAutoplayPolicy() nicht unterstützt wird, entweder mit Audio automatisch abspielt oder nicht abspielt. Der Code hat keine Kontrolle über dieses Verhalten: Sie sind dem Browserverhalten ausgeliefert!

Dieses Beispiel zeigt, wie Sie überprüfen können, ob ein bestimmtes Medienelement automatisch abspielen wird. Es ist fast genau dasselbe wie das vorherige Beispiel (eine AudioContext Überprüfung wäre ebenfalls ähnlich). Beachten Sie, dass es möglich ist, dass spezifische Elemente automatisch abspielen, auch wenn eine Überprüfung des mediaelement Typs ergibt, dass das automatische Abspielen disallowed ist; mit anderen Worten, eine Überprüfung eines bestimmten Elements ist zuverlässiger (obwohl es beim Laden der Seite keine Rolle spielt).

Der Code erzeugt ein Videoelement, das das autoplay Attribut hat. Wenn die Autoplay-Richtlinie "allowed-muted" ist, wird das Video stummgeschaltet, um es abspielen zu können.

HTML

Das untenstehende HTML hat ein div Element, das als Berichtprotokoll verwendet wird und auch ein <video> anzeigt, das das autoplay Attribut hat. Dieses sollte standardmäßig nicht stummgeschaltet werden und automatisch abspielen, wenn das automatische Abspielen nicht blockiert ist.

<div id="reportResult"></div>
<!-- Simple video example -->
<!-- 'Big Buck Bunny' licensed under CC 3.0 by the Blender foundation. Hosted by archive.org -->
<!-- Poster from peach.blender.org -->
<video
  id="bunny_vid"
  autoplay
  controls
  src="https://archive.org/download/BigBuckBunny_124/Content/big_buck_bunny_720p_surround.mp4"
  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg?x11217"
  width="620">
  Sorry, your browser doesn't support embedded videos, but don't worry, you can
  <a href="https://archive.org/details/BigBuckBunny_124">download it</a> and
  watch it with your favorite video player!
</video>

JavaScript

Der Code meldet, ob die getAutoplayPolicy() Methode unterstützt wird, und wenn ja, die Richtlinie für Medienelemente.

Wenn die Richtlinie allowed-muted ist, können nur stummgeschaltete Videos abgespielt werden, daher schaltet der Code das Video stumm.

const log = document.getElementById("reportResult");
const video = document.getElementById("bunny_vid");

if (!navigator.getAutoplayPolicy) {
  log.textContent =
    "navigator.getAutoplayPolicy() not supported. It may or may not autoplay, depending on the browser!";
} else {
  // Here we pass in the HTMLVideoElement to check
  log.textContent = `navigator.getAutoplayPolicy(video) === ${navigator.getAutoplayPolicy(
    "mediaelement",
  )}`;

  if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
    // Mute the video so it can autoplay
    video.muted = true;
    log.textContent += "Video has been muted to allow it to autoplay.";
  }
}

Ergebnis

Das Ergebnis ist dasselbe wie im vorherigen Beispiel:

• Das Video sollte automatisch mit Ton abspielen, wenn allowed zurückgegeben wird, und ohne Ton, wenn allowed-muted zurückgegeben wird.
• Wenn getAutoplayPolicy() nicht unterstützt wird, hängt das Autoplay-Verhalten des Videos nur vom Browser ab.

• Autoplay-Leitfaden für Medien- und Web-Audio-APIs