ADVMaker docs

Appearance

音频 ​

你可以在游戏中播放背景音乐和音效

使用 ​

ts
// 播放背景音乐（指定音轨 'bgm'）
Adv.audio.play('/music/bgm.mp3', 'bgm', { loop: true, volume: 0.5 })

// 播放音效（每次创建独立音轨）
Adv.audio.play('/sfx/click.mp3')

// 暂停背景音乐
Adv.audio.pause('bgm')

API 文档 ​

通过 Adv.audio() 获取的 store 实例包含以下方法。

方法 ​

play(src, channelId?, options?) ​

播放音频。

  • src string – 音频文件路径
  • channelId? string – 指定音轨 ID。若不传则创建全新独立音轨
  • options? PlayOptions – 配置项
    • loop?: boolean – 是否循环播放（默认 true）
    • volume?: number – 音量 0~1（默认 1）

返回值: string – 实际使用的音轨 ID

行为：

  • 无 channelId → 创建新音轨并播放
  • channelId 不存在 → 以该 ID 创建音轨并播放
  • channelId 已存在 → 暂停当前音频，替换为新音频并从头播放

pause(channelId) ​

暂停指定音轨。

resume(channelId) ​

继续播放暂停的音轨。

stop(channelId) ​

停止并移除指定音轨（释放资源）。

setVolume(channelId, volume) ​

设置指定音轨的音量（0 ~ 1）。

setLoop(channelId, loop) ​

设置指定音轨的循环模式。

unlockAudio() ​

手动解锁音频上下文，用于自定义“点击开始”交互。

destroyAll() ​

停止并销毁所有音轨。

自动播放处理 ​

浏览器禁止页面在无用户手势时自动播放音频。
本库已内置处理：

  1. 首次调用 play() 时若被阻止，会自动标记 needsUserInteraction = true
  2. 将播放请求加入待重试队列
  3. 当用户执行任意交互（点击、触摸）后，自动恢复队列中的播放
  4. 你也可以主动调用 unlockAudio() 来解锁