uni-app 通讯录 API 全解析addPhoneContact 添加联系人与 chooseContact 选择联系人实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app通讯录是移动端高频业务场景之一本指南聚焦 uni-app 体系含 uni-app x / uni-app Vue 3中操作手机系统通讯录的两个核心 APIuni.addPhoneContact将联系人表单写入系统通讯录与uni.chooseContact拉起系统通讯录选择联系人。文章以 docs/api/contact.md 为骨架结合仓库内uni-addPhoneContact的 UTS 插件源码src/uni_modules/uni-addPhoneContact深入讲解参数语义、兼容性差异、错误处理与底层实现原理读完即可在 Android、iOS、微信小程序与 HarmonyOS 上落地完整的联系人读写能力。一、接口总览与适用场景手机通讯录 API 在 uni-app 中分为两条能力线| API | 能力 | 典型场景 | | :- | :- | :- | |uni.addPhoneContact(options)| 添加手机通讯录联系人 | 名片交换、CRM 沉淀客户、将表单信息一键存入系统通讯录 | |uni.chooseContact(options)| 拉起手机通讯录选择联系人 | 选取已有联系人回填表单、发起拨号/短信前获取号码 |两者均由options对象承载参数均采用success/fail/complete三回调风格与 uni-app 其他 API 保持一致。需要特别说明的是addPhoneContact在仓库中有完整的 UTS 插件实现src/uni_modules/uni-addPhoneContact其 readme 明确标注仅鸿蒙平台支持而 Web 端两个 API 均标记为不可用xchooseContact则依赖宿主小程序平台微信小程序等提供对应能力仓库内未提供 UTS 插件实现以下兼容性表格均以 docs/api/contact.md 与插件interface.uts中的平台声明为准。兼容性一览addPhoneContact 兼容性版本号表示对应平台最低支持版本| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | 5.08 | 5.08 | 4.61 |chooseContact 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | 5.08 | 5.08 | 4.61 |说明文档表格中的版本号对应 uni-app x 编译器/HBuilderX 的版本线表格中的x表示该平台当前不支持。从 interface.uts 的uniPlatform平台声明可以看到更细粒度的条件Android 需系统版本 5.0、iOS 需 12.0、HarmonyOS 需 3.0uni x 4.61 起支持微信小程序宿主端即可支持。二、uni.addPhoneContact添加手机通讯录联系人2.1 函数签名与核心行为uni.addPhoneContact(options: AddPhoneContactOptions): void调用后用户可以选择将该表单以「新增联系人」或「添加到已有联系人」的方式写入手机系统通讯录——最终写入动作由用户在系统界面中确认应用无法静默写入。这也是移动平台隐私合规的通用要求。2.2 参数详解AddPhoneContactOptionsoptions为必填对象其属性全部为可选各平台可支持情况见兼容性列x表示该平台不支持| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | photoFilePath | string | 否 | Web: x | 头像本地文件路径 | | nickName | string | 否 | Web: x | 昵称 | | lastName | string | 否 | Web: x | 姓氏 | | middleName | string | 否 | Web: x | 中间名 | | firstName | string | 否 | Web: x | 名字 | | remark | string | 否 | Web: x | 备注 | | mobilePhoneNumber | string | 否 | Web: x | 手机号 | | weChatNumber | string | 否 | Web: x | 即时消息账号 | | addressCountry | string | 否 | Web: x | 联系地址国家 | | addressState | string | 否 | Web: x | 联系地址省份 | | addressCity | string | 否 | Web: x | 联系地址城市 | | addressStreet | string | 否 | Web: x | 联系地址街道 | | addressPostalCode | string | 否 | Web: x | 联系地址邮政编码 | | organization | string | 否 | Web: x | 公司 | | title | string | 否 | Web: x | 职位 | | workFaxNumber | string | 否 | Web: x | 工作传真 | | workPhoneNumber | string | 否 | Web: x | 工作电话 | | hostNumber | string | 否 | Web: x | 公司电话 | | email | string | 否 | Web: x | 电子邮件 | | url | string | 否 | Web: x | 网站 | | workAddressCountry | string | 否 | Web: x | 工作地址国家 | | workAddressState | string | 否 | Web: x | 工作地址省份 | | workAddressCity | string | 否 | Web: x | 工作地址城市 | | workAddressStreet | string | 否 | Web: x | 工作地址街道 | | workAddressPostalCode | string | 否 | Web: x | 工作地址邮政编码 | | homeFaxNumber | string | 否 | Web: x | 住宅传真 | | homePhoneNumber | string | 否 | Web: x | 住宅电话 | | homeAddressCountry | string | 否 | Web: x | 住宅地址国家 | | homeAddressState | string | 否 | Web: x | 住宅地址省份 | | homeAddressCity | string | 否 | Web: x | 住宅地址城市 | | homeAddressStreet | string | 否 | Web: x | 住宅地址街道 | | homeAddressPostalCode | string | 否 | Web: x | 住宅地址邮政编码 | | success | (result: AddPhoneContactSuccess) void | 否 | Web: x | 接口调用成功的回调函数 | | fail | (result: AddPhoneContactFail) void | 否 | Web: x | 接口调用失败的回调函数 | | complete | (result: AddPhoneContactSuccess | AddPhoneContactFail) void | 否 | Web: x | 接口调用结束的回调函数调用成功、失败都会执行 |在 interface.uts 中上述属性被完整定义所有字段类型均为string | null可选。字段覆盖了联系人信息的大多数维度姓名lastName/middleName/firstName/nickName、号码手机、住宅、工作、传真、公司电话、地址联系地址、工作地址、住宅地址各含国家/省份/城市/街道/邮编五要素、职业公司、职位、互联网信息邮箱、网站、即时消息账号以及头像和备注。2.3 错误对象与 errCode 约定失败回调接收AddPhoneContactFail对象属性如下| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | errCode | number | 是 | Web: x | 错误码 | | errSubject | string | 是 | Web: x | 统一错误主题模块名称 | | data | any | 否 | Web: x | 错误信息中包含的数据 | | cause | Error | 否 | - | 源错误信息可以包含多个错误详见 SourceError | | errMsg | string | 是 | Web: x | 错误描述 |其中errCode的合法值约定为601 / 602 / 603。结合 docs/err-spec.md 的 UniError 规范可以理解这套错误结构的统一语义errSubject是统一错误主题模块名称多级模块使用::分隔如模块名称::二级模块名称errCode为统一错误码通常0表示成功跨端App/Web平台专有错误码第 57 位使用6xx段位本 API 的 601/602/603 即属于该约定cause承载源错误SourceError当底层系统同时抛出多个错误时会封装为 AggregateError可通过err.cause.errors获取源错误数组data用于携带部分成功的数据便于上层做降级处理。2.4 完整调用示例uni.addPhoneContact({ photoFilePath: /static/avatar.png, // 头像本地文件路径 nickName: 阿D, lastName: 张, middleName: , firstName: 三, remark: 重要客户-来自扫码名片, mobilePhoneNumber: 13800138000, weChatNumber: zhangsan_wx, organization: DCloud, title: 前端工程师, workPhoneNumber: 010-12345678, hostNumber: 010-12345678, email: zhangsanexample.com, url: https://example.com, addressCountry: 中国, addressState: 北京市, addressCity: 北京市, addressStreet: 中关村大街1号, addressPostalCode: 100080, success: (res) { console.log(联系人添加成功, res) }, fail: (err) { console.error(添加失败errCode:, err.errCode, errMsg:, err.errMsg) }, complete: (res) { console.log(调用结束无论成败都会执行) } })注意尽管字段大多可空从 protocol.uts 的参数协议可以看出firstName是协议层面的必填项required: true且formatArgs中内置了参数校验——当firstName为空时会返回addPhoneContact:fail parameter error: parameter.firstName should not be empty;的格式错误。因此调用前应确保传入有效的firstName否则接口会在参数校验阶段直接失败。2.5 HarmonyOS 底层实现剖析在仓库中uni.addPhoneContact的鸿蒙实现位于 app-harmony/index.uts整体采用defineAsyncApi异步 API 封装模式核心流程如下权限申请通过UTSHarmony.requestSystemPermission([ohos.permission.WRITE_CONTACTS], callback)申请写联系人权限。若用户拒绝直接以Permission denied拒绝executor.reject因此应用需在鸿蒙工程中声明ohos.permission.WRITE_CONTACTS权限组装联系人对象将 UTS 参数映射为鸿蒙contact.Contact结构姓名givenName取firstNamefullName由lastName middleName firstName拼接头像photoFilePath映射为contactInfo.portrait.uri号码根据字段归类到不同labelId——手机号NUM_MOBILE、住宅电话NUM_HOME、住宅传真NUM_FAX_HOME、工作传真NUM_FAX_WORK、工作电话NUM_WORK、公司电话NUM_COMPANY_MAIN地址联系/工作/住宅三组地址分别映射为PostalAddress并使用ADDR_HOME/ADDR_WORK/CUSTOM_LABEL标识同时拼接生成完整的postalAddress文本其他昵称、邮箱、网址、备注、组织organization.name与organization.title逐一条件化挂载写入系统调用鸿蒙 ContactsKit 的contact.addContact(UTSHarmony.getUIAbilityContext()!, contactInfo)异步写入成功时resolve(contactId)失败时通过executor.reject(err.message)抛出错误。这段源码也印证了文档参数的边界号码和地址字段是分类填充而非简单字符串拼接——例如同时传入mobilePhoneNumber与homePhoneNumber时会生成两个带不同 label 的号码条目保证系统通讯录中字段语义准确。三、uni.chooseContact拉起通讯录选择联系人3.1 函数签名与核心行为uni.chooseContact(options: ChooseContactOptions): void调用后拉起手机通讯录界面用户选择某个联系人后返回其姓名与手机号信息。该 API 无独立的 UTS 插件实现仓库中未包含uni-chooseContact模块在支持端如微信小程序 4.41由宿主环境提供能力。3.2 参数与返回值options仅包含三个回调属性全部可选| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | success | (result: ChooseContactSuccess) void | 否 | Web: x | 接口调用成功的回调函数 | | fail | (result: ChooseContactFail) void | 否 | Web: x | 接口调用失败的回调函数 | | complete | (result: ChooseContactSuccess | ChooseContactFail) void | 否 | Web: x | 接口调用结束的回调函数调用成功、失败都会执行 |ChooseContactSuccess 属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | displayName | string | 是 | Web: x | 联系人姓名 | | phoneNumber | string | 是 | Web: x | 当前选中的手机号 | | phoneNumberList | Arraystring | 是 | Web: x | 联系人的所有手机号 | | errMsg | string | 是 | Web: x | 接口调用结果 |ChooseContactFail 属性值与AddPhoneContactFail结构一致errCode601/602/603、errSubject、data、cause、errMsg其中errCode合法值同样为 601 / 602 / 603。3.3 调用示例uni.chooseContact({ success: (res) { console.log(联系人姓名:, res.displayName) console.log(当前选中的手机号:, res.phoneNumber) console.log(该联系人全部手机号:, res.phoneNumberList) // 例如回填到拨号表单 this.phone res.phoneNumber }, fail: (err) { console.error(选择失败:, err.errCode, err.errMsg) }, complete: (res) { console.log(选择流程结束) } })phoneNumberList与phoneNumber的差异需要留意一个联系人可能绑定多个号码phoneNumberList返回全部号码而phoneNumber是当前选中默认/首个的号码业务上若需要让用户二次选择具体号码可基于phoneNumberList自行实现选择 UI。四、通用类型与跨端实践要点4.1 GeneralCallbackResult两个 API 的错误回调体系共用通用回调结果类型| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |4.2 实战注意点平台能力差异Web 端两个 API 均为x不支持addPhoneContact的仓库实现仅覆盖 HarmonyOSAndroid/iOS 端5.08与微信小程序4.41依赖各平台框架内置实现接入前务必在目标端真机验证隐私与权限鸿蒙端写入联系人需要ohos.permission.WRITE_CONTACTS权限声明与运行时授权选择联系人一般由宿主系统授权弹窗完成业务侧需处理用户拒绝授权的fail分支参数校验前置addPhoneContact的firstName必填校验发生在参数协议层protocol.uts空值会以fail回调提前返回属于快速失败设计应在 UI 层提前约束回调完整使用complete在成功与失败后都会执行适合做 loading 关闭、埋点等收尾逻辑fail中建议读取errCode/errSubject做分类提示601/602/603 分别代表不同错误类型可按 docs/err-spec.md 的规范排查联系人数据保密选择结果姓名、号码属于敏感个人信息务必在用户授权范围内使用避免未经同意上传或二次传播。五、源码导读与延伸阅读若想深入实现细节可沿以下路径在仓库中继续探索文档骨架docs/api/contact.md含全部参数表、兼容性矩阵与错误码约定UTS 接口定义src/uni_modules/uni-addPhoneContact/utssdk/interface.utsAddPhoneContactOptions类型与平台声明参数协议与校验src/uni_modules/uni-addPhoneContact/utssdk/protocol.utsfirstName必填规则HarmonyOS 实现src/uni_modules/uni-addPhoneContact/utssdk/app-harmony/index.uts权限申请、Contact 组装、addContact调用链插件说明src/uni_modules/uni-addPhoneContact/readme.mduts 与 UTS 插件机制介绍统一错误规范docs/err-spec.mdUniError / errSubject / errCode 全量约定六、小结uni.addPhoneContact与uni.chooseContact构成了 uni-app 操作手机通讯录的完整闭环前者负责将业务表单姓名、多组号码、三套地址、职业、社交信息等写入系统通讯录后者负责从系统通讯录读回联系人姓名与号码。本仓库中的uni-addPhoneContact鸿蒙实现展示了 UTS 插件如何通过defineAsyncApi 权限申请 ContactsKit 原生调用完成跨语言封装是理解 uni-app 原生能力封装范式的优秀范本。实际项目中建议结合目标平台的兼容性版本与权限模型提前设计降级方案并对联系人这类敏感数据做好合规处理。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app 通讯录 API 全解析：addPhoneContact 添加联系人与 chooseContact 选择联系人实战指南
uni-app 通讯录 API 全解析addPhoneContact 添加联系人与 chooseContact 选择联系人实战指南【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app通讯录是移动端高频业务场景之一本指南聚焦 uni-app 体系含 uni-app x / uni-app Vue 3中操作手机系统通讯录的两个核心 APIuni.addPhoneContact将联系人表单写入系统通讯录与uni.chooseContact拉起系统通讯录选择联系人。文章以 docs/api/contact.md 为骨架结合仓库内uni-addPhoneContact的 UTS 插件源码src/uni_modules/uni-addPhoneContact深入讲解参数语义、兼容性差异、错误处理与底层实现原理读完即可在 Android、iOS、微信小程序与 HarmonyOS 上落地完整的联系人读写能力。一、接口总览与适用场景手机通讯录 API 在 uni-app 中分为两条能力线| API | 能力 | 典型场景 | | :- | :- | :- | |uni.addPhoneContact(options)| 添加手机通讯录联系人 | 名片交换、CRM 沉淀客户、将表单信息一键存入系统通讯录 | |uni.chooseContact(options)| 拉起手机通讯录选择联系人 | 选取已有联系人回填表单、发起拨号/短信前获取号码 |两者均由options对象承载参数均采用success/fail/complete三回调风格与 uni-app 其他 API 保持一致。需要特别说明的是addPhoneContact在仓库中有完整的 UTS 插件实现src/uni_modules/uni-addPhoneContact其 readme 明确标注仅鸿蒙平台支持而 Web 端两个 API 均标记为不可用xchooseContact则依赖宿主小程序平台微信小程序等提供对应能力仓库内未提供 UTS 插件实现以下兼容性表格均以 docs/api/contact.md 与插件interface.uts中的平台声明为准。兼容性一览addPhoneContact 兼容性版本号表示对应平台最低支持版本| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | 5.08 | 5.08 | 4.61 |chooseContact 兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | x | 4.41 | 5.08 | 5.08 | 4.61 |说明文档表格中的版本号对应 uni-app x 编译器/HBuilderX 的版本线表格中的x表示该平台当前不支持。从 interface.uts 的uniPlatform平台声明可以看到更细粒度的条件Android 需系统版本 5.0、iOS 需 12.0、HarmonyOS 需 3.0uni x 4.61 起支持微信小程序宿主端即可支持。二、uni.addPhoneContact添加手机通讯录联系人2.1 函数签名与核心行为uni.addPhoneContact(options: AddPhoneContactOptions): void调用后用户可以选择将该表单以「新增联系人」或「添加到已有联系人」的方式写入手机系统通讯录——最终写入动作由用户在系统界面中确认应用无法静默写入。这也是移动平台隐私合规的通用要求。2.2 参数详解AddPhoneContactOptionsoptions为必填对象其属性全部为可选各平台可支持情况见兼容性列x表示该平台不支持| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | photoFilePath | string | 否 | Web: x | 头像本地文件路径 | | nickName | string | 否 | Web: x | 昵称 | | lastName | string | 否 | Web: x | 姓氏 | | middleName | string | 否 | Web: x | 中间名 | | firstName | string | 否 | Web: x | 名字 | | remark | string | 否 | Web: x | 备注 | | mobilePhoneNumber | string | 否 | Web: x | 手机号 | | weChatNumber | string | 否 | Web: x | 即时消息账号 | | addressCountry | string | 否 | Web: x | 联系地址国家 | | addressState | string | 否 | Web: x | 联系地址省份 | | addressCity | string | 否 | Web: x | 联系地址城市 | | addressStreet | string | 否 | Web: x | 联系地址街道 | | addressPostalCode | string | 否 | Web: x | 联系地址邮政编码 | | organization | string | 否 | Web: x | 公司 | | title | string | 否 | Web: x | 职位 | | workFaxNumber | string | 否 | Web: x | 工作传真 | | workPhoneNumber | string | 否 | Web: x | 工作电话 | | hostNumber | string | 否 | Web: x | 公司电话 | | email | string | 否 | Web: x | 电子邮件 | | url | string | 否 | Web: x | 网站 | | workAddressCountry | string | 否 | Web: x | 工作地址国家 | | workAddressState | string | 否 | Web: x | 工作地址省份 | | workAddressCity | string | 否 | Web: x | 工作地址城市 | | workAddressStreet | string | 否 | Web: x | 工作地址街道 | | workAddressPostalCode | string | 否 | Web: x | 工作地址邮政编码 | | homeFaxNumber | string | 否 | Web: x | 住宅传真 | | homePhoneNumber | string | 否 | Web: x | 住宅电话 | | homeAddressCountry | string | 否 | Web: x | 住宅地址国家 | | homeAddressState | string | 否 | Web: x | 住宅地址省份 | | homeAddressCity | string | 否 | Web: x | 住宅地址城市 | | homeAddressStreet | string | 否 | Web: x | 住宅地址街道 | | homeAddressPostalCode | string | 否 | Web: x | 住宅地址邮政编码 | | success | (result: AddPhoneContactSuccess) void | 否 | Web: x | 接口调用成功的回调函数 | | fail | (result: AddPhoneContactFail) void | 否 | Web: x | 接口调用失败的回调函数 | | complete | (result: AddPhoneContactSuccess | AddPhoneContactFail) void | 否 | Web: x | 接口调用结束的回调函数调用成功、失败都会执行 |在 interface.uts 中上述属性被完整定义所有字段类型均为string | null可选。字段覆盖了联系人信息的大多数维度姓名lastName/middleName/firstName/nickName、号码手机、住宅、工作、传真、公司电话、地址联系地址、工作地址、住宅地址各含国家/省份/城市/街道/邮编五要素、职业公司、职位、互联网信息邮箱、网站、即时消息账号以及头像和备注。2.3 错误对象与 errCode 约定失败回调接收AddPhoneContactFail对象属性如下| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | errCode | number | 是 | Web: x | 错误码 | | errSubject | string | 是 | Web: x | 统一错误主题模块名称 | | data | any | 否 | Web: x | 错误信息中包含的数据 | | cause | Error | 否 | - | 源错误信息可以包含多个错误详见 SourceError | | errMsg | string | 是 | Web: x | 错误描述 |其中errCode的合法值约定为601 / 602 / 603。结合 docs/err-spec.md 的 UniError 规范可以理解这套错误结构的统一语义errSubject是统一错误主题模块名称多级模块使用::分隔如模块名称::二级模块名称errCode为统一错误码通常0表示成功跨端App/Web平台专有错误码第 57 位使用6xx段位本 API 的 601/602/603 即属于该约定cause承载源错误SourceError当底层系统同时抛出多个错误时会封装为 AggregateError可通过err.cause.errors获取源错误数组data用于携带部分成功的数据便于上层做降级处理。2.4 完整调用示例uni.addPhoneContact({ photoFilePath: /static/avatar.png, // 头像本地文件路径 nickName: 阿D, lastName: 张, middleName: , firstName: 三, remark: 重要客户-来自扫码名片, mobilePhoneNumber: 13800138000, weChatNumber: zhangsan_wx, organization: DCloud, title: 前端工程师, workPhoneNumber: 010-12345678, hostNumber: 010-12345678, email: zhangsanexample.com, url: https://example.com, addressCountry: 中国, addressState: 北京市, addressCity: 北京市, addressStreet: 中关村大街1号, addressPostalCode: 100080, success: (res) { console.log(联系人添加成功, res) }, fail: (err) { console.error(添加失败errCode:, err.errCode, errMsg:, err.errMsg) }, complete: (res) { console.log(调用结束无论成败都会执行) } })注意尽管字段大多可空从 protocol.uts 的参数协议可以看出firstName是协议层面的必填项required: true且formatArgs中内置了参数校验——当firstName为空时会返回addPhoneContact:fail parameter error: parameter.firstName should not be empty;的格式错误。因此调用前应确保传入有效的firstName否则接口会在参数校验阶段直接失败。2.5 HarmonyOS 底层实现剖析在仓库中uni.addPhoneContact的鸿蒙实现位于 app-harmony/index.uts整体采用defineAsyncApi异步 API 封装模式核心流程如下权限申请通过UTSHarmony.requestSystemPermission([ohos.permission.WRITE_CONTACTS], callback)申请写联系人权限。若用户拒绝直接以Permission denied拒绝executor.reject因此应用需在鸿蒙工程中声明ohos.permission.WRITE_CONTACTS权限组装联系人对象将 UTS 参数映射为鸿蒙contact.Contact结构姓名givenName取firstNamefullName由lastName middleName firstName拼接头像photoFilePath映射为contactInfo.portrait.uri号码根据字段归类到不同labelId——手机号NUM_MOBILE、住宅电话NUM_HOME、住宅传真NUM_FAX_HOME、工作传真NUM_FAX_WORK、工作电话NUM_WORK、公司电话NUM_COMPANY_MAIN地址联系/工作/住宅三组地址分别映射为PostalAddress并使用ADDR_HOME/ADDR_WORK/CUSTOM_LABEL标识同时拼接生成完整的postalAddress文本其他昵称、邮箱、网址、备注、组织organization.name与organization.title逐一条件化挂载写入系统调用鸿蒙 ContactsKit 的contact.addContact(UTSHarmony.getUIAbilityContext()!, contactInfo)异步写入成功时resolve(contactId)失败时通过executor.reject(err.message)抛出错误。这段源码也印证了文档参数的边界号码和地址字段是分类填充而非简单字符串拼接——例如同时传入mobilePhoneNumber与homePhoneNumber时会生成两个带不同 label 的号码条目保证系统通讯录中字段语义准确。三、uni.chooseContact拉起通讯录选择联系人3.1 函数签名与核心行为uni.chooseContact(options: ChooseContactOptions): void调用后拉起手机通讯录界面用户选择某个联系人后返回其姓名与手机号信息。该 API 无独立的 UTS 插件实现仓库中未包含uni-chooseContact模块在支持端如微信小程序 4.41由宿主环境提供能力。3.2 参数与返回值options仅包含三个回调属性全部可选| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | success | (result: ChooseContactSuccess) void | 否 | Web: x | 接口调用成功的回调函数 | | fail | (result: ChooseContactFail) void | 否 | Web: x | 接口调用失败的回调函数 | | complete | (result: ChooseContactSuccess | ChooseContactFail) void | 否 | Web: x | 接口调用结束的回调函数调用成功、失败都会执行 |ChooseContactSuccess 属性值| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | | displayName | string | 是 | Web: x | 联系人姓名 | | phoneNumber | string | 是 | Web: x | 当前选中的手机号 | | phoneNumberList | Arraystring | 是 | Web: x | 联系人的所有手机号 | | errMsg | string | 是 | Web: x | 接口调用结果 |ChooseContactFail 属性值与AddPhoneContactFail结构一致errCode601/602/603、errSubject、data、cause、errMsg其中errCode合法值同样为 601 / 602 / 603。3.3 调用示例uni.chooseContact({ success: (res) { console.log(联系人姓名:, res.displayName) console.log(当前选中的手机号:, res.phoneNumber) console.log(该联系人全部手机号:, res.phoneNumberList) // 例如回填到拨号表单 this.phone res.phoneNumber }, fail: (err) { console.error(选择失败:, err.errCode, err.errMsg) }, complete: (res) { console.log(选择流程结束) } })phoneNumberList与phoneNumber的差异需要留意一个联系人可能绑定多个号码phoneNumberList返回全部号码而phoneNumber是当前选中默认/首个的号码业务上若需要让用户二次选择具体号码可基于phoneNumberList自行实现选择 UI。四、通用类型与跨端实践要点4.1 GeneralCallbackResult两个 API 的错误回调体系共用通用回调结果类型| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | errMsg | string | 是 | 错误信息 |4.2 实战注意点平台能力差异Web 端两个 API 均为x不支持addPhoneContact的仓库实现仅覆盖 HarmonyOSAndroid/iOS 端5.08与微信小程序4.41依赖各平台框架内置实现接入前务必在目标端真机验证隐私与权限鸿蒙端写入联系人需要ohos.permission.WRITE_CONTACTS权限声明与运行时授权选择联系人一般由宿主系统授权弹窗完成业务侧需处理用户拒绝授权的fail分支参数校验前置addPhoneContact的firstName必填校验发生在参数协议层protocol.uts空值会以fail回调提前返回属于快速失败设计应在 UI 层提前约束回调完整使用complete在成功与失败后都会执行适合做 loading 关闭、埋点等收尾逻辑fail中建议读取errCode/errSubject做分类提示601/602/603 分别代表不同错误类型可按 docs/err-spec.md 的规范排查联系人数据保密选择结果姓名、号码属于敏感个人信息务必在用户授权范围内使用避免未经同意上传或二次传播。五、源码导读与延伸阅读若想深入实现细节可沿以下路径在仓库中继续探索文档骨架docs/api/contact.md含全部参数表、兼容性矩阵与错误码约定UTS 接口定义src/uni_modules/uni-addPhoneContact/utssdk/interface.utsAddPhoneContactOptions类型与平台声明参数协议与校验src/uni_modules/uni-addPhoneContact/utssdk/protocol.utsfirstName必填规则HarmonyOS 实现src/uni_modules/uni-addPhoneContact/utssdk/app-harmony/index.uts权限申请、Contact 组装、addContact调用链插件说明src/uni_modules/uni-addPhoneContact/readme.mduts 与 UTS 插件机制介绍统一错误规范docs/err-spec.mdUniError / errSubject / errCode 全量约定六、小结uni.addPhoneContact与uni.chooseContact构成了 uni-app 操作手机通讯录的完整闭环前者负责将业务表单姓名、多组号码、三套地址、职业、社交信息等写入系统通讯录后者负责从系统通讯录读回联系人姓名与号码。本仓库中的uni-addPhoneContact鸿蒙实现展示了 UTS 插件如何通过defineAsyncApi 权限申请 ContactsKit 原生调用完成跨语言封装是理解 uni-app 原生能力封装范式的优秀范本。实际项目中建议结合目标平台的兼容性版本与权限模型提前设计降级方案并对联系人这类敏感数据做好合规处理。【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址: https://gitcode.com/gh_mirrors/un/uni-app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
