PhoneGap API帮助文档翻译—Contacts（通讯录）

acntw 2013-05-03

文章源自:http://blog.csdn.net/phonegapcn/article/details/6695642

contacts对象提供对设备通讯录数据库的访问。

方法：
  • contacts.create
  • contacts.find
参数：
  • contactFields
  • contactSuccess
  • contactError
  • contactFindOptions
对象：
  • Contact
  • ContactName
  • ContactField
  • ContactAddress
  • ContactOrganization
  • ContactFindOptions
  • ContactError

contacts.create

返回一个新的Contact对象。

var contact = navigator.service.contacts.create(properties);

 说明：

contacts.create是用于创建并返回一个新Contact对象的同步函数。
该方法不会将新创建的Contact对象持久化到设备的通讯录数据库。可通过调用Contact.save方法将新建的Contact对象持久化到设备。
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

var myContact = navigator.service.contacts.create({"displayName": "Test User"});

完整的范例：

<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>

<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">

	// 等待加载PhoneGap
	document.addEventListener("deviceready", onDeviceReady, false);

	// PhoneGap加载完毕
	function onDeviceReady() {
		var myContact = navigator.service.contacts.create({"displayName": "Test User"});
		myContact.gender = "male";
		console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender");
	} 

</script>
</head>
<body>
 <h1>Example</h1>
 <p>Create Contact</p>
</body>
</html>

 contacts.find

 查询设备通讯录数据库，并返回包含指定字段的一个或多个Contact对象。

navigator.service.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

 说明：

contacts.find是一个查询设备通讯录数据库并返回Contact对象数组的同步函数。返回的对象会被传递给contactSuccess回调函数的contactSuccess参数。
用户必须在contactFields参数中指定联系人的字段作为搜索限定符。系统传递给contactSuccess回调函数的Contact对象属性只会包含在contactFields参数中定义的字段。如果定义0长度的contactFields参数会导致返回的Contact对象只填充了id属性。
contactFindOptions.filter字符串可以用来作为查询通讯录数据库时的搜索过滤器。如果设定了该参数，系统会对通讯录数据库中所有联系人按照contactFields参数中指定的每个字段进行不区分大小写的部分值匹配。任何指定的字段符合过滤器所要求的内容的联系人数据都会被返回。
属性：
  • contactFields：Contact字段，用作搜索限定符。在返回的Contact对象中只有这些字段有值。（DOMString[]类型）[必填]
  • contactSuccess：通讯录获取成功时调用的回调函数，将从通讯录数据库获取的联系人作为参数。[必填]
  • contactError：错误回调函数，当发生错误的时候被调用。[可选]
  • contactFindOptions：用于过滤通讯录的搜索选项。[可选]
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

function onSuccess(contacts) {  
    alert('Found ' + contacts.length + ' contacts.');  
}  
  
function onError() {  
    alert('onError!');  
}  
  
// 从所有联系人中查找任意名字字段中包含“Bob”的联系人  
var options = new ContactFindOptions();  
options.filter="Bob";  
var fields = ["displayName", "name"];  
navigator.service.contacts.find(fields, onSuccess, onError, options);

完整的范例：

<!DOCTYPE html>
<html>
<head>
<title>Contact Example</title>

<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">

	// PhoneGap加载完毕
	function onDeviceReady() {

		// 从所有联系人中查找任意名字字段中包含“Bob”的联系人
		var options = new ContactFindOptions();
		options.filter="Bob";
		var fields = ["displayName", "name"];
		navigator.service.contacts.find(fields, onSuccess, onError, options);
	}

	// onSuccess: 获取当前联系人结果集的快照
	function onSuccess(contacts) {
		for (var i=0; i<contacts.length; i++) {
			console.log("Display Name = " + contacts[i].displayName);
		}
	}

	// onError: 获得联系人失败
	function onError() {
		alert('onError!');
	}

</script>
</head>
<body>
 <h1>Example</h1>
 <p>Find Contact</p>
</body>
</html>

Contact

包含描述联系人的属性，比如用户的个人或者商务联系方式。

属性：
  • id：全局唯一标识符。（DOMString类型）
  • displayname：联系人显示名称，适合向最终用户展示的联系人名称。（DOMString类型）
  • name：联系人姓名所有部分的对象。（CantactName类型）
  • nickname：昵称，对联系人的非正式称呼。（DOMString类型）
  • phoneNumbers：联系人所有联系电话的数组。（ContactField[]类型）
  • emails：联系人所有email地址的数组。（ContactField[]类型）
  • addrsses：联系人所有联系地址的数组。（ContactAddresses[]类型）
  • ims：联系人所有IM地址的数组。（ContactField[]类型）
  • organizations：联系人所属所有组织的数组。（ContactOrganization[]类型）
  • birthday：联系人的生日。（日期类型）
  • note：联系人的注释信息。（DOMString类型）
  • photos：联系人所有照片的数组.（ContactField[]类型）
  • categories：联系人所属的所有用户自定义类别的数组。（ContactField[]类型）
  • urls：与联系人相关网页的数组。（ContactField[]类型）
