更新记录

1.0.1（2026-06-05）

• 棣–娆″‘甯ƒ Android �üš璇�Ÿ�俊�›‘��’浠� 1.0.1�ü
• �”�Œ�üš璇�Š舵ü�›‘��ü�Ÿ�俊�›‘��ü�üš璇璁板�•�ü�Ÿ�俊�ˆ—琛ㄣü�”绯讳汉�üSIM�ü�œ�œ哄风 �ü�‹ㄥ枫ü�Ÿ�俊�ü褰•�Ÿ虫–‡浠舵‰��’Œ�‰�伴üš�Ÿヨ�…�Š┿ü
• 琛ュ……� ‡�‡†�Ÿ哄骇�ü�‡��š涔‰�Ÿ哄骇�ü浜‘�‰“�Œ…�ü�•�„Ÿ�ƒ�™�ü�‰ü�œ‰�–‡浠惰��—�ƒ�™�’Œ甯歌��”�Ž璇存˜Ž�ü

平台兼容性

uni-app(3.97)

uni-app x(3.97)

安卓通话短信监听 UTS 插件

JQ-CallSmsMon-UTS 是一个面向 uni-app / uni-app x 的通话、短信、本地记录辅助插件。Android 端基于系统原生能力实现通话状态监听、短信接收监听、通话记录、短信列表、联系人、SIM 信息、录音文件扫描等能力；iOS、H5、HarmonyOS、小程序提供系统允许范围内的安全降级能力。

插件不包含网络请求、数据上传、统计、广告或云端存储能力，不声明 android.permission.INTERNET 权限。

功能亮点

• Android 原生监听：通话来电、接通、挂断状态实时回调。
• Android 原生短信监听：接收短信后返回号码、内容、时间。
• Android 本机数据读取：通话记录、短信列表、联系人列表。
• Android 电话短信能力：拨号界面、直接拨打、短信界面、静默短信、接听/挂断尝试。
• Android SIM 能力：多卡判断、默认拨号卡、本机号码读取。
• Android 录音辅助：常见录音目录扫描、音频时长读取、文件复制/移动/删除、所有文件访问权限跳转。
• 全端安全降级：非 Android 平台不会伪造监听能力，只返回明确的 unsupported 结果；拨号、用户确认短信、添***人等系统允许能力可继续使用。

平台支持

安装

1. 在 DCloud 插件市场购买并导入插件。
2. HBuilderX 打开项目，确认目录存在：uni_modules/JQ-CallSmsMon-UTS。
3. Android 项目在 manifest.json 中配置业务需要的权限。
4. App 启动后先完成应用隐私弹窗，再调用 requestPermissions 申请运行时权限。

App 端完整真机测试请使用自定义基座或云打包后的测试包。HBuilderX 默认标准基座可能没有声明电话、短信、本机号码等敏感权限，适合验证页面和基础 UTS 调用链路，不适合验证完整监听/读取能力。1.0.1 起文档把 custom base、云打包、敏感权限排查写成固定流程，便于售后直接按步骤定位。

Android 常用权限如下，按业务实际使用能力配置即可：

<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.READ_PHONE_NUMBERS"/>
<uses-permission android:name="android.permission.READ_CALL_LOG"/>
<uses-permission android:name="android.permission.CALL_PHONE"/>
<uses-permission android:name="android.permission.ANSWER_PHONE_CALLS"/>
<uses-permission android:name="android.permission.READ_SMS"/>
<uses-permission android:name="android.permission.RECEIVE_SMS"/>
<uses-permission android:name="android.permission.SEND_SMS"/>
<uses-permission android:name="android.permission.READ_CONTACTS"/>
<uses-permission android:name="android.permission.WRITE_CONTACTS"/>
<uses-permission android:name="android.permission.MANAGE_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE 属于旧版存储权限，部分 DCloud 云打包环境会自动合并，手动重复声明可能导致 manifest 合并失败；确实需要兼容 Android 10 以下录音目录时再按项目情况配置。MANAGE_EXTERNAL_STORAGE 是 Android 11+ 的特殊权限，只用于用户主动选择“所有文件访问权限”后扫描通话录音等本地文件。它不能通过普通运行时权限弹窗授权，必须跳转系统设置页由用户手动打开。如果设置页开关不可点击，通常表示当前标准基座/APK 没有声明该权限，请改用自定义基座或云打包测试包重新安装后验证。该权限属于应用市场敏感权限，请仅在业务确实需要全文件扫描时配置。

自定义基座与云打包

