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',
})
// Change initial media properties
onMounted(() => {
volume.value = 0.5
currentTime.value = 60
})
</script>
<template>
<video ref="video" />
<button @click="playing = !playing">
Play / Pause
</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
/**
* Many of the jsdoc definitions here are modified version of the
* documentation from MDN(https://mdn.org.cn/en-US/docs/Web/API/HTMLMediaElement)
*/
export interface UseMediaSource {
/**
* The source url for the media
*/
src: string
/**
* The media codec type
*/
type?: string
/**
* Specifies the media query for the resource's intended media.
*/
media?: string
}
export interface UseMediaTextTrackSource {
/**
* Indicates that the track should be enabled unless the user's preferences indicate
* that another track is more appropriate
*/
default?: boolean
/**
* How the text track is meant to be used. If omitted the default kind is subtitles.
*/
kind: TextTrackKind
/**
* A user-readable title of the text track which is used by the browser
* when listing available text tracks.
*/
label: string
/**
* Address of the track (.vtt file). Must be a valid URL. This attribute
* must be specified and its URL value must have the same origin as the document
*/
src: string
/**
* Language of the track text data. It must be a valid BCP 47 language tag.
* If the kind attribute is set to subtitles, then srclang must be defined.
*/
srcLang: string
}
interface UseMediaControlsOptions extends ConfigurableDocument {
/**
* The source for the media, may either be a string, a `UseMediaSource` object, or a list
* of `UseMediaSource` objects.
*/
src?: MaybeRefOrGetter<string | UseMediaSource | UseMediaSource[]>
/**
* A list of text tracks for the media
*/
tracks?: MaybeRefOrGetter<UseMediaTextTrackSource[]>
}
export interface UseMediaTextTrack {
/**
* The index of the text track
*/
id: number
/**
* The text track label
*/
label: string
/**
* Language of the track text data. It must be a valid BCP 47 language tag.
* If the kind attribute is set to subtitles, then srclang must be defined.
*/
language: string
/**
* Specifies the display mode of the text track, either `disabled`,
* `hidden`, or `showing`
*/
mode: TextTrackMode
/**
* How the text track is meant to be used. If omitted the default kind is subtitles.
*/
kind: TextTrackKind
/**
* Indicates the track's in-band metadata track dispatch type.
*/
inBandMetadataTrackDispatchType: string
/**
* A list of text track cues
*/
cues: TextTrackCueList | null
/**
* A list of active text track cues
*/
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
kind: TextTrackKind
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
kind: TextTrackKind
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