Navigator：getAutoplayPolicy() 方法

实验性： 这是一项实验性技术
在生产环境中使用此功能前，请仔细查看浏览器兼容性表格。

自动播放策略检测 API 的getAutoplayPolicy() 方法提供有关媒体元素和音频上下文的自动播放是否允许、不允许或仅在音频静音时允许的信息。

应用程序可以使用此信息提供合适的用户体验。例如，如果用户代理策略仅允许无声内容自动播放，则应用程序可能会将视频静音，以便它们仍然可以自动播放。

该方法可用于获取文档中特定类型的所有项目的广泛自动播放策略，或特定媒体元素或音频上下文的策略。

语法

// Test autoplay policy for a particular media playing feature
getAutoplayPolicy(type)

// Test autoplay support for a specific element or context
getAutoplayPolicy(element)
getAutoplayPolicy(context)

参数

该方法必须使用以下三个参数之一（且只能使用一个）调用

type 可选

一个字符串，指示需要获取其广泛自动播放策略的媒体播放功能。

支持的值为：

mediaelement: 获取文档中媒体元素的广泛自动播放策略。媒体元素是HTMLMediaElement派生对象，例如HTMLAudioElement和HTMLVideoElement，以及它们对应的标签<audio>和<video>。
audiocontext: 获取文档中Web 音频 API播放器的广泛自动播放策略。

element 可选

一个特定的媒体元素。这必须是HTMLMediaElement，包括派生元素，例如HTMLVideoElement和HTMLAudioElement。

context 可选

一个特定的AudioContext。

返回值

一个字符串，指示指定媒体功能类型、元素或上下文的自动播放策略。这将是一个包含以下值之一的字符串：

allowed: 允许自动播放。
allowed-muted: 仅允许无声媒体自动播放。这包括没有音频轨道的媒体，或音频已被静音的媒体。
disallowed: 不允许自动播放。

请注意，为type参数返回的自动播放策略是指示类型项目的广泛策略。在页面加载时，所有类型的项目都将具有与类型相同的策略。一旦用户与页面/站点交互，在某些浏览器中，各个项目可能具有与相应类型不同的策略。

异常

TypeError: 传递给方法的对象不是允许的类型。允许的类型包括HTMLMediaElement（或派生元素，例如HTMLVideoElement和HTMLAudioElement），或AudioContext。

描述

“自动播放”是指导致内容开始播放而无需用户明确请求开始播放的任何功能。这包括 HTML <video> 和 <audio> 元素中的autoplay属性，以及使用 JavaScript 代码在没有任何用户交互的情况下开始播放。

用户代理通常会阻止自动播放，或仅允许无声内容自动播放，因为页面首次加载时出现意外声音可能会导致令人不快且令人反感的用户体验。用于确定内容是否可以自动播放或仅播放无声内容的机制在不同的用户代理之间有所不同。

getAutoplayPolicy() 方法提供了一种标准机制来确定特定用户代理对特定类型或内容项的自动播放策略。这使得应用程序能够进行自定义，例如在不允许自动播放有声内容的网站上自动静音视频，或修改应用程序以在没有自动播放的情况下运行。

建议使用方法是在页面加载时（或在创建内容播放元素之前）调用它，指定要检查的功能类型，然后根据结果配置媒体元素的自动播放。例如，如果应用程序想要自动播放具有音频轨道的视频元素，则可以使用以下代码在仅允许无声内容播放时静音视频。

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.
}

该方法还可以用来检查特定媒体元素或音频上下文的自动播放策略。如下所示，代码看起来完全相同，只是您传递了特定的项目而不是type字符串。

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.
}

在页面加载时，在用户与页面或站点交互之前，类型和各个项目的自动播放策略将相同。在用户与站点、页面或特定元素交互后，整个type的自动播放策略可能会发生变化。即使type的整体策略没有改变，特定项目的策略也可能发生变化。

无法收到有关自动播放策略已更改的通知。因此，虽然您可以随时检查类型或项目的策略，但通常您只会在页面加载时或尝试播放内容之前这样做。

示例

检查功能是否受支持

以下代码显示了如何检查navigator.getAutoplayPolicy()是否受支持。

<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.";
}

在此页面上运行代码的结果是

测试媒体元素类型的自动播放策略

此示例演示了如何检查媒体元素类型的自动播放策略。

代码创建一个具有autoplay属性并且默认情况下未静音的视频元素。如果自动播放策略为“allowed-muted”，则视频将被静音以允许其播放。

HTML

下面的 HTML 包含一个用作报告日志的div元素，以及一个具有<video>属性的autoplay元素。默认情况下，此元素不应被静音，并且如果未阻止自动播放，则应自动播放。

html

<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

代码报告getAutoplayPolicy()方法是否受支持，如果受支持，则报告媒体元素的策略。

如果策略为allowed-muted，则只能播放静音的视频。在这种情况下，我们会添加一些文本解释正在发生的事情，并静音视频。

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.";
  }
}

请注意，您也可以类似地检查allowed和disallowed。

结果

视频显示在下面，以及有关getAutoplayPolicy()方法是否受支持以及策略的信息。

如果getAutoplayPolicy()受支持且策略为allowed，则视频将自动播放并带有声音。如果策略为allowed-muted，则视频将无声播放。

请注意，如果getAutoplayPolicy()不受支持，则视频将自动播放音频或不播放。代码无法控制此行为：您受制于浏览器实现！

测试特定媒体元素的自动播放策略

此示例显示了如何检查特定媒体元素是否会自动播放。它与前面的示例几乎完全相同（AudioContext检查也类似）。请注意，即使对mediaelement类型进行检查表明自动播放为disallowed，特定元素也可能自动播放；换句话说，对特定元素的检查更可靠（尽管在页面加载时无关紧要）。

代码创建一个具有autoplay属性的视频元素。如果自动播放策略为“allowed-muted”，则视频将被静音以允许其播放。

HTML

html

<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

代码报告getAutoplayPolicy()方法是否受支持，如果受支持，则报告媒体元素的策略。

如果策略为allowed-muted，则只能播放静音的视频，因此代码会静音视频。

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.";
  }
}

结果

结果与前面的示例相同。

如果返回allowed，则视频应自动播放并带有声音；如果返回allowed-muted，则视频应无声播放。
如果getAutoplayPolicy()不受支持，则视频自动播放行为仅取决于浏览器。

规范

规范
自动播放策略检测 # dom-navigator-getautoplaypolicy

浏览器兼容性

BCD 表格仅在启用 JavaScript 的浏览器中加载。

另请参阅

媒体和 Web 音频 API 的自动播放指南