什么时候必须使用自定义基座或云打包？

• 要验证通话监听、短信监听、通话记录、短信列表、本机号码、直接拨打、静默短信等 Android 敏感能力。
• 要验证 MANAGE_EXTERNAL_STORAGE 所有文件访问权限。
• 要让系统安装包真正包含插件声明的 Android 权限。

标准基座能测什么？

• 能测 demo 页面、按钮、基础 UTS 调用链路、安全降级返回。
• 不建议用标准基座判断敏感权限是否可用，因为标准基座可能没有声明电话、短信、本机号码、所有文件访问等权限。

云打包排队怎么处理？

提交云打包后不要频繁刷新。建议前 30 分钟每 10-15 分钟查看一次，超过 30 分钟每 20-30 分钟查看一次。排队期间可以先整理隐私政策、审核备注、客服答复和真机验证表。

云打包提示权限重复怎么办？

如果出现类似 uses-permission#android.permission.WRITE_EXTERNAL_STORAGE duplicated 的 manifest 合并错误，通常是项目手动声明了旧版存储权限，同时 DCloud 或插件合并阶段又生成了一份。优先保留插件默认声明和业务真正需要的敏感权限，删除重复的旧版 READ_EXTERNAL_STORAGE / WRITE_EXTERNAL_STORAGE 手工配置；Android 11+ 扫描录音文件主要看 MANAGE_EXTERNAL_STORAGE。

快速接入

import {
  requestPermissions,
  registerListener,
  registerSmsListener,
  getCallRecords,
  getSmsList,
  makePhoneCall
} from '@/uni_modules/JQ-CallSmsMon-UTS'

requestPermissions({ group: 'all' }, (res) => {
  console.log('权限结果', res)
})

registerListener((event) => {
  console.log('通话事件', event)
})

registerSmsListener((event) => {
  console.log('短信事件', event)
})

const calls = getCallRecords({ limit: 20 })
const sms = getSmsList({ limit: 20 })

makePhoneCall({
  phoneNumber: '10000',
  direct: false
})

返回格式

所有同步方法统一返回：

{
  ok: true,
  code: 0,
  message: 'ok',
  errMsg: 'apiName:ok',
  platform: 'android',
  data: {}
}

非 Android 平台调用 Android 专属能力时返回：

{
  ok: false,
  code: 10001,
  message: '当前平台不开放该能力...',
  platform: 'safe-fallback'
}

权限 API

requestPermissions(options, callback)

申请 Android 运行时权限。

requestPermissions({
  group: 'all'
}, (res) => {
  console.log(res.data.grantedList)
  console.log(res.data.deniedList)
})

group 可选值：

也可以直接传 Android 权限数组：

requestPermissions({
  permissions: [
    'android.permission.READ_PHONE_STATE',
    'android.permission.READ_CALL_LOG'
  ]
}, callback)

checkPermissions(options)

检查权限是否已授予，参数同 requestPermissions。

监听 API

registerListener(callback)

注册通话状态监听。

registerListener((event) => {
  console.log(event.data.state)       // idle / ringing / offhook
  console.log(event.data.phoneNumber) // 部分系统可能不返回来电号码
})

unRegisterListener()

取消通话状态监听。

registerSmsListener(callback)

注册短信接收监听。

registerSmsListener((event) => {
  console.log(event.data.messages)
})

unRegisterSmsListener()

取消短信接收监听。

电话短信 API

makePhoneCall(options)

打开拨号界面或直接拨打。

makePhoneCall({
  phoneNumber: '10000',
  direct: false
})

direct: false 只打开系统拨号界面，通常不需要 CALL_PHONE 权限。direct: true 会使用 Android ACTION_CALL 直接拨打，必须先申请并获得 CALL_PHONE 权限；HBuilderX 标准基座可能没有声明该敏感权限，请使用自定义基座或云打包测试包验证。权限不足时方法会返回 code: 10002，不会直接抛出系统异常。

sendSmsByUserConfirm(options)

打开系统短信界面，由用户确认发送。

sendSmsByUserConfirm({
  phoneNumber: '10000',
  content: 'hello'
})

sendSmsSilently(options)

Android 静默发送短信，需要 SEND_SMS 权限。

sendSmsSilently({
  phoneNumber: '10000',
  content: 'hello',
  simSlot: 0
})

answerCall()

Android 8.0+ 尝试接听来电，需要系统允许和 ANSWER_PHONE_CALLS 权限。

endCall()

Android 9.0+ 尝试挂断电话，需要系统允许和 ANSWER_PHONE_CALLS 权限。

