NativeScript Contacts Lite

此 nativescript-contacts-lite 插件提供了对 iOS 和 Android 联系人目录的快速（但请记住，所有这些都是相对的）只读访问。通过通过 desiredFields 限制结果集的范围，可以在几百毫秒内获取包含联系人目录相关数据的 JSON 对象。

演示应用程序

此存储库包含在 demo-angular 文件夹中的演示应用程序，该应用程序使用此插件来显示联系人选择器。此演示应用程序可以作为您的应用程序的良好起点，并在调试时缩小问题。只需克隆此存储库，并在 demo-angular 文件夹中运行 tns run <platform>。

安装

运行 tns plugin add nativescript-contacts-lite

用法

要使用联系人模块，您必须首先 require() 它。

var Contacts = require("nativescript-contacts-lite");

方法

getContacts & getContactsWorker

这两种方法都检索联系人并具有相同的接口。区别在于前者在主线程中运行，而后者在 Web Worker 中运行。

参数 1：desiredFields 包含要从手机存储后端获取的所需字段的数组。可能的值是

[
  'address',
  'display_name',
  'email',
  'name_details',
  'nickname',
  'note',
  'organization',
  'phone',
  'photo',
  'thumbnail',
  'website'
]

参数 2：searchTerm（可选） 包含搜索词的字符串，以限制结果集仅包含联系人，其中 display_name 包含该词。默认情况下，如果提供空搜索词或根本不提供，则获取所有相关联系人。

参数 3：debug（可选） 布尔值（true/false），确定是否将调试消息传递到控制台。默认为 false。

使用 getContacts 的示例

let desiredFields = ['display_name','phone'];
let searchTerm = 'Jon';

console.log('Loading contacts...');
let timer = new Date().getTime();

Contacts.getContacts(desiredFields,searchTerm).then((result) => {
  console.log(`Loading contacts completed in ${(new Date().getTime() - timer)} ms.`);
  console.log(`Found ${result.length} contacts.`);
  console.dir(result);
}, (e) => { console.dir(e); });

使用 getContactsWorker 的示例

let desiredFields = ['display_name','phone','thumbnail','email','organization'];

console.log('Loading contacts...');
let timer = new Date().getTime();

Contacts.getContactsWorker(desiredFields).then((result) => {
  console.log(`Loading contacts completed in ${(new Date().getTime() - timer)} ms.`);
  console.log(`Found ${result.length} contacts.`);
  console.dir(result);
}, (e) => { console.dir(e); });

getContactById

获取特定联系人的详细信息。

参数 1：contactId 您希望获取详细信息的联系人的标识符（通过 getContacts(Worker) 方法获取）。

参数 2：desiredFields 包含要从手机存储后端获取的所需字段的数组。请参阅 getContacts 方法以获取可能的值。

参数 3：debug（可选） 布尔值（true/false），确定是否将调试消息传递到控制台。默认为 false。

示例

let contact_id = contact.contact_id // get id from result of getContacts method

let desiredFields = [
  'address',
  'display_name',
  'email',
  'name_details',
  'nickname',
  'note',
  'organization',
  'phone',
  'photo',
  'thumbnail',
  'website'
]

Contacts.getContactById(contact_id,desiredFields).then((result) => {
  console.dir(result);
}, (e) => { console.dir(e); });

性能

注意事项

在主线程中运行与在 Web Worker 中运行

此插件提供了两种方法，可以在主/UI 线程或 Web Worker 中运行。虽然将处理卸载到单独的线程会增加 Web Worker 初始化时间，但它保证了主 UI 线程将继续顺利工作。

如果您正在实现自动完成功能，其中每次键入都查询联系人的较小子集，您可能希望使用非工作器版本以避免用户等待时的 Web Worker 初始化时间。另一方面，如果您在初始化应用程序时正在读取整个联系人目录，则可能希望将其在后台进行，以避免在处理时使 UI 停滞。在这种情况下，您可能希望使用 Web Worker 版本。

联系人选择器示例

在某些情况下可以采取另一种方式来提高性能，例如当你正在构建一个联系人选择器时。在这种情况下，首先向getContacts提供一系列所需字段，如['display_name','thumbnail']，以显示列表可能就足够了。只有当用户选择特定联系人时，你才能通过向getContactById提供更广泛所需字段来获取特定联系人的所有详细信息。此示例已在位于本存储库中的演示应用程序中实现。

基准测试

Android

在一个相对较旧的Samsung Galaxy S4上，当在主线程或Web Worker中运行时，返回大约600个联系人的列表大约需要300ms到2s不等，这取决于所需字段。

iOS

在iPhone 7 plus上，当运行getContacts(['display_name', 'phone'])时（所以非Worker模式），大约在105ms返回大约600个联系人。如果有人有一些不同模式（例如更多字段和Web Worker模式）的真正iOS设备数据，这将是很有帮助的。

注意事项

与Webpack捆绑

自NativeScript 3.2起，此插件通过nativescript-dev-webpack插件与Webpack捆绑兼容。但是，如果你使用Web Worker函数，我们需要确保Web Worker资源包含在包中。为此，你应该将nativescript-worker-loader添加到你的项目中：npm i -D nativescript-worker-loader。

照片和缩略图图像

该插件将photo和thumbnail图像作为base64编码的字符串返回，以便用作图像的源属性，例如<Image *ngIf="item.thumbnail" [src]="item.thumbnail"></Image>

Android特定

权限

此插件使用Nathanael Anderson的nativescript-permissions插件，在Android 6及以上版本中获取对电话联系人的只读权限。

iOS特定

由于该插件使用联系框架，它仅在iOS 9.0及以上版本中得到支持！

权限

从iOS 10开始，将NSContactsUsageDescription密钥添加到应用程序的Info.plist中已成为强制性的（请参阅Apple的开发者文档）。

因此，你应该在~/app/App_Resources/iOS/Info.plist中添加如下内容：

<key>NSContactsUsageDescription</key>
<string>This application requires access to your contacts to function properly.</string>

致谢

此插件iOS部分的代码基于nativescript-contacts插件的代码。