cordova-plugin-contacts 2.2.0

您可以将以下内容类似地添加到您的 Podfile 中：`pod 'cordova-plugin-contacts', '~> 2.2'`

target 'MyApp' do
  pod 'cordova-plugin-contacts', '~> 2.2'
end

然后在终端中运行 `pod install`，或者从 CocoaPods.app 运行。

或者为了进行测试运行，运行以下命令

pod try cordova-plugin-contacts

cordova-plugin-contacts 2.2.0

由
Adobe PhoneGap 团队

标题：联系人

描述：管理设备上的联系人。

Android	iOS	Windows 8.1 Store	Windows 8.1 Phone	Windows 10 Store	Travis CI

cordova-plugin-contacts

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

尽管该对象附着在全局作用域的 navigator 上，但它直到 deviceready 事件之后才可用。

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

警告：收集和使用联系人数据会引发重要的隐私问题。您的应用程序的隐私策略应讨论应用程序如何使用联系人数据以及是否与任何其他方共享。由于联系人信息揭示了一个人与之交流的人，因此它被认为是敏感的。因此，除了应用程序的隐私策略外，您还应强烈考虑在应用程序访问或使用联系人数据之前提供实时通知（如果在设备操作系统尚未这样做的情况下）。此通知应提供上述信息，以及获取用户的许可（例如，通过提供确定和 不谢谢 的选择）。请注意，某些应用程序市场可能要求在访问联系人数据之前提供实时通知并获取用户的许可。围绕使用联系人数据的使用清晰易懂的用户体验有助于避免用户困惑和认为误用了联系人数据。有关更多信息，请参阅隐私指南。

在 Apache Cordova 问题跟踪器上报告此插件的问题

安装

这需要 cordova 5.0+（当前稳定版 v1.0.0）

cordova plugin add cordova-plugin-contacts

较旧版本的 cordova 仍然可以通过 已弃用 的 ID（旧版本 v0.2.16）进行安装

cordova plugin add org.apache.cordova.contacts

还可以直接通过存储库 URL 安装（不稳定）

cordova plugin add https://github.com/apache/cordova-plugin-contacts.git

iOS 特性

由于 iOS 10，强制在 info.plist 中添加 NSContactsUsageDescription 条目。

NSContactsUsageDescription 用于描述应用程序访问用户联系人隐私的原因。当系统提示用户允许访问时，此字符串将作为对话框的一部分显示。要添加该条目，您可以在安装插件时传入变量 CONTACTS_USAGE_DESCRIPTION。

示例： cordova plugin add cordova-plugin-contacts --variable CONTACTS_USAGE_DESCRIPTION="您的用途说明消息"

如果您没有传入变量，则插件将添加一个空字符串作为值。

Firefox OS 的特性

按照Manifest 文档中的说明创建 www/manifest.webapp。添加相关权限。还需要将 webapp 类型更改为 "privileged" - Manifest 文档。警告：所有具有特权的应用程序都强制实行内容安全策略，该策略禁止内联脚本。请以其他方式初始化您的应用程序。

"type": "privileged",
"permissions": {
    "contacts": {
        "access": "readwrite",
        "description": "Describe why there is a need for such permission"
    }
}

Windows 的特性

Windows 10 之前的版本：从 find 和 pickContact 方法返回的任何联系人都是只读的，所以您的应用程序无法修改它们。find方法仅适用于 Windows Phone 8.1 设备。

Windows 10 及以上版本：联系人可以被保存，并保存在应用程序本地的联系人存储中。联系人也可以被删除。

Windows 8 的特性

Windows 8 的联系人只读。通过 Cordova API，无法对联系人进行查询/搜索，您应提醒用户使用 contacts.pickContact 来选择联系人，这将打开 "People" 应用程序，用户必须在该应用程序中选择联系人。返回的任何联系人都是只读的，因此您的应用程序无法修改它们。

navigator.contacts

方法

navigator.contacts.create
navigator.contacts.find
navigator.contacts.pickContact

对象

联系人
联系人名称
联系人字段
联系人地址
联系人组织
联系人查询选项
联系人错误
联系人字段类型

navigator.contacts.create

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

