更新记录

1.0.0（2026-08-08）

• 新版发布

平台兼容性

uni-app(4.87)

uni-app x(4.87)

yt-callphone

面向 uni-app-x / uni-app 的 Android 通话能力 UTS 插件。

特别提醒

• 购买本插件前，请先试用，请先试用，请先试用，确认满足需求之后再行购买。虚拟物品一旦购买之后无法退款。
• 如有使用上的疑问、bug，可以进交流群联系作者；
• 请在合法范围内使用，若使用本插件做非法开发，本方概不负责；
• 插件需先引入再打自定义基座后运行测试
• 可导入示例项目试用，uniapp-x示例项目在uniapp示例项目的static文件夹下
• 试用时建议使用提供的示例项目打包测试，没问题再在自己项目试用，有问题方便定位。

只支持 Android 真机。 修改插件 AndroidManifest / 依赖后，必须重新制作自定义调试基座（或云打包正式包）再运行，标准基座不会带上本插件原生能力。

目录

1. 插件能做什么
2. 两种「通话录音」先分清
3. 使用系统通话录音：必读
4. 需要开哪些权限
5. 5 分钟上手
6. 怎么获取通话录音
7. 完整调用示例
8. API 一览
9. 常见问题

1. 插件能做什么

2. 两种「通话录音」先分清（重要）

不要把下面两种混在一起，请先记住：

方案 A：厂商「系统通话自动录音」（推荐，能录到双方）

• 录音是 系统电话 App 生成的，文件在手机录音目录 / MediaStore 里。
• 本插件负责：打开系统录音设置、申请读文件权限、扫描文件、挂断后回调路径。
• 能录到 本机 + 对方 的通话内容（取决于厂商实现，一般比 MIC 靠谱）。

方案 B：App「麦克风 MIC 录音」（startRecord / stopRecord）

• 录音是 本 App 用麦克风 录的，不是系统通话录音。
• 高版本 Android（尤其 Android 10+）对通话音频有隔离：MIC 往往只能录到本机环境音/本端说话，经常录不到对方声音。
• 若业务要「完整通话录音」，请优先用 方案 A，不要依赖 MIC。

3. 使用系统通话录音：必读

3.1 不要把集成了本插件的 App 设为默认拨号器

若业务依赖 系统通话录音文件：

• 不要调用 setToTheDefaultCallApplication()，也不要在系统设置里把本 App 设成「默认电话 / 默认拨号器」。
• 请保持 系统自带电话 为默认拨号器。

原因：本 App 成为默认通话应用后，通话由本 App 的 InCallService 接管，厂商系统自动录音通常不会落盘——系统录音目录里也没有这次通话的文件，插件自然扫不到。

可用 isDefaultCallApplication() 自查：若返回 true 又要系统录音，请先改回系统电话为默认。

3.2 系统侧还要打开「通话自动录音」

不同品牌路径不一样，可先调插件：

openAutoCallRecordSettings()

若跳不过去，请到手机设置里手动打开，例如：

• 电话 / 通话设置 → 自动录音 / 通话录音 → 全部通话 / 陌生人 等
• 部分品牌在「录音机」「智能助手」相关菜单

没开系统自动录音 = 永远没有录音文件可扫。

4. 需要开哪些权限

4.0 重要：开电话监听前，请先请求全部权限

务必先调用 requestAllPermission()，用户点完允许后，再调用 openCallListener()。

不要一进页面就先点「打开电话监听」。否则常见问题：

1. 跳到悬浮窗设置页（当前实现里若未开悬浮窗会顺带引导）；
2. 从设置页返回时，部分机型 / 自定义基座会进程重启，看起来像 App 重启；
3. 电话状态相关权限未齐时，监听不稳定，甚至再次点击异常。

推荐顺序：

import { requestAllPermission, openCallListener } from '@/uni_modules/yt-callphone'

// ① 先申请全部权限，弹窗全部点「允许」
requestAllPermission()

// ② 用户授权完成后再打开监听（可放在按钮里，勿与①同一瞬间连点）
openCallListener((info) => {
  console.log(info.callState, info.number, info.filePath)
})

Demo 页也请先点「请求全部权限」，再点「打开电话监听」。

4.1 功能 → 权限对照表（小白看这张表）

一键申请（弹窗类危险权限）：

requestAllPermission()

说明：Manifest 里已声明权限，但仍需用户在弹窗里点「允许」。悬浮窗、所有文件访问属于特殊权限，要跳系统设置页，不会全靠这一次弹窗搞定。

