HTMLMediaElement

Baseline 广泛可用 *

此特性已相当成熟，可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来，各浏览器均已提供此特性。

* 此特性的某些部分可能存在不同级别的支持。

HTMLMediaElement 接口在 HTMLElement 的基础上增加了支持音频和视频共同的基本媒体相关功能所需的属性和方法。

HTMLVideoElement 和 HTMLAudioElement 元素都继承了此接口。

实例属性

此接口还继承了其祖先 HTMLElement、Element、Node 和 EventTarget 的属性。

HTMLMediaElement.audioTracks 只读: 一个 AudioTrackList，列出了元素中包含的 AudioTrack 对象。
HTMLMediaElement.autoplay: 一个布尔值，反映了 autoplay HTML 属性，指示一旦有足够的媒体可用，播放是否应自动开始而不中断。

注意：在用户不期望或不希望的情况下自动播放音频会带来糟糕的用户体验，在大多数情况下应避免，尽管也有例外。有关更多信息，请参阅媒体和 Web 音频 API 的自动播放指南。请记住，浏览器可能会忽略自动播放请求，因此您应确保您的代码不依赖于自动播放的正常工作。
HTMLMediaElement.buffered 只读: 返回一个 TimeRanges 对象，该对象指示在访问 buffered 属性时浏览器已缓冲的媒体源范围（如果有）。
HTMLMediaElement.controls: 一个布尔值，反映了 controls HTML 属性，指示是否应显示用于控制资源的 UI 元素。
HTMLMediaElement.controlsList: 返回一个 DOMTokenList，它有助于用户代理选择当用户代理显示其自己的控件集时在媒体元素上显示哪些控件。DOMTokenList 接受三个可能值中的一个或多个：nodownload、nofullfullscreen 和 noremoteplayback。
HTMLMediaElement.crossOrigin: 一个字符串，指示此媒体元素的 CORS 设置。
HTMLMediaElement.currentSrc 只读: 返回一个字符串，其中包含所选媒体资源的绝对 URL。
HTMLMediaElement.currentTime: 一个双精度浮点值，指示当前播放时间（秒）；如果媒体尚未开始播放且未进行查找，则此值为媒体的初始播放时间。设置此值会将媒体查找至新时间。时间是相对于媒体时间线指定的。
HTMLMediaElement.defaultMuted: 一个布尔值，反映了 muted HTML 属性，指示媒体元素的音频输出是否应默认静音。
HTMLMediaElement.defaultPlaybackRate: 一个 double，指示媒体的默认播放速率。
HTMLMediaElement.disableRemotePlayback: 一个布尔值，用于设置或返回远程播放状态，指示媒体元素是否允许具有远程播放 UI。
HTMLMediaElement.duration 只读: 一个只读双精度浮点值，指示媒体的总时长（秒）。如果没有媒体数据可用，则返回值为 NaN。如果媒体长度不确定（例如直播流媒体、WebRTC 通话媒体或类似情况），则该值为 Infinity。
HTMLMediaElement.ended 只读: 返回一个布尔值，指示媒体元素是否已播放完毕。
HTMLMediaElement.error 只读: 返回一个 MediaError 对象，表示最近的错误，如果未发生错误，则为 null。
HTMLMediaElement.loop: 一个布尔值，反映了 loop HTML 属性，指示媒体元素在到达末尾时是否应重新开始。
HTMLMediaElement.mediaKeys 只读安全上下文: 返回一个 MediaKeys 对象，这是一组元素在播放期间用于解密媒体数据的密钥。如果没有密钥可用，则可以为 null。
HTMLMediaElement.muted: 一个布尔值，指示音频是否静音。如果音频静音，则为 true，否则为 false。
HTMLMediaElement.networkState 只读: 返回一个 unsigned short（枚举），指示通过网络获取媒体的当前状态。
HTMLMediaElement.paused 只读: 返回一个布尔值，指示媒体元素是否已暂停。
HTMLMediaElement.playbackRate: 一个 double，指示媒体的播放速率。
HTMLMediaElement.played 只读: 返回一个 TimeRanges 对象，其中包含浏览器已播放的媒体源范围（如果有）。
HTMLMediaElement.preload: 一个字符串，反映了 preload HTML 属性，指示应预加载哪些数据（如果有）。可能的值有：none、metadata、auto。
HTMLMediaElement.preservesPitch: 一个布尔值，指示是否保留音高。如果设置为 false，则音高将根据音频速度进行调整。
HTMLMediaElement.readyState 只读: 返回一个 unsigned short（枚举），指示媒体的就绪状态。
HTMLMediaElement.remote 只读: 返回与媒体元素关联的 RemotePlayback 对象实例。
HTMLMediaElement.seekable 只读: 返回一个 TimeRanges 对象，其中包含用户可以查找的时间范围（如果有）。
HTMLMediaElement.seeking 只读: 返回一个布尔值，指示媒体是否正在查找新位置。
HTMLMediaElement.sinkId 只读安全上下文: 返回一个字符串，表示提供输出的音频设备的唯一 ID，如果正在使用用户代理默认音频设备，则返回一个空字符串。
HTMLMediaElement.src: 一个字符串，反映了 src HTML 属性，其中包含要使用的媒体资源的 URL。
HTMLMediaElement.srcObject: 一个对象，作为与 HTMLMediaElement 关联的媒体的源，如果未分配，则为 null。
HTMLMediaElement.textTracks 只读: 返回一个 TextTrackList 对象，其中包含元素中包含的 TextTrack 对象的列表。
HTMLMediaElement.videoTracks 只读: 返回一个 VideoTrackList 对象，其中包含元素中包含的 VideoTrack 对象的列表。
HTMLMediaElement.volume: 一个 double，指示音量，从 0.0（静音）到 1.0（最大声）。

