useMediaControls

類別

瀏覽器

匯出大小

2.17 kB

上次變更

5 天前

用於 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

用法

基本用法

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

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

類型宣告

顯示類型宣告

/**
 * Many of the jsdoc definitions here are modified version of the
 * documentation from MDN(https://developer.mozilla.org/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

Andrew

aaron lejeune

Darren

huiliangShen

丶远方

Bryce

CommanderRoot

jelf

rimday

Shinigami

變更日誌

v12.8.0 於 2025/3/5

7432f - feat(types): 棄用 MaybeRef 和 MaybeRefOrGetter，改用 Vue 原生型別 (#4636)

v12.5.0 於 2025/1/22

c6c6e - feat: 在未使用 useEventListener 的地方使用它 (#4479)

v12.4.0 於 2025/1/10

dd316 - feat: 在所有可能的地方使用被動事件處理器 (#4477)

v12.3.0 於 2025/1/2

59f75 - feat(toValue): 棄用來自 @vueuse/shared 的 toValue，改用 Vue 原生型別

v12.1.0 於 2024/12/22

209de - feat: 新增 'media' 選項，用於定義資源的媒體查詢 (#4344)

v12.0.0-beta.1 於 2024/11/21

0a9ed - feat!: 移除 Vue 2 支援，最佳化 bundle 並清理程式碼 (#4349)

v11.2.0 於 2024/10/30

e1169 - feat: 新增播放錯誤事件 (#4253)

v10.10.0 於 2024/5/27

1fe2f - fix: 目標參數可能不是 ref (#3921)

v10.2.0 於 2023/6/16

0b253 - fix: 更好地表示 "waiting" 值 (#3072)

v10.1.0 於 2023/4/22

b20aa - fix: 在目標 ref 變更時套用狀態 (#2999)

v10.0.0-beta.5 於 2023/4/13

cb644 - refactor!: 移除 isFunction 和 isString 工具函式

v10.0.0-beta.4 於 2023/4/13

4d757 - feat(types)!: 將 MaybeComputedRef 重新命名為 MaybeRefOrGetter

0a72b - feat(toValue): 將 resolveUnref 重新命名為 toValue

v9.12.0 於 2023/1/29

4ef27 - fix: 修正結束狀態未更新問題 (#2680)