更新记录

1.0.0（2026-07-02）

• 实现 HarmonyOS 后台录音核心功能
• 支持后台长时任务与常驻通知
• 支持动态权限申请
• 支持暂停/恢复录音
• 支持来电中断自动检测
• 通知文案、文件名可自定义

平台兼容性

uni-app(3.7.13)

uni-app x(3.7.13)

harmony-background-recorder

HarmonyOS 后台录音 UTS 插件，支持息屏/后台持续录音、常驻通知栏提示、来电中断自动检测。

功能特性

• 基于 HarmonyOS AVRecorder 原生 API 实现
• 支持后台长时任务（backgroundTaskManager），息屏/切后台录音不中断
• 自动发布常驻通知，满足华为应用市场审核要求
• 动态权限申请（麦克风 + 后台运行）
• 来电中断自动检测，无需电话权限
• 支持暂停/恢复录音
• 通知文案、文件名可自定义

安装方式

1. 导入插件

将 uni_modules/harmony-background-recorder/ 整个目录复制到目标 uni-app 项目的 uni_modules/ 目录下。

2. 宿主工程配置（必须）

唯一需要手动配置的是 backgroundModes。权限和合规文案已由插件自动声明，无需重复配置。

选择以下任一方式：

方式 A：harmony-configs（推荐，一次配置永久生效）

在项目根目录创建 harmony-configs/entry/src/main/module.json5，确保 EntryAbility 包含 backgroundModes: ["audioRecording"]：

{
  "module": {
    "abilities": [
      {
        "name": "EntryAbility",
        "backgroundModes": ["audioRecording"]
      }
    ]
  }
}

也可直接使用插件自带的配置模板，将插件目录下的 harmony-configs/ 复制到项目根目录即可（模板已包含 audioRecording 声明，同时保留了原有的 ohos.permission.INTERNET 等基础配置）。

方式 B：manifest.json

在项目 manifest.json 的 app-harmony.distribute 下添加：

"app-harmony": {
  "distribute": {
    "abilities": [
      {
        "name": "EntryAbility",
        "backgroundModes": ["audioRecording"]
      }
    ]
  }
}

注意：部分 HBuilderX 版本可能不支持通过 manifest.json 配置 backgroundModes，此时请使用方式 A。

API

startBackgroundRecord(options?)

启动后台录音，自动完成权限申请、后台任务注册、通知发布、录音器初始化。

import { startBackgroundRecord } from '@/uni_modules/harmony-background-recorder'

startBackgroundRecord({
  fileName: 'my_recording.m4a',            // 可选，默认 recording.m4a
  notificationTitle: '正在录音',            // 可选
  notificationText: '点击返回应用',         // 可选
  success: (res) => { /* res.success, res.errMsg */ },
  fail: (err) => { /* err.errCode, err.errMsg */ },
  complete: (res) => { }
})

stopBackgroundRecord(options?)

停止录音，释放资源、取消后台任务和通知。

import { stopBackgroundRecord } from '@/uni_modules/harmony-background-recorder'

stopBackgroundRecord({
  success: (res) => { /* res.filePath - .m4a 文件完整路径 */ },
  fail: (err) => { },
  complete: (res) => { }
})

pauseBackgroundRecord(options?)

暂停当前录音。

import { pauseBackgroundRecord } from '@/uni_modules/harmony-background-recorder'

pauseBackgroundRecord({
  success: (res) => { },
  fail: (err) => { }
})

resumeBackgroundRecord(options?)

恢复已暂停的录音。

import { resumeBackgroundRecord } from '@/uni_modules/harmony-background-recorder'

resumeBackgroundRecord({
  success: (res) => { },
  fail: (err) => { }
})

startCallMonitoring(callback?)

启动来电监听。基于 AVRecorder 状态变化检测系统来电中断，无需申请电话权限。必须在 startBackgroundRecord 成功后调用。

import { startCallMonitoring } from '@/uni_modules/harmony-background-recorder'

startCallMonitoring({
  onCallIncoming: () => { /* 来电中断了录音 */ },
  onCallEnded: () => { /* 来电结束，录音已自动恢复 */ },
  fail: (err) => { }
})

stopCallMonitoring()

停止来电监听。

import { stopCallMonitoring } from '@/uni_modules/harmony-background-recorder'

stopCallMonitoring()

错误码

录音参数

权限要求

• ohos.permission.MICROPHONE — 麦克风权限，用于采集音频
• ohos.permission.KEEP_BACKGROUND_RUNNING — 后台运行权限，用于息屏/切后台时保持录音

适用平台

• HarmonyOS (app-harmony)，minSdkVersion 11+

版本历史

• 1.0.0: 初始版本，实现后台录音核心功能