# [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 : 无
- API参考
- Accelerometer
- Audio
- Camera
- Contacts
- Device
- Downloader
- Events
- Gallery
- Geolocation
- IO
- Key
- Messaging
- NativeUI
- Navigator
- Orientation
- Proximity
- SplashScreen
- Storage
- UI
- Uploader
- InterfaceOrientation
- Runtime
- WebView
- XMLHttpRequest
- Zip
- Plugins
- Barcode
- Maps
- Payment
- Push
- Share
- Speech
- Statistic
- Native.js
- Android
- iOS