此方法不会在设备联系人数据库中保留联系人对象，您需要调用 Contact.save 方法来实现这一点。

支持的平台

Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8

示例

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

navigator.contacts.find

navigator.contacts.find 方法是异步执行的，它会查询设备联系人数据库，并返回一个包含 Contact 对象的数组。这些结果对象将通过指定给 contactSuccess 参数的 contactSuccess 回调函数传递。

contactFields参数指定用于搜索条件的字段。contactFields参数长度为零是无效的，会导致错误ContactError.INVALID_ARGUMENT_ERROR。如果contactFields的值为"*"，则搜索所有联系人字段。

contactFindOptions.filter字符串可以用作查询联系人数据库时的搜索过滤器。如果提供，则对contactFields参数中指定的每个字段应用不区分大小写的部分值匹配。如果为所指定的任一字段找到匹配项，则返回该联系人的信息。使用contactFindOptions.desiredFields参数来控制必须返回哪些联系人属性。

ContactFieldType对象中列出了contactFields和contactFindOptions.desiredFields参数的有效值。

参数

contactFields：用作搜索条件的联系人字段。 (DOMString[]) [必须]
contactSuccess：成功回调函数，在从数据库返回联系人对象数组时调用。 [必须]
contactError：错误回调函数，在发生错误时调用。 [可选]
contactFindOptions：筛选navigator.contacts的搜索选项。 [可选]

键包括
- filter：用于查找navigator.contacts的搜索字符串。 (DOMString) (默认："")
- multiple：确定查找操作是否返回多个navigator.contacts。 (Boolean) (默认：false)
- desiredFields：要返回的联系人字段。如果指定，则结果Contact对象只包含这些字段的值。 (DOMString[]) [可选]
- hasPhoneNumber(仅限Android)：筛选搜索结果，只返回包含电话号码的联系人。 (Boolean) (默认：false)

支持的平台

Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8
Windows (Windows Phone 8.1 and Windows 10)

示例

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：成功回调函数，使用单一代理人道对象调用。 [必须]
contactError：错误回调函数，在发生错误时调用。 [可选]

支持的平台

Android
iOS
Windows Phone 8
Windows

示例

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

Android 特性

此插件将启动外部Activity以选择联系人。请参阅Android 生命周期指南了解它会如何影响您的应用程序。如果插件在resume事件中返回其结果，则在使用之前必须首先将返回的对象包装在Contact对象中。以下是一个示例

function onResume(resumeEvent) {
    if(resumeEvent.pendingResult) {
        if(resumeEvent.pendingResult.pluginStatus === "OK") {
            var contact = navigator.contacts.create(resumeEvent.pendingResult.result);
            successCallback(contact);
        } else {
            failCallback(resumeEvent.pendingResult.result);
        }
    }
}

联系人

代表用户的联系人对象。可以创建、保存或在设备联系人数据库中删除联系人。也可以通过调用navigator.contacts.find方法从数据库获取联系人（单独或在批量中）。

注意：并非上述列出的所有联系人字段均在每个设备平台上都得到支持。请查看每个平台上的《异常》部分以获取详细信息。

属性

id：一个全局唯一标识符。 (DOMString)
displayName：此联系人的名称，适合向最终用户提供显示。 (DOMString)
name：包含一个人名所有组成部分的对象。 (ContactName)
nickname：用于称呼该联系人的非正式名称。 (DOMString)
phoneNumbers：一个包含联系人所有电话号码的数组。 (ContactField[])
emails：一个包含联系人所有电子邮件地址的数组。 (ContactField[])
addresses：一个包含联系人所有地址的数组。 (ContactAddress[])
ims：一个包含联系人所有即时消息地址的数组。 (ContactField[])
organizations：一个包含联系人所有组织的数组。 (ContactOrganization[])
birthday：联系人的生日。 (Date)
note：关于联系人的备注。 (DOMString)
photos：一个包含联系人照片的数组。 (ContactField[])
categories：一个包含与联系人关联的所有用户定义类别的数组。 (ContactField[])
urls：一个与联系人关联的网页数组。 (ContactField[])

方法

