useMediaControls
为 audio 和 video 元素提供响应式的媒体控制。
示例
00:00
00:00 / 00:00
关闭
循环
2x
1x
currentTime: 0
duration: 0
waiting: false
seeking: false
ended: false
stalled: false
buffered: []
playing: false
rate: 1
volume: 1
muted: false
tracks: []
selectedTrack: -1
isPictureInPicture: false
使用方法
基本用法
vue
<script setup lang="ts">
import { useMediaControls } from '@vueuse/core'
import { onMounted, useTemplateRef } from 'vue'
const video = useTemplateRef('video')
const { playing, currentTime, duration, volume } = useMediaControls(video, {
src: 'video.mp4',
})
// 更改初始媒体属性
onMounted(() => {
volume.value = 0.5
currentTime.value = 60
})
</script>
<template>
<video ref="video" />
<button @click="playing = !playing">
播放 / 暂停
</button>
<span>{{ currentTime }} / {{ duration }}</span>
</template>提供字幕、副标题等...
你可以在 useMediaControls 函数的 tracks 选项中提供字幕、副标题等。该函数将返回一个包含轨道的数组，以及两个控制它们的函数，enableTrack、disableTrack 和 selectedTrack。使用这些函数，你可以管理当前选择的轨道。如果没有选择的轨道，selectedTrack 将为 -1。
vue
<script setup lang="ts">
import { useMediaControls } from '@vueuse/core'
import { useTemplateRef } from 'vue'
const video = useTemplateRef('video')
const {
tracks,
enableTrack
} = useMediaControls(video, {
src: 'video.mp4',
tracks: [
{
default: true,
src: './subtitles.vtt',
kind: 'subtitles',
label: 'English',
srcLang: 'en',
},
]
})
</script>
<template>
<video ref="video" />
<button v-for="track in tracks" :key="track.id" @click="enableTrack(track)">
{{ track.label }}
</button>
</template>类型声明
显示类型声明
ts
/**
* 这里的许多 jsdoc 定义都是修改自 MDN 的文档（https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement）的版本
*/
export interface UseMediaSource {
/**
* 媒体的源 URL
*/
src: string
/**
* 媒体的编解码器类型
*/
type?: string
/**
* Specifies the media query for the resource's intended media.
*/
media?: string
}
export interface UseMediaTextTrackSource {
/**
* 指示除非用户的偏好指示其他轨道更合适，否则轨道应启用
*/
default?: boolean
/**
* 文本轨道的使用方式。如果省略，则默认类型是字幕。
*/
kind: TextTrackKind
/**
* 文本轨道的用户可读标题，在列出可用文本轨道时浏览器使用
*/
label: string
/**
* 轨道的地址（.vtt 文件）。必须是有效的 URL。必须指定此属性，其 URL 值必须与文档具有相同的来源。
*/
src: string
/**
* 轨道文本数据的语言。它必须是有效的 BCP 47 语言标签。
* 如果 kind 属性设置为 subtitles，则必须定义 srclang。
*/
srcLang: string
}
interface UseMediaControlsOptions extends ConfigurableDocument {
/**
* 媒体的源，可以是字符串、`UseMediaSource` 对象或 `UseMediaSource` 对象的列表
*/
src?: MaybeRefOrGetter<string | UseMediaSource | UseMediaSource[]>
/**
* 媒体的文本轨道列表
*/
tracks?: MaybeRefOrGetter<UseMediaTextTrackSource[]>
}
export interface UseMediaTextTrack {
/**
* 文本轨道的索引
*/
id: number
/**
* 文本轨道的标签
*/
label: string
/**
* 轨道文本数据的语言。它必须是有效的 BCP 47 语言标签。
* 如果 kind 属性设置为 subtitles，则必须定义 srclang。
*/
language: string
/**
* 指定文本轨道的显示模式，可以是 `disabled`、`hidden` 或 `showing`
*/
mode: TextTrackMode
/**
* 文本轨道的带内元数据轨道调度类型
*/
inBandMetadataTrackDispatchType: string
/**
* 文本轨道的提示列表
*/
cues: TextTrackCueList | null
/**
* 活动文本轨道提示的列表
*/
activeCues: TextTrackCueList | null
}
export declare function useMediaControls(
target: MaybeRef<HTMLMediaElement | null | undefined>,
options?: UseMediaControlsOptions,
): {
currentTime: ShallowRef<number, number>
duration: ShallowRef<number, number>
waiting: ShallowRef<boolean, boolean>
seeking: ShallowRef<boolean, boolean>
ended: ShallowRef<boolean, boolean>
stalled: ShallowRef<boolean, boolean>
buffered: Ref<[number, number][], [number, number][]>
playing: ShallowRef<boolean, boolean>
rate: ShallowRef<number, number>
volume: ShallowRef<number, number>
muted: ShallowRef<boolean, boolean>
tracks: Ref<
{
id: number
label: string
language: string
mode: TextTrackMode
inBandMetadataTrackDispatchType: string
cues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
activeCues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
}[],
| UseMediaTextTrack[]
| {
id: number
label: string
language: string
mode: TextTrackMode
inBandMetadataTrackDispatchType: string
cues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
activeCues: {
[x: number]: {
endTime: number
id: string
onenter: ((this: TextTrackCue, ev: Event) => any) | null
onexit: ((this: TextTrackCue, ev: Event) => any) | null
pauseOnExit: boolean
startTime: number
readonly track: {
readonly activeCues: /*elided*/ any | null
readonly cues: /*elided*/ any | null
readonly id: string
readonly inBandMetadataTrackDispatchType: string
readonly kind: TextTrackKind
readonly label: string
readonly language: string
mode: TextTrackMode
oncuechange: ((this: TextTrack, ev: Event) => any) | null
addCue: (cue: TextTrackCue) => void
removeCue: (cue: TextTrackCue) => void
addEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackEventMap>(
type: K,
listener: (this: TextTrack, ev: TextTrackEventMap[K]) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
} | null
addEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | AddEventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | AddEventListenerOptions,
): void
}
removeEventListener: {
<K extends keyof TextTrackCueEventMap>(
type: K,
listener: (
this: TextTrackCue,
ev: TextTrackCueEventMap[K],
) => any,
options?: boolean | EventListenerOptions,
): void
(
type: string,
listener: EventListenerOrEventListenerObject,
options?: boolean | EventListenerOptions,
): void
}
dispatchEvent: {
(event: Event): boolean
(event: Event): boolean
}
}
readonly length: number
getCueById: (id: string) => TextTrackCue | null
[Symbol.iterator]: () => ArrayIterator<TextTrackCue>
} | null
}[]
>
selectedTrack: ShallowRef<number, number>
enableTrack: (
track: number | UseMediaTextTrack,
disableTracks?: boolean,
) => void
disableTrack: (track?: number | UseMediaTextTrack) => void
supportsPictureInPicture: boolean | undefined
togglePictureInPicture: () => Promise<unknown>
isPictureInPicture: ShallowRef<boolean, boolean>
onSourceError: EventHookOn<Event>
onPlaybackError: EventHookOn<Event>
}
export type UseMediaControlsReturn = ReturnType<typeof useMediaControls>源码
贡献者
Anthony Fu
一纸忘忧
Alex Kozack
Anthony Fu
Fernando Fernández
wheat
IlyaL
Justin Halsall
webfansplz
IlyaL
Robin
Andrew
aaron lejeune
Darren
huiliangShen
丶远方
Bryce
CommanderRoot
jelf
rimday
Shinigami