contacts

Contacts模块管理系统通讯录，用于可对系统通讯录进行增、删、改、查等操作。通过plus.contacts获取系统通讯录管理对象。

常量：

方法：

对象：

回调方法：

权限：

5+功能模块（permissions）

  2. {
  3. // ...
  4. "permissions":{
  5.     // ...
  6.     "Contacts": {
  7.         "description": "通讯录，访问系统联系人"
  8.     }
  9. }
  10. }
  11.

ADDRESSBOOK_PHONE

手机通讯录

  2. plus.contacts.ADDRESSBOOK_PHONE;
  3.

说明：

Number类型

通讯录类型常量，数值类型，固定值为0，用于获取系统的联系人信息。

ADDRESSBOOK_SIM

SIM卡通讯录

  2. plus.contacts.ADDRESSBOOK_SIM;
  3.

说明：

Number类型

通讯录类型常量，数值类型，固定值为1，用于获取SIM卡上的联系人信息。

平台支持

  • Android - 2.2+ (不支持): 暂未实现SIM卡联系人的访问
  • iOS - 4.3+ (不支持): 不支持SIM卡联系人的访问

getAddressBook

获取通讯录对象

  2. void plus.contacts.getAddressBook( type, succesCB, errorCB );
  3.

说明：

根据指定通讯录类型获取通讯录对象，获取通讯录对象后可对其进行增、删、改操作。

参数：

  • type: (Number)必选 要获取的通讯录类型可取通讯录类型常量，可获取手机通讯录或SIM卡通讯录。
  • successCB: (AddressBookSuccessCallback)必选 获取通讯录对象成功回调
  • errorCB: (ContactsErrorCallback)可选 获取通讯录对象失败回调

返回值：

void: 无

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8"/>
  6.     <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
  7.     <title>Contacts Example</title>
  8.     <script type="text/javascript">
  9. // 监听plusready事件  
  10. document.addEventListener( "plusready", function(){
  11.     // 扩展API加载完毕，现在可以正常调用扩展API
  12.     plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
  13.         // 可通过addressbook进行通讯录操作
  14.         alert( "Get address book success!" );
  15.     }, function ( e ) {
  16.         alert( "Get address book failed: " + e.message );
  17.     } );
  18. }, false );
  19.     </script>
  20.     </head>
  21.     <body>
  22.     </body>
  23. </html>
  24.

uni-app使用plus注意事项

AddressBook

通讯录对象

  2. interface AddressBook {
  3.     function Contact create();
  4.     function void find( contactFields, successCB, errorCB, findOptions );
  5. }
  6.

说明：

通讯录管理对象，可对系统通讯录进行联系人的增、删、改、查操作。

方法：

  • create: 创建联系人
  • find: 在通讯录中查找联系人

create

创建联系人

  2.     Contact addressbook.create();
  3.

说明：

创建一个系统联系人，并返回联系人对象，可对联系人对象进行操作设置联系人信息，如名称、地址、电话等。

参数：

无

返回值：

Contact: 联系人对象

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8"/>
  6.     <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
  7.     <title>Contacts Example</title>
  8.     <script type="text/javascript">
  9. // 监听plusready事件  
  10. document.addEventListener( "plusready", function(){
  11.     // 扩展API加载完毕，现在可以正常调用扩展API
  12.     plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
  13.         // 向通讯录中添加联系人
  14.         var contact = addressbook.create();
  15.         contact.name = {givenName:"王安"};
  16.         contact.phoneNumbers = [{type:"手机",value:"88888888",preferred:true}];
  17.         contact.save();
  18.     }, function ( e ) {
  19.         alert( "Get address book failed: " + e.message );
  20.     } );
  21. }, false );
  22.     </script>
  23.     </head>
  24.     <body>
  25.     </body>
  26. </html>
  27.

uni-app使用plus注意事项

find

在通讯录中查找联系人

  2. void addressbook.find( contactFields, successCB, errorCB, findOptions );
  3.

说明：

在通讯录中安装指定的规则查找联系人，contactFields可设定查找返回的联系人中包含的字段值，查找联系人成功时通过successCB回调返回，查找联系人失败则通过errorCB回调返回。

