更新记录

1.2.46（2026-06-25）

• 修复 uni-app x 客户在业务工具文件中使用 const options: any = { loopMode: 'all' } 后调用 setLoopMode(options) 可能触发 UTS 参数类型不匹配的问题；根入口现在会把动态 options 归一化为 SetLoopModeOptions 后再调用平台层。
• Android 平台公开入口同步放宽 setLoopMode(options) 入参，兼容误用平台深路径或 HBuilderX 生成层把参数标记为 Any 的场景。
• uni-app x 示例新增 Any循环 all/off 测试按钮，用于真机验证客户同款 any 参数调用。
• 兼容性说明：本版本不修改播放队列、媒体卡、原生 Kotlin/Swift 播放逻辑，也不删除 uni-app 的 web/mp/app-plus 兼容入口。

1.2.45（2026-06-23）

• Android 回调桥接修复：pause / resume / stop / skipToNext / skipToPrev / getPlayerState / getCapabilities 等入口不再把 BridgeCallbacksImpl 强转为 ActionOptions 或其他接口 type，统一从动态 options 中提取 success / fail / complete 后构造真实回调对象，修复 uni-app x 自定义基座点击按钮被拦截的问题。
• Android 播放控制链路修复：根入口与 utssdk/app-android 保持一致的动态 options 归一化策略，避免 BridgeCallbacksImpl cannot be cast to ActionOptions、BackgroundAudioEvent cannot be cast to UTSJSONObject 等运行时类型转换异常影响播放、暂停、继续、停止和切歌。
• uni-app x 示例页兼容修复：示例调用改为动态 options 传参并增强运行时异常提示，避免 DemoOptions 与公开接口 type 不匹配导致编译错误，同时保留自定义基座缺少原生生成物时的可读诊断。
• 验证结果：Android 自定义基座真机验证通过，initPlayer / setPlaylist / play / pause / resume / stop / skipToNext / getPlayerState / getCapabilities 均可正常回调；skipToPrev 在第一首时返回“没有上一首曲目”为预期业务失败。
• 兼容性说明：本版本未删除 uni-app 的 web/mp/app-plus 兼容实现；共享根入口只增强动态回调归一化，已同步到 uni-app 与 uni-app x 两个验证项目，保持插件目录统一。

1.2.44（2026-06-17）

• 发布整合版本：延续 1.2.43 的 iOS 云打包兼容修复和标准基座兜底能力，统一纳入本轮多插件发布批次。
• 补充发布口径：README、package.json 与 uni_modules.json 当前版本同步到 1.2.44，便于插件市场按本轮修复集合统一上架。
• 验证提醒：iOS 原生背景音频、锁屏控制和媒体卡能力仍需重新制作自定义基座或正式包验证，避免继续运行旧基座。
• 兼容性说明：本版本只更新发布元数据和修复日志，不改变 1.2.43 已验证的 uni-app / uni-app x 运行逻辑。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

lizhao-bg-audio

lizhao-bg-audio 是一个纯 UTS 背景音频播放插件，统一封装初始化、播放控制、播放队列、系统媒体卡、锁屏/通知栏控制、播放进度、播放完成回调和错误码。

适合音乐、电台、有声书、课程音频、长音频播放等场景。

当前版本：1.2.46

先看最小接入

1. 从插件根目录导入。
2. 在页面生命周期或用户点击方法中调用 initPlayer() 初始化。
3. 初始化成功后调用 setTrack() 设置音频，再调用 play() 播放。

<template>
  <view>
    <button @click="initAndPlay">初始化并播放</button>
  </view>
</template>

<script>
import * as BgAudio from "@/uni_modules/lizhao-bg-audio";

const  = (event) => {
  console.log("播放完成回调", event.payload);
};