方法：
  • clone：返回一个新的Contact对象，它是调用对象的深度拷贝，其id属性被设为null。
  • remove：从通讯录数据库中删除联系人。当删除不成功的时候，触发以ContactError对象为参数的错误处理回调函数。
  • save：将一个新联系人存储到通讯录数据库，如果通讯录数据库中已经包含与其ID相同的记录，则更新该已有记录。
详述：
Contact对象代表一个用户联系人。Contacts可以在设备通讯录数据库中被创建，存储或者删除，同样也可以使用 contacts.find方法从数据库中进行检索。
备注：并不是所有的设备平台都支持以上列出的所有联系人字段。请通过查看每个平台的特异情况描述部分，了解每个平台分别支持哪些字段。
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

Save 简单的范例：

function onSuccess(contacts) {  
    alert("Save Success");  
    }  
  
function onError(contactError) {  
    alert("Error = " + contactError.code);  
}  
  
// 建立一个新的联系人对象  
var contact = navigator.service.contacts.create();  
contact.displayName = "Plumber";  
contact.nickname = "Plumber";       //同时指定以支持所有设备  
  
// 填充一些字段  
var name = new ContactName();   
name.givenName = "Jane";  
name.familyName = "Doe";  
contact.name = name;  
  
// 存储到设备上  
contact.save(onSuccess,onError);

 Clone 简单的范例：

// 克隆联系人对象  
var clone = contact.clone();  
clone.name.givenName = "John";  
console.log("Original contact name = " + contact.name.givenName);  
console.log("Cloned contact name = " + clone.name.givenName);

 Remove 简单的范例：

function onSuccess() {
	alert("Removal Success");
}
function onError(contactError) {
	alert("Error = " + contactError.code);
}
// 从设备上删除该联系人
contact.remove(onSuccess,onError);

 完整的范例：

<!DOCTYPE html>  
<html>  
<head>  
<title>Contact Example</title>  
  
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8">  
  
    // 等待加载PhoneGap  
    document.addEventListener("deviceready", onDeviceReady, false);  
      
    // PhoneGap加载完毕  
    function onDeviceReady() {  
      
        // 创建联系人  
        var contact = navigator.service.contacts.create();  
        contact.displayName = "Plumber";  
        contact.nickname = "Plumber";       //同时指定以支持所有设备  
        var name = new ContactName();  
        name.givenName = "Jane";  
        name.familyName = "Doe";  
        contact.name = name;  
      
        // 存储联系人  
        contact.save(onSaveSuccess,onSaveError);  
      
        // 克隆联系人  
        var clone = contact.clone();  
        clone.name.givenName = "John";  
        console.log("Original contact name = " + contact.name.givenName);  
        console.log("Cloned contact name = " + clone.name.givenName);  
      
        // 删除联系人  
        contact.remove(onRemoveSuccess,onRemoveError);  
    }  
      
        // onSaveSuccess: 返回当前保存成功的联系人数据的快照  
    function onSaveSuccess(contacts) {  
        alert("Save Success");  
    }  
      
    // onSaveError: 获取联系人数据失败  
    function onSaveError(contactError) {  
        alert("Error = " + contactError.code);  
    }  
      
    // onRemoveSuccess: 返回当前删除成功的联系人数据的快照  
    function onRemoveSuccess(contacts) {  
        alert("Removal Success");  
    }  
      
    // onRemoveError: 获取联系人数据失败  
    function onRemoveError(contactError) {  
        alert("Error = " + contactError.code);  
    }  
  
</script>  
</head>  
<body>  
 <h1>Example</h1>  
 <p>Find Contact</p>  
</body>  
</html>
Android 2.X的特异情况：
  • categories：Android2.X设备上不支持该属性，返回值总是null。
Android 1.X的特异情况：
  • name：Android1.x设备上不支持该属性，返回值总是null。
  • nickname：Android1.x设备上不支持该属性，返回值总是null。
  • birthday： Android1.x设备上不支持该属性，返回值总是null。
  • photos：Android1.x设备上不支持该属性，返回值总是null。
  • categories：Android1.x设备上不支持该属性，返回值总是null。
  • urls：Android1.x设备上不支持该属性，返回值总是null。
