VueUse 中文文档

简体中文

English

简体中文

English

主题

useMediaControls ​

类别
导出体积
2.17 kB
上次更改
5 minutes ago

为 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>

类型声明 ​

显示类型声明
typescript
/**
 * 这里的许多 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: Ref<number, number>
  duration: Ref<number, number>
  waiting: Ref<boolean, boolean>
  seeking: Ref<boolean, boolean>
  ended: Ref<boolean, boolean>
  stalled: Ref<boolean, boolean>
  buffered: Ref<[number, number][], [number, number][]>
  playing: Ref<boolean, boolean>
  rate: Ref<number, number>
  volume: Ref<number, number>
  muted: Ref<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: Ref<number, number>
  enableTrack: (
    track: number | UseMediaTextTrack,
    disableTracks?: boolean,
  ) => void
  disableTrack: (track?: number | UseMediaTextTrack) => void
  supportsPictureInPicture: boolean | undefined
  togglePictureInPicture: () => Promise<unknown>
  isPictureInPicture: Ref<boolean, boolean>
  onSourceError: EventHookOn<Event>
  onPlaybackError: EventHookOn<Event>
}
export type UseMediaControlsReturn = ReturnType<typeof useMediaControls>

源码 ​

源码 • 演示 • 文档

贡献者 ​

Anthony Fu
Alex Kozack
一纸忘忧
Fernando Fernández
wheat
Anthony Fu
Justin Halsall
webfansplz
Andrew
aaron lejeune
Darren
huiliangShen
丶远方
Bryce
CommanderRoot
jelf
rimday
Shinigami

更新日志 ​

Pending for release...
c6c6e - feat: use useEventListener where it was not being used (#4479)
v12.4.0 on 1/10/2025
dd316 - feat: use passive event handlers everywhere is possible (#4477)
v12.3.0 on 1/2/2025
59f75 - feat(toValue): deprecate toValue from @vueuse/shared in favor of Vue's native
v12.1.0 on 12/22/2024
209de - feat: add 'media' option to define media query for resources (#4344)
v12.0.0-beta.1 on 11/21/2024
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)
v11.2.0 on 10/30/2024
e1169 - feat: add playback error event (#4253)
v10.10.0 on 5/27/2024
1fe2f - fix: target params may not be ref (#3921)
v10.2.0 on 6/16/2023
0b253 - fix: better representation for "waiting" value (#3072)
v10.1.0 on 4/22/2023
b20aa - fix: apply state when target ref changes (#2999)
v10.0.0-beta.5 on 4/13/2023
cb644 - refactor!: remove isFunction and isString utils
v10.0.0-beta.4 on 4/13/2023
4d757 - feat(types)!: rename MaybeComputedRef to MaybeRefOrGetter
0a72b - feat(toValue): rename resolveUnref to toValue
v9.12.0 on 1/29/2023
4ef27 - fix: ended status not updating (#2680)