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

通讯录对象

interface AddressBook {
	function Contact create();
	function void find( contactFields, successCB, errorCB, findOptions );
}
				

说明：

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

方法：

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

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: 联系人显示的名字
• 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 : 无