BlackBerry WebWorks (OS 5.0或更高版本)的特异情况：
  • id：支持，系统在存储联系人记录时自动分配。
  • displayname：支持，存储到BlackBerry的user1字段。
  • nickname：不支持该属性，返回值总是null。
  • phoneNumber：部分支持，类型为“home”的电话号码将被存储到BlackBerry的homePhone1和homePhone2字段；类型为“work”将被存储到workPhone1和workPhone2字段；类型为“mobile”将被存储到mobilePhone；类型为“fax”将被存储到faxPhone字段；类型为“pager”将被存储到pagerPhone；如果电话号码不属于以上类型则被存储到otherPhone字段。
  • emails：部分支持，前三个邮件地址将被分别存储到BlackBerry的email1、email2和email3这三个字段。
  • addresses：部分支持，第一和第二个地址将被分别存储到BlackBerry的homeAddress以及workAddress字段。
  • ims： 不支持该属性，返回值总是null。
  • organizations：部分支持，第一个组织的名称和职务将被分别存储到BlackBerry的company和title字段。
  • photos：部分支持，只支持一个缩略图大小的照片。要设置一个联系人照片的话，可以通过传递一个Base64编码的图片或一个指向图片的URL，该图片在存储到联系人数据库之前会被缩小。联系人照片会以Base64编码形式的图片返回。
  • categories：部分支持，只支持“Business”和“Personal”这两个类别。
  • urls：部分支持，第一个url将被存储到BlackBerry的webpage字段。
iOS的特异情况：
  • displayName：iOS不支持该属性。除非没有给联系人指定ContactName，否则该字段返回值总是null。如果没有指定ContactName，系统会根据有无设定值的情况依次返回composite name，nickename或空字符串。
  • birthday：对于输入而言，必须为其提供一个JavaScript日期对象。同样其返回值也是JavaScript日期对象。
  • photos：传回的照片存储在应用程序的临时目录，同时返回指向该照片的文件URL。临时目录在应用程序退出后被删除。
  • categories：目前不支持该属性，返回值总是null。

ContactAddress

包含Contact对象的地址属性。

属性：
  • pref：如果该ContactAddress包含用户的首选值，则设置为true。（布尔类型）
  • type：用来标示该地址对应的类型的字符串（例如：“home”）。（DOMString类型）
  • formatted：完整的地址显示格式。（DOMString格式）
  • streeAddress：完整的街道地址。（DOMString格式）
  • locality：城市或地区。（DOMString格式）
  • region：州或省份。（DOMString格式）
  • postalCode：邮政编码。（DOMString格式）
  • country：国家名称。（DOMString格式）
详述：
ContactAddress对象存储一个联系人的单个地址。一个Contact对象可以拥有一个或多个地址，这些地址存储在一个ContactAddress[]数组中。
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

// 显示所有联系人的地址信息  
function onSuccess(contacts) {  
    for (var i=0; i< contacts.length; i++) {  
        for (var j=0; j< contacts[i].addresses.length; j++) {  
            alert("Pref: " + contacts[i].addresses[j].pref + "\n" +  
                "Type: " + contacts[i].addresses[j].type + "\n" +  
                "Formatted: " + contacts[i].addresses[j].formatted + "\n" +   
                "Street Address: "  + contacts[i].addresses[j].streetAddress + "\n" +   
                "Locality: "  + contacts[i].addresses[j].locality + "\n" +   
                "Region: "  + contacts[i].addresses[j].region + "\n" +   
                "Postal Code: "  + contacts[i].addresses[j].postalCode + "\n" +   
                "Country: "  + contacts[i].addresses[j].country);  
        }  
    }  
}  
  
function onError(contactError) {  
    alert('onError!');  
}  
  
// 从全部联系人中查找  
var options = new ContactFindOptions();  
options.filter="";   
var filter = ["displayName","addresses"];  
navigator.contacts.find(filter, onSuccess, onError, options);

 完整的范例：

<!DOCTYPE html>  
<html>  
<head>  
<title>Contact Example</title>  
  
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8">  
  
    // 等待加载PhoneGap  
    document.addEventListener("deviceready", onDeviceReady, false);  
      
    // PhoneGap加载完毕  
    function onDeviceReady() {  
      
        // 从全部联系人中进行搜索  
        var options = new ContactFindOptions();  
        options.filter="";  
        var filter = ["displayName","addresses"];  
        navigator.service.contacts.find(filter, onSuccess, onError, options);  
    }  
      
    // onSuccess: 返回当前联系人结果集的快照  
    function onSuccess(contacts) {  
        // 显示所有联系人的地址信息  
        for (var i=0; i<contacts.length; i++) {  
            for (var j=0; j<contacts[i].addresses.length; j++) {  
                alert("Pref: " + contacts[i].addresses[j].pref + "\n" +  
                    "Type: " + contacts[i].addresses[j].type + "\n" +  
                    "Formatted: " + contacts[i].addresses[j].formatted + "\n" +  
                    "Street Address: "  + contacts[i].addresses[j].streetAddress + "\n" +  
                    "Locality: "  + contacts[i].addresses[j].locality + "\n" +  
                    "Region: "  + contacts[i].addresses[j].region + "\n" +  
                    "Postal Code: "  + contacts[i].addresses[j].postalCode + "\n" +  
                    "Country: "  + contacts[i].addresses[j].country);  
            }  
        }  
    }  
      
    // onError: 获取联系人结果集失败  
    function onError() {  
        alert('onError!');  
    }  
  