export default {
  onLoad() {
    // 事件监听建议先注册，避免初始化或起播后立刻派发的事件被页面错过。
    BgAudio.on("ended", );
  },
  onUnload() {
    BgAudio.off("ended", );
  },
  methods: {
    initAndPlay() {
      const track = {
        id: "demo-1",
        url: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
        title: "SoundHelix Song 1",
        singer: "SoundHelix"
      };

      BgAudio.initPlayer({
        success: () => {
          BgAudio.setTrack({
            track,
            success: () => {
              BgAudio.play({
                startPosition: 0,
                fail: (err) => {
                  console.log("播放失败", err.errCode, err.errMsg);
                }
              });
            },
            fail: (err) => {
              console.log("设置音频失败", err.errCode, err.errMsg);
            }
          });
        },
        fail: (err) => {
          console.log("初始化失败", err.errCode, err.errMsg);
        }
      });
    }
  }
};
</script>

只能 import 插件根目录：@/uni_modules/lizhao-bg-audio。不要 import 到 utssdk/index.uts。 App 端建议使用 success: () => {} / fail: (err) => {} 这种字段箭头函数写法，并把调用放在页面方法或生命周期内；不要在 <script> 顶层直接执行 initPlayer()。 iOS 端同样支持各 API options 内的 success / fail / complete 回调，也支持在 BgAudio.on() 事件回调里继续写日志、查询状态或触发业务逻辑；更新插件 iOS UTS 原生逻辑后，需要重新打 iOS 自定义基座后再验证这些回调。 uni-app x 的 iOS 标准基座不包含本插件原生 UTS 生成物，运行示例或调用 App-iOS 原生能力时请先制作自定义基座或正式包；标准基座只能用于看到缺少原生插件时的提示，不代表插件能力不可用。

插件内置示例页

插件包内已提供可直接复制使用的示例页面：

客户下载插件后，如需使用完整演示页，可以把 uni_modules/lizhao-bg-audio/example/backgroundAudio.vue 复制到项目的 pages/backgroundAudio/backgroundAudio.vue，并在 pages.json 中加入：

{
  "path": "pages/backgroundAudio/backgroundAudio",
  "style": {
    "navigationBarTitleText": "背景音频演示"
  }
}

示例页已按插件根目录导入：import * as BgAudio from '@/uni_modules/lizhao-bg-audio';。如果要验证 Android 通知栏媒体卡、后台播放、iOS 锁屏控制或 Harmony 后台音频，请使用包含插件原生配置的新自定义基座或正式包。

支持平台

常用能力

推荐调用顺序

on 绑定事件
  -> initPlayer
  -> setTrack 或 setPlaylist
  -> play
  -> pause / resume / seek / skipToNext
  -> stop
  -> off 解绑事件

完整示例

下面示例同时适用于 uni-app 和 uni-app x。页面可以直接复制使用，再替换成自己的音频地址。

<template>
  <view class="page">
    <view class="title">背景音频示例</view>
    <view class="state">{{ stateText }}</view>
    <view class="track">{{ trackText }}</view>
    <view class="time">{{ timeText }}</view>

    <view class="buttons">
      <button type="primary" @click="initAndLoad">初始化并加载歌单</button>
      <button @click="play">播放</button>
      <button @click="pause">暂停</button>
      <button @click="resume">继续</button>
      <button @click="stop">停止</button>
      <button @click="seek30">跳转 30 秒</button>
      <button @click="prev">上一首</button>
      <button @click="next">下一首</button>
      <button @click="rate15">1.5 倍速</button>
      <button @click="volume80">音量 80%</button>
      <button @click="loopAll">列表循环</button>
      <button @click="readState">读取状态</button>
      <button @click="readQueue">读取队列</button>
      <button @click="readCapabilities">能力探测</button>
    </view>

    <scroll-view class="logs" scroll-y>
      <text>{{ logsText }}</text>
    </scroll-view>
  </view>
</template>

<script>
import * as BgAudio from "@/uni_modules/lizhao-bg-audio";

