更新记录

1.0.0（2026-10-23）

初始版本

• 电话/短信/通话录音/通讯录全套能力，统一为 zy-call UTS 插件
• 权限：申请权限、检查/跳转所有文件访问权限
• 通话录音：检测是否开启自动录音、跳转自动录音设置页、获取全部录音文件、按条件搜索录音文件、自定义录音目录
• 通话监听：注册/取消监听、挂断、接听、当前通话状态、是否已注册；挂断后自动返回录音文件路径与时长
• 通话记录：获取全部记录、按条件查询、指定卡槽拨打电话
• 短信：注册/取消监听、静默发送（支持指定 subId）、获取短信列表
• 设备信息：是否双卡、获取手机号码、默认通话卡槽、机型适配判断
• 文件操作：移动、复制、删除文件或目录、获取音频时长
• 通讯录：获取通讯录、添***人
• 前台服务：通知权限检查与跳转、开启/关闭前台通知服务
• 配置：setConfig 设置挂断后搜索录音文件的延迟时间

平台兼容性

uni-app(4.72)

uni-app x(4.72)

其他

插件介绍

安卓电话通话短信监听 UTS 插件（zy-call），支持获取所有录音文件、来电监听、去电监听、挂断电话后返回通话录音文件、短信监听与静默发送、通话记录、通讯录、获取手机号码、前台通知保活等功能。

平台支持：仅 Android（uni-app app-vue / app-nvue、uni-app x app-android），iOS 无对应系统能力。

接口风格：所有方法统一为 options 单对象入参，回调通过对象属性承载：

methodName({
    // 业务参数……
    success ?: (res : XxxResult) => void   // 成功回调
    fail ?: (err : ZyCallFail) => void     // 失败回调（UniError 规范）
    complete ?: (res : any) => void        // 完成回调（成功/失败都会触发）
    onEvent ?: (res : XxxEvent) => void    // 仅监听注册类方法，持续回调
})

失败回调 err 为 UniError 对象：err.errSubject = 'zy-call'、err.errCode（见下方错误码表）、err.errMsg（具体原因，如缺少的权限名）。

权限说明

插件所需权限

requestPermission 缺省会按系统版本动态裁剪后申请上表全部运行时权限；MANAGE_EXTERNAL_STORAGE 为特殊权限，需用 toAllFilesPermissionPage 跳转设置页授予。

权限被永久拒绝怎么办

Android 运行时权限规则：权限一旦被用户永久拒绝（勾选过“不再询问”，或部分 OEM ROM 首次拒绝即视为永久拒绝，或累计拒绝达到上限），requestPermissions 不再弹系统框、直接静默拒绝。此时 requestPermission / checkPermissionState 会把这些权限放入返回值的 permanentlyDenied 列表中，需调用 toAppSettingsPage 跳转应用详情设置页引导用户手动开启，返回页面后调用 checkPermissionState 刷新状态。

import { requestPermission, checkPermissionState, toAppSettingsPage } from '@/uni_modules/zy-call'

export default {
    onShow() {
        // 页面显示时刷新（从系统设置页返回也会触发）
        checkPermissionState({
            success: (res) => {
                if (!res.allGranted && res.permanentlyDenied.length > 0) {
                    toAppSettingsPage({}) // 引导用户去设置页手动开启
                }
            }
        })
    },
    methods: {
        applyPermission() {
            requestPermission({
                success: (res) => {
                    console.log('授予情况', res.list, '全部授予', res.allGranted)
                    if (res.permanentlyDenied.length > 0) {
                        uni.showToast({ title: '部分权限被永久拒绝，请去设置页开启', icon: 'none' })
                    }
                },
                fail: (err) => console.error('申请失败', err.errCode, err.errMsg)
            })
        }
    }
}

使用注意事项

• 涉及大量危险权限（电话、短信、通讯录、存储），建议真机测试；模拟器无 SIM 卡时拨号/短信/手机号相关能力不可用。
• 建议配合保活方案使用：本插件内置前台通知服务 startForeground（Android 8+ 后台启动受限时会自动回退为普通服务），退到后台仍可监听来电/短信；同时建议把应用加入系统省电白名单。
• 各厂商对通话录音目录的路径不统一，插件已内置 15 个厂商的常见目录探测；目录不在预期位置时用 setCustomAudioRecorderDir 指定。
• 所有方法均为异步；阻塞型操作（文件枚举、短信/通讯录查询）在子线程执行，回调切回主线程。

快速开始

1. 在 HBuilderX 中把插件导入项目（uni_modules 方式），或直接从插件市场选择「zy-call」导入。
2. 页面中引入：

import { registerCallListener } from '@/uni_modules/zy-call'
// 或
import * as zyCall from '@/uni_modules/zy-call'

3. 最小可用示例（注册通话监听，挂断后拿录音文件）：