已废弃的属性

这些属性已废弃，即使浏览器仍然支持它们，也不应使用。

HTMLMediaElement.controller 已废弃非标准: 一个 MediaController 对象，表示分配给元素的媒体控制器，如果未分配，则为 null。
HTMLMediaElement.mediaGroup 已废弃非标准: 一个字符串，反映了 mediagroup HTML 属性，指示其所属组的名称。一组媒体元素共享一个共同的 MediaController。
HTMLMediaElement.mozAudioCaptured 只读非标准已废弃: 返回一个布尔值。与音频流捕获相关。
HTMLMediaElement.mozFragmentEnd 非标准已废弃: 一个 double，如果媒体元素的 currentSrc 具有片段 URI，则提供对片段结束时间的访问，否则它等于媒体时长。

实例方法

此接口还继承了其祖先 HTMLElement、Element、Node 和 EventTarget 的方法。

HTMLMediaElement.addTextTrack(): 向媒体元素添加新的 TextTrack 对象（例如字幕轨道）。这仅是编程接口，不影响 DOM。
HTMLMediaElement.captureStream(): 返回 MediaStream，捕获媒体内容的流。
HTMLMediaElement.canPlayType(): 给定一个指定 MIME 媒体类型（可能包含 codecs 参数）的字符串，canPlayType() 返回字符串 probably（如果媒体应该可播放），maybe（如果没有足够的信息来确定媒体是否会播放），或者一个空字符串（如果媒体无法播放）。
HTMLMediaElement.fastSeek(): 以低精度快速查找给定时间。
HTMLMediaElement.load(): 将媒体重置到开头，并从使用 src 属性或 <source> 元素提供的源中选择最佳可用源。
HTMLMediaElement.pause(): 暂停媒体播放。
HTMLMediaElement.play(): 开始播放媒体。
HTMLMediaElement.seekToNextFrame() 已废弃非标准: 查找媒体中的下一帧。此非标准、实验性方法使得可以以自定义速度手动驱动媒体的读取和渲染，或者逐帧移动媒体以执行过滤或其他操作。
HTMLMediaElement.setMediaKeys() 安全上下文: 返回 Promise。设置在播放期间解密媒体时要使用的 MediaKeys 密钥。
HTMLMediaElement.setSinkId() 安全上下文: 设置用于输出的音频设备的 ID 并返回一个 Promise。这仅在应用程序被授权使用指定设备时有效。

已废弃的方法

这些方法已废弃，即使浏览器仍然支持它们，也不应使用。

HTMLMediaElement.mozCaptureStream() 非标准: 带有 Firefox 前缀的 HTMLMediaElement.captureStream() 等效方法。有关详细信息，请参阅其浏览器兼容性。
HTMLMediaElement.mozCaptureStreamUntilEnded() 非标准已废弃: [输入描述]
HTMLMediaElement.mozGetMetadata() 非标准已废弃: 返回 Object，其中包含表示来自正在播放的媒体资源的元数据作为 {key: value} 对的属性。每次调用此方法时都会返回数据的单独副本。此方法必须在 loadedmetadata 事件触发后调用。

事件

继承自其父级 HTMLElement 的事件.

使用 addEventListener() 监听这些事件，或通过将事件监听器分配给此接口的 oneventname 属性。

abort: 当资源未完全加载但并非由于错误而触发。
canplay: 当用户代理可以播放媒体，但估计没有加载足够的数据以播放媒体直到结束而无需停止进一步缓冲内容时触发。
canplaythrough: 当用户代理可以播放媒体，并且估计已加载足够的数据以播放媒体直到结束而无需停止进一步缓冲内容时触发。
durationchange: 当 duration 属性已更新时触发。
emptied: 当媒体变空时触发；例如，当媒体已加载（或部分加载），并且调用 HTMLMediaElement.load() 方法重新加载它时。
encrypted: 当在媒体中发现指示媒体已加密的初始化数据时触发。
ended: 当播放停止时触发，因为媒体（<audio> 或 <video>）已结束或因为没有更多数据可用。
error: 当资源由于错误而无法加载时触发。
loadeddata: 当媒体的第一帧加载完成时触发。
loadedmetadata: 当元数据已加载时触发。
loadstart: 当浏览器开始加载资源时触发。
pause: 当处理暂停播放请求并且活动已进入其暂停状态时触发，最常见的情况是调用媒体的 HTMLMediaElement.pause() 方法时。
play: 当 paused 属性从 true 更改为 false 时触发，这是由 HTMLMediaElement.play() 方法或 autoplay 属性引起的。
playing: 当播放因数据不足而暂停或延迟后准备开始时触发。
progress: 当浏览器加载资源时定期触发。
ratechange: 当播放速率发生变化时触发。
seeked: 当查找操作完成时触发。
seeking: 当查找操作开始时触发。
stalled: 当用户代理尝试获取媒体数据，但数据意外地没有到来时触发。
suspend: 当媒体数据加载已暂停时触发。
timeupdate: 当由 currentTime 属性指示的时间已更新时触发。
volumechange: 当音量发生变化时触发。
waiting: 当播放因数据暂时不足而停止时触发。
waitingforkey: 当播放首次因等待密钥而被阻止时触发。

规范

规范
HTML # htmlmediaelement

浏览器兼容性

另见

参考

<video> 和 <audio> HTML 元素
HTMLVideoElement 和 HTMLAudioElement 接口，派生自 HTMLMediaElement

指南

帮助改进 MDN

了解如何贡献

此页面上次修改于 2025 年 9 月 4 日由 MDN 贡献者。

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