通讯录联系人插件

这个插件定义一个全局navigator.contacts对象,它提供了访问设备的联系人数据库。

deviceready事件后方可使用

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(navigator.contacts);
}

警告:收集和使用接触数据提出了 重要的隐私问题。你的应用程序的隐私政策应该讨论如何应用程序使用 联系人数据是否与其他 方共享。联系信息是敏感的因为它 揭示了人与人沟通。因此,在 添加到应用程序的隐私政策,你应该认真考虑 提供及时的通知之前,应用程序访问或使用 联系人数据,如果设备操作系统不会 已经。该通知应提供相同的信息,上面提到的, 以及获取用户的权限(例如,通过 选择 OK  No Thanks)。请注意,有些应用程序 市场可能需要应用程序提供了一个及时的通知和 之前访问联系人数据获得用户的许可。

navigator.contacts

方法

navigator.contacts.create
navigator.contacts.find
navigator.contacts.pickcontact

对象:

Contact
ContactName
ContactField
ContactAddress
ContactOrganization
ContactFindOptions
ContactError
ContactFieldType


navigator.navigator.contacts.create

这个navigator.contacts.create方法是同步的,并返回一个新的Contact对象

此方法不保留在设备接触 数据库的联系对象,这需要调用contact.save方法contacts.create

例子

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

navigator.contacts.find

这个navigator.contacts.find方法异步执行,查询 装置联系人数据库并返回一个Contact对象数组。 产生的对象传递给contactsuccess 指定的回调函数contactsuccess参数.

这个contactfields参数指定的字段作为一 搜索修饰符。10长度contactfields参数无效的结果ContactError.INVALID_ARGUMENT_ERROR.。一contactfields价值“*”搜索所有联系人字段。

contactfindoptions.filter 当查询联系人数据库是,字符串可以作为一个搜索过滤器。如果提供,一个 不区分大小写,偏值匹配应用到各个领域中,可以通过使用contactfields参数来实。使用contactfindoptions.desiredfields参数控制contact属性必须返回。

contactfieldtype对象支持contactfields和contactfindoptions.desiredfields参数

参数:

contactFields:联系人字段作为搜索修饰符 . (DOMString[]) [要求]

contactSuccess: 成功回调函数调用与contact对象队列一起从数据库返回 [要求]

contactError: 错误回调函数,说明调用时发生错误。[选]

contactFindOptions: 搜索过滤选项navigator.contacts。 [可选]

关键字包括:

filter: 用来发现navigator.contacts搜索字符串 (DOMString) (默认: "")

multiple: 确定查找操作返回多个navigator.contacts。 (Boolean) (默认: false)

desiredFields: 要返回联系人字段。如果指定,由此产生的contact对象的唯一特点这些字段的值。 (DOMString[]) [Optional]

hasPhoneNumber(Android only):过滤器的搜索只返回联系电话号码(Boolean) (默认: false)

例子

function onSuccess(contacts) {
    alert('Found ' + contacts.length + ' contacts.');
};
 
function onError(contactError) {
    alert('onError!');
};
// find all contacts with 'Bob' in any name field
var options      = new ContactFindOptions();
options.filter   = "Bob";
options.multiple = true;
options.desiredFields = [navigator.contacts.fieldType.id];
options.hasPhoneNumber = true;
var fields       = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
navigator.contacts.find(fields, onSuccess, onError, options);

注意:在windows平台__contactfields__不支持将被忽略。find方法将始终尝试匹配的名字,电子邮件地址或联系电话

navigator.contacts.pickcontact

这个navigator.contacts.pickcontact方法展开接触选择器选择一个联系人。 产生的对象传递给contactsuccess 指定的回调函数contactsuccess参数.

参数:

contactSuccess: 执行成功时的回调函数,返回contact对象 [要求]

contactError: 错误回调函数,说明调用时发生错误。[可选]

例子:

navigator.contacts.pickContact(function(contact){
        console.log('The following contact has been selected:' + JSON.stringify(contact));
    },function(err){
        console.log('Error: ' + err);
    });

Contact

这个Contact对象代表用户的联系人。联系人可以是 创建,存储,或从设备中删除联系人数据库。 联系人也可以被检索(单独或批量)从 数据库的调用navigator.contacts.find方法

 

注意:不是所有联系人字段上面列出的支持 每个设备平台。请留意各平台的细节部分。

属性:

