Contacts · Html5+參考

# [contacts]() Contacts模塊管理系統通訊錄，用于可對系統通訊錄進行增、刪、改、查等操作。通過plus.contacts獲取系統通訊錄管理對象。 ### 常量： - [ADDRESSBOOK_PHONE](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ADDRESSBOOK_PHONE): 手機通訊錄 - [ADDRESSBOOK_SIM](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ADDRESSBOOK_SIM): SIM卡通訊錄 ### 方法： - [getAddressBook](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.getAddressBook): 獲取通訊錄對象 ### 對象： - [AddressBook](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.AddressBook): 通訊錄對象 - [Contact](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact): 聯系人對象 - [ContactField](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactField): JSON對象，聯系人域數據對象 - [ContactName](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactName): JSON對象，聯系人名稱對象 - [ContactAddress](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactAddress): JSON對象，聯系人地址對象 - [ContactOrganization](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactOrganization): JSON對象，聯系人所屬組織信息 - [ContactFindOption](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactFindOption): JSON對象，查找聯系人參數 - [ContactFindFilter](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactFindFilter): JSON對象，聯系人查找過濾器 ### 回調方法： - [AddressBookSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.AddressBookSuccessCallback): 獲取通訊錄操作成功回調函數 - [FindSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.FindSuccessCallback): 查找聯系人操作成功回調函數 - [ContactsSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsSuccessCallback): 聯系人操作成功回調函數 - [ContactsErrorCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsErrorCallback): 聯系人操作失敗回調 ### 權限： permissions ~~~ "Contacts": { "description": "訪問系統聯系人" } ~~~ # [ADDRESSBOOK_PHONE]() 手機通訊錄 ~~~ plus.contacts.ADDRESSBOOK_PHONE; ~~~ ### 說明： Number 類型通訊錄類型常量，數值類型，固定值為0，用于獲取系統的聯系人信息。 # [ADDRESSBOOK_SIM]() SIM卡通訊錄 ~~~ plus.contacts.ADDRESSBOOK_SIM; ~~~ ### 說明： Number 類型通訊錄類型常量，數值類型，固定值為1，用于獲取SIM卡上的聯系人信息。 ### 平臺支持 - Android - 2.2+ (不支持): 暫未實現SIM卡聯系人的訪問 - iOS - 4.3+ (不支持): 不支持SIM卡聯系人的訪問 # [getAddressBook]() 獲取通訊錄對象 ~~~ void plus.contacts.getAddressBook( type, succesCB, errorCB ); ~~~ ### 說明：根據指定通訊錄類型獲取通訊錄對象，獲取通訊錄對象后可對其進行增、刪、改操作。 ### 參數： - type: *( Number ) 必選 *要獲取的通訊錄類型可取通訊錄類型常量，可獲取手機通訊錄或SIM卡通訊錄。 - successCB: *( [AddressBookSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.AddressBookSuccessCallback) ) 必選 *獲取通訊錄對象成功回調 - errorCB: *( [ContactsErrorCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsErrorCallback) ) 可選 *獲取通訊錄對象失敗回調 ### 返回值： void : 無 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Contacts Example</title> <script type="text/javascript"> // 監聽plusready事件 document.addEventListener( "plusready", function(){ // 擴展API加載完畢，現在可以正常調用擴展API plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) { // 可通過addressbook進行通訊錄操作 alert( "Get address book success!" ); }, function ( e ) { alert( "Get address book failed: " + e.message ); } ); }, false ); </script> </head> <body> </body> </html> ~~~ # [AddressBook]() 通訊錄對象 ~~~ interface AddressBook { function Contact create(); function void find( contactFields, successCB, errorCB, findOptions ); } ~~~ ### 說明：通訊錄管理對象，可對系統通訊錄進行聯系人的增、刪、改、查操作。 ### 方法： - [create](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.AddressBook.create): 創建聯系人 - [find](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.AddressBook.find): 在通訊錄中查找聯系人 # [create]() 創建聯系人 ~~~ Contact addressbook.create(); ~~~ ### 說明：創建一個系統聯系人，并返回聯系人對象，可對聯系人對象進行操作設置聯系人信息，如名稱、地址、電話等。 ### 參數：無 ### 返回值： [Contact](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact) : 聯系人對象 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Contacts Example</title> <script type="text/javascript"> // 監聽plusready事件 document.addEventListener( "plusready", function(){ // 擴展API加載完畢，現在可以正常調用擴展API plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) { // 向通訊錄中添加聯系人 var contact = addressbook.create(); contact.name = {givenName:"王安"}; contact.phoneNumbers = [{type:"手機",value:"88888888",preferred:true}]; contact.save(); }, function ( e ) { alert( "Get address book failed: " + e.message ); } ); }, false ); </script> </head> <body> </body> </html> ~~~ # [find]() 在通訊錄中查找聯系人 ~~~ void addressbook.find( contactFields, successCB, errorCB, findOptions ); ~~~ ### 說明：在通訊錄中安裝指定的規則查找聯系人，contactFields可設定查找返回的聯系人中包含的字段值，查找聯系人成功時通過successCB回調返回，查找聯系人失敗則通過errorCB回調返回。 ### 參數： - contactFields: *( String[] ) 必選 *查找返回聯系人中需要包含的信息可取Contact對象的屬性名稱，若指定為null或""或空數組則包含所有聯系人信息。可通過“.”來分割子項，如“name.familyName”指定獲取聯系人名稱中的姓；對于ContactField類型的值則可指定類型值，如“phoneNumbers.mobile”指定獲取聯系人的手機號碼。 - successCB: *( [FindSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.FindSuccessCallback) ) 必選 *查找聯系人操作成功回調 - errorCB: *( [ContactsErrorCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsErrorCallback) ) 可選 *查找聯系人操作失敗回調 - findOptions: *( [ContactFindOption](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactFindOption) ) 可選 *查找聯系人的參數 ### 返回值： void : 無 ### 示例： ~~~ <!DOCTYPE html> <html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Contacts Example</title> <script type="text/javascript"> // 監聽plusready事件 document.addEventListener( "plusready", function(){ }, false ); function find(){ plus.contacts.getAddressBook(plus.contacts.ADDRESSBOOK_PHONE, function (addressbook) { addressbook.find(["displayName","phoneNumbers"],function(contacts){ alert(contacts.length); }, function () { alert("error"); },{multiple:true}); },function(e){ alert("Get address book failed: " + e.message); }); } </script> </head> <body> <button onclick="find()">Find</button> </body> </html> ~~~ # [Contact]() 聯系人對象 ~~~ interface Contact { attribute String displayName; attribute ContactName name; attribute String nickname; attribute ContackField[] phoneNumbers; attribute ContactField[] emails; attribute ContactAddress[] addresses; attribute ContactField[] ims; attribute ContactOriganization[] organizations; attribute Date birthday; attribute String note; attribute ContactField[] photos; attribute ContactField[] categories; attribute ContactField[] urls; function Contact clone(); function void remove( successCB, errorCB ); function void save( successCB, errorCB ); } ~~~ ### 說明：聯系人對象，包括聯系人的各種信息，如名稱、電話號碼、地址等。也包括新增、刪除聯系人的操作方法。 ### 屬性： - [displayName](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.displayName): 聯系人顯示的名字 - [name](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.name): 聯系人的名稱 - [nickname](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.nickname): 聯系人的昵稱 - [phoneNumbers](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.phoneNumbers): 數組，聯系人的電話 - [emails](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.emails): 數組，聯系人的郵箱 - [addresses](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.addresses): 數組，聯系人的地址 - [ims](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.ims): 數組，聯系人的即時通訊地址 - [organizations](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.organizations): 數組，聯系人所屬組織信息 - [birthday](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.birthday): 聯系人的生日 - [note](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.note): 聯系人的備注 - [photos](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.photos): 數組，聯系人的頭像 - [categories](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.categories): 數組，聯系人的組名 - [urls](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.urls): 數組，聯系人的網址 ### 方法： - [clone](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.clone): 克隆聯系人 - [remove](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.remove): 刪除聯系人 - [save](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact.save): 保存聯系人 # [displayName]() 聯系人顯示的名字 ### 說明： String 類型可選屬性聯系人顯示的名字通常有其姓和名組合而成。 # [name]() 聯系人的名稱 ### 說明： [ContactName](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactName) 類型 # [nickname]() 聯系人的昵稱 ### 說明： String 類型可選屬性 # [phoneNumbers]() 數組，聯系人的電話 ### 說明： [ContactField](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactField) 類型可選屬性 # [emails]() 數組，聯系人的郵箱 ### 說明： [ContactField](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactField) 類型可選屬性 # [addresses]() 數組，聯系人的地址 ### 說明： [ContactAddress](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactAddress) 類型可選屬性 # [ims]() 數組，聯系人的即時通訊地址 ### 說明： [ContactField](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactField) 類型可選屬性 # [organizations]() 數組，聯系人所屬組織信息 ### 說明： [ContactOrganization](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactOrganization) 類型可選屬性 # [birthday]() 聯系人的生日 ### 說明： Date 類型可選屬性 # [note]() 聯系人的備注 ### 說明： String 類型可選屬性 # [photos]() 數組，聯系人的頭像 ### 說明： [ContactField](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactField) 類型可選屬性其值為頭像圖片url地址或圖片數據： url地址：僅支持本地圖片地址，可以是絕對路徑或相對路徑，如“_doc/a.png”；圖片數據：必須符合Data URI scheme（RFC2397）格式的數據，如“image/png;base64,XXXX”，其中XXXX為base64編碼的圖片數據。在獲取聯系人時默認返回此類型的數據。 # [categories]() 數組，聯系人的組名 ### 說明： [ContactOrganization](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactOrganization) 類型可選屬性 # [urls]() 數組，聯系人的網址 ### 說明： [ContactOrganization](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactOrganization) 類型可選屬性 # [clone]() 克隆聯系人 ~~~ Contact contact.clone(); ~~~ ### 說明：克隆聯系人，創建出一個新的聯系人對象。 ### 參數： ### 返回值： [Contact](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact) : 克隆出的Contact對象 ### 示例： ~~~ var newcnt = contact.clone(); ~~~ # [remove]() 刪除聯系人 ~~~ void contact.remove( successCB, errorCB ); ~~~ ### 參數： - successCB: *( [ContactsSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsSuccessCallback) ) 必選 *刪除聯系人操作成功回調 - errorCB: *( [ContactsErrorCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsErrorCallback) ) 可選 *刪除聯系人操作失敗回調 ### 返回值： void : 無 ### 示例： ~~~ plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) { // 可通過addressbook進行通訊錄操作 var contact = addressbook.find( null, function ( contacts ) { if ( contacts.length> 0 ) { var dc = contacts[0]; dc.remove( function () { alert( "Remove "+dc.displayName+" success!" ); } }, function ( e ) { alert( "Find contact error: " e.message ); }, {filter:[{logic:"or",field:"phoneNumbers",value:"88888888"}],multi:false} ); } ); ~~~ # [save]() 保存聯系人 ~~~ void contact.save( successCB, errorCB ); ~~~ ### 說明：將聯系人數據保存到通訊錄中，操作成功將通過successCB回調函數返回保存結果，操作失敗將通過通過errorCB回調函數返回錯誤信息。 ### 參數： - successCB: *( [ContactsSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsSuccessCallback) ) 必選 *添加聯系人操作成功回調 - errorCB: *( [ContactsErrorCallback](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactsErrorCallback) ) 可選 *添加聯系人操作失敗回調 ### 返回值： void : 無 ### 示例： ~~~ plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) { // 可通過addressbook進行通訊錄操作 var contact = addressbook.create(); contact.name = {givenName:"王安"}; contact.phoneNumbers = [{type:"手機",value:"88888888",preferred:true}]; contact.save( function () { alert( "保存聯系人成功" ); }, function ( e ) { alert( "保存聯系人失敗：" + e.message ); } ); }, function ( e ) { alert( "Get address book failed: " + e.message ); } ); ~~~ # [ContactField]() JSON對象，聯系人域數據對象 ~~~ interface ContactField { attribute String type; attribute String value; attribute Boolean preferred; } ~~~ ### 說明：聯系人域數據對象，保存聯系人特定域信息。 ### 屬性： - type: *(String 類型)*聯系人域類型，如電話號碼中的“mobile”、“home”、“company” - value: *(String 類型)*聯系人域值 - preferred: *(Boolean 類型)*是否為首選項 # [ContactName]() JSON對象，聯系人名稱對象 ~~~ interface ContactName { attribute String formatted; attribute String familyName; attribute String givenName; attribute String middleName; attribute String honorificPrefix; attribute String honorificSuffix; } ~~~ ### 說明：聯系人名稱對象，保存聯系人名稱信息，如姓、名等。 ### 屬性： - formatted: *(String 類型)*聯系人的完整名稱，由其它字段組合生成 - familyName: *(String 類型)*聯系人的姓 - givenName: *(String 類型)*聯系人的名 - middleName: *(String 類型)*聯系人的中間名 - honorificPrefix: *(String 類型)*聯系人的前綴（如Mr.或Dr.） - honorificSuffix: *(String 類型)*聯系人的后綴 # [ContactAddress]() JSON對象，聯系人地址對象 ~~~ interface ContactAddress { attribute String type; attribute String formatted; attribute String streetAddress; attribute String locality; attribute String region; attribute String country; attribute String postalCode; attribute Boolean preferred; } ~~~ ### 說明：聯系人地址對象，保存聯系人地址信息，如國家、省份、城市等。 ### 屬性： - type: *(String 類型)*聯系人地址類型，如“home”表示家庭地址、“company”表示單位地址 - formatted: *(String 類型)*完整地址，由其它字段組合而成 - streetAddress: *(String 類型)*完整的街道地址 - locality: *(String 類型)*城市或地區 - region: *(String 類型)*省或地區 - country: *(String 類型)*國家 - postalCode: *(String 類型)*郵政編碼 - preferred: *(Boolean 類型)*是否為首選項 # [ContactOrganization]() JSON對象，聯系人所屬組織信息 ~~~ interface ContactOrganization { attribute String type; attribute String name; attribute String department; attribute String title; attribute Boolean preferred; } ~~~ ### 屬性： - type: *(String 類型)*聯系人所屬組織類型，如"company" - name: *(String 類型)* 聯系人所屬組織名稱 - department: *(String 類型)*聯系人所屬組織部門 - title: *(String 類型)*聯系人在組織中的職位 - preferred: *(Boolean 類型)*是否為首選項 # [ContactFindOption]() JSON對象，查找聯系人參數 ~~~ interface ContactFindOption { attribute ContactFindFilte[] filter; attribute Boolean multiple; } ~~~ ### 屬性： - filter: *([ContactFindFilter](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.ContactFindFilter) 類型)*數組，查找時的過濾器可設置為空，表示不過濾。 - multiple: *(Boolean 類型)*是否查找多個聯系人，默認值為true # [ContactFindFilter]() JSON對象，聯系人查找過濾器 ~~~ interface ContactFindFilter { attribute String logic; attribute String field; attribute String value; } ~~~ ### 屬性： - logic: *(String 類型)*區配的邏輯可取“and”、“or”、“not”，默認值為“and”。 - field: *(String 類型)*區配的聯系人域，可取聯系人的屬性名稱 - value: *(String 類型)*區配的聯系人值，可使用區配符號“?”和“*” # [AddressBookSuccessCallback]() 獲取通訊錄操作成功回調函數 ~~~ void onSuccess( addressbook ){ // Code AddressBook here } ~~~ ### 參數： - addressbook: *( [AddressBook](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.AddressBook) ) 必選 *獲取到的通訊錄對象 ### 返回值： void : 無 # [FindSuccessCallback]() 查找聯系人操作成功回調函數 ~~~ void onSuccess( contacts ){ // Find contact success. } ~~~ ### 參數： - contacts: *( [Contact](http://www.dcloud.io/docs/api/zh_cn/contacts.shtml#plus.contacts.Contact) ) 必選 *數組，查找到的聯系人對象 ### 返回值： void : 無 # [ContactsSuccessCallback]() 聯系人操作成功回調函數 ~~~ void onSuccess(){ // Operate success } ~~~ ### 參數： ### 返回值： void : 無 # [ContactsErrorCallback]() 聯系人操作失敗回調 ~~~ void onError( error ){ // Handle the error } ~~~ ### 參數： - error: *( DOMException ) 必選 *聯系人操作的錯誤信息 ### 返回值： void : 無