HTMLMediaElement

https://html.spec.whatwg.org/multipage/media.html#htmlmediaelement（仅提供英文版）除了w3c规范中描述的标准事件外，此对象还会发出数量很少的自定义事件。“playbackstarted”：当MediaPlayer开始播放时发送给客户端的事件“audiofocusgranted”：当MediaPlayer在获得音频焦点后于内部恢复播放时发送给客户端的事件。“audiofocuspaused”：当MediaPlayer因暂时失去音频焦点而在内部暂停播放时发送给客户端的事件。“audiofocuslost”：当MediaPlayer因永久失去音频焦点而在内部暂停播放时发送给客户端的事件。

扩展自

• MediaPlayer
• HTMLVideoElement
• HTMLAudioElement

实现

• EventTarget

构造函数

new HTMLMediaElement()

new HTMLMediaElement(): HTMLMediaElement

返回值

HTMLMediaElement

属性

src

src: string

设置媒体源的URL。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#location-of-the-media-resource。

---

srcObject

srcObject: MediaProvider

设置源MediaProvider对象。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-srcobject（仅提供英文版）。

---

error

readonly error: MediaError

获取上次遇到的媒体错误。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-error（仅提供英文版）。

---

currentSrc

readonly currentSrc: string

获取当前正在播放的媒体的源URL。https://html.spec.whatwg.org/multipage/media.html#dom-media-currentsrc（仅提供英文版）。

---

networkState

readonly networkState: number

https://html.spec.whatwg.org/multipage/media.html#dom-media-networkstate（仅提供英文版）。

---

buffered

readonly buffered: TimeRanges

获取内容的缓冲时间范围。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-buffered（仅提供英文版）。

---

readyState

readonly readyState: number

获取媒体元素的就绪状态。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-readystate（仅提供英文版）。

---

seeking

readonly seeking: boolean

检查媒体元素当前是否在搜索。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-seeking（仅提供英文版）。

---

duration

readonly duration: number

获取正在播放的内容的持续时间。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-duration（仅提供英文版）。

---

paused

readonly paused: boolean

检查媒体播放是否已暂停。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-paused（仅提供英文版）。

---

played

readonly played: TimeRanges

https://html.spec.whatwg.org/multipage/media.html#dom-media-played（仅提供英文版）

---

seekable

readonly seekable: TimeRanges

获取内容的可搜索时间范围。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-seekable（仅提供英文版）。

---

ended

readonly ended: boolean

检查媒体播放是否已结束。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-ended（仅提供英文版）。

---

preload

preload: string

https://html.spec.whatwg.org/multipage/media.html#attr-media-preload（仅提供英文版）

---

currentTime

currentTime: number

获取或设置播放的当前时间。设置当前时间会导致搜索操作。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-currenttime（仅提供英文版）。

---

defaultPlaybackRate

defaultPlaybackRate: number

https://html.spec.whatwg.org/multipage/media.html#dom-media-defaultplaybackrate（仅提供英文版）

---

playbackRate

playbackRate: number

https://html.spec.whatwg.org/multipage/media.html#dom-media-playbackrate（仅提供英文版）

---

autoplay

autoplay: boolean

如果设置为true，则在加载URL时自动开始播放。如果设置为false，则应用必须明确调用播放才能开始播放。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-autoplay（仅提供英文版）。

---

loop

loop: boolean

https://html.spec.whatwg.org/multipage/media.html#dom-media-loop（仅提供英文版）

---

controls?

optional controls: boolean | undefined

启用或禁用媒体控件的用户界面。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-controls（仅提供英文版）。

---

volume

volume: number

https://html.spec.whatwg.org/multipage/media.html#dom-media-volume（仅提供英文版）

---

muted

muted: boolean

https://html.spec.whatwg.org/multipage/media.html#dom-media-muted（仅提供英文版）

---

defaultMuted

defaultMuted: boolean

https://html.spec.whatwg.org/multipage/media.html#dom-media-defaultmuted（仅提供英文版）

---

audioTracks

readonly audioTracks: AudioTrackList

获取音频轨道的列表。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-audiotracks（仅提供英文版）。

---

videoTracks

readonly videoTracks: VideoTrackList

获取视频轨道的列表。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-videotracks（仅提供英文版）。

---

textTracks

readonly textTracks: TextTrackList

获取文本轨道的列表。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-texttracks（仅提供英文版）。

---

mediaKeys?

readonly optional mediaKeys: MediaKeys | undefined

用于解密受DRM保护的内容的媒体密钥。有关更多信息，请参阅https://www.w3.org/TR/encrypted-media/#dom-htmlmediaelement-mediakeys。

---

nodeName

readonly nodeName: string

有关更多信息，请参阅https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeName（仅提供英文版）。