id: 一个全局的唯一标识符. (DOMString)
displayName: 显示的用户名. (DOMString)
name: 一个对象包含所有组件的一个人的名字。. (ContactName)
nickname: 昵称. (DOMString)
phoneNumbers: 该联系人的电话号码数组. (ContactField[])
emails: 该联系人的email数组. (ContactField[])
addresses: 联系人的地址数组. (ContactAddress[])
ims:联系人的IM地址数组. (ContactField[])
organizations: 联系人的组织数组. (ContactOrganization[])
birthday: 联系人的生日. (Date)
note: 备注. (DOMString)
photos:照片. (ContactField[])
categories:联系人的分类类别 (ContactField[])
urls: 相关的网页地址. (ContactField[])

方法:

clone:返回一个新的Contact对象,是一个深拷贝的调用对象,id属性为null.

remove: 删除从设备的联系人数据库的联系,否则执行一个错误回调 ContactError .

save: 保存为新的联系人数据库,如果联系人的ID相关(已经存在)则更新现有的联系人

Save方法例子:

function onSuccess(contact) {
    alert("Save Success");
};
function onError(contactError) {
    alert("Error = " + contactError.code);
};
// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";            // specify both to support all devices
// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;
// save to device
contact.save(onSuccess,onError);
Clone方法示例:
// clone the contact object
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);
};
// remove the contact from the device
contact.remove(onSuccess,onError);

从保存的联系人当中移除号码:

// Example to create a contact with 3 phone numbers and then remove
// 2 phone numbers. This example is for illustrative purpose only
var myContact = navigator.contacts.create({"displayName": "Test User"});
var phoneNumbers = [];
 