记录与联系人 API

getCallRecords(options)

读取通话记录。

const res = getCallRecords({ limit: 50 })
console.log(res.data.list)

返回字段包含 phoneNumber、name、type、date、duration。

getSmsList(options)

读取短信列表。

const res = getSmsList({
  box: 'inbox',
  limit: 50
})

box 可传 inbox、sent、draft、outbox，不传则读取全部。

getContacts(options)

读取联系人列表。

const res = getContacts({ limit: 200 })

addContact(options)

打开系统新增联系人界面。

addContact({
  name: '测试联系人',
  phoneNumber: '10000'
})

SIM API

isMultiSim()

判断是否多卡。

getDefaultCallSimCard()

读取默认拨号 SIM 信息。

getPhoneNumber(options)

尝试读取本机号码。

const res = getPhoneNumber({ simSlot: 0 })

国内运营商和多数系统不会向三方应用开放本机号码，返回空是常见系统限制。

录音文件 API

scanRecordFiles(options)

扫描常见通话录音目录或自定义目录。

const res = scanRecordFiles({
  dir: '/storage/emulated/0/MIUI/sound_recorder/call_rec',
  limit: 50,
  recursive: true,
  readDuration: true
})

不传 dir 时会扫描常见目录：Record、Recorder、Recordings、CallRecord、Sounds/CallRecord、MIUI/sound_recorder/call_rec 等。

copyFile(options)

复制文件。

copyFile({
  sourcePath: '/storage/emulated/0/Record/a.m4a',
  targetPath: '/storage/emulated/0/Download/a.m4a'
})

moveFile(options)

移动文件。

deleteFile(options)

删除文件。

getAudioDuration(options)

读取音频时长，单位毫秒。

权限页面与前台通知

checkAllFilesPermission()

Android 11+ 检查所有文件访问权限。该权限对应 MANAGE_EXTERNAL_STORAGE，属于系统特殊权限，不能通过 requestPermissions 普通弹窗申请。

toAllFilesPermissionPage()

跳转所有文件访问权限页面。若页面中的“授予所有文件的管理权限”开关不可点击，说明当前 APK 通常未声明 MANAGE_EXTERNAL_STORAGE 或系统限制该应用授权；请使用自定义基座或云打包测试包，并确认 manifest 已包含该权限。

isForegroundPermission()

Android 13+ 检查通知权限。

toForegroundPage()

跳转通知设置页面。

startForeground(options)

显示一个持续通知，辅助用户知道监听处于运行状态。该接口不是偷偷保活能力。

startForeground({
  title: '通话短信监听运行中',
  content: '正在等待系统事件'
})

stopForeground()

关闭持续通知。

真机测试建议

1. 使用自定义基座或云打包测试包运行 example 到 Android 手机。
2. 点击 申请全部权限，同意系统弹窗。
3. 点击 SIM 数量、默认拨号卡、本机号码 检查电信卡识别情况。
4. 点击 通话监听，从另一台手机拨入，观察 ringing、offhook、idle 回调。
5. 点击 短信监听，发送一条短信到当前手机，观察短信回调。
6. 点击 通话记录、短信列表，验证授权后读取结果。
7. 如需通话录音文件，先确认系统已开启通话录音，再点击 扫描录音。

发布前真机验证清单

常见售后答复

权限已经写了，为什么手机上还是不可用？

请确认运行的是自定义基座或云打包后的测试包。HBuilderX 标准基座不一定包含电话、短信、本机号码、所有文件访问等敏感权限，运行时申请不会把未声明的权限临时加进 APK。

本机号码为什么为空？

多数国内运营商、SIM 卡和系统版本不会向三方应用开放本机号码，返回空是正常系统限制，不代表插件失败。建议业务不要强依赖本机号码。

短信监听为什么收不到历史短信？

短信监听只监听新收到的短信；历史短信请调用 getSmsList，并确保已获得短信读取权限。

通话录音为什么扫描不到？

请确认系统已开启通话录音、录音文件实际存在、目录路径正确，并且 Android 11+ 已手动授予所有文件访问权限。部分厂商把录音目录放在私有路径，三方应用可能无法读取。

合规说明

• 插件不包含网络功能，不上传、不保存、不统计用户数据。
• Android 通话记录、短信、联系人、录音文件属于敏感数据，接入方必须先完成隐私政策告知和用户授权。
• 非 Android 平台由于系统限制，不支持电话监听、短信监听、通话记录、短信列表等能力。