clone：返回一个新的 Contact 对象，它是调用对象的深拷贝，其中 id 属性设置为 null。
remove：从设备联系人数据库中删除联系人，否则执行带有一个 ContactError 对象的错误回调。
save：将新的联系人保存到设备联系人数据库中，如果已存在具有相同 id 的联系人，则更新现有联系人。

支持的平台

Amazon Fire OS
Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8
Windows

保存示例

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

删除示例

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

Android 2.X 异常

categories：不支持在 Android 2.X 设备上，返回 null。

BlackBerry 10 异常

id：由设备在保存联系人时分配。

FirefoxOS 异常

categories：部分支持。字段 pref 和 type 返回 null
ims：不支持
photos：不支持

iOS 异常

displayName：不支持在 iOS 上，除非没有指定 ContactName，在这种情况下返回组合名称、nickname 或 ""，分别。
生日：必须以 JavaScript Date 对象的形式输入，与返回的方式相同。
图片：返回图像的文件 URL，存储在应用程序的临时目录中。当应用程序退出时，临时目录的内容将被删除。
类别：当前不支持此属性，返回 null。

Windows Phone 8 的问题

displayName：当创建联系人时，提供给显示名称参数的值与查找联系人时检索到的显示名称不同。
urls：当创建联系人时，用户可以输入和保存多个网址，但在搜索联系人时只能使用一个。
phoneNumbers：不支持 pref 选项。在 find 操作中不支持 type。每个 type 只允许一个 phoneNumber。
emails：不支持 pref 选项。家庭和个人引用相同的电子邮件条目。每个 type 只允许一个条目。
addresses：仅支持工作地址和家庭/个人 type。家庭和个人 type 引用相同的地址条目。每个 type 只允许一个条目。
organizations：只允许一个，不支持 pref、type 和 department 属性。
note：不支持，返回 null。
ims：不支持，返回 null。
birthdays：不支持，返回 null。
categories：不支持，返回 null。
remove：方法不支持

Windows 的问题

photos：返回图像的文件 URL，存储在应用程序的临时目录中。
birthdays：不支持，返回 null。
categories：不支持，返回 null。
remove：方法仅在 Windows 10 或更高版本中受支持。

ContactAddress

ContactAddress 对象存储联系人的单个地址的属性。一个 Contact 对象可以包含一个 ContactAddress[] 数组中的多个地址。

属性

pref：如果此 ContactAddress 包含用户的首选值，则设置为 true。(布尔值)
type：表示此字段类型的字符串，例如 home。 (DOMString)
formatted：用于显示的全地址。 (DOMString)
streetAddress：完整的街道地址。 (DOMString)
locality：城市或地区。 (DOMString)
region：州或地区。 (DOMString)
postalCode：邮政代码或邮编。 (DOMString)
country：国家名称。 (DOMString)

受支持的平台

Amazon Fire OS
Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8
Windows

示例

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

Android 2.X 的问题

pref：不支持，在 Android 2.X 设备上返回 false。

BlackBerry 10 的问题

pref：在 BlackBerry 设备上不支持，返回 false。
type：部分支持。每个联系人可以存储一个 Work 和一个 Home 类型的地址。
格式化：部分支持。返回所有BlackBerry地址字段的连接。
streetAddress：支持。返回BlackBerry address1 和 address2 地址字段的连接。
locality：支持。存储在BlackBerry city 地址字段中。
region：支持。存储在BlackBerry stateProvince 地址字段中。
postalCode：支持。存储在BlackBerry zipPostal 地址字段中。
country：支持。

FirefoxOS 的一些特殊之处

格式化：当前不支持。

iOS 的一些特殊之处

pref：iOS 设备上不支持，返回 false。
格式化：当前不支持。

Windows 的一些特殊之处

pref：不支持。

ContactError

当发生错误时，将通过 contactError 回调函数返回 ContactError 对象给用户。

属性

code：以下预定义错误代码之一。

常量

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

ContactField

该 ContactField 对象是一个可重复使用的组件，用于表示联系信息字段。每个 ContactField 对象包含一个 value、type 和 pref 属性。一个 Contact 对象在 ContactField[] 数组中存储多个属性，如电话号码和电子邮件地址。