phoneNumbers[0] = new ContactField('work', '768-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '999-555-5432', true); // preferred number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
myContact.phoneNumbers = phoneNumbers;
myContact.save(function (contact_obj) {
    var contactObjToModify = contact_obj.clone();
    contact_obj.remove(function(){
        var phoneNumbers = [contactObjToModify.phoneNumbers[0]];
        contactObjToModify.phoneNumbers = phoneNumbers;
        contactObjToModify.save(function(c_obj){
            console.log("All Done");
        }, function(error){
            console.log("Not able to save the cloned object: " + error);
        });
    }, function(contactError) {
        console.log("Contact Remove Operation failed: " + contactError);
    });
});

注意事项:

Android2.X设备不支categories属性,返回null

对于IOS:

displayName:不支持iOS,返回null的除非没有ContactName 规定,在这种情况下它返回复合名称,nickname“”,分别。

birthdat:必须输入一个JavaScript日期的对象,同样的方式返回。

phonto:返回一个文件的URL的图像,并存储在应用程序的临时目录。内容的临时目录中删除应用程序退出时。

categories:目前不支持这个属性,返回null:

对于Window是 Phone8:

DisplayName:当创建一个联系,所提供的值的显示名称参数不同于显示名称检索时,查找联系人时

Urls:当创建一个联系人,用户可以输入和保存多个Web地址,但只有一个是搜索时的接触。

phoneNumbers:的県期权是不支持的。这个类型不支持在发现运营只有一个phoneNumber允许每一个类型。

email:选项不支持。家庭和个人引用相同的电子邮件进入。一个选项只允许一个

address:支持只有工作和家庭/个人。家庭和个人引用同一地址条目。一个选项只允许一个

organizations只允许一个并且不支持pref,type,和department属性

note:不支持,返回null

ims:不支持,返回null

birthdays:不支持,返回null

categories:不支持,返回null

remove:方法不支持

 

ContactAddress

这个ContactAddress 对象存储性能的一个单一的地址 一接触。一联系对象可以包括在 有多个地址ContactAddress[]阵列。

属性:

pref: 如果这个ContactAddress包含用户的优选指则设置为true (boolean)
type: 类型领域,例如家. (DOMString)
formatted: 格式化显示的完整地址. (DOMString)
streetAddress: 完整的街道地址. (DOMString)
locality:城市或地方. (DOMString)
region: 国家或地区. (DOMString)
postalCode: 邮政编码. (DOMString)
country:国家名称. (DOMString)

例子:

// display the address information for all contacts
 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!');
};
// find all contacts
var options = new ContactFindOptions();
options.filter = "";
options.multiple = true;
var filter = ["displayName", "addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);

注意:

Android2.X设备不支持pref属性,返回false

IOS不支持pref属性,返回false;目前也不支持formatted格式设置

Windows不支持pref属性

ContactError

这个contacterror对象是通过返回给用户contacterror回调函数时发生错误。

属性:

code:一个预定义的错误代码如下.

常数:

ContactError.UNKNOWN_ERROR (code 0)
ContactError.INVALID_ARGUMENT_ERROR (code 1)
ContactError.TIMEOUT_ERROR (code 2)
ContactError.PENDING_OPERATION_ERROR (code 3)
ContactError.IO_ERROR (code 4)
ContactError.NOT_SUPPORTED_ERROR (code 5)
ContactError.OPERATION_CANCELLED_ERROR (code 6)
ContactError.PERMISSION_DENIED_ERROR (code 20)

ContactField

这个contactfield对象是一个可重用的组件,代表 接触领域一般。每个contactfield对象包含一个value,type,pref属性Contact对象存储 的几个性质contactfield [ ]阵列,如电话号码和电子邮件地址的 。

 

在大多数情况下,没有预先确定的值为contactfield对象的type属性。例如,一个手机号码可以指定工作,手机,iPhone,或任何其他的 type值,由一个特定的设备 平台的联系人数据库支持。然而,对于Contact的photos属性,该类型指出返回的图像格式:URL当值属性包含一个URL的照片 图像,或Base64值包含Base64编码的图像 字符串。

属性:

type: 类型领域,例如家. (DOMString)
value: 值,例如电话号码或电子邮件地址. (DOMString)
pref:如果这个contactfield包含用户的优选指则设置为true. (boolean)

例子

// create a new contact
var contact = navigator.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
 
// save the contact
contact.save();

注意:

Android2.X设备、IOS、Windows均不支持pref属性,返回false

ContactName

含有不同种类的有关信息Contact对象的名字。

属性:

formatted: 联系人完整的名称. (DOMString)
familyName: 联系人的姓. (DOMString)
givenName: 联系人的名字. (DOMString)
middleName: 联系人的名字. (DOMString)
honorificPrefix: 联系人的前缀,如 先生或博士 (DOMString)
honorificSuffix: 联系人的后缀 (example Esq.). (DOMString)

例子:

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(contactError) {
    alert('onError!');
};
var options = new ContactFindOptions();
options.filter = "";
options.multiple = true;
filter = ["displayName", "name"];
navigator.contacts.find(filter, onSuccess, onError, options);

注意:

Android平台formatted属性:部分支持,返回一个连接honorificPrefix, givenName, middleName, familyName, and honorificSuffix.

IOS平台的formatted属性:部分支持,返回IOS复合名称,但是只读

Windows平台formatted属性:这是唯一的名称属性,和displayName、 nickname类似.不支持familyName、givenName、middleName、honorificPrefix、honorificSuffix。

 

ContactOrganization

这个contactorganization对象存储联系人的组织 性质。一个Contact对象存储一个或多个contactorganization对象数组

属性:

pref: 如果这个ContactOrganization 包含用户的优选指则设置为true  (boolean)
type: 类型领域,例如家. (DOMString)
name: 组织的名称 (DOMString)
department: 部门. (DOMString)
title: 标题. (DOMString)

例子:

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(contactError) {
    alert('onError!');
};
var options = new ContactFindOptions();
options.filter = "";
options.multiple = true;
filter = ["displayName", "organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);

注意:

Android2.X设备不支持pref属性,返回false

IOS不支持pref属性,返回false;不支持type属性,返回null;

name属性:部分支持,第一组织的名称存储在IOS kABPersonOrganizationProperty 

Department属性:部分支持,第一组织的名称存储在IOS  kABPersonOrganizationProperty 

 

title属性:部分支持,第一组织的名称存储在IOS  kABPersonOrganizationProperty 

Windows不支持pref属性,返回false;不支持type属性,返回null;

ContactFieldType

contactfieldtype

这个contactfieldtype对象是可能的字段类型的枚举,如“phoneNumbers”或“emails”,可以通过contacts.find()方法的返回值contact 属性来控制(见contactfindoptions.desiredfields),或指定要搜索字段(通过contactfields参数)。可能的值是:

navigator.contacts.fieldType.addresses
navigator.contacts.fieldType.birthday
navigator.contacts.fieldType.categories
navigator.contacts.fieldType.country
navigator.contacts.fieldType.department
navigator.contacts.fieldType.displayName
navigator.contacts.fieldType.emails
navigator.contacts.fieldType.familyName
navigator.contacts.fieldType.formatted
navigator.contacts.fieldType.givenName
navigator.contacts.fieldType.honorificPrefix
navigator.contacts.fieldType.honorificSuffix
navigator.contacts.fieldType.id
navigator.contacts.fieldType.ims
navigator.contacts.fieldType.locality
navigator.contacts.fieldType.middleName
navigator.contacts.fieldType.name
navigator.contacts.fieldType.nickname
navigator.contacts.fieldType.note
navigator.contacts.fieldType.organizations
navigator.contacts.fieldType.phoneNumbers
navigator.contacts.fieldType.photos
navigator.contacts.fieldType.postalCode
navigator.contacts.fieldType.region
navigator.contacts.fieldType.streetAddress
navigator.contacts.fieldType.title
navigator.contacts.fieldType.urls