export default {
  data() {
    return {
      inited: false,
      stateText: "未初始化",
      trackText: "未加载曲目",
      currentTime: 0,
      duration: 0,
      logs: [],
      progressHandler: null,
      stateHandler: null,
      endedHandler: null,
      errorHandler: null,
      remoteHandler: null
    };
  },
  computed: {
    logsText() {
      return this.logs.join("\n");
    },
    timeText() {
      return `${this.formatTime(this.currentTime)} / ${this.formatTime(this.duration)}`;
    }
  },
  onUnload() {
    this.unbindEvents();
  },
  methods: {
    initAndLoad() {
      BgAudio.initPlayer({
        // 调试时开启插件内部日志，正式包建议保持默认关闭。
        debug: false,
        // iOS：允许系统音频中断结束后自动恢复。
        autoRecover: true,
        // iOS：注册锁屏、控制中心、耳机线控等远程控制。
        autoRegisterRemoteCommand: true,
        // Android：通知栏媒体按钮，默认推荐三键。
        notificationActions: ["prev", "playPause", "next"],
        success: (res) => {
          this.inited = true;
          this.stateText = "初始化成功";
          this.log("初始化成功 " + JSON.stringify(res));
          this.bindEvents();
          this.setPlaylist();
        },
        fail: (err) => {
          this.handleFail("初始化", err);
        }
      });
    },
    setPlaylist() {
      BgAudio.setPlaylist({
        tracks: [
          {
            id: "demo-1",
            url: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
            title: "SoundHelix Song 1",
            singer: "SoundHelix",
            album: "Demo",
            cover: ""
          },
          {
            id: "demo-2",
            url: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3",
            title: "SoundHelix Song 2",
            singer: "SoundHelix",
            album: "Demo",
            cover: ""
          }
        ],
        startIndex: 0,
        success: (res) => {
          this.log("歌单加载成功 " + JSON.stringify(res));
          this.readState();
        },
        fail: (err) => {
          this.handleFail("加载歌单", err);
        }
      });
    },
    play() {
      if (!this.ensureReady()) return;
      BgAudio.play({
        startPosition: 0,
        success: () => {
          this.stateText = "播放中";
          this.log("播放成功");
        },
        fail: (err) => {
          this.handleFail("播放", err);
        }
      });
    },
    pause() {
      if (!this.ensureReady()) return;
      BgAudio.pause({
        success: () => {
          this.stateText = "已暂停";
          this.log("暂停成功");
        },
        fail: (err) => {
          this.handleFail("暂停", err);
        }
      });
    },
    resume() {
      if (!this.ensureReady()) return;
      BgAudio.resume({
        success: () => {
          this.stateText = "继续播放";
          this.log("继续播放成功");
        },
        fail: (err) => {
          this.handleFail("继续播放", err);
        }
      });
    },
    stop() {
      if (!this.ensureReady()) return;
      BgAudio.stop({
        success: () => {
          this.currentTime = 0;
          this.stateText = "已停止";
          this.log("停止成功");
        },
        fail: (err) => {
          this.handleFail("停止", err);
        }
      });
    },
    seek30() {
      if (!this.ensureReady()) return;
      BgAudio.seek({
        position: 30,
        success: () => {
          this.currentTime = 30;
          this.log("已跳转到 30 秒");
        },
        fail: (err) => {
          this.handleFail("跳转进度", err);
        }
      });
    },
    prev() {
      if (!this.ensureReady()) return;
      BgAudio.skipToPrev({
        success: (res) => {
          this.log("上一首成功 " + JSON.stringify(res));
          this.readState();
        },
        fail: (err) => {
          this.handleFail("上一首", err);
        }
      });
    },
    next() {
      if (!this.ensureReady()) return;
      BgAudio.skipToNext({
        success: (res) => {
          this.log("下一首成功 " + JSON.stringify(res));
          this.readState();
        },
        fail: (err) => {
          this.handleFail("下一首", err);
        }
      });
    },
    rate15() {
      if (!this.ensureReady()) return;
      BgAudio.setPlaybackRate({
        playbackRate: 1.5,
        success: () => {
          this.log("倍速已设置为 1.5");
        },
        fail: (err) => {
          this.handleFail("设置倍速", err);
        }
      });
    },
    volume80() {
      if (!this.ensureReady()) return;
      BgAudio.setVolume({
        volume: 0.8,
        success: () => {
          this.log("音量已设置为 80%");
        },
        fail: (err) => {
          this.handleFail("设置音量", err);
        }
      });
    },
    loopAll() {
      if (!this.ensureReady()) return;
      BgAudio.setLoopMode({
        loopMode: "all",
        success: () => {
          this.log("已设置为列表循环");
        },
        fail: (err) => {
          this.handleFail("设置循环", err);
        }
      });
    },
    readState() {
      if (!this.ensureReady()) return;
      BgAudio.getPlayerState({
        success: (state) => {
          this.applyState(state);
          this.log("状态 " + JSON.stringify(state));
        },
        fail: (err) => {
          this.handleFail("读取状态", err);
        }
      });
    },
    readQueue() {
      if (!this.ensureReady()) return;
      BgAudio.getQueueState({
        success: (state) => {
          this.log("队列 " + JSON.stringify(state));
        },
        fail: (err) => {
          this.handleFail("读取队列", err);
        }
      });
    },
    readCapabilities() {
      BgAudio.getCapabilities({
        success: (res) => {
          this.log("能力 " + JSON.stringify(res));
        },
        fail: (err) => {
          this.handleFail("能力探测", err);
        }
      });
    },
    bindEvents() {
      this.unbindEvents();

      this.progressHandler = (event) => {
        const payload = event.payload || {};
        this.currentTime = Number(payload.currentTime || 0);
        this.duration = Number(payload.duration || this.duration || 0);
      };

      this.stateHandler = (event) => {
        const payload = event.payload || {};
        this.log("状态回调 " + JSON.stringify(payload));
      };

      this.endedHandler = (event) => {
        this.stateText = "播放完成";
        this.log("播放完成回调 " + JSON.stringify(event.payload || {}));
      };

      this.errorHandler = (event) => {
        this.log("错误回调 " + JSON.stringify(event.payload || {}));
      };

      this.remoteHandler = (event) => {
        this.log("媒体卡控制回调 " + JSON.stringify(event.payload || {}));
      };

      BgAudio.on("progress", this.progressHandler);
      BgAudio.on("stateChange", this.stateHandler);
      BgAudio.on("ended", this.endedHandler);
      BgAudio.on("error", this.errorHandler);
      BgAudio.on("remoteCommand", this.remoteHandler);
    },
    unbindEvents() {
      if (this.progressHandler != null) BgAudio.off("progress", this.progressHandler);
      if (this.stateHandler != null) BgAudio.off("stateChange", this.stateHandler);
      if (this.endedHandler != null) BgAudio.off("ended", this.endedHandler);
      if (this.errorHandler != null) BgAudio.off("error", this.errorHandler);
      if (this.remoteHandler != null) BgAudio.off("remoteCommand", this.remoteHandler);
      this.progressHandler = null;
      this.stateHandler = null;
      this.endedHandler = null;
      this.errorHandler = null;
      this.remoteHandler = null;
    },
    applyState(state) {
      if (state == null) return;
      this.currentTime = Number(state.currentTime || 0);
      this.duration = Number(state.duration || 0);
      this.stateText = "当前状态：" + (state.status || "unknown");
      if (state.currentTrack != null) {
        this.trackText = `${state.currentTrack.title || ""} ${state.currentTrack.singer || ""}`;
      }
    },
    ensureReady() {
      if (this.inited) return true;
      this.log("请先初始化播放器");
      return false;
    },
    handleFail(action, err) {
      const code = err && err.errCode ? err.errCode : "";
      const msg = err && err.errMsg ? err.errMsg : "";
      this.log(`${action}失败 ${code} ${msg}`);
    },
    log(text) {
      this.logs.unshift(new Date().toLocaleTimeString() + " " + text);
      if (this.logs.length > 40) this.logs.pop();
    },
    formatTime(second) {
      const value = Math.max(0, Math.floor(Number(second || 0)));
      const minute = Math.floor(value / 60);
      const remain = value % 60;
      return minute + ":" + (remain < 10 ? "0" + remain : remain);
    }
  }
};
</script>

