更新记录

0.3.0(2026-11-19)

  • 新增通话记录查询,支持号码片段、时间范围和分页。
  • 新增系统录音目录选择、文件列表和文件名搜索,覆盖所选目录及子目录。
  • 示例页新增条件弹窗和分页入口,查询成功、空结果及异常都写入底部日志。
  • 补充通话记录权限及目录授权说明。

平台兼容性

uni-app x(5.08)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × 5.0 × × ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

zhuanz-phonekit

Android UTS API 插件,提供前台蜂窝通话状态、通话记录查询、录音目录列表与搜索,以及系统拨号、短信编辑、联系人号码选择和录音试听入口。

将此目录复制到宿主的 uni_modules/zhuanz-phonekit。首版提供 uni-app x Android 示例,最低目标版本 Android 5.0(API 21),开发工具 HBuilderX 5.08 起。导入与调用放在 APP-ANDROID 条件编译范围内。

import { ref } from 'vue'
import { onUnload } from '@dcloudio/uni-app'
import { startCallStateMonitor, stopCallStateMonitor } from '@/uni_modules/zhuanz-phonekit'

const callState = ref('unknown')

// 绑定到页面的「开始监听」按钮。
function startMonitor(): void {
  startCallStateMonitor((event) => {
    if (event.type == 'state') callState.value = event.state
    if (event.type == 'stopped') callState.value = 'unknown'
    if (event.type == 'error') uni.showToast({ title: event.errMsg, icon: 'none' })
  })
}

onUnload(() => stopCallStateMonitor())
API 行为
startCallStateMonitor(callback) 如有需要,先发起电话权限申请。回调产生 started、state、stopped 或 error 事件。同一进程只允许一个会话,重复启动会报告忙碌
stopCallStateMonitor() 取消等待授权的监听或注销现有监听,并向该会话发出 stopped。空闲时可直接调用
getCallState(callback) 一次查询,需已授权电话权限。返回当前 state 和 timestamp
openDialer(number, callback) 打开系统拨号页并预填号码,拨号由用户确认
openSmsComposer(number, body, callback) 打开系统短信页,尝试预填号码和正文,发送由用户确认
pickContactPhone(callback) 打开系统联系人号码选择器。返回单个 number 以及结果码
pickAudioRecording(callback) 打开系统音频文件选择器。返回 uri、name、mimeType、sizeBytes 和 durationMs
openAudioRecording(uri, mimeType, callback) 将刚选中的录音交给设备上的音频播放器
queryCallHistory(options, callback) 查询系统通话记录,按时间倒序分页返回
pickRecordingFolder(callback) 打开系统目录选择器,返回所选目录的 uri 和 name
queryRecordingFiles(folderUri, options, callback) 列出授权目录及子目录的音频,支持按文件名搜索和分页

状态与生命周期

监听事件统一包括 type、state、timestamp、errCode 和 errMsg。时间戳为毫秒。仅 state 事件携带实时系统状态,其他监听事件的 state 为 unknown。

  • idle 表示空闲。
  • ringing 表示振铃或来电等待。
  • offhook 表示拨号、通话或保持。
  • unknown 表示当前结果无可用状态。

Android Activity 停止或销毁时,插件结束会话。宿主页面隐藏或销毁时也应调用 stopCallStateMonitor(),用于多个页面共享 Activity 的情况。回到页面后应由用户再次点击启动。默认订阅监听和一次查询的来源在旧系统存在差异,详见工程分析。

拨号和短信支持 1–20 位数字及可选 +,输入可含空格、括号、连字符。动作成功代表系统已接收打开请求,用户在系统应用里完成后续操作。部分短信客户端对预填内容的支持有差异。 Android 通用 Intent

联系人与录音

两种选择器一次可打开一个。联系人接口仅查询用户选择的那条号码。音频接口使用系统授予的 content:// URI 读取所选文件,大小和时长无法取得时为 -1。系统授权失效后需要重新选择。试听依赖设备上能处理该音频格式的应用。 Android 联系人选择 · Android 系统文件选择

选择成功后,可用 result.name、result.durationMs 和 result.sizeBytes 更新页面。用户点击试听时,将 result.uri 和 result.mimeType 传给 openAudioRecording。

查询通话记录

queryCallHistory 的筛选项均可省略。numberKeyword 使用号码子串,fromMs 为包含的下界,beforeMs 为排除的上界,单位为 Unix 毫秒时间戳。缺省时间范围内返回最近记录。offset 从 0 起,limit 默认 20,支持 1–100。用 hasMore 判断是否有下一页。结果 items 包括 number、type、timestamp 和 durationSeconds。系统隐藏的号码返回空字符串。

import { queryCallHistory } from '@/uni_modules/zhuanz-phonekit'

queryCallHistory({ numberKeyword: '010', fromMs: Date.now() - 7 * 86400000, limit: 20 }, (result) => {
  if (result.errCode == 0) {
    // 将 result.items 和 result.hasMore 绑定到界面。
  }
})

启用通话记录功能的宿主在 Android 清单中按需声明 android.permission.READ_CALL_LOG,并为 Android 调试生成包含该权限的自定义基座。插件在发起查询时检查权限并按需请求。该权限受系统硬限制和发行渠道政策约束,请按应用实际用途核对许可。 DCloud Android 权限配置 · Android READ_CALL_LOG · Google Play 权限规则

录音目录列表和搜索

使用 pickRecordingFolder 获取目录 URI,再传给 queryRecordingFiles。keyword 为空时列举音频,填入关键词时按文件名忽略大小写匹配。offset 和 limit 与通话记录查询一致。结果按修改时间倒序返回,含 uri、name、relativePath、mimeType、sizeBytes 和 modifiedAt。大小未知时为 -1,修改时间未知时为 0。可将条目的 uri 和 mimeType 交给 openAudioRecording。

插件以系统授权的目录树为范围,一次遍历最多 256 个目录和 10,000 个条目。scanLimited 为真时,total 是已扫描范围内的匹配数。大目录可选择更具体的子目录搜索。授权依赖系统当前会话,失效后重新选择目录。Android 11 起系统限制部分位置的目录访问。 Android 目录选择与限制

权限与结果

系统清单声明 READ_PHONE_STATE,首次点击开始监听且尚未授权时发起授权请求。联系人和录音选择依赖 Android 系统为所选条目授予访问权限,拨号和短信入口可独立使用。

errCode 含义
0 成功
1001 Android Activity 或应用上下文不可用
1002 设备缺少蜂窝电话能力
1003 电话权限未授予
1004 已有监听或电话授权请求
1005 没有可以处理当前操作的系统应用
1006 号码格式无效
1007 Android 系统调用失败
1008 用户取消选择,或承载选择器的 Activity 已销毁
1009 无法读取选中的条目,或录音的 URI 访问权已失效
1010 已有系统选择器正在使用
1011 当前宿主或调试基座未声明通话记录权限
1012 查询条件无效
1013 已有通话记录权限申请正在进行

隐私、权限声明

1. 本插件需要申请的系统权限列表:

READ_PHONE_STATE 用于通话状态;READ_CALL_LOG 由启用通话记录功能的合规宿主按需声明并在查询时申请;录音目录和联系人号码由系统选择器授予访问。

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

通话状态、用户请求查询的通话记录、所选联系人号码和录音文件信息通过本地回调交给宿主。拨号号码、短信内容和所选录音由用户操作交给对应的 Android 应用。插件无网络传输和持久化。

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。