</script>  
</head>  
<body>  
 <h1>Example</h1>  
 <p>Find Contact</p>  
</body>  
</html>
Android 2.X 的特异情况
  • pref：Android2.X设备上不支持该属性，返回值总是false。
Android 1.X 的特异情况：
  • pref：Android1.X设备上不支持该属性，返回值总是false。
  • type：Android1.X设备上不支持该属性，返回值总是null。
  • streetAddress：Android1.X设备上不支持该属性，返回值总是null。
  • locality：Android1.X设备上不支持该属性，返回值总是null。
  • region：Android1.X设备上不支持该属性，返回值总是null。
  • postalCode：Android1.X设备上不支持该属性，返回值总是null。
  • country：Android1.X设备上不支持该属性，返回值总是null。
BlackBerry WebWorks (OS 5.0或更高版本)的特异情况：
  • pref：BlackBerry设备上不支持该属性，返回值总是false。
  • type：部分支持，对于一个联系人对象只能分别存储一个“Work”和一个“Home”类型的地址。
  • formatted：部分支持，将返回所有BlackBerry 地址字段的串联。
  • streetAddress：支持，将返回BlackBerry address1和address2两个地址字段的串联。
  • locality：支持，存储到BlackBerry city字段。
  • region：支持，存储到BlackBerry stateProvince字段。
  • postalCode：支持，存储到BlackBerry zipPostal字段。
  • country：支持。
iOS的特异情况：
  • pref：iOS设备上不支持该属性，返回值总是false。
  • formatted：目前不支持。

ContactField

Contact对象中支持的通用字段类型，存储为ContactField对象的属性包括：email addresses、phone numbers和urls等。
属性：
  • type：说明当前字段类型的字符串（例如：“home”）。（DOMString类型）
  • value：字段的值（例如：电话号码或邮件地址）。（DOMString类型）
  • pref：如果当前ContactField包含用户的首选项，则设置为true。（布尔类型）
详述：
ContactField 对象是一个可重用的组件，用于支持通用方式的联系人字段。每个ContactField对象都包含一个值属性、一个类型属性和一个首选项属性。一个 Contact对象将多个属性分别存储到多个ContactField[]数组中，例如电话号码与邮件地址等。
在大多数情况下，ContactField对象中的type属性并没有事先确定值。例如，一个电话号码的type属性值可以是：“home”、“work”、“mobile”、“iPhone”或其他相应特定设备平台的联系人数据库所支持的值。然而对于Contact对象的photos字段，PhoneGap使用type字段来表示返回的图像格式。如果value属性包含的是一个指向照片图像的URL，PhoneGap对于type会返回“url”；如果value属性包含的是图像的Base64编码字符串，PhoneGap对于type会返回“base64”。
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

// 建立一个新的联系人记录  
var contact = navigator.service.contacts.create();  
  
// 存储联系人电话号码到ContactField[]数组  
var phoneNumbers = [3];  
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);  
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true);     // 首选项  
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);  
contact.phoneNumbers = phoneNumbers;  
  
// 保存联系人  
contact.save();

 完整的范例：

<!DOCTYPE html>  
<html>  
<head>  
<title>Contact Example</title>  
  
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8">  
  
    // 等待加载PhoneGap  
    document.addEventListener("deviceready", onDeviceReady, false);  
      
    // PhoneGap加载完毕  
    function onDeviceReady() {  
      
        // 建立一个新的联系人记录  
        var contact = navigator.service.contacts.create();  
      
        //存储联系人电话号码到ContactField[]数组  
        var phoneNumbers = [3];  
        phoneNumbers[0] = new ContactField('work', '212-555-1234', false);  
        phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true);     // 首选项  
        phoneNumbers[2] = new ContactField('home', '203-555-7890', false);  
        contact.phoneNumbers = phoneNumbers;  
      
        // 存储联系人  
        contact.save();  
      
        // 搜索联系人列表，返回符合条件联系人的显示名及电话号码  
        var options = new ContactFindOptions();  
        options.filter="";  
        filter = ["displayName","phoneNumbers"];  
        navigator.service.contacts.find(filter, onSuccess, onError, options);  
    }  
      
    // onSuccess：返回联系人结果集的快照  
    function onSuccess(contacts) {  
        for (var i=0; i< contacts.length; i++) {  
        // 显示电话号码  
            for (var j=0; j< contacts[i].phoneNumbers.length; j++) {  
                alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" +  
                    "Value: "  + contacts[i].phoneNumbers[j].value + "\n" +  
                    "Preferred: "  + contacts[i].phoneNumbers[j].pref);  
            }  
        }  
    }  
      
    // onError: 获取联系人结果集失败  
    function onError() {  
        alert('onError!');  
    }  
  
</script>  
</head>  
<body>  
 <h1>Example</h1>  
 <p>Find Contact</p>  