<style>
.page {
  padding: 28rpx;
}

.title {
  font-size: 36rpx;
  font-weight: 600;
  margin-bottom: 16rpx;
}

.state,
.track,
.time {
  margin-bottom: 12rpx;
  color: #333;
}

.buttons button {
  margin-top: 16rpx;
}

.logs {
  height: 320rpx;
  margin-top: 24rpx;
  padding: 20rpx;
  background: #f7f7f7;
  border-radius: 12rpx;
  font-size: 24rpx;
  white-space: pre-wrap;
}
</style>

单曲播放示例

import * as BgAudio from "@/uni_modules/lizhao-bg-audio";

const track = {
  id: "single-1",
  url: "https://download.samplelib.com/mp3/sample-3s.mp3",
  title: "Sample 3s"
};

BgAudio.initPlayer({
  success: () => {
    BgAudio.setTrack({
      track,
      success: () => {
        BgAudio.play({
          startPosition: 0,
          fail: (err) => {
            console.log("播放失败", err.errCode, err.errMsg);
          }
        });
      },
      fail: (err) => {
        console.log("设置音频失败", err.errCode, err.errMsg);
      }
    });
  },
  fail: (err) => {
    console.log("初始化失败", err.errCode, err.errMsg);
  }
});

歌单播放示例

