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: 联系人操作失败回调
权限：
5+功能模块（permissions）
{
// ...
"permissions":{
// ...
"Contacts": {
"description": "通讯录，访问系统联系人"
}
}
}
AddressBook
通讯录对象
interface AddressBook {
function Contact create();
function void find( contactFields, successCB, errorCB, findOptions );
}
说明：
通讯录管理对象，可对系统通讯录进行联系人的增、删、改、查操作。
方法：
Contact
联系人对象
interface Contact {
readonly attribute String id;
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 );
}
说明：
联系人对象，包括联系人的各种信息，如名称、电话号码、地址等。也包括新增、删除联系人的操作方法。
属性：
- id: 联系人的id
- displayName: 联系人显示的名字
- name: 联系人的名称
- nickname: 联系人的昵称
- phoneNumbers: 数组，联系人的电话
- emails: 数组，联系人的邮箱
- addresses: 数组，联系人的地址
- ims: 数组，联系人的即时通讯地址
- organizations: 数组，联系人所属组织信息
- birthday: 联系人的生日
- note: 联系人的备注
- photos: 数组，联系人的头像
- categories: 数组，联系人的组名
- urls: 数组，联系人的网址
方法：
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
类型
)数组，查找时的过滤器
可设置为空，表示不过滤。
- 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
)
必选 获取到的通讯录对象
返回值：
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
)
必选 联系人操作的错误信息