参数：

  • contactFields: (String[])必选 查找返回联系人中需要包含的信息可取Contact对象的属性名称，若指定为null或""或空数组则包含所有联系人信息。可通过“.”来分割子项，如“name.familyName”指定获取联系人名称中的姓；对于ContactField类型的值则可指定类型值，如“phoneNumbers.mobile”指定获取联系人的手机号码。
  • successCB: (FindSuccessCallback)必选 查找联系人操作成功回调
  • errorCB: (ContactsErrorCallback)可选 查找联系人操作失败回调
  • findOptions: (ContactFindOption)可选 查找联系人的参数

返回值：

void: 无

示例：

  2. <!DOCTYPE html>
  3. <html>
  4.     <head>
  5.     <meta charset="utf-8"/>
  6.     <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
  7.     <title>Contacts Example</title>
  8.     <script type="text/javascript">
  9. // 监听plusready事件  
  10. document.addEventListener( "plusready", function(){
  11. }, false );
  12. function find(){
  13.     plus.contacts.getAddressBook(plus.contacts.ADDRESSBOOK_PHONE, function (addressbook) {
  14.         addressbook.find(["displayName","phoneNumbers"],function(contacts){
  15.             alert(contacts.length);
  16.         }, function () {
  17.             alert("error");
  18.         },{multiple:true});
  19.     },function(e){
  20.         alert("Get address book failed: " + e.message);
  21.     });
  22. }
  24.     </script>
  25.     </head>
  26.     <body>
  27.         <button onclick="find()">Find</button>
  28.     </body>
  29. </html>
  30.

uni-app使用plus注意事项

Contact

联系人对象

  2. interface Contact {
  3.     readonly attribute String id;
  4.     attribute String displayName;
  5.     attribute ContactName name;
  6.     attribute String nickname;
  7.     attribute ContackField[] phoneNumbers;
  8.     attribute ContactField[] emails;
  9.     attribute ContactAddress[] addresses;
  10.     attribute ContactField[] ims;
  11.     attribute ContactOriganization[] organizations;
  12.     attribute Date birthday;
  13.     attribute String note;
  14.     attribute ContactField[] photos;
  15.     attribute ContactField[] categories;
  16.     attribute ContactField[] urls;
  17.     function Contact clone();
  18.     function void remove( successCB, errorCB );
  19.     function void save( successCB, errorCB );
  20. }
  21.

说明：

联系人对象，包括联系人的各种信息，如名称、电话号码、地址等。也包括新增、删除联系人的操作方法。

属性：

方法：

id

联系人的id

说明：

String类型 只读属性 可选属性

联系人id由系统分配维护，从系统获取联系人时自动赋值，再次查询时可使用此id值进行检索。注意：此值为只读属性，改写此值可能会导致无法预期的错误。

displayName

联系人显示的名字

说明：

String类型 可选属性

联系人显示的名字通常由其姓和名组合而成。

平台支持：

  • Android- 2.2+(支持): 如果name（ContactName）的givenName未设置，则会保存到givenName值中。
  • iOS- 5.1+(支持): 此属性为只读属性，修改此属性后无法保存，必须通过修改name（ContactName）的familyName、givenName、middleName值后保存。

name

联系人的名称

说明：

ContactName类型

nickname

联系人的昵称

说明：

String类型 可选属性

phoneNumbers

数组，联系人的电话

说明：

ContactField类型 可选属性

如果联系人中未保存电话信息，则返回空数组。

emails

数组，联系人的邮箱

说明：

ContactField类型 可选属性

如果联系人中未保存邮箱信息，则返回空数组。

addresses

数组，联系人的地址

说明：

ContactAddress类型 可选属性

如果联系人中未保存地址信息，则返回空数组。

ims

数组，联系人的即时通讯地址

说明：

ContactField类型 可选属性

如果联系人中未保存即时通讯地址信息，则返回空数组。

organizations

数组，联系人所属组织信息

说明：

ContactOrganization类型 可选属性

如果联系人中未保存所属组织信息，则返回空数组。

birthday

联系人的生日

说明：

