# [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 : 无