import { requestPermission, registerCallListener } from '@/uni_modules/zy-call'

export default {
    onLoad() {
        requestPermission({}) // 先申请权限
        registerCallListener({
            onEvent: (e) => {
                if (e.status === 3) {
                    console.log('挂断，录音文件:', e.audioPath, '时长:', e.duration)
                } else {
                    console.log('通话事件:', e.status, e.phoneNumber)
                }
            },
            success: (res) => console.log('注册成功'),
            fail: (err) => console.error('注册失败', err.errCode, err.errMsg)
        })
    },
    onUnload() {
        unregisterCallListener({}) // 页面卸载时取消，避免回调泄漏
    }
}

错误码表

API 详解

一、权限

requestPermission(options)

申请权限（批量运行时权限）。对未授予的权限发起系统授权弹窗；已被永久拒绝的权限不再弹框，通过 permanentlyDenied 返回。

success 返回：

注意：UTS 插件无法可靠接收 onRequestPermissionsResult，success 返回的是弹窗前状态。用户授权后请重新调用 requestPermission 或 checkPermissionState 确认。

checkPermissionState(options)

只查询权限状态，不发起授权弹窗。参数同 requestPermission（permissions 可缺省），返回结构完全一致。适合页面 onShow 时刷新（如从设置页返回后）。

checkAllFilesPermission(options)

检查是否有「所有文件」访问权限（Android 11+ 读取公共目录录音文件需要）。

success 返回：{ status: boolean }

toAllFilesPermissionPage(options)

跳转到「所有文件」访问权限页面。无参数。

toAppSettingsPage(options)

跳转应用详情设置页，引导用户手动开启被永久拒绝的运行时权限。无参数。

二、通话录音

checkCallAutoRecorder(options)

检测当前机型是否开启了「通话自动录音」（系统设置项，各厂商 key 不同，已内置 15 个厂商的探测逻辑）。

success 返回：{ isOpen: boolean }

关闭自动录音时，挂断事件可能拿不到录音文件（status 为 4/5）。

toCallAutoRecorderPage(options)

按机型跳转到对应的「通话自动录音」设置页（华为/小米/OPPO/vivo/三星走各自设置组件，其余机型跳拨号界面）。无参数。

getAllRecorderFiles(options)

获取当前机型通话录音目录下的全部文件（按最后修改时间倒序，不递归子目录）。

success 返回：{ files: ZyCallRecorderFile[] }

getRecorderFiles(options)

按条件搜索录音文件。

success 返回：{ files: ZyCallRecorderFile[] }（结构同上）

setCustomAudioRecorderDir(options)

自定义录音文件目录。设置后 getAllRecorderFiles / getRecorderFiles / 挂断取录音均从该目录查找。

三、通话监听

registerCallListener(options)

注册通话监听。注册结果走 success/fail（一次性）；通话事件走 onEvent（持续回调）。

ZyCallEvent 字段：

status 取值：

挂断事件内部延迟 delayTime（默认 2000ms，可用 setConfig 调整）后再搜索录音文件，等待厂商录音落盘。

unregisterCallListener(options)

取消通话监听。无参数。

endCall(options)

挂断当前通话（需先注册通话监听）。API 28+ 用 TelecomManager，以下用反射 getITelephony。无参数。

answerRingingCall(options)

接听来电（需先注册通话监听，Android 8.0+）。无参数。

getCallState(options)

获取当前通话状态。success 返回：{ state: number }（0 空闲 / 1 响铃 / 2 通话中）

isRegisterCallListener(options)

判断是否已注册电话监听。success 返回：{ isRegisterListener: boolean }

四、通话记录

getAllCalls(options)

获取全部通话记录（按时间倒序）。无参数。

success 返回：{ list: ZyCallCallRecord[] }

getCalls(options)

按条件查询通话记录（各条件均可选，组合为 AND）。

success 返回：{ list: ZyCallCallRecord[] }

callPhone(options)

拨打电话。

五、短信

registerSmsListener(options)

注册短信监听。注册结果走 success/fail；收到短信走 onEvent（持续回调）。

unregisterSmsListener(options)

取消短信监听。无参数。

sendSmsHide(options)

静默发送短信（无界面，自动处理长短信分段，发送/送达状态通过 success/fail 回调）。

success 表示已提交发送；送达结果会再次以 success 回调或 fail（9031012 未送达）返回。

getSmsList(options)

获取短信列表（按时间倒序）。

success 返回：{ list: ZyCallSms[] }

六、设备信息

isMultiSim(options)

是否是双卡。success 返回：{ isMultiSim: boolean }

getPhoneNumber(options)

获取各卡槽手机号码（需要 READ_PHONE_STATE + READ_PHONE_NUMBERS；部分机型/运营商返回空号）。

success 返回：{ numbers: ZyCallSimInfo[] }

getDefaultCallSimCard(options)

