contacts
Contacts模块管理系统通讯录,用于可对系统通讯录进行增、删、改、查等操作。通过plus.contacts获取系统通讯录管理对象。
常量:
- ADDRESSBOOK_PHONE: 手机通讯录
- ADDRESSBOOK_SIM: SIM卡通讯录
方法:
- getAddressBook: 获取通讯录对象
对象:
- AddressBook: 通讯录对象
- Contact: 联系人对象
- ContactField: JSON对象,联系人域数据对象
- ContactName: JSON对象,联系人名称对象
- ContactAddress: JSON对象,联系人地址对象
- ContactOrganization: JSON对象,联系人所属组织信息
- ContactFindOption: JSON对象,查找联系人参数
- ContactFindFilter: JSON对象,联系人查找过滤器
回调方法:
- AddressBookSuccessCallback: 获取通讯录操作成功回调函数
- FindSuccessCallback: 查找联系人操作成功回调函数
- ContactsSuccessCallback: 联系人操作成功回调函数
- ContactsErrorCallback: 联系人操作失败回调
权限:
permissions
"Contacts": { "description": "访问系统联系人" }
ADDRESSBOOK_PHONE
手机通讯录
plus.contacts.ADDRESSBOOK_PHONE;
说明:
Number 类型
通讯录类型常量,数值类型,固定值为0,用于获取系统的联系人信息。
ADDRESSBOOK_SIM
SIM卡通讯录
plus.contacts.ADDRESSBOOK_SIM;
说明:
Number 类型
通讯录类型常量,数值类型,固定值为1,用于获取SIM卡上的联系人信息。
平台支持
- Android2.2+ (不支持): 暂未实现SIM卡联系人的访问
- iOS4.3+ (不支持): 不支持SIM卡联系人的访问
- WP7.5+ (不支持): 不支持SIM卡联系人的访问
getAddressBook
获取通讯录对象
void plus.contacts.getAddressBook( type, succesCB, errorCB );
说明:
根据指定通讯录类型获取通讯录对象,获取通讯录对象后可对其进行增、删、改操作。
参数:
- type:
(
Number
)
必选 要获取的通讯录类型
可取通讯录类型常量,可获取手机通讯录或SIM卡通讯录。 - successCB:
(
AddressBookSuccessCallback
)
必选 获取通讯录对象成功回调
- errorCB:
(
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
创建联系人
Contact addressbook.create();
说明:
创建一个系统联系人,并返回联系人对象,可对联系人对象进行操作设置联系人信息,如名称、地址、电话等。
参数:
无
返回值:
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.firstname = "王安"; 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:
(
DOMString
)
必选 查找返回联系人中需要包含的信息
可取Contact对象的属性名称,若指定为null或""或空数组则包含所有联系人信息。可通过“.”来分割子项,如“name.familyName”指定获取联系人名称中的姓;对于ContactField类型的值则可指定类型值,如“phoneNumbers.mobile”指定获取联系人的手机号码。 - successCB:
(
FindSuccessCallback
)
必选 查找联系人操作成功回调
- errorCB:
(
ContactsErrorCallback
)
可选 查找联系人操作失败回调
- findOptions:
(
ContactFindOption
)
必选 查找联系人的参数
返回值:
void : 无Contact
联系人对象
interface Contact { attribute DOMString displayName; attribute ContactName name; attribute DOMString nickname; attribute ContackField[] phoneNumbers; attribute ContactField[] emails; attribute ContactAddress[] addresses; attribute ContactField[] ims; attribute ContactOriganization[] organizations; attribute Date birthday; attribute DOMString note; attribute ContactField[] photos; attribute ContactField[] categories; attribute ContactField[] urls; function Contact clone(); function void remove( successCB, errorCB ); function void save( successCB, errorCB ); }
说明:
联系人对象,包括联系人的各种信息,如名称、电话号码、地址等。也包括新增、删除联系人的操作方法。
属性:
- displayName: 联系人显示的名字
- name: 联系人的名称
- nickname: 联系人的昵称
- phoneNumbers: 数组,联系人的电话
- emails: 数组,联系人的邮箱
- addresses: 数组,联系人的地址
- ims: 数组,联系人的即时通讯地址
- organizations: 数组,联系人所属组织信息
- birthday: 联系人的生日
- note: 联系人的备注
- photos: 数组,联系人的头像
- categories: 数组,联系人的组名
- urls: 数组,联系人的网址
方法:
displayName
联系人显示的名字
说明:
DOMString 类型 可选属性
联系人显示的名字通常有其姓和名组合而成。
name
联系人的名称
说明:
ContactName 类型
nickname
联系人的昵称
说明:
DOMString 类型 可选属性
phoneNumbers
数组,联系人的电话
说明:
ContactField 类型 可选属性
emails
数组,联系人的邮箱
说明:
ContactField 类型 可选属性
addresses
数组,联系人的地址
说明:
ContactAddress 类型 可选属性
ims
数组,联系人的即时通讯地址
说明:
ContactField 类型 可选属性
organizations
数组,联系人所属组织信息
说明:
ContactOrganization 类型 可选属性
birthday
联系人的生日
说明:
Date 类型 可选属性
note
联系人的备注
说明:
DOMString 类型 可选属性
photos
数组,联系人的头像
说明:
ContactField 类型 可选属性
其值为头像图片url地址或图片数据: url地址:仅支持本地图片地址,可以是绝对路径或相对路径,如“_doc/a.png”; 图片数据:必须符合Data URI scheme(RFC2397)格式的数据,如“image/png;base64,XXXX”,其中XXXX为base64编码的图片数据。在获取联系人时默认返回此类型的数据。
categories
数组,联系人的组名
说明:
ContactOrganization 类型 可选属性
urls
数组,联系人的网址
说明:
ContactOrganization 类型 可选属性
clone
克隆联系人
Contact contact.clone();
说明:
克隆联系人,创建出一个新的联系人对象。
参数:
返回值:
Contact : 克隆出的Contact对象示例:
var newcnt = contact.clone();
remove
删除联系人
void contact.remove( successCB, errorCB );
参数:
- successCB:
(
ContactsSuccessCallback
)
必选 删除联系人操作成功回调
- errorCB:
(
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.firstName + " " + dc.lastName + " 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
)
必选 添加联系人操作成功回调
- errorCB:
(
ContactsErrorCallback
)
可选 添加联系人操作失败回调
返回值:
void : 无示例:
plus.contacts.getAddressBook( plus.contacts.ADDRESSBOOK_PHONE, function( addressbook ) { // 可通过addressbook进行通讯录操作 var contact = addressbook.create(); contact.firstname = "王安"; 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 DOMString type; attribute DOMString value; attribute Boolean preferred; }
说明:
联系人域数据对象,保存联系人特定域信息。
属性:
- type: (DOMString
类型
)联系人域类型,如电话号码中的“mobile”、“home”、“company”
- value: (DOMString
类型
)联系人域值
- preferred: (Boolean
类型
)是否为首选项
ContactName
JSON对象,联系人名称对象
interface ContactName { attribute DOMString formatted; attribute DOMString familyName; attribute DOMString givenName; attribute DOMString middleName; attribute DOMString honorificPrefix; attribute DOMString honorificSuffix; }
说明:
联系人名称对象,保存联系人名称信息,如姓、名等。
属性:
- formatted: (DOMString
类型
)联系人的完整名称,由其它字段组合生成
- familyName: (DOMString
类型
)联系人的姓
- givenName: (DOMString
类型
)联系人的名
- middleName: (DOMString
类型
)联系人的中间名
- honorificPrefix: (DOMString
类型
)联系人的前缀(如Mr.或Dr.)
- honorificSuffix: (DOMString
类型
)联系人的后缀
ContactAddress
JSON对象,联系人地址对象
interface ContactAddress { attribute DOMString type; attribute DOMString formatted; attribute DOMString streetAddress; attribute DOMString locality; attribute DOMString region; attribute DOMString country; attribute DOMString postalCode; attribute Boolean preferred; }
说明:
联系人地址对象,保存联系人地址信息,如国家、省份、城市等。
属性:
- type: (DOMString
类型
)联系人地址类型,如“home”表示家庭地址、“company”表示单位地址
- formatted: (DOMString
类型
)完整地址,由其它字段组合而成
- streetAddress: (DOMString
类型
)完整的街道地址
- locality: (DOMString
类型
)城市或地区
- region: (DOMString
类型
)省或地区
- country: (DOMString
类型
)国家
- postalCode: (DOMString
类型
)邮政编码
- preferred: (Boolean
类型
)是否为首选项
ContactOrganization
JSON对象,联系人所属组织信息
interface ContactOrganization { attribute DOMString type; attribute DOMString name; attribute DOMString department; attribute DOMString title; attribute Boolean preferred; }
属性:
- type: (DOMString
类型
)联系人所属组织类型,如"company"
- name: (DOMString
类型
) 联系人所属组织名称
- department: (DOMString
类型
)联系人所属组织部门
- title: (DOMString
类型
)联系人在组织中的职位
- preferred: (Boolean
类型
)是否为首选项
ContactFindOption
JSON对象,查找联系人参数
interface ContactFindOption { attribute ContactFindFilte[] filter; attribute Boolean multiple; }
属性:
- filter: (ContactFindFilter
类型
)数组,查找时的过滤器
可设置为空,表示不过滤。
- multiple: (Boolean
类型
)是否查找多个联系人,默认值为true
ContactFindFilter
JSON对象,联系人查找过滤器
interface ContactFindFilter { attribute DOMString logic; attribute DOMString field; attribute DOMString value; }
属性:
- logic: (DOMString
类型
)区配的逻辑
可取“and”、“or”、“not”,默认值为“and”。
- field: (DOMString
类型
)区配的联系人域,可取联系人的属性名称
- value: (DOMString
类型
)区配的联系人值,可使用区配符号“?”和“*”
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
)
必选 联系人操作的错误信息