</body>  
</html>
Android 的特异情况：
  • pref：Android设备上不支持该属性，返回值总是false。
BlackBerry WebWorks (OS 5.0或更高版本)的特异情况：
  • type：部分支持，用于电话号码。
  • value：支持。
  • pref：不支持该属性，返回值总是false。
iOS的特异情况：
  • pref：iOS设备上不支持该属性，返回值总是false。

ContactFindOptions

包含用于contacts.find操作对所有联系人进行过滤的属性。
属性：
  • filter：用于查找联系人的搜索字符串。(DOMString类型) (默认值为空字符串)
  • multiple：决定查收操作是否可以返回多条联系人记录。(布尔类型) (默认值为false)
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

// 成功后的回调函数  
function onSuccess(contacts) {  
    for (var i=0; i< ;contacts.length; i++) {  
        alert(contacts[i].displayName);  
    }  
}  
  
// 出错后的回调函数  
function onError() {  
    alert('onError!');  
}  
  
// 指定联系人搜索条件  
var options = new ContactFindOptions();  
options.filter="";          // 空搜索字符串将返回所有联系人                      
options.multiple=true;      // 可返回多条记录  
filter = ["displayName"];   // 仅返回contact.displayName字段  
  
// 查找联系人  
navigator.service.contacts.find(filter, onSuccess, onError, options);

 完整的范例：

<!DOCTYPE html>  
<html>  
<head>  
<title>Contact Example</title>  
  
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8">  
  
    // 等待加载PhoneGap  
    document.addEventListener("deviceready", onDeviceReady, false);  
      
    // PhoneGap加载完毕  
    function onDeviceReady() {  
      
        // 指定联系人搜索条件  
        var options = new ContactFindOptions();  
        options.filter="";          // 空搜索字符串将返回所有联系人  
        options.multiple=true;      // 可返回多条记录          
        filter = ["displayName"];   // 仅返回contact.displayName字段  
      
        // 查找联系人  
        navigator.service.contacts.find(filter, onSuccess, onError, options);  
    }  
      
    // onSuccess: 返回当前联系人记录集的快照  
    function onSuccess(contacts) {  
        for (var i=0; i< contacts.length; i++) {  
        alert(contacts[i].displayName);  
    }  
    }  
      
    // onError: 获取联系人失败  
    function onError() {  
        alert('onError!');  
    }  
  
</script>  
</head>  
<body>  
 <h1>Example</h1>  
 <p>Find Contact</p>  
</body>  
</html>

 ContactName

包含Contact对象的名称属性。
属性：
  • formatted：联系人的全名。（DOMString类型）
  • familyName：联系人的姓氏。 （DOMString类型）
  • givenName：联系人的名字。（DOMString类型）
  • middleName：联系人的中间名。（DOMString类型）
  • honorificPrefix：敬语前缀。（例如：Mr.或Dr.）(DOMString类型)
  • honorificSuffix：敬语后缀。（例如：Esq.）(DOMString)
详述：
ContactName对象存储联系人的name属性。
支持的平台：
  • Android 2.X
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

function onSuccess(contacts) {  
    for (var i=0; i< ;contacts.length;i++) {  
        alert('Formatted: ' + contacts[i].name.formatted + '\n' +  
            'Family Name: '  + contacts[i].name.familyName + '\n' +  
            'Given Name: '  + contacts[i].name.givenName + '\n' +  
            'Middle Name: '  + contacts[i].name.middleName + '\n' +  
            'Suffix: '  + contacts[i].name.honorificSuffix + '\n' +  
            'Prefix: '  + contacts[i].name.honorificSuffix);  
    }  
}  
  
function onError() {  
    alert('onError!');  
}  
  
var options = new ContactFindOptions();  
options.filter="";  
filter = ["displayName","name"];  
  
navigator.service.contacts.find(filter, onSuccess, onError, options);

 完整的范例：

<!DOCTYPE html>  
<html>  
<head>  
<title>Contact Example</title>  
  
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8">  
  
    // 等待加载PhoneGap  
    document.addEventListener("deviceready", onDeviceReady, false);  
      
    // PhoneGap加载完毕  
    function onDeviceReady() {  
        var options = new ContactFindOptions();  
        options.filter="";  
        filter = ["displayName"];  
        navigator.service.contacts.find(filter, onSuccess, onError, options);  
    }  
      
    // onSuccess: 返回联系人结果集的快照  
    function onSuccess(contacts) {  
        for (var i=0; i< contacts.length; i++) {  
            alert("Formatted: " + contacts[i].name.formatted + "\n" +  
                "Family Name: "  + contacts[i].name.familyName + "\n" +  
                "Given Name: "  + contacts[i].name.givenName + "\n" +  
                "Middle Name: "  + contacts[i].name.middleName + "\n" +  
                "Suffix: "  + contacts[i].name.honorificSuffix + "\n" +  
                "Prefix: "  + contacts[i].name.honorificPrefix);  
        }  
    }  
      
    // onError: 获取联系人结果集失败  
    function onError() {  
        alert('onError!');  
    }  
  
