方法:
参数:
对象:
返回一个新的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>
查询设备通讯录数据库,并返回包含指定字段的一个或多个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>
包含描述联系人的属性,比如用户的个人或者商务联系方式。
属性:
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);
Remove 简单的范例:
- 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);
完整的范例:
- <!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。
包含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:目前不支持。
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。
包含用于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>
包含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,但不会单独存储。
包含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回调函数。
属性:
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数组。
简单的范例:
- function(contacts) {
- // 后续操作
- }
参数:
contacts:查找操作返回的联系人数组。(Contact[]类型)
范例:
- function contactSuccess(contacts) {
- for (var i=0; i< contacts.length; i++) {
- console.log(“Display Name = ” + contacts[i].displayName;
- }
- }
操作联系人出错时的回调函数。
- function(error) {
- // 错误处理
- }
contacts.find方法的必填参数,该参数定义了查找操作返回的Contact对象中应该包含哪些字段。
- ["name", "phoneNumbers", "emails"]
- contactFindOptions
contats.find方法的可选参数,通过该参数从通讯录数据库中筛选联系人。
- {
- filter: "",
- multiple: true
- }
选项:
filter:用于查找联系人的搜索字符串。(DOMString类型) (默认值为空字符串)
multiple:决定查找操作是否可以返回多条联系人记录。(布尔类型) (默认值为false)