1. Web
  2. Web API
  3. Navigator
  4. getAutoplayPolicy()

Navigator: getAutoplayPolicy() 方法

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

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

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

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

语法

js
// 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 Audio API 播放器的宽泛自动播放策略。

element 可选

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

context 可选

一个特定的 AudioContext。

返回值

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

allowed

允许自动播放。

allowed-muted

仅允许自动播放无声媒体。这包括没有音轨的媒体，或音频已静音的媒体。

disallowed

不允许自动播放。

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

异常

TypeError

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

描述

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

用户代理通常会阻止自动播放，或只允许无声内容自动播放，因为页面首次加载时意想不到的声音可能会导致刺耳和不愉快的用户体验。用于确定内容是否可以自动播放，或只播放无声内容的机制，在不同的用户代理之间有所不同。

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

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

js
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 字符串。

js
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() 是否受支持

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

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

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

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

此代码创建了一个带有 autoplay 属性且默认未静音的视频元素。如果自动播放策略为 "allowed-muted"，则视频将被静音以允许其播放。

HTML

下面的 HTML 有一个用作报告日志的 div 元素，并显示一个带有 autoplay 属性的 <video>。它默认不应该静音，如果自动播放未被阻止，则应该自动播放。

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，则只能播放静音视频。在这种情况下，我们添加一些文本解释正在发生的事情并使视频静音。

js
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 元素，并显示一个带有 autoplay 属性的 <video>。它默认不应该静音，如果自动播放未被阻止，则应该自动播放。

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，则只能播放静音视频，因此代码会将视频静音。

js
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

浏览器兼容性

另见

帮助改进 MDN

了解如何贡献

此页面由MDN 贡献者上次修改于 。

在 GitHub 上查看此页面 • 报告此内容的问题