更新记录
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 |
已有通话记录权限申请正在进行 |

收藏人数:
购买源码授权版(
试用
赞赏(0)
下载 208
赞赏 0
下载 12775000
赞赏 1960
赞赏
京公网安备:11010802035340号