import * as BgAudio from "@/uni_modules/lizhao-bg-audio";

const tracks = [
  {
    id: "track-1",
    url: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
    title: "第一首"
  },
  {
    id: "track-2",
    url: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-2.mp3",
    title: "第二首"
  }
];

function appendTracks(index) {
  if (index >= tracks.length) {
    return;
  }
  BgAudio.appendTrack({
    track: tracks[index],
    success: () => {
      appendTracks(index + 1);
    },
    fail: (err) => {
      console.log("追加队列失败", err.errCode, err.errMsg);
    }
  });
}

BgAudio.initPlayer({
  success: () => {
    BgAudio.setTrack({
      track: tracks[0],
      success: () => {
        appendTracks(1);
        BgAudio.play({
          startPosition: 0,
          fail: (err) => {
            console.log("播放失败", err.errCode, err.errMsg);
          }
        });
      },
      fail: (err) => {
        console.log("设置首曲失败", err.errCode, err.errMsg);
      }
    });
  },
  fail: (err) => {
    console.log("初始化失败", err.errCode, err.errMsg);
  }
});

Android / Harmony / Web / 小程序等非 iOS 平台推荐优先使用 setPlaylist({ tracks, startIndex }) 一次性加载完整歌单，避免依赖多次 appendTrack 回调链导致尾曲未入队。仅当旧 iOS 自定义基座存在数组桥接兼容问题时，再使用上面的 setTrack + appendTrack 逐首追加写法。

播放完成与媒体卡事件示例

import * as BgAudio from "@/uni_modules/lizhao-bg-audio";

const  = (event) => {
  console.log("播放完成", event.payload);
};

const onRemote = (event) => {
  console.log("系统媒体控制", event.payload);
};

BgAudio.on("ended", );
BgAudio.on("remoteCommand", onRemote);

// 页面销毁时解绑，避免重复进入页面后回调触发多次。
BgAudio.off("ended", );
BgAudio.off("remoteCommand", onRemote);

API 说明

initPlayer(options)