Date类型 可选属性

note

联系人的备注

说明：

String类型 可选属性

photos

数组，联系人的头像

说明：

ContactField类型 可选属性

其值为头像图片url地址或图片数据：url地址：仅支持本地图片地址，可以是绝对路径或相对路径，如“_doc/a.png”；图片数据：必须符合Data URI scheme（RFC2397）格式的数据，如“image/png;base64,XXXX”，其中XXXX为base64编码的图片数据。在获取联系人时默认返回此类型的数据。

categories

数组，联系人的组名

说明：

ContactField类型 可选属性

如果联系人中未保存组名信息，则返回空数组。

urls

数组，联系人的网址

说明：

ContactField类型 可选属性

如果联系人中未保存网址信息，则返回空数组。

clone

克隆联系人

  2. Contact contact.clone();
  3.

说明：

克隆联系人，创建出一个新的联系人对象。

参数：

返回值：

Contact: 克隆出的Contact对象

示例：

  2. var newcnt = contact.clone();
  3.

uni-app使用plus注意事项

remove

删除联系人

  2. void contact.remove( successCB, errorCB );
  3.

参数：

返回值：

void: 无

示例：

  2. plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
  3.     // 可通过addressbook进行通讯录操作
  4.     var contact = addressbook.find( null, function ( contacts ) {
  5.         if ( contacts.length> 0 ) {
  6.             var dc = contacts[0];
  7.             dc.remove( function () {
  8.                 alert( "Remove "+dc.displayName+" success!" );
  9.             }
  10.         }, function ( e ) {
  11.             alert( "Find contact error: " e.message );
  12.     }, {filter:[{logic:"or",field:"phoneNumbers",value:"88888888"}],multi:false} );
  13. } );
  14.

uni-app使用plus注意事项

save

保存联系人

  2. void contact.save( successCB, errorCB );
  3.

说明：

将联系人数据保存到通讯录中，操作成功将通过successCB回调函数返回保存结果，操作失败将通过通过errorCB回调函数返回错误信息。

参数：

返回值：

void: 无

示例：

  2. plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) {
  3.     // 可通过addressbook进行通讯录操作
  4.     var contact = addressbook.create();
  5.         contact.name = {givenName:"王安"};
  6.         contact.phoneNumbers = [{type:"手机",value:"88888888",preferred:true}];
  7.         contact.save( function () {
  8.             alert( "保存联系人成功" );
  9.         }, function ( e ) {
  10.             alert( "保存联系人失败：" + e.message );
  11.         } );
  12.     }, function ( e ) {
  13.         alert( "Get address book failed: " + e.message );
  14. } );
  15.

uni-app使用plus注意事项

ContactField

JSON对象，联系人域数据对象

  2. interface ContactField {
  3.     attribute String type;
  4.     attribute String value;
  5.     attribute Boolean preferred;
  6. }
  7.

说明：

联系人域数据对象，保存联系人特定域信息。

属性：

  • 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类型)数组，查找时的过滤器可设置为空，表示不过滤。

  • 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类型)区配的联系人值，可使用区配符号“?”和“*”

示例：


// 区配所有包括姓或名中包括“王”的联系人
[{logic:"or",field:"displayNam",value:"*王*"},{logic:"or",field:"nickname",value:"*王*"}]

uni-app使用plus注意事项

AddressBookSuccessCallback

获取通讯录操作成功回调函数


void onSuccess( addressbook ){
    // Code AddressBook here
}

参数：

  • addressbook: (AddressBook)必选 获取到的通讯录对象

返回值：

void: 无

FindSuccessCallback

查找联系人操作成功回调函数


void onSuccess( contacts ){
    // Find contact success.
}

参数：

  • contacts: (Contact)必选 数组，查找到的联系人对象

返回值：

void: 无

ContactsSuccessCallback

联系人操作成功回调函数


void onSuccess(){
    // Operate success
}

参数：

返回值：

void: 无

ContactsErrorCallback

联系人操作失败回调


void onError( error ){
    // Handle the error
}

参数：

  • error: (DOMException)必选 联系人操作的错误信息

返回值：

void: 无