4.2 扫「系统通话录音文件」还要这些

if (!hasAllFilesAccess()) {
  openAllFilesAccessSettings()
}

4.3 权限名速查

5. 5 分钟上手

5.1 制作自定义基座

HBuilderX：运行 → 运行到手机或模拟器 → 制作自定义调试基座 → 用新基座安装到真机后再运行。

5.2 App 启动时初始化

App.uvue：

import { init } from '@/uni_modules/yt-callphone'

onLaunch(() => {
  // #ifdef APP-ANDROID
  try {
    init()
  } catch (e) {
    console.error('yt-callphone init fail', e)
  }
  // #endif
})

5.3 页面里引用（注意权限顺序）

import * as CallPhone from '@/uni_modules/yt-callphone'

// ① 先请求全部权限（必做，尤其是电话监听前）
CallPhone.requestAllPermission()

// ② 授权完成后再拨号 / 监听 / 挂断
CallPhone.makingCalls('10086', '展示号')
CallPhone.openCallListener((info) => {
  console.log(info.callState)
})
CallPhone.hangUpCall()

也可具名导入：import { requestAllPermission, openCallListener, hangUpCall } from '@/uni_modules/yt-callphone'。

工程内完整按钮 Demo：pages/index/index.uvue（请先点「请求全部权限」，再点「打开电话监听」）。

6. 怎么获取通话录音

下面只讲 方案 A：系统通话录音（推荐）。

步骤 1：确认默认拨号器

• 系统电话 = 默认
• 本 App ≠ 默认（isDefaultCallApplication() 应为 false）

步骤 2：申请权限

requestAllPermission()
if (!hasAllFilesAccess()) {
  openAllFilesAccessSettings()  // 用户打开「允许管理所有文件」后返回 App
}

步骤 3：打开系统自动录音

openAutoCallRecordSettings()
// 在设置页打开「自动录音」后返回

步骤 4：打开监听（可选，用于挂断后自动拿到文件）

再次强调：必须先完成步骤 2 的 requestAllPermission()，再打开监听。

import { requestAllPermission, openCallListener, setAutoScanOemRecordOnHangUp } from '@/uni_modules/yt-callphone'

// 若步骤 2 已申请过可跳过；未申请务必先执行
requestAllPermission()

// 挂断后自动扫描（默认就是 true，可显式打开）
setAutoScanOemRecordOnHangUp(true)

openCallListener((info) => {
  if (info.callState == 'oemRecordReady') {
    // 扫到了系统录音
    console.log('录音路径', info.filePath)
    console.log('文件名', info.fileName)
  }
})

步骤 5：用系统电话打电话（或本插件 makingCalls 拨出）

打完一通电话并挂断，等几秒。

步骤 6：主动拉取文件列表（随时可查）

import { getAllOemRecordFiles, diagnoseOemRecordScan } from '@/uni_modules/yt-callphone'

const files = getAllOemRecordFiles(true)
if (files.length == 0) {
  // 扫不到时看诊断
  const d = diagnoseOemRecordScan(true)
  console.log(d.hint)              // 人话提示
  console.log(d.hasStorageAccess)  // 权限够不够
  console.log(d.existingDirs)      // 目录在不在
} else {
  console.log('最新录音', files[0].path, files[0].name)
}

若品牌目录特殊

setCustomRecordDirs([
  '/storage/emulated/0/Music/Recordings/Call Recordings' // 换成真机实际目录
])

7. 完整调用示例

import {
  init,
  setCallPageConfig,
  requestAllPermission,
  hasAllFilesAccess,
  openAllFilesAccessSettings,
  openAutoCallRecordSettings,
  openCallListener,
  removeCallListener,
  makingCalls,
  hangUpCall,
  makingCallsWithSim,
  isDefaultCallApplication,
  getCallRecords,
  getAllOemRecordFiles,
  diagnoseOemRecordScan,
  setAutoScanOemRecordOnHangUp,
  startRecord,
  stopRecord
} from '@/uni_modules/yt-callphone'

// ---------- 初始化 & 配置 ----------
init()
setCallPageConfig({
  callInlabel: '来电',
  callOutlabel: '去电中',
  isRealPhone: true,
  showTxtSize: 18
})

// ---------- 权限（开监听前必做）----------
requestAllPermission()
// 等用户点完权限弹窗后再继续下面逻辑（不要同一瞬间连点打开监听）
if (!hasAllFilesAccess()) {
  openAllFilesAccessSettings()
}
openAutoCallRecordSettings()

