blob: e492d4581e951dce17492e6cbd291d0e56cbccae (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
---
title: play()
slug: Web/API/HTMLMediaElement/play
tags:
- API
- HTMLMediaElement
- 参考
- 媒体
- 接口
- 播放
- 方法
- 视频
- 音频
translation_of: Web/API/HTMLMediaElement/play
---
<p>{{APIRef("HTML DOM")}}</p>
<p><strong><code>HTMLMediaElement.play()</code></strong> 方法会尝试播放媒体。这个方法返回一个 {{jsxref("Promise")}}，当媒体成功开始播放时被解决（resolved）。当播放因为任何原因失败时，这个 promise 被拒绝（rejected）。</p>
<h2 id="语法">语法</h2>
<pre class="notranslate">let <em>promise</em> = <em>HTMLMediaElement</em>.play();</pre>
<h3 id="参数">参数</h3>
<p>无</p>
<h3 id="返回值">返回值</h3>
<p> 一个 {{jsxref("Promise")}}，当媒体成功开始播放时被解决，当播放因为任何原因失败时则被被拒绝。</p>
<div class="blockIndicator note">
<p><strong>注意：</strong>旧版本的浏览器可能不会从 <code>play()</code> 返回值。</p>
</div>
<h3 id="异常">异常</h3>
<p>当 promise 接收到一个异常名称作为其唯一输入参数时（相对于传统的异常抛出），promise 的拒绝处理程序会被调用。可能的异常如下：</p>
<dl>
<dt><code>NotAllowedError</code></dt>
<dd>用户代理（浏览器）或操作系统在当前上下文或当前情境下不允许媒体播放。例如，这会发生在浏览器要求用户显式按下播放按钮才播放媒体时。</dd>
<dt><code>NotSupportedError</code></dt>
<dd>媒体源（可能是{{domxref("MediaStream")}}、{{domxref("MediaSource")}}、{{domxref("Blob")}} 或 {{domxref("File")}} 等）不是一个支持的媒体格式。</dd>
</dl>
<p>也可能报告其他异常，取决于浏览器的实现细节，媒体播放器的实现等等。</p>
<h2 id="使用说明">使用说明</h2>
<p>虽然“autoplay”这个词常常被用于描述当媒体加载完成时立即开始播放，浏览器的自动播放策略其实也应用于脚本驱动的媒体播放，包括调用 <code>play()</code>。</p>
<p>如果 {{Glossary("user agent")}} 被设置为不允许自动或脚本驱动的媒体播放，调用 <code>play()</code> 会导致返回的 promise 被立即以 <code>NotAllowedError</code> 拒绝。网页应该对这种情况做好准备。举个例子，一个网页不应该假定播放已经自动开始而直接展示相应的用户界面，而应该在返回的 promise 被解决或拒绝后再更新用户界面。更多信息参见 {{anch("示例", "示例")}}。</p>
<div class="blockIndicator note">
<p><strong>注意：</strong><code>play()</code> 方法可能会让用户被询问是否给予播放媒体的权限，这可能会使返回的 promise 延迟解决。你应该确保你的代码不需要即时响应。</p>
</div>
<p>关于自动播放和禁止自动播放的更多深度内容，参见我们的文章 <a href="/zh-CN/docs/Web/Media/Autoplay_guide">Autoplay guide for media and Web Audio APIs</a>。</p>
<h2 id="示例">示例</h2>
<p>这个例子展示了如何确认播放已经开始以及如何优雅地处理自动播放被禁止：</p>
<pre class="notranslate">let videoElem = document.getElementById("video");
let playButton = document.getElementById("playbutton");
playButton.addEventListener("click", handlePlayButton, false);
playVideo();
async function playVideo() {
try {
await videoElem.play();
playButton.classList.add("playing");
} catch(err) {
playButton.classList.remove("playing");
}
}
function handlePlayButton() {
if (videoElem.paused) {
playVideo();
} else {
videoElem.pause();
playButton.classList.remove("playing");
}
}</pre>
<p>在这个例子中，视频的播放由 <code><a href="/zh-CN/docs/Web/JavaScript/Reference/Statements/async_function">async</a></code> <code>playVideo()</code> 函数控制。函数尝试播放视频，如果播放成功，将 <code>playButton</code> 元素的类名称设为 <code>"playing"</code>。如果播放失败，去除 <code>playButton</code> 元素的类名称，恢复其原来的样式。通过监视 <code>play()</code> 返回的 {{jsxref("Promise")}} 是被解决还是被拒绝以保证播放按钮的外观与实际的播放状态相匹配。</p>
<p>上述代码开始执行时，先获取 {{HTMLElement("video")}} 元素和用于切换播放、暂停的 {{HTMLElement("button")}} 元素的引用。在切换按钮上添加 {{event("click")}} 事件的处理程序。最后调用 <code>playVideo()</code> 尝试自动开始播放。</p>
<p>你可以在 <a href="https://media-play-promise.glitch.me/">这里</a> 查看或修改这个例子。</p>
<h2 id="规范">规范</h2>
<table class="standard-table">
<tbody>
<tr>
<th>Specification</th>
<th>Status</th>
<th>Comment</th>
</tr>
<tr>
<td>{{SpecName('HTML WHATWG', 'embedded-content.html#dom-media-play', 'play()')}}</td>
<td>{{Spec2('HTML WHATWG')}}</td>
<td>Initial definition; living specification.</td>
</tr>
<tr>
<td>{{SpecName('HTML5 W3C','embedded-content-0.html#playing-the-media-resource','play()')}}</td>
<td>{{Spec2('HTML5 W3C')}}</td>
<td>Initial definition.</td>
</tr>
</tbody>
</table>
<div class="note">
<p>注意，WHATWG 版本和 W3C 版本的规范不一样（2016年4月20日），一个返回 {{jsxref("Promise")}}，一个不返回。</p>
</div>
<h2 id="浏览器兼容性">浏览器兼容性</h2>
<p>{{Compat("api.HTMLMediaElement.play")}}</p>
<h2 id="参见">参见</h2>
<ul>
<li><a href="/zh-CN/docs/Web/Media">Web media technologies</a></li>
<li>Learning: <a href="/zh-CN/docs/Learn/HTML/Multimedia_and_embedding/Video_and_audio_content">Video and audio content</a></li>
<li><a href="/zh-CN/docs/Web/Media/Autoplay_guide">Autoplay guide for media and Web Audio APIs</a></li>
<li><a href="/zh-CN/docs/Web/API/Web_Audio_API/Using_Web_Audio_API">Using the Web Audio API</a></li>
</ul>
<div id="compat-mobile"></div>
|