初始化播放器。App 端会创建原生音频会话、媒体卡或远程控制能力。

setTrack(options)

设置当前单曲和媒体元数据。

setPlaylist(options)

设置播放队列。

play(options)

开始播放。

pause(options) / resume(options) / stop(options)

暂停、继续、停止播放。

seek(options)

跳转到指定播放进度。

setPlaybackRate(options)

设置播放倍速。Harmony 真机不再写入 BackgroundAudioManager.playbackRate，改由 AVPlayer.setSpeed() 执行；系统只支持固定档位时会按最近档位归一化。

setVolume(options)

设置播放音量。部分平台由系统音量控制，可能返回不支持。

setLoopMode(options)

设置循环模式。

appendTrack(options)

向当前队列追加曲目。

开启智能下一曲预加载并且播放器处于 waitingNext 状态时，业务接口拿到下一曲后调用 appendTrack()，插件会自动切到刚追加的下一曲并继续播放，成功回调会额外返回 autoPlay: true。

removeTrack(options)

从队列移除指定曲目。

skipToNext(options) / skipToPrev(options) / skipToIndex(options)

切换上一首、下一首或指定队列下标。

skipToIndex 的 success / complete 表示目标曲目已装载并同步队列下标；插件会随后自动尝试播放，避免 iOS 因播放二级回调未返回而丢失本次切歌回调。

getPlayerState(options) / getQueueState(options) / getCapabilities(options)

读取播放器状态、队列状态和平台能力。

on(eventName, callback) / off(eventName, callback)

订阅和取消订阅播放器事件。

事件说明：

智能下一曲预加载

适合“下一曲需要先请求业务接口”的场景，例如有声书、课程音频、付费内容鉴权或动态推荐。开启后，插件会在当前曲快结束且队列里还没有下一曲时提前触发 preloadNext；如果当前曲播完接口还没返回，会进入 waitingNext 状态等待。业务拿到下一曲后调用 appendTrack()，插件会自动续播。

import * as BgAudio from "@/uni_modules/lizhao-bg-audio";

BgAudio.initPlayer({
  preloadNext: true,
  preloadNextTime: 20,
  nextTrackTimeout: 15000,
  success() {
    console.log("背景音频初始化成功");
  }
});

BgAudio.on("preloadNext", async (event) => {
  const currentTrack = event.payload.currentTrack;
  // 这里换成你的接口请求，例如根据 currentTrack.extras 或 currentTrack.id 获取下一集。
  const nextTrack = await requestNextTrack(currentTrack);
  if (nextTrack != null) {
    BgAudio.appendTrack({
      track: nextTrack,
      success(res) {
        console.log("下一曲已追加", res);
      }
    });
  }
});

BgAudio.on("waitingNext", () => {
  console.log("当前曲已播完，正在等待下一曲接口返回");
});

BgAudio.on("nextTrackTimeout", (event) => {
  console.log("等待下一曲超时", event.payload);
});

注意事项：

• preloadNext 只在 loopMode = "off" 且当前播放到队列末尾时触发；队列里已经有下一曲时，插件会直接续播已有下一曲。
• 如果业务先调用 setPlaylist() 或连续 appendTrack() 把下一曲提前放进队列，当前曲临近结束时不会触发 preloadNext，这是正常行为；只有“当前曲就是队列最后一首、插件确实缺少下一曲”时才需要通知业务请求接口。
• 测试 preloadNext 时请确保队列只有当前这一首，例如先调用 setPlaylist({ tracks: [currentTrack], startIndex: 0 }) 清掉旧队列；如果之前加载过完整歌单，旧的下一曲仍在队列中，会导致看不到 preloadNext 回调。
• Harmony 真机调试时建议参考示例页“加载单曲预加载测试”：示例页会用唯一 id 和唯一 url 调用 setTrack()，确保当前曲就是队列最后一首。若设备或基座中 setPlaylist() 的数组桥接不稳定，也可以采用这种方式重置为单曲队列。
• “跳到预加载触发点”只是把进度移动到阈值附近，真正触发还需要已经开启 preloadNext、当前曲有有效 duration、loopMode = "off"，并且队列里没有下一曲；满足条件后事件可能在 seek 完成或后续播放进度回调中立即触发。
• preloadNext 对同一首曲目只触发一次，避免进度频繁上报导致接口重复请求。
• nextTrackTimeout 默认 0，表示一直等待；业务希望超时展示重试按钮时可设置为 10000 或 15000。
• 如果业务主动切歌、重新设置歌单、停止播放或移除等待中的曲目，插件会清理本次等待状态。

