更新记录

2.0.1（2026-06-07）

-修复小米和一些低版本设备，监听电话状态需要【读取通话记录】权限的bug

2.0.0（2026-06-05）

• 回调 KeepAlive 修复：解决 HBuilderX 4.25+ UTS 运行时回调首次执行后自动释放问题
  • 新增 onRing / onDialing / onConnected / onDisconnected / onError 等 onXxx 接口
  • 改用 onRing(cb) + registerPhoneListener(null) 模式替代传复合对象
  • onXxx 函数名以 on 开头自动 keepalive（UTSCallback 桥接，与 XRay 一致）
• 回调去重防抖：来电空号码跳过、同号码 1.5s 防抖、接通/挂断单次触发
• 事件历史 API：新增 getCallHistoryEvents / getSmsHistoryEvents / clearXxxHistoryEvents

1.0.0（2026-05-21）

• 初始发布
• Android 电话通话监听（来电、去电、挂断）
• 获取通话录音文件（全部/条件搜索/音频时长）
• 获取通话记录（全部/条件筛选）
• 拨打电话、挂断电话、接听电话
• 短信监听、取消监听
• 静默发送短信、获取短信列表
• 获取手机通讯录、添加通讯录
• 检测/跳转通话自动录音设置
• 文件操作（复制/移动/删除）
• 双卡检测、获取本机号码
• 所有文件访问权限检测/跳转
• 前台通知服务（启动/停止/权限管理）
• 设备适配检测

平台兼容性

uni-app(4.18)

uni-app x(4.18)

ly028-PhoneTracker

安卓电话通话短信监听原生插件

点击下载体验

扫码体验

功能列表

电话通话监听

• ✅ 注册/取消电话监听（来电/去电/挂断）
• ✅ 获取通话记录（全部/条件筛选）
• ✅ 拨打电话 / 挂断电话 / 接听电话
• ✅ 获取当前通话状态

录音文件

• ✅ 获取所有录音文件
• ✅ 条件搜索录音文件
• ✅ 获取音频时长
• ✅ 检测/跳转通话自动录音设置

短信

• ✅ 注册/取消短信监听
• ✅ 静默发送短信
• ✅ 获取短信列表（收件箱/已发送等）

通讯录

• ✅ 获取手机通讯录
• ✅ 添***人

设备信息

• ✅ 双卡检测
• ✅ 获取本机号码
• ✅ 设备适配检测

文件操作

• ✅ 复制/移动/删除文件或目录

权限管理

• ✅ 所有文件访问权限检测/跳转
• ✅ 通知权限检测/跳转

前台通知服务

• ✅ 启动/停止前台通知服务

快速开始

npm install
# 或直接在 HBuilderX 中导入插件

使用方法

导入

import {
  // 电话监听回调（on 前缀 auto keepalive，推荐用法）
  onRing, onDialing, onConnected, onDisconnected, onError,
  // 电话监听
  registerPhoneListener, unregisterPhoneListener, isPhoneListenerRegistered, getCallState,
  // 电话监听事件历史
  getCallHistoryEvents, clearCallHistoryEvents,
  // 通话记录（同步）
  getCallRecords, getCallRecordsByCondition,
  // 通话记录（异步，不阻塞 UI）
  getCallRecordsAsync,
  // 通话控制
  makeCall, hangupCall, answerCall,
  // 录音文件（同步）
  getAllAudioRecords, searchAudioRecords, getAudioDuration,
  // 录音文件（异步）
  getAllAudioRecordsAsync,
  // 短信回调（on 前缀 auto keepalive）
  onSmsReceived, onSmsError,
  // 短信监听
  registerSmsListener, unregisterSmsListener,
  // 短信（同步）
  getSmsList, sendSmsSilently,
  // 短信（异步）
  getSmsListAsync,
  // 短信监听事件历史
  getSmsHistoryEvents, clearSmsHistoryEvents,
  // 通讯录（同步）
  getContacts, addContact,
  // 通讯录（异步）
  getContactsAsync,
  // 设备信息
  isDualSim, getPhoneNumber, isDeviceAdapted, isXiaomiDevice,
  openPhonePermissionSettings,
  // 文件操作
  copyFile, moveFile, deleteFile,
  // 权限
  requestPermission, setPermissionCallback, hasAllFilesAccess,
  openAllFilesAccessSettings, hasForegroundNotificationPermission,
  openNotificationPermissionSettings,
  // 前台服务
  startForegroundNotificationService, stopForegroundNotificationService,
  // 默认短信应用
  isDefaultSmsApp, openDefaultSmsAppSettings,
  // 调试
  setDebugMode,
  // 平台能力
  getCapabilities,
} from '@/uni_modules/ly028-PhoneTracker'