获取通话/短信的默认卡槽信息（Android 7.0+）。success 返回：{ defaultSim: ZyCallSimInfo }（字段同上）

isAdaptPhone(options)

判断当前机型是否在支持的厂商列表中。success 返回：{ status: boolean, settings: string[] }（settings 为系统设置中与录音/通话相关的 key:value 列表，辅助排查）

七、文件操作

moveFile(options)

移动文件（先复制后删除源文件）。

copyFile(options)

复制文件。参数同 moveFile。

deleteFile(options)

删除文件或目录（目录递归删除）。

getAudioDuration(options)

获取音频时长。

success 返回：{ duration: number }（毫秒）

八、通讯录

getContacts(options)

获取手机通讯录（按姓名排序）。

success 返回：{ list: ZyCallContact[] }，元素为 { name: string, phoneNumber: string }

addContact(options)

添加通讯录。

九、前台服务

isForegroundPermission(options)

是否有前台通知权限（Android 13+ 还需 POST_NOTIFICATIONS 运行时权限）。success 返回：{ status: boolean }

toForegroundPage(options)

跳转到通知权限页面。无参数。

startForeground(options)

开启前台通知服务（保活，建议监听来电/短信期间保持开启）。

stopForeground(options)

关闭前台通知服务。无参数。

十、其他配置

setConfig(options)

配置自定义数据。

完整场景示例

来电监听 + 挂断自动取录音：

import {
    requestPermission,
    registerCallListener,
    unregisterCallListener,
    startForeground,
    setConfig
} from '@/uni_modules/zy-call'

export default {
    onLoad() {
        startForeground({ title: '通话监听中', content: '正在监听来电与短信' }) // 保活
        setConfig({ delayTime: 3000 }) // 挂断后等 3 秒再找录音文件
        this.applyPermissionAndListen()
    },
    methods: {
        applyPermissionAndListen() {
            requestPermission({
                success: (res) => {
                    if (!res.allGranted) {
                        uni.showToast({ title: '请先授予全部权限', icon: 'none' })
                        return
                    }
                    this.startListen()
                },
                fail: (err) => console.error('权限申请失败', err.errCode, err.errMsg)
            })
        },
        startListen() {
            registerCallListener({
                onEvent: (e) => {
                    if (e.status === 1) {
                        console.log('来电响铃', e.phoneNumber)
                    } else if (e.status === 2) {
                        console.log('通话中', e.phoneNumber)
                    } else if (e.status === 3) {
                        console.log('挂断，录音文件', e.audioPath, '时长', e.duration)
                        // 拿到 e.audioPath 后可播放、上传或移动到自己的目录
                    } else {
                        console.log('挂断，未拿到录音，status =', e.status, '目录', e.recorderDirPath)
                    }
                },
                success: (res) => console.log('监听注册成功'),
                fail: (err) => console.error('监听注册失败', err.errCode, err.errMsg)
            })
        }
    },
    onUnload() {
        unregisterCallListener({})
    }
}

各厂商录音目录说明

插件按 Build.MANUFACTURER 自动探测以下目录（子目录不递归，按顺序取第一个存在的）：

不在上述目录时，用 setCustomAudioRecorderDir 指定实际目录。isAdaptPhone 可判断当前机型是否在支持列表。

常见问题

Q1：点了申请权限，有些权限不弹框？ 这些权限已被永久拒绝（勾选过“不再询问”或 OEM ROM 策略）。用 toAppSettingsPage 跳转设置页手动开启，返回后 checkPermissionState 刷新。

Q2：挂断后 status 是 4/5，拿不到录音文件？ 依次检查：① checkCallAutoRecorder 确认系统「通话自动录音」已开启；② 录音目录是否在预期位置（不在则 setCustomAudioRecorderDir）；③ 部分机型落盘慢，setConfig({ delayTime: 5000 }) 调大延迟；④ 未接通（响铃即挂）本身不会产生录音（status 5）。

Q3：双卡手机怎么指定卡拨号/发短信？ 拨号用 callPhone({ number, slot: 2 })（slot 1/2）；静默发短信的 subId 通过 getPhoneNumber 或 getDefaultCallSimCard 获取。

Q4：getPhoneNumber 返回空号？ 本机号码依赖运营商写入 SIM 卡（EF_MSISDN），部分 SIM 卡未写入时任何方式都取不到，与插件无关。

Q5：退到后台收不到来电/短信广播？ 开启 startForeground 前台通知保活，并把应用加入系统省电白名单（各厂商设置路径不同）。

Q6：Android 8+ 提示无法启动前台服务？ 插件已做兼容：startForegroundService 在后台启动受限时自动回退为 startService；仍失败时通过 fail 回调返回错误，请确保从前台页面调用。

权限声明（Manifest 合并）

插件 utssdk/app-android/AndroidManifest.xml 声明以下权限，会与宿主应用合并：