HTMLMediaElement.play()
HTMLMediaElement
の play()
メソッドは、メディアの再生を開始しようとします。 再生が正常に開始されると解決する Promise
を返します。 パーミッションの問題など、何らかの理由で再生を開始しなかった場合、その promise は拒否されます。
構文
var promise = HTMLMediaElement.play();
パラメーター
無し。
戻り値
再生が開始されたときに解決される、または何らかの理由で再生を開始できない場合は拒否される Promise
。
注: 古いブラウザーは play()
から値を返さないかもしれません。
例外
promise の拒否ハンドラ(rejection handler)は、その唯一の入力パラメータとして渡された例外名で呼び出されます(従来の例外がスローされるのとは対照的に)。 考えられるエラーは次のとおりです。
NotAllowedError
- ユーザーエージェント(ブラウザー)またはオペレーティングシステムは、現在のコンテキストまたはシチュエーションではメディアの再生を許可していません。 これは、例えば、「再生」ボタンをクリックすることによってメディアの再生を明示的に開始することをブラウザーがユーザーに要求する場合に起こり得ます。
NotSupportedError
- メディアソース(
MediaStream
、MediaSource
、Blob
、File
など)はサポートしているメディア形式を表していません。
ブラウザーの実装の詳細、メディアプレーヤーの実装などによっては、他の例外が報告されることがあります。
使用上の注意
「自動再生(autoplay)」という用語は通常、読み込まれるとすぐにメディアの再生を開始するページを指すと考えられていますが、ウェブブラウザーの自動再生ポリシーは、play()
の呼び出しを含むスクリプト起動によるメディアの再生にも適用されます。
ユーザーエージェントが自動またはスクリプト起動によるメディアの再生を許可しないように設定されている場合、play()
を呼び出すと返された promise が直ちに NotAllowedError
で拒否されます。 ウェブサイトはこの状況に対処する準備をしておくべきです。 例えば、サイトには再生が自動的に開始されたことを前提としたユーザーインターフェイスを表示するのではなく、返された promise が解決されたか拒否されたかに基づいて UI を更新する必要があります。 詳しくは、以下の例を参照してください。
注: play()
メソッドを使用すると、ユーザーはメディアの再生を許可するように要求され、返された promise が解決されるまでに遅延が生じる可能性があります。 コードが即座の応答を期待していないことを確認してください。
自動再生および自動再生のブロックの詳細については、メディアおよびウェブオーディオ API の自動再生ガイドを参照してください。
例
この例では、再生が開始されたことを確認する方法と、ブロックされた自動再生を適切に処理する方法を示します。
let videoElem = document.getElementById("video");
let playButton = document.getElementById("playbutton");
playButton.addEventListener("click", handlePlayButton, false);
playVideo();
async function playVideo() {
try {
await videoElem.play();
playButton.className = "playing";
} catch(err) {
playButton.className = "";
}
}
function handlePlayButton() {
if (videoElem.paused) {
playVideo();
} else {
videoElem.pause();
playButton.className = "";
}
}
この例では、動画の再生は async
の playVideo()
関数によってオンとオフを切り替えられます。 動画を再生しようとし、成功した場合は playButton
要素のクラス名を "playing"
(再生中)に設定します。 再生が開始されない場合、playButton
要素のクラスはクリアされ、デフォルトの外観に戻ります。 これは、play()
によって返された Promise
の解決または拒否を監視することによって、再生ボタンが実際の再生状態と一致することを保証します。
この例が実行されると、再生のオンとオフを切り替えるために使用する <button>
と同様に <video>
要素への参照を収集することから始めます。 次に、再生トグルボタンの click
イベントのイベントハンドラを設定し、playVideo()
を呼び出して自動的に再生を開始しようとします。
あなたは Glitch でこの例を試したり、リミックスすることができます。
仕様
仕様 | 状態 | コメント |
---|---|---|
HTML Living Standard play() の定義 |
現行の標準 | 初期定義; リビング仕様 |
HTML5 play() の定義 |
勧告 | 初期定義 |
注: WHATWG バージョンと W3C バージョンの仕様は、このメソッドが Promise
を返すか、まったく返さないかについて、それぞれ異なります(2018年8月現在)。
ブラウザーの互換性
BCD tables only load in the browser