// ---------- 强烈建议：系统录音场景下不要当默认拨号器 ----------
if (isDefaultCallApplication()) {
  console.warn('当前是默认拨号器，系统通话录音可能无法落盘！请改回系统电话为默认。')
}

// ---------- 监听通话 + 挂断后拿系统录音（务必在 requestAllPermission 之后）----------
setAutoScanOemRecordOnHangUp(true)
openCallListener((info) => {
  console.log('状态', info.callState)
  if (info.callState == 'oemRecordReady' && info.filePath != null) {
    console.log('系统录音文件', info.filePath)
  }
})

// ---------- 拨号 ----------
makingCalls('10086', '客服热线')
// makingCallsWithSim('10086', null, 1) // 指定卡 1
// hangUpCall() // 挂断当前通话

// ---------- 系统通话记录（不是录音） ----------
const logs = getCallRecords({ limit: 20 })

// ---------- 主动查系统录音文件 ----------
const files = getAllOemRecordFiles(true)
const diag = diagnoseOemRecordScan(true)

// ---------- App MIC 录音（高版本可能录不到对方） ----------
// startRecord()
// stopRecord((name) => { console.log(name) })

// ---------- 不用时关闭监听 ----------
// removeCallListener()

8. API 一览

类型定义见：utssdk/interface.uts。 Android 实现见：utssdk/app-android/index.uts。

错误码：

9. 常见问题

Q：打开电话监听要什么权限？要先做什么？ 先调用 requestAllPermission()，再调用 openCallListener()。监听核心是 READ_PHONE_STATE（Android 12+ 建议加 READ_PRECISE_PHONE_STATE），通话记录变化还要 READ_CALL_LOG。详见 第 4 节。

Q：一点「打开电话监听」就跳到悬浮窗设置，回来 App 像重启了？ 当前实现在未开悬浮窗时会引导去设置页；部分机型从该页返回会杀进程重建，属常见现象。正确用法：先请求全部权限并授权完成，再打开监听。纯监听场景悬浮窗不是核心必需，但以当前插件行为仍可能被引导去开。

Q：扫不到系统录音？ 按顺序查：① 是不是本 App 成了默认拨号器 → ② 系统自动录音开了没 → ③ hasAllFilesAccess() → ④ diagnoseOemRecordScan() 看 hint。

Q：MIC 录音只有自己没有对方？ 属于 Android 高版本限制，预期内。要双方声音请用系统通话自动录音（方案 A）。

Q：改了 AAR 或 Manifest 没生效？ 重新打自定义基座 / 正式包，不要用旧基座。

Q：iOS / 鸿蒙？ 当前不支持，调用会报 9010001。

Q：依赖有哪些？ app-android/config.json 已声明：appcompat、mmkv、gson、glide 等，云打包会按配置拉取。

更多好用插件推荐

• 高德定位连续定位后台定位保活定位
• 百度汽车摩托车导航插件
• 百度鹰眼轨迹插件支持后台采集、保活
• 百度定位插件、连续定位、保活、坐标系转换、支持双端
• 计步器插件，支持Android、iOS双端
• uts经典蓝牙插件、蓝牙电子秤
• 获取唯一标识、ServiceID、卸载更新不变iOS+Android
• Android经典蓝牙
• 华为ScanKit统一扫码插件支持iOS+Android原生插件
• 【华为扫码】统一扫码插件支持多码连续扫码支持半屏扫码uts插件iOS+Android+HarmonyOS
• 截屏、录屏、防截屏、录屏iOS、Android
• 人脸采集插件 最新百度SDK 离线人脸采集、活体检测
• 页面截长图、截取WebView内容，生成长截图Android+iOS
• Android无预览拍照、录制、静默拍照、静默录制、抓拍插件支持
• uni高德地图功能拓展地图截图
• 科大讯飞离线合成插件支持iOS、android
• iOS保活Android保活鸿蒙保活定位插件系统定位
• 高德定位、猎鹰轨迹插件
• 海康威视综合安防平台视频播放插件
• 支持NFC读写功能检测支持Android iOS HarmonyOS
• 自定义相机
• VLC视频播放器-兼容式组件
• VLC视频播放器-标准模式组件
• 桌面小组件
• 海康网络摄像头
• 百度OCR
• 录音pcm播放插件
• 原生离线语音合成原生TTS
• 科大讯飞离线语音合成、识别插件
• 科大讯飞离线语音听写

开发文档

• UTS 语法
• UTS API 插件