更新记录

1.0.5（2026-06-08） 下载此版本

不兼容iOS 鸿蒙 添加空壳

1.0.2（2026-06-05） 下载此版本

• 同步插件名称为 s-phone-listener
• 更新 readme.md 中的安装说明与导入示例
• 同步插件版本号与 Android extVersion

1.0.1（2026-06-05） 下载此版本

修改插件名

平台兼容性

uni-app(5.07)

uni-app x(5.07)

s-phone-listener

Android 电话状态监听 UTS 原生插件（免费）

监听电话状态：来电响铃、去电拨号、接听、挂断（含通话时长）、未接来电。

功能

• 查询 / 申请 READ_PHONE_STATE 权限
• 查询 / 申请 POST_NOTIFICATIONS 权限（Android 13+ 前台服务模式）
• 监听来电响铃 ringing
• 监听去电拨号 dialing
• 监听通话接通 answered
• 监听通话挂断 hangup（附带通话时长）
• 监听未接来电 missed
• 支持前台服务常驻监听，应用退到后台后继续保活监听

平台支持

iOS / Web / 小程序暂不支持。

安装

HBuilderX 中直接导入 s-phone-listener 插件，或：

# 通过 uni_modules 安装
npm install s-phone-listener

使用方法

导入

import {
  hasPhoneStatePermission,
  requestPhoneStatePermission,
  hasPhoneNotificationPermission,
  requestPhoneNotificationPermission,
  openPhonePermissionSettings,
  openPhoneNotificationSettings,
  startPhoneCallListener,
  stopPhoneCallListener
} from '@/uni_modules/s-phone-listener'

完整示例

// 1. 检查电话状态权限
if (!hasPhoneStatePermission()) {
  // 2. 申请电话状态权限
  requestPhoneStatePermission((granted) => {
    if (!granted) {
      // 引导用户去系统设置开启电话状态权限
      openPhonePermissionSettings()
      return
    }
    ensureNotificationPermissionAndStart()
  })
} else {
  ensureNotificationPermissionAndStart()
}

function ensureNotificationPermissionAndStart() {
  if (hasPhoneNotificationPermission()) {
    startListening()
    return
  }

  requestPhoneNotificationPermission((granted) => {
    if (!granted) {
      openPhoneNotificationSettings()
      return
    }
    startListening()
  })
}

function startListening() {
  startPhoneCallListener((event) => {
    switch (event.type) {
      case 'ringing':
        console.log('来电响铃:', event.phoneNumber)
        break
      case 'dialing':
        console.log('去电拨号:', event.phoneNumber)
        break
      case 'answered':
        console.log('通话接通:', event.phoneNumber)
        break
      case 'hangup':
        console.log(
          '通话结束:',
          event.phoneNumber,
          '方向:', event.direction,  // 'incoming' | 'outgoing'
          '时长:', event.duration, '秒',
          '时间:', new Date(event.timestamp).toLocaleString()
        )
        break
      case 'missed':
        console.log('未接来电:', event.phoneNumber)
        break
    }
  }, {
    useForegroundService: true,
    notificationTitle: '电话状态监听',
    notificationText: '正在后台监听通话状态'
  })
}

// 页面卸载时停止监听
onUnload(() => {
  stopPhoneCallListener()
})

事件参数

启动选项

API 说明

权限说明

插件已内置以下权限声明：

<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

其中 POST_NOTIFICATIONS 仅在 Android 13+ 且使用前台服务模式时需要用户授权。

注意事项

1. Android 10+ 电话号码为空：系统出于隐私保护，onCallStateChanged 回调中的电话号码可能为空。去电号码当前版本暂未捕获（需要 PROCESS_OUTGOING_CALLS 权限，Android 14 已弃用）。
2. 主动挂断 vs 对方挂断：Android 公共 API 无法区分是本机挂断还是对方挂断。
3. @UTSJS.keepAlive：插件已配置回调保活注解，确保监听不会被 GC 回收。
4. 前台服务模式：如果希望应用退到后台后继续监听，调用 startPhoneCallListener 时请传 { useForegroundService: true }，并确保 Android 13+ 已授予通知权限。
5. 标准基座提示：插件依赖原生配置（AndroidManifest.xml、前台服务声明），首次使用标准基座运行时会提示「原生配置不能生效」，不影响功能。如需完全生效可制作自定义调试基座。
6. 后台限制：Android 14+ 对后台应用获取电话状态有更严格限制，前台服务可以提升稳定性，但无法保证所有 ROM 都 100% 不丢回调。
7. 高版本兼容策略：Android 12+ 优先使用 TelephonyCallback，Android 12 以下回退到 PhoneStateListener。

已知限制

• Android 12+ 已切换为 TelephonyCallback，Android 12 以下继续使用 PhoneStateListener
• Android 13+ 若未授予通知权限，则前台服务常驻监听模式无法启动
• 小米/MIUI 等定制系统可能因省电策略延迟或阻止状态回调，建议在真机前台测试

开源协议

MIT