Skip to main content
版本：v3+

Player

API_LEVEL 3.0 开始支持，API 兼容性请参考 API_LEVEL。

Player_image

播放器控制器，用于设置音频文件、准备播放资源、控制播放状态和查询媒体信息。

属性​

source​

属性类型必填默认值说明API_LEVEL
FILEnumber是-播放指定音频文件3.0

event​

属性类型必填默认值说明API_LEVEL
PREPAREnumber是-prepare() 的异步结果3.0
COMPLETEnumber是-音频文件播放结束3.0
PLAYnumber是-start() 或 resume() 后的播放结果3.0
STOPnumber是-播放停止3.0
PAUSEnumber是-播放暂停3.0
PROGRESSnumber是-播放进度更新3.0

state​

属性类型必填默认值说明API_LEVEL
IDLEnumber是-初始状态3.0
INITIALIZEDnumber是-setSource() 后的状态3.0
PREPARINGnumber是-准备播放中的中间状态3.0
PREPAREDnumber是-准备完成3.0
STARTINGnumber是-开始播放中的中间状态3.0
PLAYnumber是-正在播放3.0
PAUSINGnumber是-暂停处理中的中间状态3.0
PAUSEDnumber是-已暂停3.0
RESUMINGnumber是-恢复播放中的中间状态3.0

方法​

setSource​

在开始播放之前，设置播放参数，指定音频文件路径。

player.source.FILE 播放指定文件，支持 MP3 格式，以及使用音频 API 录制的 OPUS 格式。 options.file 默认相对小程序 assets 目录，也可以使用 data:// 访问小程序 data 目录。

setSource(source: Player['source']['FILE'], options: { file: string }): void

prepare​

播放器进入准备阶段，检查路径、文件格式和码率是否支持。成功后播放器状态变化并开始缓存多媒体数据，通过事件监听函数获取调用结果。

prepare(): void

start​

开始播放

start(): void

pause​

暂停播放

pause(): void

resume​

恢复播放，调用 start() 有同样效果

resume(): void

stop​

停止播放

stop(): void

seek​

API_LEVEL 4.2

设置播放位置（播放文件时长的百分比位置），percentage 有效值为 [0 - 100]，返回值代表是否设置成功。

  • 如果当前是 PREPARED 状态，在 seek() 之后会自动开始播放
  • 如果当前是 PAUSED 或 PLAY 状态，在 seek() 之后保持当前状态
seek(percentage: number): boolean

seekTo​

API_LEVEL 4.3

按秒设置播放位置，功能同 seek()

seekTo(seconds: number): boolean

getDuration​

获取当前播放的媒体文件总时长，单位秒。返回 0 代表无效，需要播放器处于 PREPARED 状态才可以获取到值

getDuration(): number

getVolume​

获取当前系统音量值，范围 [0 - 100]

getVolume(): number

setVolume​

设置系统音量值，范围 [0 - 100]，返回值代表是否设置成功，true 表示设置成功

setVolume(volume: number): boolean

getTitle​

获取当前播放媒体文件标题，调用失败时返回 undefined

getTitle(): string | undefined

getArtist​

获取当前播放媒体文件艺术家信息，调用失败时返回 undefined

getArtist(): string | undefined

getMediaInfo​

获取当前播放媒体文件的标题、艺术家和时长信息。title、artist 在 setSource() 后可获取，duration 需要播放器处于 PREPARED 状态才可以获取

getMediaInfo(): {
      title: string | undefined
      artist: string | undefined
      duration: number
    }

getStatus​

获取播放器状态，返回值含义参考 player.state

getStatus(): number

addEventListener​

事件监听，用于播放状态监听，当状态发生变化时会触发 callback

addEventListener(event: number, callback: (result: boolean | number | undefined) => void): void

代码示例​

import { create, id } from '@zos/media'

const player = create(id.PLAYER)
player.addEventListener(player.event.PREPARE, (result) => {
  if (result) player.start()
})
player.addEventListener(player.event.COMPLETE, () => {
  player.stop()
})
player.setSource(player.source.FILE, { file: 'data://music.opus' })
const info = player.getMediaInfo()
console.log(info.title, info.artist, info.duration)
player.prepare()
player.pause()
player.resume()
player.stop()