---

HAVE_NOTHING

static readonly HAVE_NOTHING: number = 0

有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-have_nothing（仅提供英文版）。

---

HAVE_METADATA

static readonly HAVE_METADATA: number = 1

有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-have_metadata（仅提供英文版）。

---

HAVE_CURRENT_DATA

static readonly HAVE_CURRENT_DATA: number = 2

有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-have_current_data（仅提供英文版）。

---

HAVE_FUTURE_DATA

static readonly HAVE_FUTURE_DATA: number = 3

有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-have_future_data（仅提供英文版）。

---

HAVE_ENOUGH_DATA

static readonly HAVE_ENOUGH_DATA: number = 4

有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-have_enough_data（仅提供英文版）。

---

NETWORK_EMPTY

static readonly NETWORK_EMPTY: number = 0

https://html.spec.whatwg.org/multipage/media.html#dom-media-network_empty（仅提供英文版）。

---

NETWORK_IDLE

static readonly NETWORK_IDLE: number = 1

https://html.spec.whatwg.org/multipage/media.html#dom-media-network_idle（仅提供英文版）。

---

NETWORK_LOADING

static readonly NETWORK_LOADING: number = 2

https://html.spec.whatwg.org/multipage/media.html#dom-media-network_loading（仅提供英文版）。

---

NETWORK_NO_SOURCE

static readonly NETWORK_NO_SOURCE: number = 3

https://html.spec.whatwg.org/multipage/media.html#dom-media-network_no_source（仅提供英文版）。

---

defaultSeekIntervalInSec

defaultSeekIntervalInSec: number

为远程控制媒体键按下功能“快进”或“快退”配置默认搜索间隔（以秒为单位）

方法

addEventListener()

abstract addEventListener(type: string, listener: EventListener, options?: boolean | AddEventListenerOptions | undefined): void

参数

type

string

listener

EventListener

options?

boolean | AddEventListenerOptions | undefined

---

addTextTrack()

abstract addTextTrack(kind: TextTrackKind, label?: string | undefined, language?: string | undefined, uri?: string | undefined, mimeType?: string | undefined): TextTrack

有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-addtexttrack（仅提供英文版）。

参数

kind

TextTrackKind

kind参数必须返回TextTrack对象所代表的文本轨道的文本轨道类型。

label?

string | undefined

label参数必须返回TextTrack对象所代表的文本轨道的文本轨道标签。

language?

string | undefined

language参数必须返回TextTrack对象所代表的文本轨道的文本轨道语言。

uri?

string | undefined

uri参数必须返回TextTrack对象所代表的文本轨道的带外字幕的uri。这是自定义添加（不是w3c规范的一部分）。如果您指定uri参数，则该组件将解析并呈现字幕。

mimeType?

string | undefined

mimeType参数必须返回TextTrack对象所代表的文本轨道的带外字幕的mime类型。这是自定义添加（不是w3c规范的一部分）。

返回值

TextTrack

---

canPlayType()

abstract canPlayType(type: string): CanPlayTypeResult

https://html.spec.whatwg.org/multipage/media.html#dom-navigator-canplaytype（仅提供英文版）

参数

type

string

mime类型

返回值

CanPlayTypeResult

---

fastSeek()

abstract fastSeek(time: number): void

https://html.spec.whatwg.org/multipage/media.html#dom-media-fastseek（仅提供英文版）

参数

time

number

---

getStartDate()

abstract getStartDate(): Date

https://html.spec.whatwg.org/multipage/media.html#dom-media-getstartdate（仅提供英文版）

返回值

Date

---

load()

abstract load(): void

https://html.spec.whatwg.org/multipage/media.html#dom-media-load（仅提供英文版）

---

pause()

abstract pause(): void

暂停播放。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-pause（仅提供英文版）。

---

play()

abstract play(): void

开始播放。有关更多信息，请参阅https://html.spec.whatwg.org/multipage/media.html#dom-media-play（仅提供英文版）。

---

removeEventListener()

abstract removeEventListener(type: string, listener: EventListener, options?: boolean | EventListenerOptions | undefined): void

参数

type

string

listener

EventListener

options?

boolean | EventListenerOptions | undefined

---

setMediaKeys()

abstract setMediaKeys(mediaKeys?: MediaKeys | undefined): Promise<void>

设置用于解密受DRM保护的内容的媒体密钥。有关更多信息，请参阅https://www.w3.org/TR/encrypted-media/#dom-htmlmediaelement-setmediakeys（仅提供英文版）。

参数

mediaKeys?

MediaKeys | undefined

有关更多信息，请参阅https://www.w3.org/TR/encrypted-media/#dom-mediakeys（仅提供英文版）。

返回值

Promise<void>

---

Last updated: 2026年7月22日