</script>  
</head>  
<body>  
 <h1>Example</h1>  
 <p>Find Contact</p>  
</body>  
</html>
Android 的特异情况：
  • formatted：部分支持，将返回honorificPrefix、givenName、middleName、familyName和honorificSuffix的串联结果，但不会单独存储。
BlackBerry WebWorks (OS 5.0或更高版本)的特异情况：
  • formatted：部分支持，将返回BlackBerry firstName和lastName两个字段的串联结果。
  • familyName：支持，存放到BlackBerry 的lastName字段。
  • givenName：支持，存储到BlackBerry 的firstName字段。
  • middleName：不支持该属性，返回值总是null。
  • honorificPrefix：不支持该属性，返回值总是null。
  • honorificSuffix：不支持该属性，返回值总是null。
iOS的特异情况：
  • formatted：部分支持，将返回iOS的Composite Name，但不会单独存储。

ContactOrganization

包含Contact对象的所属组织属性。
属性：
  • pref：如果该ContactOrganization包含用户的首选值，则设置为true。（布尔类型）
  • type：用来标示该所属组织对应的类型的字符串（例如：“home”）。（DOMString类型）
  • name：组织的名称。（DOMString类型）
  • department：联系人工作的部门。（DOMString类型）
  • title：联系人在所属组织内的职务。（DOMString类型）
详述：
ContactOrganization对象存储联系人的所属组织属性，Contact对象通过一个数组存储一个或多个ContactOrganization对象。
支持的平台：
  • Android
  • BlackBerry WebWorks (OS 5.0或更高版本)
  • iOS

简单的范例：

function onSuccess(contacts) {  
    for (var i=0; i< contacts.length; i++) {  
        for (var j=0; j< contacts[i].organizations.length; j++) {  
            alert("Pref: " + contacts[i].organizations[j].pref + "\n" +  
                "Type: " + contacts[i].organizations[j].type + "\n" +  
                "Name: " + contacts[i].organizations[j].name + "\n" +  
                "Department: "  + contacts[i].organizations[j].department + "\n" +  
                "Title: "  + contacts[i].organizations[j].title);  
        }  
    }  
}  
  
function onError() {  
    alert('onError!');  
}  
  
var options = new ContactFindOptions();  
options.filter="";  
filter = ["displayName","organizations"];  
navigator.service.contacts.find(filter, onSuccess, onError, options);

 完整的范例：

<!DOCTYPE html>  
<html>  
<head>      
<title>Contact Example</title>  
  
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>  
<script type="text/javascript" charset="utf-8">  
  
// 等待加载PhoneGap  
document.addEventListener("deviceready", onDeviceReady, false);  
  
// PhoneGap加载完毕  
function onDeviceReady() {  
    var options = new ContactFindOptions();  
    options.filter="";  
    filter = ["displayName","organizations"];  
    navigator.service.contacts.find(filter, onSuccess, onError, options);  
}  
  
// onSuccess: 返回当前联系人结果集的快照  
function onSuccess(contacts) {  
    for (var i=0; i<contacts.length; i++) {  
        for (var j=0; j<contacts[i].organizations.length; j++) {  
            alert("Pref: " + contacts[i].organizations[j].pref + "\n" +  
            "Type: " + contacts[i].organizations[j].type + "\n" +  
            "Name: " + contacts[i].organizations[j].name + "\n" +  
            "Department: "  + contacts[i].organizations[j].department + "\n" +  
            "Title: "  + contacts[i].organizations[j].title);  
        }  
    }  
}  
  
// onError：获取联系人失败  
function onError() {  
    alert('onError!');  
}     
  
</script>  
</head>  
<body>  
 <h1>Example</h1>  
 <p>Find Contact</p>  
</body>  
</html>
Android 2.X 的特异情况：
  • pref：Android2.X设备上不支持该属性，返回值总是false。
Android 1.X 的特异情况：
  • pref：Android1.X设备上不支持该属性，返回值总是false。
  • type：Android1.X设备上不支持该属性，返回值总是null。
  • title：Android1.X设备上不支持该属性，返回值总是null。
BlackBerry WebWorks (OS 5.0或更高版本)的特异情况：
  • pref：BlackBerry设备上不支持该属性，返回值总是false。
  • type：BlackBerry设备上不支持该属性，返回值总是null。
  • name：部分支持，第一个组织名称将被存储到BlackBerry 的company字段。
  • department：不支持该属性，返回值总是null。
  • title：部分支持，第一个组织职务将被存储到BlackBerry 的jobTitle字段。
iOS的特异情况：
  • pref：iOS设备上不支持该属性，返回值总是false。
  • type：iOS设备上不支持该属性，返回值总是null。
  • name：部分支持，第一个组织名称将被存放到iOS的kABPersonOrganizationProperty字段。
  • department：部分支持，第一个部门名字将被存放到iOS的kABPersonDepartmentProperty字段。
  • title：部分支持，第一个组织职务将被存放到iOS的kABPersonJobTitleProperty字段。