电话监听

⚠️ 重要：必须使用 onXxx 逐个注册回调，禁止传复合对象！ 传 registerPhoneListener({onRing:...}) 复合对象会导致子回调在首次执行后被 UTS 运行时释放（只触发一次）。 onXxx 函数名以 on 开头，UTS 运行时自动保持回调持续存活。与 XRay 的 onTraffic(cb) 模式一致。

💡 辅助功能 & 权限说明：

• 辅助功能（无障碍服务）：监听来电/去电/接通/挂断等通话状态事件需开启
• 读取通话记录（READ_CALL_LOG）：Android 9+ 必需，用于获取来电/去电的真实号码
• 注意：部分设备上，接通/挂断事件的检测以及获取来/去电真实号码也依赖此权限，否则可能无法获取到号码或事件不触发

// ✅ 正确用法：先逐个注册回调（on 前缀 auto keepalive），再启动监听
onRing((number) => console.log('来电:', number))
onDialing((number) => console.log('去电:', number))
onConnected((number) => console.log('接通:', number))
onDisconnected((phoneNumber, duration, type, recordFilePath, endTime) => {
  console.log('挂断:', phoneNumber, '时长:', duration + 's')
  if (recordFilePath) console.log('录音文件:', recordFilePath)
})
onError((err) => console.log('监听错误:', err))

// 注册电话监听（传 null 表示回调已通过 onXxx 注册）
const result = registerPhoneListener(null)

// ❌ 错误用法（回调只触发一次）：
// registerPhoneListener({
//   onRing: (number) => console.log('来电:', number),
//   onDialing: (number) => console.log('去电:', number),
//   ...
// })

通话记录

同步方式（可能阻塞 UI）

const records = JSON.parse(getCallRecords(100, 0))
console.log('通话记录:', records.length, '条')

异步方式（推荐，不阻塞 UI）

getCallRecordsAsync(50, 0, {
  onSuccess: (raw) => {
    const records = JSON.parse(raw)
    console.log('获取成功:', records.length, '条')
  },
  onError: (err) => {
    console.log('获取失败:', err)
  }
})

录音文件

同步方式

const records = JSON.parse(getAllAudioRecords())

异步方式（推荐）

getAllAudioRecordsAsync({
  onSuccess: (raw) => {
    const records = JSON.parse(raw)
    console.log('录音文件:', records.length, '个')
  },
  onError: (err) => console.log('获取失败:', err)
})

短信

短信监听（onXxx 模式，回调持续存活）

// ✅ 先逐个注册回调（on 前缀 auto keepalive）
onSmsReceived((smsJson) => {
  const sms = JSON.parse(smsJson)
  console.log('新短信:', sms.address, sms.body)
})
onSmsError((err) => console.log('短信错误:', err))

// 再启动监听（传 null 表示回调已注册）
registerSmsListener(null)

同步方式

const smsList = JSON.parse(getSmsList({ type: 'inbox', limit: 20 }))

异步方式（推荐，避免 ContentProvider 查询阻塞 UI）

getSmsListAsync({ type: 'inbox', limit: 20 }, {
  onSuccess: (raw) => {
    const list = JSON.parse(raw)
    console.log('短信列表:', list.length, '条')
  },
  onError: (err) => console.log('获取失败:', err)
})

