# 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 );
    }

## 说明：

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

## 方法：

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

# 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: 数组，联系人的网址

## 方法：

- clone: 克隆联系人
- remove: 删除联系人
- save: 保存联系人

# 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 ) 必选 联系人操作的错误信息

## 返回值：

void : 无