uni-app，小程序中的addPhoneContact，保存联系人到手机通讯录

方法详解

简介

addPhoneContact是uni-app框架提供的一个实用API，用于向系统通讯录添加联系人信息。这个方法在需要将应用内的联系人信息快速保存到用户设备通讯录的场景下非常有用，比如会员名片、商家联系方式保存等功能。

基本语法

uni.addPhoneContact(OBJECT)

参数说明

OBJECT参数对象支持以下属性：

属性名	类型	必填	说明
firstName	String	是	名字
lastName	String	否	姓氏
mobilePhoneNumber	String	否	手机号
phoneNumber	String	否	电话号码
email	String	否	电子邮件
organization	String	否	公司/组织名
title	String	否	职位
address	String	否	地址
addressCountry	String	否	国家
addressState	String	否	省份
addressCity	String	否	城市
addressStreet	String	否	街道
addressPostalCode	String	否	邮政编码
success	Function	否	接口调用成功的回调函数
fail	Function	否	接口调用失败的回调函数
complete	Function	否	接口调用结束的回调函数（调用成功、失败都会执行）

基础用法

uni.addPhoneContact({
    firstName: '张',
    lastName: '三',
    mobilePhoneNumber: '13812345678',
    email: 'zhangsan@example.com',
    organization: 'XX科技有限公司',
    title: '前端工程师',
    success: () => {
        uni.showToast({
            title: '已添加到通讯录',
            icon: 'success'
        });
    },
    fail: () => {
        uni.showToast({
            title: '添加联系人失败',
            icon: 'none'
        });
    }
});

使用示例

// 保存联系人信息到通讯录
saveContact() {
    // 判断是否有权限或是否登录
    if (!this.isAuthorized) {
        uni.showModal({
            title: '提示',
            content: '您需要授权才能保存联系人',
            confirmText: '去授权',
            success: (res) => {
                if (res.confirm) {
                    this.requestAuthorization();
                }
            }
        });
        return;
    }
    
    // 添加联系人
    uni.addPhoneContact({
        firstName: this.memberInfo.name || '',
        mobilePhoneNumber: this.memberInfo.phone || '',
        title: this.memberInfo.position || '',
        organization: this.memberInfo.company || '',
        email: this.memberInfo.email || '',
        address: this.memberInfo.address || '',
        success: () => {
            uni.showToast({
                title: '已添加到通讯录',
                icon: 'success'
            });
        },
        fail: (err) => {
            console.error('添加联系人失败:', err);
            uni.showToast({
                title: '添加联系人失败',
                icon: 'none'
            });
        }
    });
}

平台差异说明

App	H5	微信小程序	支付宝小程序	百度小程序	抖音小程序	QQ小程序
√	√	√	√	√	√	√

注意事项

权限问题：在某些平台上，调用此API可能需要用户授予通讯录访问权限。
必填字段：不同平台对必填字段的要求可能有所不同，但一般来说firstName是必填的。
iOS特殊处理：在iOS系统中，firstName和lastName会合并显示为一个名字。
用户体验：添加联系人前最好先向用户说明将要执行的操作，获得用户同意后再进行。
错误处理：务必添加fail回调处理添加失败的情况，并给予用户适当的反馈。

最佳实践

提前告知：在用户点击"保存联系人"按钮前，应明确告知用户该操作的目的和结果。
数据验证：在调用API前，应对要保存的联系人数据进行验证，确保至少有姓名和电话号码等基本信息。
优雅降级：对于不支持此API的平台，应提供替代方案，如复制联系信息到剪贴板。
状态反馈：操作成功或失败后，应给予用户明确的反馈，如使用toast提示。
通过合理使用addPhoneContactAPI，可以为用户提供便捷的联系人保存体验，提升应用的实用性和用户满意度。