通讯录

同步方式

const contacts = JSON.parse(getContacts())

异步方式（推荐，通讯录查询较慢）

getContactsAsync({
  onSuccess: (raw) => {
    const contacts = JSON.parse(raw)
    console.log('通讯录:', contacts.length, '个联系人')
  },
  onError: (err) => console.log('获取失败:', err)
})

权限请求

// 请求单个权限，结果通过回调返回
requestPermission('android.permission.READ_CONTACTS', (granted) => {
  if (granted) {
    console.log('权限已授予')
    // 继续后续操作
  }
})

// 设置全局权限结果监听
setPermissionCallback((permission, granted) => {
  console.log('权限结果:', permission, granted)
})

// 跳转应用权限设置页
openApplicationSettings()

调试模式

// 开启调试日志（Info/Debug 级别日志输出到 Logcat）
setDebugMode(true)

// 关闭调试日志（仅 Error/Warn 级别日志）
setDebugMode(false)

权限说明

版本要求

• Android: API 21+
• HBuilderX: ^4.18（低于此版本云打包会报 String? / Any 类型错误）
• uni-app: ^3.7.7
• uni-app-x: ^4.18

版本更新

v2.1.0 (2026-06)

v2.0.0 (2026-06)

常见问题

云打包报错 Argument type mismatch: actual type is 'String?', but 'Any' was expected

原因： HBuilderX 版本低于 4.18，UTS 编译器将 any 映射为 Kotlin 非空类型 Any，导致 toMap() 生成的 Map<string, any> 不接受 String? 等可空字段。

解决： 升级 HBuilderX 到 4.18 或更高版本。

云打包报错 FAILURE: Build failed with an exception，无具体错误信息

解决： 打开 HBuilderX 的 控制台 → 查看详细构建日志，或勾选 "导出日志" 重新打包，获取完整错误堆栈后再排查。

插件方法调用没反应 / 返回 false

常见原因：

1. 权限未授予 — 插件功能需要动态权限（电话、短信、通知等），需先调用对应权限申请
2. Android 11+ 分区存储 — 文件相关功能需先申请 MANAGE_EXTERNAL_STORAGE 权限
3. 监听未注册成功 — registerPhoneListener / registerSmsListener 返回 false 表示注册失败，检查是否已在 Android 授权管理中授予权限

通话录音获取不到文件

• 确认手机支持并已开启 "通话自动录音" 功能（部分 ROM 需在电话设置中手动开启）
• 录音文件可能存储在外部存储，需要 MANAGE_EXTERNAL_STORAGE 权限（Android 11+）
• 部分厂商系统对录音文件有访问限制

静默发送短信不成功

• Android 4.4+ 默认短信应用限制：非默认短信应用无法静默发送。可通过 isDefaultSmsApp() 检测，openDefaultSmsAppSettings() 引导用户设置
• 部分厂商系统限制了后台发送短信的能力

Android 14（API 34）兼容

• PROCESS_OUTGOING_CALLS 权限在 Android 14 中已废弃，去电监听改用 READ_PHONE_STATE + 通知监听
• READ_SMS 在 Android 14 中需要动态申请
• 前台服务需声明 FOREGROUND_SERVICE_SPECIAL_USE 类型（已包含在插件 manifest 中）

离线打包找不到 utsplugin-release.aar

解决： 确认 HBuilderX 安装目录下 SDK/Android/ 包含 utsplugin-release.aar，并在项目的 build.gradle 中正确引用。需要与当前 HBuilderX 版本对应的 SDK 包。

白屏 / 闪退

• 确认 HBuilderX 版本与本地打包 SDK 版本一致
• 离线打包时确认 appid（__UNI__871F2B2）与 HBuilderX 生成资源的 appid 一致
• 检查 AndroidManifest.xml 中是否有冲突的组件声明

点击下载体验

扫码体验