getDebugTrace() / clearDebugTrace() / getCrashReports() / clearCrashReports()

iOS 诊断 API，用于读取和清理持久化调试轨迹。正常业务一般不需要调用。

类型说明

BackgroundAudioTrack

BackgroundAudioPlayerState

BackgroundAudioCapabilities

错误码

权限与配置

Harmony 后台音频连续任务配置

Harmony 息屏后仍要保持播放和系统媒体卡可用时，必须在鸿蒙工程 harmony-configs/entry/src/main/module.json5 的 EntryAbility 中配置 backgroundModes: ["audioPlayback"]，并在 requestPermissions 中声明 ohos.permission.INTERNET 和 ohos.permission.KEEP_BACKGROUND_RUNNING。

示例（只展示关键字段）：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "backgroundModes": [
          "audioPlayback"
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
      }
    ]
  }
}

INTERNET 用于网络音频访问；KEEP_BACKGROUND_RUNNING 与 audioPlayback 用于配合插件内部后台音频连续任务申请，让息屏播放和媒体卡控制在系统后台策略下继续可用。修改该配置后必须重新打鸿蒙自定义基座或运行包。

Harmony 短音/瞬态音频焦点策略

Harmony 上架检测会检查短音、瞬态音播放场景是否使用 share / duck / pause 等不会永久打断后台音乐的焦点策略。插件的 Harmony 原生链路会在 AVPlayer 首次 prepare() / play() 前激活 AudioSessionManager 的 CONCURRENCY_MIX_WITH_OTHERS 并发策略，同时显式设置 audioInterruptMode = SHARE_MODE 和 audioRendererInfo.usage = STREAM_USAGE_MUSIC，让后台音乐按系统策略并发播放或在短暂暂停后自动恢复，避免被识别为 stop 独占焦点策略。

是否需要自定义基座

目录结构

uni_modules/
└─ lizhao-bg-audio/
   ├─ package.json
   ├─ readme.md
   ├─ changelog.md
   ├─ example/
   │  ├─ index.vue
   │  ├─ backgroundAudio.vue
   │  └─ readme.md
   └─ utssdk/
      ├─ interface.uts
      ├─ unierror.uts
      ├─ index.uts
      ├─ app-android/index.uts
      ├─ app-ios/index.uts
      ├─ app-harmony/index.uts
      ├─ web/index.uts
      ├─ mp-weixin/index.uts
      └─ mp-alipay/index.uts

注意事项

1. 先 initPlayer()，再调用播放、队列、状态 API。
2. progress 事件频率较高，页面日志建议采样展示。
3. on() 和 off() 需要使用同一个回调函数引用。
4. iOS 中文 URL 会做安全编码归一化，但仍建议业务侧使用可直接访问的 HTTPS 音频地址。
5. setVolume()、setPlaybackRate() 在部分平台可能受系统策略限制，建议先用 getCapabilities() 判断；Harmony 通过 AVPlayer.setSpeed() 支持常见固定倍速档位。
6. Harmony 后台保活依赖 module.json5 中的 backgroundModes: ["audioPlayback"] 和 ohos.permission.KEEP_BACKGROUND_RUNNING；配置变化后必须重新打鸿蒙自定义基座或运行包。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列UTS插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。