uni-app 拨打电话 API 全解析uni.makePhoneCall 跨端实现原理与实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app本篇技术指南以 uni-app 开源仓库的 API 文档 docs/api/make-phone-call.md 为核心系统讲解uni.makePhoneCall拨打电话接口的参数规范、错误码体系与平台差异并结合仓库内 UTS 插件源码Android/iOS/HarmonyOS 三端实现深入剖析其底层调用链与号码校验规则。读者学完后将能正确使用该 API 完成拨打电话功能、精确处理三类失败场景并理解跨端框架如何用同一套 TypeScript 风格代码对接各平台原生电话能力。一、接口概览一段代码打通全平台拨号能力uni.makePhoneCall(options)是 uni-app 提供的拨打电话能力接口属于设备/系统能力类 API。在 uni-app 的跨端架构下开发者只需编写一次调用代码即可在 Web、微信小程序、Android、iOS、HarmonyOS 等多个平台唤起系统拨号界面。该接口在仓库中的 UTS 类型声明位于 src/uni_modules/uni-makePhoneCall/utssdk/interface.uts插件元信息id、版本、平台支持矩阵可在 src/uni_modules/uni-makePhoneCall/package.json 中查看模块说明文档为 src/uni_modules/uni-makePhoneCall/readme.md。兼容性版本要求根据原文档makePhoneCall在各平台的可用版本如下| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 4.0 | 4.41 | 4.63 | 4.63 | 4.61 |从 src/uni_modules/uni-makePhoneCall/utssdk/interface.uts 中的uniPlatform注解可以看到更细致的平台矩阵Android/iOS/微信小程序均标记为unixVer4.63/4.41 起支持HarmonyOS 的unixVer为 4.61其中 vapor 版本为 5.0Web 端为 4.0而支付宝、百度、抖音、QQ、快手、京东等小程序平台的unixVer标记为x说明这些平台在 uni-app x 编译目标下未单独封装实现实际运行依赖宿主小程序的原始能力。注意HarmonyOS 平台在 HarmonyOS 平台使用makePhoneCall时需要申请受限开放权限ohos.permission.WRITE_CONTACTS否则系统可能拒绝拨号请求。该权限属于受限开放权限需要按华为官方受限权限申请流程处理。二、参数规范options 对象详解uni.makePhoneCall接受一个必填的 options 对象参数类型为MakePhoneCallOptions。options 属性描述| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | phoneNumber | string | 是 | Web: 4.0; 微信小程序: 4.41; Android: 4.63; iOS: 4.63; HarmonyOS: 4.61 | 需要拨打的电话号码 | | success | (result: MakePhoneCallSuccess) void | 否 | 同上 | 成功返回的回调函数 | | fail | (result: MakePhoneCallFail) void | 否 | 同上 | 失败的回调函数 | | complete | (result: any) void | 否 | 同上 | 结束的回调函数调用成功、失败都会执行 |对应地src/uni_modules/uni-makePhoneCall/utssdk/interface.uts 中完整定义了MakePhoneCallOptions的类型结构phoneNumber为必填 stringsuccess、fail、complete三个回调均为可选类型标注为| null即显式传 null 也合法。参数协议校验源码级在 src/uni_modules/uni-makePhoneCall/utssdk/protocol.uts 中定义了接口入参协议export const API_MAKE_PHONE_CALL makePhoneCall export const MakePhoneCallProtocol new Mapstring, ProtocolOptions([ [ phoneNumber, { type: string, required: true, } ] ])可以看到phoneNumber被声明为type: string且required: true。这意味着在 uni-app x 的强类型校验体系下调用时必须提供字符串类型的电话号码缺失或类型不符会在协议层被拦截无需等到平台原生层再报错。三、错误处理MakePhoneCallFail 与 errCode 错误码MakePhoneCallFail 属性当调用失败时fail回调会收到一个符合MakePhoneCallFail结构的结果对象| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errCode | number | 是 | 错误码具体合法值见下表 | | errSubject | string | 是 | 统一错误主题模块名称 | | data | any | 否 | 错误信息中包含的数据 | | cause | Error | 否 | 源错误信息可以包含多个错误详见 SourceError | | errMsg | string | 是 | 错误信息文本 |其中cause字段的类型定义可参阅仓库的 docs/err-spec.md 中UniError一节。errCode 合法值| 合法值 | 描述 | | :- | :- | | 1500601 | 当前设备不支持此功能 | | 1500602 | 无效号码 | | 1500603 | 内部错误 |这三个错误码并非随意定义它们与源码中的错误映射一一对应。在 src/uni_modules/uni-makePhoneCall/utssdk/unierror.uts 中可以看到export const MakePhoneCallUniErrors : Mapnumber, string new Map([ [1500601, not support], [1500602, invalid number], [1500603, internal error] ]); export class MakePhoneCallErrorImpl extends UniError implements IMakePhoneCallError { override errCode : MakePhoneCallErrorCode; constructor(code : MakePhoneCallErrorCode) { super(); this.errSubject uni-makePhoneCall; this.errCode code; this.errMsg MakePhoneCallUniErrors.get(code) ?? ; } }要点错误主题errSubject统一为uni-makePhoneCall对应 UTS 插件模块 ID便于在统一错误处理体系中定位错误来源errMsg 与 errCode 严格对应1500601 →not support、1500602 →invalid number、1500603 →internal error类型定义MakePhoneCallErrorCode见 interface.uts将这三个合法值固化为联合类型开发者在 UTS 中可享受编译期枚举约束。平台原生错误码到统一错误码的转换一个值得注意的源码细节HarmonyOS 平台的实现中src/uni_modules/uni-makePhoneCall/utssdk/app-harmony/index.uts会将鸿蒙系统层的原生错误码转换为统一 errCodefunction transformErrorCode(code: number): MakePhoneCallErrorCode { switch (code) { case 401: case 8300001: return 1500602 case 8300003: return 1500603 } return 1500603 }也就是说鸿蒙系统返回的401参数错误或8300001会被归一为无效号码15006028300003及未知错误统一归为内部错误1500603。这种平台码 → 统一码的映射正是 uni-app 跨端错误处理的核心机制上层业务代码无需感知各平台原生错误码差异。四、号码校验规则拨打前的一道防线在拨号真正发起前各端实现都会先执行号码合法性校验该校验函数为 src/uni_modules/uni-makePhoneCall/utssdk/phoneRuleValidation.utsexport function isValidPhoneRules(input: string): boolean { const cleaned input.trim(); // 仅允许字符0-9 - * # , ; const validDialPattern /^[0-9\-*#;,]$/; return validDialPattern.test(cleaned); }该规则的设计意图值得说明先trim()去除首尾空白避免用户误输入空格允许的字符集为0-9 - * # , ;——这并非仅限普通手机号而是兼容了国际长途前缀、分机号, ;、运营商服务码* #等电话拨号盘的合法字符是一种拨号键盘字符级别的宽泛校验校验不通过时各端统一返回 1500602无效号码。五、三端源码实现底层调用链深度剖析uni-makePhoneCall采用 UTS 插件形式实现各平台实现源码按目录隔离存放位于 src/uni_modules/uni-makePhoneCall/utssdk/ 下由 readme 的目录说明可知app-android编译为 Kotlin、app-ios编译为 Swift、app-harmony编译为 ArkTS。下面逐一剖析。5.1 Android 实现Intent 拨号不直接呼出源码文件src/uni_modules/uni-makePhoneCall/utssdk/app-android/index.utsexport const makePhoneCall : MakePhoneCall function (options : MakePhoneCallOptions) { const activity UTSAndroid.getUniActivity(); if (activity null) { const error new MakePhoneCallErrorImpl(1500603); options.fail?.(error); options.complete?.(error); return; } if (!activity.getPackageManager().hasSystemFeature(PackageManager.FEATURE_TELEPHONY)) { const error new MakePhoneCallErrorImpl(1500601); options.fail?.(error); options.complete?.(error); return; } if (!isValidPhoneRules(options.phoneNumber)) { const error new MakePhoneCallErrorImpl(1500602); options.fail?.(error); options.complete?.(error); return; } const uri Uri.parse(tel: options.phoneNumber); const intent new Intent(Intent.ACTION_DIAL, uri); activity.startActivity(intent); options.success?.({}); options.complete?.({}); }Android 端的实现逻辑清晰对应了错误码体系Activity 获取失败UTSAndroid.getUniActivity 返回 null→ 内部错误 1500603设备不支持电话功能通过PackageManager.hasSystemFeature(FEATURE_TELEPHONY)检测若设备没有电话模块如平板等返回当前设备不支持此功能1500601号码校验失败→ 无效号码 1500602校验通过后构造tel:URI发起ACTION_DIALIntent通过startActivity打开系统拨号盘。实现细节Android 端使用的是ACTION_DIAL拨号盘而非ACTION_CALL直接呼叫这是有意的设计——调用后停留在系统拨号界面由用户确认后手动呼出既符合惯例也规避了直接呼叫所需的CALL_PHONE高危权限。另外注意options.success?.({})在startActivity后同步调用表示拨号界面已成功唤起。5.2 iOS 实现tel:// URL Scheme源码文件src/uni_modules/uni-makePhoneCall/utssdk/app-ios/index.utsexport const makePhoneCall : MakePhoneCall function (options : MakePhoneCallOptions) { if (options.phoneNumber.length 0 || isValidPhoneRules(options.phoneNumber) false) { const err new MakePhoneCallErrorImpl(1500602); options.fail?.(err) options.complete?.(err) return } let phoneString tel:// options.phoneNumber let phoneUrl URL(string phoneString) if (phoneUrl null) { const err new MakePhoneCallErrorImpl(1500602); options.fail?.(err) options.complete?.(err) return } if (UIApplication.shared.canOpenURL(phoneUrl!)) { const map new MapUIApplication.OpenExternalURLOptionsKey, any() UIApplication.shared.open(phoneUrl!, options map, completionHandler (isSuccessOpen : boolean) : void { if (isSuccessOpen) { let success new MakePhoneCallSuccess() options.success?.(success) options.complete?.(success) } else { const err new MakePhoneCallErrorImpl(1500603); options.fail?.(err) options.complete?.(err) } }) } else { const err new MakePhoneCallErrorImpl(1500601); options.fail?.(err) options.complete?.(err) } }iOS 端的实现要点号码校验多了一层length 0的空串检查校验失败返回 1500602URL 构造将号码拼装为tel://Scheme 的 URLURL(string:)构造失败同样视为无效号码能力检测通过UIApplication.shared.canOpenURL判断系统能否打开该 Scheme——不能打开说明设备不支持拨号如 iPod touch返回 1500601异步打开UIApplication.shared.open的 completionHandler 中根据打开结果回调 success/fail打开失败返回内部错误 1500603。与 Android 的同步回调不同iOS 的 success 是异步触发的这提示开发者不应依赖回调的同步/异步特性。5.3 HarmonyOS 实现ohos.telephony.call 原生接口源码文件src/uni_modules/uni-makePhoneCall/utssdk/app-harmony/index.utsimport call from ohos.telephony.call export const makePhoneCall: MakePhoneCall defineAsyncApiMakePhoneCallOptions, MakePhoneCallSuccess( API_MAKE_PHONE_CALL, (options: MakePhoneCallOptions, res: ApiExecutorMakePhoneCallSuccess) { const { phoneNumber } options if (!isValidPhoneRules(phoneNumber)) { const err new MakePhoneCallErrorImpl(1500602) res.reject(err.errMsg, err as ApiError) return } try { call.makeCall(phoneNumber) .then(res.resolve) .catch((err: BusinessErrorvoid) { const error new MakePhoneCallErrorImpl(transformErrorCode(err.code)) res.reject(error.errMsg, error as ApiError) }) } catch (e) { const error new MakePhoneCallErrorImpl(transformErrorCode((e as BusinessError).code)) res.reject(error.errMsg, error as ApiError) } }, MakePhoneCallProtocol ) as MakePhoneCallHarmonyOS 端的关键差异实现范式不同使用defineAsyncApi包装异步 API配合MakePhoneCallProtocol做参数协议声明式校验回调通过res.resolve/res.reject分发原生能力直接调用ohos.telephony.call模块的call.makeCall(phoneNumber)返回 Promise错误归一化如前文所述通过transformErrorCode将鸿蒙 BusinessError 的code映射为统一错误码401/8300001 → 15006028300003 → 1500603权限前置此平台需要受限开放权限ohos.permission.WRITE_CONTACTS对应原文档的 warning 说明。5.4 各端实现对比小结| 维度 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | | 原生手段 | Intent(ACTION_DIAL) tel: URI |tel://URL UIApplication.open | ohos.telephony.call.makeCall | | 是否直接呼出 | 否打开拨号盘用户确认 | 视系统行为tel:// 通常直接进入拨号确认界面 | 调用系统拨号能力 | | 号码校验 | phoneRuleValidation.uts | 空串 phoneRuleValidation.uts | phoneRuleValidation.uts | | 能力检测 | FEATURE_TELEPHONY | canOpenURL | 系统接口失败映射 | | success 触发时机 | 同步 | 异步completionHandler | Promise resolve异步 |六、完整可运行示例原文档附带的示例与仓库演示页 src/pages/API/make-phone-call/make-phone-call.uvue 完全一致是一个输入号码 → 点击拨打的典型场景。该页面已注册进演示应用的 src/pages.json可直接在 hello uni-app x 演示工程中运行体验。template view page-head :titletitle/page-head view classuni-padding-wrap uni-common-mt view classuni-hello-text uni-center请在下方输入电话号码/view input classinput uni-common-mt typenumber nameinput inputbindInput / view classuni-btn-v uni-common-mt button tapmakePhoneCall typeprimary :disableddata.disabled拨打/button /view /view /view /template script setup languts type DataType { disabled: boolean; inputValue: string; } const title ref(makePhoneCall) const data reactive({ disabled: true, inputValue: } as DataType) const bindInput (e : UniInputEvent) { data.inputValue e.detail.value if (data.inputValue.length 0) { data.disabled false } else { data.disabled true } } const makePhoneCall () { uni.makePhoneCall({ phoneNumber: data.inputValue, success: () { console.log(成功拨打电话) }, fail: (err) { console.log(err.errCode) uni.showToast({ title: 错误码 err.errCode.toString(), icon: error }) } }) } /script style .input { height: 60px; line-height: 60px; font-size: 39px; border-bottom: 1px solid #E2E2E2; text-align: center; } /style示例代码要点解读输入联动bindInput监听 input 的input事件UniInputEvent类型根据e.detail.value的长度动态启用/禁用拨打按钮避免空号码提交失败提示fail回调中通过err.errCode拿到统一错误码配合uni.showToast以 error 图标展示是处理拨号失败的标准姿势脚本语言script setup languts表明页面使用 UTSuni type script编写逻辑代码同样享受强类型检查。七、最佳实践与注意事项永远处理 fail 回调拨号失败是常见场景——平板设备1500601、号码含非法字符1500602、系统内部异常1500603。建议像示例一样将错误码展示给用户或写入日志体系号码格式phoneNumber应传纯拨号字符数字、、-、*、#、,、;。国际号码建议带前缀若需传分机可结合,暂停或;等待字符HarmonyOS 权限前置发布到 HarmonyOS 的应用需提前申请ohos.permission.WRITE_CONTACTS受限开放权限否则真机可能出现调用失败且该权限属于受限权限审核周期需提前规划回调时序不要假设同步如 5.2、5.3 节所示iOS/HarmonyOS 的 success 为异步触发Android 为同步触发业务逻辑不应依赖回调触发时机直接呼出 vs 拨号盘Android 端当前实现为唤起拨号盘ACTION_DIAL如需一键直接呼叫能力需要依赖宿主平台原生扩展或系统级能力uni.makePhoneCall本身不承诺直接呼出配合统一错误处理errSubject固定为uni-makePhoneCall可将拨号错误纳入应用级错误监控通过errCode分类统计。八、延伸阅读API 错误码与UniError/cause结构定义docs/err-spec.mdUTS 插件实现规范与平台目录组织src/uni_modules/uni-makePhoneCall/readme.md接口类型与平台注解定义src/uni_modules/uni-makePhoneCall/utssdk/interface.utsAndroid 实现Intent 拨号src/uni_modules/uni-makePhoneCall/utssdk/app-android/index.utsiOS 实现tel:// URL Schemesrc/uni_modules/uni-makePhoneCall/utssdk/app-ios/index.utsHarmonyOS 实现ohos.telephony.callsrc/uni_modules/uni-makePhoneCall/utssdk/app-harmony/index.uts号码校验规则src/uni_modules/uni-makePhoneCall/utssdk/phoneRuleValidation.uts可运行演示页src/pages/API/make-phone-call/make-phone-call.uvue【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考