返回介绍

contacts

发布于 2021-10-21 18:08:11 字数 20309 浏览 834 评论 0 收藏 0

Contacts模块管理系统通讯录,用于可对系统通讯录进行增、删、改、查等操作。通过plus.contacts获取系统通讯录管理对象。

常量:

方法:

对象:

回调方法:

权限:

5+功能模块(permissions)


{
// ...
"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 ) 必选 获取通讯录对象成功回调

  • 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>
				

uni-app使用plus注意事项

AddressBook

通讯录对象


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

说明:

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

方法:

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

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.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>
						

uni-app使用plus注意事项

find

在通讯录中查找联系人


void addressbook.find( contactFields, successCB, errorCB, findOptions );
						

说明:

在通讯录中安装指定的规则查找联系人,contactFields可设定查找返回的联系人中包含的字段值,查找联系人成功时通过successCB回调返回,查找联系人失败则通过errorCB回调返回。

参数:

  • contactFields: ( String[] ) 必选 查找返回联系人中需要包含的信息

    可取Contact对象的属性名称,若指定为null或""或空数组则包含所有联系人信息。可通过“.”来分割子项,如“name.familyName”指定获取联系人名称中的姓;对于ContactField类型的值则可指定类型值,如“phoneNumbers.mobile”指定获取联系人的手机号码。

  • successCB: ( FindSuccessCallback ) 必选 查找联系人操作成功回调

  • errorCB: ( ContactsErrorCallback ) 可选 查找联系人操作失败回调

  • findOptions: ( 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>
						

uni-app使用plus注意事项

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

说明:

String 类型 只读属性 可选属性

联系人id由系统分配维护,从系统获取联系人时自动赋值,再次查询时可使用此id值进行检索。 注意:此值为只读属性,改写此值可能会导致无法预期的错误。

displayName

联系人显示的名字

说明:

String 类型 可选属性

联系人显示的名字通常由其姓和名组合而成。

平台支持:

  • Android - 2.2+ (支持) :

    如果name(ContactName)的givenName未设置,则会保存到givenName值中。

  • iOS - 5.1+ (支持) :

    此属性为只读属性,修改此属性后无法保存,必须通过修改name(ContactName)的familyName、givenName、middleName值后保存。

name

联系人的名称

说明:

ContactName 类型

nickname

联系人的昵称

说明:

String 类型 可选属性

phoneNumbers

数组,联系人的电话

说明:

ContactField 类型 可选属性

如果联系人中未保存电话信息,则返回空数组。

emails

数组,联系人的邮箱

说明:

ContactField 类型 可选属性

如果联系人中未保存邮箱信息,则返回空数组。

addresses

数组,联系人的地址

说明:

ContactAddress 类型 可选属性

如果联系人中未保存地址信息,则返回空数组。

ims

数组,联系人的即时通讯地址

说明:

ContactField 类型 可选属性

如果联系人中未保存即时通讯地址信息,则返回空数组。

organizations

数组,联系人所属组织信息

说明:

ContactOrganization 类型 可选属性

如果联系人中未保存所属组织信息,则返回空数组。

birthday

联系人的生日

说明:

Date 类型 可选属性

note

联系人的备注

说明:

String 类型 可选属性

photos

数组,联系人的头像

说明:

ContactField 类型 可选属性

其值为头像图片url地址或图片数据: url地址:仅支持本地图片地址,可以是绝对路径或相对路径,如“_doc/a.png”; 图片数据:必须符合Data URI scheme(RFC2397)格式的数据,如“image/png;base64,XXXX”,其中XXXX为base64编码的图片数据。在获取联系人时默认返回此类型的数据。

categories

数组,联系人的组名

说明:

ContactField 类型 可选属性

如果联系人中未保存组名信息,则返回空数组。

urls

数组,联系人的网址

说明:

ContactField 类型 可选属性

如果联系人中未保存网址信息,则返回空数组。

clone

克隆联系人


Contact contact.clone();
						

说明:

克隆联系人,创建出一个新的联系人对象。

参数:

    返回值:

    Contact : 克隆出的Contact对象

    示例:

    
    var newcnt = contact.clone();
    						

    uni-app使用plus注意事项

    remove

    删除联系人

    
    void contact.remove( successCB, errorCB );
    						

    参数:

    返回值:

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

    uni-app使用plus注意事项

    save

    保存联系人

    
    void contact.save( successCB, errorCB );
    						

    说明:

    将联系人数据保存到通讯录中,操作成功将通过successCB回调函数返回保存结果,操作失败将通过通过errorCB回调函数返回错误信息。

    参数:

    返回值:

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

    uni-app使用plus注意事项

    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 类型 )区配的联系人值,可使用区配符号“?”和“*”

    示例:

    
    // 区配所有包括姓或名中包括“王”的联系人
    [{logic:"or",field:"displayNam",value:"*王*"},{logic:"or",field:"nickname",value:"*王*"}]
    				

    uni-app使用plus注意事项

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

      返回值:

      void : 无

      如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。

      扫码二维码加入Web技术交流群

      发布评论

      需要 登录 才能够评论, 你可以免费 注册 一个本站的账号。

      列表为空,暂无数据
        我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击“接受”或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。