方法詳解

簡介

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，可以為用戶提供便捷的聯系人保存體驗，提升應用的實用性和用戶滿意度。