useMediaSession

在系统媒体控制中心显示媒体信息，响应系统媒体控制按钮。

前置依赖

依赖参数

参数名	类型	说明
deps.vue.ref	<T>(value: T) => Ref<T>	Vue ref 函数
deps.vue.onUnmounted	(fn: () => void) => void	Vue onUnmounted 钩子
deps.mediaSession	MediaSession	MediaSession API

环境要求

浏览器 API: Media Session API

平台支持：

• ✅ Chrome/Edge（Windows、macOS、Android）
• ✅ Safari（macOS、iOS）
• ✅ Firefox（部分支持）

函数签名

function useMediaSession(
  deps: UseMediaSessionDeps
): UseMediaSessionReturn

interface UseMediaSessionDeps {
  vue: VueCompositionAPI
  mediaSession: MediaSession | undefined
}

interface UseMediaSessionReturn {
  isSupported: Ref<boolean>
  playbackState: Ref<'none' | 'paused' | 'playing'>
  error: Ref<string | null>
  setMetadata: (metadata: MediaMetadata) => void
  setPlaybackState: (state: 'none' | 'paused' | 'playing') => void
  setActionHandler: (action: MediaSessionAction, handler: MediaSessionActionHandler | null) => void
}

interface MediaMetadata {
  title?: string
  artist?: string
  album?: string
  artwork?: Array<{
    src: string
    sizes?: string
    type?: string
  }>
}

type MediaSessionAction = 
  | 'play' | 'pause' | 'stop'
  | 'previoustrack' | 'nexttrack'
  | 'seekbackward' | 'seekforward' | 'seekto'

参数

参数名	类型	必填	说明
deps	UseMediaSessionDeps	是	依赖注入对象

返回值

属性	类型	说明
isSupported	Ref<boolean>	是否支持 MediaSession API
playbackState	Ref<'none' | 'paused' | 'playing'>	当前播放状态
error	Ref<string | null>	错误信息
setMetadata	(metadata) => void	设置媒体元数据
setPlaybackState	(state) => void	设置播放状态
setActionHandler	(action, handler) => void	设置动作处理器

工作原理

1. 检查浏览器是否支持 MediaSession API
2. 调用 setMetadata() 设置歌曲信息和封面
3. 调用 setPlaybackState() 设置播放状态
4. 调用 setActionHandler() 设置按钮处理函数
5. 系统媒体控制中心会显示媒体信息和控制按钮
6. 组件卸载时自动清除所有设置

显示位置：

• 浏览器工具栏媒体控制器
• 系统通知栏
• 锁屏界面
• 媒体控制中心（macOS、Windows）

支持的控制按钮：

• 播放/暂停
• 上一首/下一首
• 快进/快退
• 停止

适用场景：

• 音乐播放器
• 播客应用
• 视频播放器
• 在线电台

异常

无异常抛出