在大多数情况下，ContactField 对象的 type 属性没有预定义值。例如，电话号码可以指定 type 的值为 home、work、mobile、iPhone 或其他任何特定设备平台联系人数据库支持的价值。然而，对于 Contact 的 photos 字段，type 字段表示返回图像的格式：当 value 属性包含指向照片图像的URL时，为 url；当 value 包含 base64 编码的图像字符串时，为 base64。

属性

type：一个字符串，表示此字段的类型，例如 home。 (DOMString)
value：字段值，例如电话号码或电子邮件地址。 (DOMString)
pref：如果此 ContactField 包含用户的首选值，则设置为 true。 (boolean)

支持的平台

Amazon Fire OS
Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8
Windows

示例

// 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();

Android 的一些特殊之处

pref：不支持，返回 false。

BlackBerry 10 特殊行为

类型：部分支持。用于电话号码。
值：支持。
pref：不支持，返回 false。

iOS 特殊行为

pref：不支持，返回 false。

Windows 特殊行为

pref：不支持，返回 false。

联系姓名

包含有关 联系 对象名称的各类信息。

属性

formatted：联系人的完整姓名。 (DOMString)
lastName：联系人的姓氏。 (DOMString)
givenName：联系人的名字。 (DOMString)
middleName：联系人的中间名。 (DOMString)
：联系人的称谓前缀（例如先生或博士） (DOMString)
honorificSuffix：联系人的称谓后缀（例如先生）。 (DOMString)

支持的平台

Amazon Fire OS
Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8
Windows

示例

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、和 honorificSuffix 的拼接。

BlackBerry 10 特殊行为

formatted：部分支持。返回 BlackBerry 的 firstName 和 lastName 字段的拼接。
lastName：支持。存储在 BlackBerry 的 lastName 字段中。
givenName：支持。存储在 BlackBerry 的 firstName 字段中。
middleName：不支持，返回 null。
honorificPrefix：不支持，返回 null。
honorificSuffix：不支持，返回 null。

FirefoxOS 特殊行为

formatted：部分支持，是只读的。返回 honorificPrefix、givenName、middleName、familyName、和 honorificSuffix 的拼接。

iOS 特殊行为

formatted：部分支持。返回 iOS 组合名称，但只读。

Windows 特殊行为

formatted：这是唯一的一个名称属性，与 displayName 和 nickname 相同。
lastName：不支持
givenName：不支持
middleName：不支持
honorificPrefix：不支持
honorificSuffix：不支持

联系组织

ContactOrganization 对象存储联系人的组织属性。一个 Contact 对象在一个数组中存储一个或多个 ContactOrganization 对象。

属性

pref：如果此 ContactOrganization 包含用户的偏好值，则设置为 true。 (boolean)
type：表示此字段类型的字符串，例如 home。 _(DOMString)
name：组织的名称。 (DOMString)
department：合同工作的部门。 (DOMString)
title：联系人在组织中的职位。 (DOMString)

支持的平台

Android
BlackBerry 10
Firefox OS
iOS
Windows Phone 8
Windows（仅限于Windows 8.1和Windows Phone 8.1设备）

示例

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

Android 2.X问题

pref：Android 2.X设备不支持，返回 false。

BlackBerry 10问题

pref：BlackBerry设备不支持，返回 false。
type：不支持，返回 null。
name：部分支持。第一个组织名称存储在BlackBerry的 company 字段中。
department：不支持，返回 null。
title：部分支持。第一个组织标题存储在BlackBerry的 jobTitle 字段中。

Firefox OS问题

pref：不支持。
type：不支持
department：不支持
name 和 title 字段存储在 org 和 jobTitle。

iOS问题

pref：iOS 设备上不支持，返回 false。
type：iOS设备不支持，返回 null。
name：部分支持。第一个组织名称存储在iOS的 kABPersonOrganizationProperty 字段中。
department：部分支持。第一个部门名称存储在iOS的 kABPersonDepartmentProperty 字段中。
title：部分支持。第一个标题存储在iOS的 kABPersonJobTitleProperty 字段中。

Windows问题

pref：不支持，返回 false。
type：不支持，返回 null。

ContactFieldType

ContactFieldType 对象是可能字段类型的枚举，如 'phonesNumbers' 或 'emails'，可用于控制从 contacts.find() 方法返回哪些联系人类别属性（请参阅 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