概览
“概览”章节使用 @capgo/capacitor-native-audio 当您的 Capacitor 应用需要响应式播放 UI 音效、短片段或音乐类场景，且不想处理多个原生音频 API 时，可以使用此插件。支持预加载资源、循环播放、淡入淡出音量、流式传输远程 URL 或 HLS，并可选择显示锁屏控制栏。
典型场景：游戏 SFX、通知铃声、引导式冥想、播客播放器，以及任何需要与设备上其他应用音频会话共存的流程。
平台支持
标题为“平台支持”的部分| 平台 | 支持 | 备注 |
|---|---|---|
| iOS | 是 | AVFoundation，可选 Now Playing 和音频会话类别 |
| Android | 是 | 媒体播放、通知，以及可选的后台前台服务 |
| Web 端 | 部分支持 | 核心播放功能；部分监听事件在 Web 端不会触发 |
核心功能
标题为“核心功能”的章节configure- 配置音频播放器。preload- 加载音频文件。playOnce- 播放一次音频文件并自动清理。isPreloaded- 检查音频文件是否已预加载。
公开 API
标题为“公开 API”的章节| 方法 | 描述 |
|---|---|
configure | 配置音频播放器。 |
preload | 加载音频文件。 |
playOnce | 播放一次音频文件并自动清理。 |
isPreloaded | 检查音频文件是否已预加载。 |
play | 播放音频文件。 |
pause | 暂停音频文件。 |
resume | 继续播放音频文件。 |
loop | 停止音频文件。 |
stop | 停止音频文件。 |
unload | 卸载音频文件。 |
setVolume | 设置音频文件的音量。 |
setRate | 设置音频文件的播放速率。 |
setCurrentTime | 设置音频文件的当前播放时间。 |
getCurrentTime | 获取音频文件的当前播放时间。 |
getDuration | 获取音频文件的时长（秒）。 |
isPlaying | 检查音频文件是否正在播放。 |
addListener | 监听播放完成事件。 |
addListener | 监听当前时间更新。音频播放时每 100ms 触发一次。 |
addListener | 监听播放状态变化，包括通知栏和锁屏控制。由 Android 和 iOS 触发。当前的 Web 实现暂不支持此事件。 |
clearCache | 清除远程音频文件的缓存。 |
setDebugMode | 设置调试模式日志。 |
getPluginVersion | 获取原生 Capacitor 插件版本。 |
deinitPlugin | 反初始化插件并恢复原始音频会话设置。此方法会停止所有正在播放的音频，并撤销插件所做的任何音频会话更改。当需要确保与其他音频插件的兼容性时，请使用此方法。 |
单一事实来源
标题为“单一事实来源”的部分此参考文档同步自 src/definitions.ts 中的 capacitor-native-audio.
继续阅读 @capgo/capacitor-native-audio
标题为“继续阅读 @capgo/capacitor-native-audio”的部分如果你正在使用 @capgo/capacitor-native-audio 来规划原生媒体和界面行为，并将其与 使用 @capgo/capacitor-native-audio 关于使用 @capgo/capacitor-native-audio 中的原生能力， 使用 @capgo/capacitor-live-activities 用于使用 @capgo/capacitor-live-activities 时的原生能力， @capgo/capacitor-live-activities 在 @capgo/capacitor-live-activities 中的实现细节， 使用 @capgo/capacitor-video-player 有关使用 @capgo/capacitor-video-player 时的原生能力，以及 @capgo/capacitor-video-player 关于 @capgo/capacitor-video-player. 中的实现细节