ContactError

当有错误发生时，一个ContactError对象会传递给contactError回调函数。
属性：
  • code：一个在下面常量中定义好的错误代码。
常量：
  • ContactError.UNKNOWN_ERROR：未知错误类型
  • ContactError.INVALID_ARGUMENT_ERROR：无效参数错误类型
  • ContactError.TIMEOUT_ERROR：请求超时错误类型
  • ContactError.PENDING_OPERATION_ERROR：挂起操作错误类型
  • ContactError.IO_ERROR：输入输出错误类型
  • ContactError.NOT_SUPPORTED_ERROR：平台不支持错误类型
  • ContactError.PERMISSION_DENIED_ERROR：权限被拒绝错误类型
说明：
当有错误发生时，ContactError对象会通过contactError回调函数返回给用户。

contactSuccess

contacts.find操作成功时调用的回调函数，同时返回查找到的Contact数组。

参数：
  • contacts：查找操作返回的联系人数组。（Contact[]类型）

范例：

function contactSuccess(contacts) {   
    for (var i=0; i< contacts.length; i++) {   
        console.log(“Display Name = ” + contacts[i].displayName;   
    }  
}

 contactError

操作联系人出错时的回调函数。

contactFields

contacts.find方法的必填参数，该参数定义了查找操作返回的Contact对象中应该包含哪些字段。

["name", "phoneNumbers", "emails"]

 contactFindOptions

contats.find方法的可选参数，通过该参数从通讯录数据库中筛选联系人。

{    
        filter: "",   
        multiple: true  
    }
选项：
  • filter：用于查找联系人的搜索字符串。(DOMString类型) (默认值为空字符串)
  • multiple：决定查找操作是否可以返回多条联系人记录。(布尔类型) (默认值为false)
acntw

acntw

相关推荐

2.0联系人增、删、改、查

本章和大家分享的是手机通讯录方面的经验，需求背景:对手机通讯录进行增、删、改、查，或者有时候App需要与手机 contacts进行交互或共享contacts。首先，我们来看下如何通过ContentProvider查找contacts，以下我以查找其姓、名、

梦工厂 / 0评论 2011-09-22

Android SDK2.0 通讯录

数据是应用的核心，在Android的应用程序中我们经常需要调用通信录，比如给联系人发送贺卡，发送Email。我们已经知道可以通过ContentProvider去拿到数据，但是其uri如何得到呢。这就需要我们去查看文档，但是Android开发者指南已经很久没

GoAheadY / 0评论 2011-07-18

一篇文章，带你玩转MVVM，Dapper，AutoMapper

由于现在做的项目都是采用WPF来进行UI设计，开发过程中都是基于MVVM来进行开发，但是项目中的MVVM并不是真正的把实体和视图进行解耦，而是将实体和视图完全融合起来，ViewModel只是用来实现View和Model的数据同步，违背了MVVM设计的数据双

86523296 / 0评论 2019-10-19

Android手机通讯录备份还原代码

最近想写段Android程序玩玩。实现方法很简单1.把通讯录中的联系人，电话号码保存到txt文件中完成备份。File saveFile=new File; FileOutputStream outStream;try {outStream = new Fi

omguare / 0评论 2011-11-01

纯css实现手机通讯录

粘性定位元素是计算后位置属性为 sticky 的元素。兼容性还不错，至少在移动端可以放心使用。<div id='A'></div>如果整个页面是可以滚动的，那么只要点击a，那么页面就会迅速跳转到id=A的元素上

dangzhangjing / 0评论 2019-06-28

iOS9 之 Contacts

在以前开发者访问用户的联系人在他们的iOS设备上使用C API，那是个蛮痛苦的事情。直到iOS8还一直在使用，不过现在Apple推出了两个功能强大的面相对象的框架来管理用户联系人。Contacts和ContactsUI接下来，我们就来看看如何使用这些框架。

好好学习天天 / 0评论 2019-06-20

【Android】Uri、UriMatcher、ContentUris详解

通用资源标志符。Uri代表要操作的数据，Android上可用的每种资源 - 图像、视频片段等都可以用Uri来表示。访问资源的命名机制。存放资源的主机名。资源自身的名称，由路径表示。我们很经常需要解析Uri，并从Uri中获取数据。Android系统提供了两个

thankYouLikeMe / 0评论 2017-02-10

android 调用系统界面

现在开发中的功能需要直接跳转到拨号、联系人、短信界面等等，查找了很多资料，自己整理了一下。

tihi / 0评论 2013-01-11

模仿微信好友列表功能(数据从手机中读取)

感谢这两位的博客:. 模仿微信好友列表功能，实现汉首字母排序筛选：。用到了一个pinyin4j-2.5.0.jar这个包。其中还有一个 ContentResolver的知识点：。这篇文章中用到这样一个查询条件：

quickisbest / 0评论 2012-12-06

Android通讯录数据库

拨打该电话号码的开始时间计算到当前的时间差以毫秒为单位。打电话持续时间以秒为单位。拨打类型：1为接听2为打出。直接将来电转到语音信箱：0为不设置；1为设置。最后通话的日期计算。加星标的那些人:0为不加星；1为加星。联系人在UI中是否可见:0为不可见；1为可

XPY / 0评论 2012-12-03

android 调用系统界面

现在开发中的功能需要直接跳转到拨号、联系人、短信界面等等，查找了很多资料，自己整理了一下。startActivity;到应用：Intent intent = new Intent("android.in

ChainDestiny / 0评论 2012-10-25

phonegap contact API的使用

temp.append("<li>通讯录没有通讯信息!

figerDeng / 0评论 2012-07-10

2.0联系人增、删、改、查

推荐安卓开发神器本章和大家分享的是手机通讯录方面的经验，需求背景:对手机通讯录进行增、删、改、查，或者有时候App需要与手机 contacts进行交互或共享contacts。我们都知道android系统没有完全将contacts向developer开放，开

BeiHaiZuoPeng / 0评论 2011-09-22

基于 android 数据备份恢复的一种实现

本文主要论述了基于Android平台所提供的开发框架和应用组件，并给出了一种数据备份恢复的设计与实现。本文基于目前最热门的Android系统平台，该平台具有开源、易用、开发方便、与个人电脑有较强的融合性等众多优势。Android会与一个核心应用程序包一起发

chadeltu / 0评论 2011-07-29

【Android】Uri、UriMatcher、ContentUris详解

Uri代表要操作的数据，Android上可用的每种资源-图像、视频片段等都可以用Uri来表示。访问资源的命名机制。存放资源的主机名。我们很经常需要解析Uri，并从Uri中获取数据。Android系统提供了两个用于操作Uri的工具类，分别为UriMatche

yinbaoshiguang / 0评论 2011-04-29

源码库编译全过程及示例

修改Ubuntu的登陆设置,首先用sudopasswdroot设置root账户密码，输入两次，然后修改/etc/gdm/gdm.conf文件的AllowRoot=false字段，改成AllowRoot=true，然后重启电脑。注修改gdm.conf文件需要

wuqiong / 0评论 2010-08-27

android1.5获得所有联系人ID，人名，默认移动电话号码，并生成 JSONArray数据

JSONArray peopleJSON = new JSONArray();null, null, null);JSONObject jsonPeopleNumbers = new JSONObject();.getString(mobileNumber

zxiaocun / 0评论 2010-05-20

sqlite3 使用

E:\anddev\sdk\android-sdk-windows-1.5_r2\tools>adb shell2. 列出emulator 所以可用application 列表。3||||||1||shijintao|Jiangsu.Huaian|0

IT成长 / 0评论 2010-04-08

Android 联系人开发- 保存联系人

android在保存联系人的时候要特别注意的是 电话和手机的输入格式，以及添加IM时候要主要private属性

fanleiym / 0评论 2010-03-02

利用Angularjs中模块ui-route管理状态的方法

ui-router 的工作原理非常类似于 Angular 的路由控制器，但它只关注状态。在应用程序的整个用户界面和导航中，一个状态对应于一个页面位置 通过定义controller、template和view等属性，来定义指定位置的用户界面和界面行为 通

carrymyteams / 0评论 2016-12-27

前端轻量级MVC框架CanJS详解

创建一个JS APP没有好的工具是很有难度的，jQuery只是操作DOM的库，没有提供任何创建APP的基础，这就是为什么我们要一个类似CanJS的专门的库。它提供有MVC 模式的基本框架，模板动态绑定， route的支持且 内存安全。同时支持 jQuer

kennsand / 0评论 2019-04-18

Android应用程序模块详解

在大多数操作系统里，存在独立的一个1对1的可执行文件，它可以产生进程，并能和界面图标、应用进行用户交互。但在Android里，这是不固定的，理解将这些分散的部分如何进行组合是非常重要的。一个android包，里面包含应用程序的代码以及资源。这是一个应用发布

就这么Android着 / 0评论 2009-06-10

php simplexmlElement操作xml的命名空间实现代码

看了这个问题，第一个反应就是namespace的关系，但我从来没有使用simplexml操作过namespace，于是就翻开手册查了一下资料，问题并没有解决，最终是通过google解决了该问题。

PHP100 / 0评论 2019-03-27

ContentProvider中央档案馆,以及获取联系人电话的示例

Android官方文档介绍的数据存储方式共有五种,sqlite,SharedPreferences,网络存储,外储存储,文件存储,但是这些数据都无法进行共享,那么我们就引入了今天的主角:ContentProvider

手机开发 / 0评论 2016-11-15