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 线程将继续平稳运行。

如果您正在实现自动完成，并且每次按键都会查询联系人的较小子集，您可能希望选择非 Worker 变体以避免在用户等待时 Web Worker 初始化时间。另一方面，如果您在初始化应用程序时正在读取整个联系人目录，则可能希望将其在后台执行，以避免在处理时 UI 被卡住。在这种情况下，您可能希望使用 Web Worker 变体。

联系人选择器示例

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

基准测试

Android

在相对较旧的 Samsung Galaxy S4 上，根据所需的字段以及是否在主线程或网络工作者中运行，大约 600 个联系人的列表返回时间在 ~300ms 到 ~2s 之间。

iOS

在 iPhone 7 Plus 上进行测试，大约 600 个联系人返回 ~105ms 时运行 getContacts(['display_name', 'phone'])（非工作者）。如果有人有一些不同模式（例如更多字段和 Web Worker 模式）的实际 iOS 设备数据，这将很有帮助。

注意

与 Webpack 打包

从 NativeScript 3.2 开始，此插件通过 nativescript-dev-webpack 插件与 webpack 打包兼容。但是，如果您正在使用网络工作者函数，我们需要确保将网络工作者资源包含在包中。为此，您应将 nativescript-worker-loader 添加到项目中：npm i -D nativescript-worker-loader。

照片和缩略图图像

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

Android 特定

权限

此插件使用 Nathanael Anderson 的 nativescript-permissions 插件来获取 Android 6 及以上版本对手机联系人的只读权限。

iOS 特定

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

权限

从 iOS 10 开始，必须在应用程序的 Info.plist 中添加 NSContactsUsageDescription 键（请参阅 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 插件中的代码。