市场place
作者 NativeScript.org
@nativescript/contacts
由 NativeScript 团队编写 | v3.0.0
轻松访问 iOS 和 Android 联系人目录。选择联系人，更新日期或添加新的联系人！
npm i --save @nativescript/contacts

@nativescript/contacts

一个插件，允许您访问 iOS 和 Android 的联系人目录。您可以选择联系人，更新它，删除它或添加新的联系人。

内容

安装

运行以下命令安装插件

npm install @nativescript/contacts

权限要求

为了使应用访问用户的联系人应用，用户必须授予它相应的权限。在请求权限之前，请确保满足以下要求。

iOS 权限要求

  • 为了说明为什么您的应用需要访问用户联系人的权限，请将 NSContactsUsageDescription 键添加到 App_Resources/iOS/Info.plist 文件中，并将其澄清作为其值。
<key>NSContactsUsageDescription</key>
<string>Kindly provide permission to access contacts on your device.</string>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.developer.contacts.notes</key>
    <true/>
  </dict>
</plist>

Android 权限要求

对于 API 级别 23+，通过在 AndroidManifest.xml 中列出以下权限，向 Android 通知您的应用需要哪些用户权限才能访问联系人。

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
<uses-permission android:name="android.permission.GLOBAL_SEARCH" />

使用 @nativescript/contacts

一旦您指明了您的应用需要从用户那里获取哪些权限，您就可以通过调用 @nativescript-community/perms 插件中的 request() 方法来请求这些权限。

import { Contact } from '@nativescript/contacts';
import { request } from '@nativescript-community/perms';

const contact = new Contact();
// build a new contact...

requestPermissions({
	"contacts": {},
	"android.permission.GET_ACCOUNTS": {},
	"android.permission.READ_CONTACTS": {},
	"android.permission.WRITE_CONTACTS": {},
	"android.permission.GLOBAL_SEARCH": {},
}).then(() => {
	contact.save();
})

获取联系人

要获取所选联系人，请调用 Contacts 类的 getContact() 方法。

import { Contact } from '@nativescript/contacts';

Contacts.getContact().then(function (args) {
	/// Returns args:
	/// args.data: Generic cross platform JSON object
	/// args.reponse: "selected" or "cancelled" depending on wheter the user selected a contact.

	if (args.response === 'selected') {
		const contact = args.data; //See data structure below

		console.log(contact.name.given + ' ' + contact.name.family);

		contact.phoneNumbers.forEach(function (phone) {
			console.log(phone.value);
		});

		//lets say you want to get the addresses
		contact.postalAddresses.forEach(function (address) {
			console.log(address.location.street);
		});
	}
});

创建新的联系人

要创建新的联系人，首先实例化 Contact 类，设置联系人的各种数据，然后调用实例上的 save() 方法以保存联系人。

import { Contact, KnownLabel } from '@nativescript/contacts';
import { ImageSource } from '@nativescript/core';

const newContact = new Contact();
newContact.name.given = 'John';
newContact.name.family = 'Doe';
newContact.phoneNumbers.push({
	label: KnownLabel.HOME,
	value: '123457890',
}); // See below for known labels
newContact.phoneNumbers.push({ label: 'My Custom Label', value: '11235813' });
newContact.photo = ImageSource.fromFileOrResource('~/photo.png');
newContact.save();

更新联系人

要更新现有的联系人，使用 getContact() 方法获取它，编辑它，然后调用 save() 方法以更新它。

import { Application, ImageSource } from '@nativescript/core';
import { Contacts } from '@nativescript/contacts';

Contacts.getContact().then(function (args) {
	if (args.response === 'selected') {
		const contact = args.data;
		contact.name.given = 'Jane';
		contact.name.family = 'Doe';

		ImageSource.fromUrl('http://www.google.com/images/errors/logo_sm_2.png').then(function (src) {
			contact.photo = src;
			contact.save();
		});
	}
});

删除联系人

要删除联系人，使用 getContact() 方法获取它，然后在其上调用 delete() 方法。

import { Contacts } from '@nativescript/contacts';

Contacts.getContact().then(function (args) {
	/// args.data: Generic cross platform JSON object
	/// args.reponse: "selected" or "cancelled" depending on wheter the user selected a contact.

	if (args.response === 'selected') {
		const contact = args.data; //See data structure below
		contact.delete();
	}
});

检查联系人是否已统一/链接（iOS 特定）

要检查联系人是否已统一，请调用联系人的 isUnified()。

import { Contacts } from '@nativescript/contacts';

Contacts.getContact().then(function (args) {
	/// args.data: Generic cross platform JSON object
	/// args.reponse: "selected" or "cancelled" depending on whether the user selected a contact.

	if (args.response === 'selected') {
		const contact = args.data; //See data structure below
		console.log(contact.isUnified() ? 'Contact IS unified' : 'Contact is NOT unified');
	}
});

按名称获取联系人

要查找所有与特定名称匹配的联系人，请使用 getContactsByName() 方法。返回联系人数据数组。

import { Contacts } from '@nativescript/contacts';

/*
  contactFields contains the fields to retrieve from native backend to reduce processing time
  const contactFields = ['name','organization','nickname','notes','photo','urls','phoneNumbers','emailAddresses','postalAddresses']
*/
const contactFields = ['name', 'phoneNumbers'];

Contacts.getContactsByName('Hicks', contactFields).then(
	function (args) {
		console.log('getContactsByName Complete');
		/// Returns args:
		/// args.data: Generic cross platform JSON object, null if no contacts were found.
		/// args.reponse: "fetch"
	},
	function (err) {
		console.log('Error: ' + err);
	}
);

获取所有联系人

要读取所有联系人，请使用 getAllContacts() 方法。它返回一个包含 Contact 实例的数组。

import { Contacts } from '@nativescript/contacts';

/*
  Optional: contactFields contains the fields to retrieve from native backend to reduce processing time
  const contactFields = ['name','organization','nickname','notes','photo','urls','phoneNumbers','emailAddresses','postalAddresses']

  If not supplied, all available contactFields will be returned.
*/
const contactFields = ['name', 'phoneNumbers'];

Contacts.getAllContacts(contactFields).then(
	function (args) {
		console.log('getAllContacts Complete');
		/// Returns args:
		/// args.data: Generic cross platform JSON object, null if no contacts were found.
		/// args.reponse: "fetch"
	},
	function (err) {
		console.log('Error: ' + err);
	}
);

按 ID 获取联系人

要查找具有特定标识符的联系人，请使用 getContactById() 方法。该方法返回一个 iOS-specific GetFetchResult 对象。

import { Contacts } from '@nativescript/contacts';

const contactId = '[Contact Identifier]'; // Assumes this is a valid contact identifier (Contact.id)

Contacts.getContactById(contactId).then(
	function (args) {
		console.log('getContactById Complete');
		/// Returns args:
		/// args.data: Generic cross platform JSON object, null if no contacts were found.
		/// args.reponse: "fetch"
	},
	function (err) {
		console.log('Error: ' + err);
	}
);

获取联系人组或联系人组

要获取一个或多个联系人组，请使用 getGroups() 方法。要获取具有特定名称的联系人组，请将组名称传递给该方法。

import { Contacts } from '@nativescript/contacts';

Contacts
	.getGroups('Test Group') //[name] optional. If defined will look for group with the specified name, otherwise will return all groups.
	.then(
		function (args) {
			console.log('getGroups Complete');
			/// Returns args:
			/// args.data: Generic cross platform JSON object, null if no groups were found.
			/// args.reponse: "fetch"

			if (args.data === null) {
				console.log('No Groups Found!');
			} else {
				console.log('Group(s) Found!');
			}
		},
		function (err) {
			console.log('Error: ' + err);
		}
	);

创建新的联系人组

要创建一个新的联系人组，创建一个 Group 类的实例，设置组名，然后在该实例上调用 save() 方法以保存。

import { Group } from '@nativescript/contacts/models';

const groupModel = new Group();
groupModel.name = 'Test Group';
//Save Argument (boolean)
//iOS: [false=> Use Local Container, true=> Use Default Container]
//Android: will always be true, setting this value will not affect android.
groupModel.save(false);

删除联系人组

要删除联系人组，首先使用 getGroups() 方法获取感兴趣的组。然后在该组上调用 delete() 方法以删除它。

import { Contacts } from '@nativescript/contacts';

Contacts.getGroups('Test Group').then(
	function (args) {
		console.log('getGroups Complete');
		console.log(JSON.stringify(args));
		/// Returns args:
		/// args.data: Generic cross platform JSON object, null if no groups were found.
		/// args.reponse: "fetch"

		if (args.data !== null) {
			console.log('Group(s) Found!');
			args.data[0].delete(); //Delete the first found group
		}
	},
	function (err) {
		console.log('Error: ' + err);
	}
);

将联系人添加到组中

要将联系人添加到组中，获取感兴趣的联系人和组的引用。接下来，在组上调用 addMember() 方法，并传递要添加的联系人引用。

import { Contacts } from '@nativescript/contacts';

Contacts.getContact().then(function (args) {
	/// args.reponse: "selected" or "cancelled" depending on whether the user selected a contact.

	if (args.response === 'selected') {
		const contact = args.data; //See data structure below
		Contacts.getGroups('Test Group').then(
			function (a) {
				if (a.data !== null) {
					const group = a.data[0];
					group.addMember(contact);
				}
			},
			function (err) {
				console.log('Error: ' + err);
			}
		);
	}
});

从组中删除联系人

在 Group 类实例上调用 removeMember()，传递要删除的联系人。

import { Contacts } from '@nativescript/contacts';

Contacts
	.getGroups('Test Group') 
	.then(
		function (args) {
			if (args.data !== null) {
				const group = args.data[0];

				Contacts.getContactsInGroup(group).then(
					function (a) {
						
						/// args.reponse: "fetch"
						console.log('getContactsInGroup complete');

						if (a.data !== null) {
							a.data.forEach(function (c, idx) {
								group.removeMember(c);
							});
						}
					},
					function (err) {
						console.log('Error: ' + err);
					}
				);
			}
		},
		function (err) {
			console.log('Error: ' + err);
		}
	);

获取组中的所有联系人

要获取组的所有联系人，请使用 Contacts.getContactsInGroup() 方法，并传递组实例。

import { Contacts } from '@nativescript/contacts';

Contacts
	.getGroups('Test Group') //[name] optional. If defined will look for group with the specified name, otherwise will return all groups.
	.then(
		function (args) {
			if (args.data !== null) {
				const group = args.data[0];

				Contacts.getContactsInGroup(group).then(
					function (a) {
						console.log('getContactsInGroup complete');
						/// Returns args:
						/// args.data: Generic cross platform JSON object, null if no groups were found.
						/// args.reponse: "fetch"
					},
					function (err) {
						console.log('Error: ' + err);
					}
				);
			}
		},
		function (err) {
			console.log('Error: ' + err);
		}
	);

联系人类

联系人类具有以下结构

{
    id : "",
    name : {
        given: "",
        middle: "",
        family: "",
        prefix: "",
        suffix: "",
        displayname: "",
        phonetic : {
            given: "",
            middle: "",
            family: ""
        }
    },
    nickname : "",
    organization : {
        name: "",
        jobTitle: "",
        department: "",

        // Android Specific properties
        symbol: "",
        phonetic: "",
        location: "",
        type: ""
    },
    notes : "",
    photo: null, // {N} ImageSource instance

    phoneNumbers : [],
    emailAddresses : [],
    postalAddresses : [],
    urls : []
}

电话号码/电子邮件地址结构

{
    id: "",
    label: "",
    value: ""
}

URL 结构

{
    label: "",
    value: ""
}

邮政地址结构

{
    id: "",
    label: "",
    location: {
        street: "",
        city: "",
        state: "",
        postalCode: "",
        country: "",
        countryCode: ""
    }
}

已知标签（用于 URL、地址和电话）

插件通过 KnownLabel 对象公开以下标签，用于联系人数据。

  • HOME iOS - 电话，电子邮件，邮政，网址 Android - 电话，电子邮件，邮政，网址
  • WORK iOS - 电话，电子邮件，邮政，网址 Android - 电话，电子邮件，邮政，网址
  • OTHER iOS - 电话，电子邮件，邮政，网址 Android - 电话，电子邮件，邮政，网址
  • FAX_HOME iOS - 电话 Android - 电话
  • FAX_WORK iOS - 电话 Android - 电话
  • PAGER iOS - 电话 Android - 电话
  • MAIN iOS - 电话 Android - 电话
  • HOMEPAGE iOS - 网址 Android - 网址
  • CALLBACK Android - 电话
  • CAR Android - 电话
  • COMPANY_MAIN Android - 电话
  • ISDN Android - 电话
  • OTHER_FAX Android - 电话
  • RADIO Android - 电话
  • TELEX Android - 电话
  • TTY_TDD Android - 电话
  • WORK_MOBILE Android - 电话
  • WORK_PAGER Android - 电话
  • ASSISTANT Android - 电话
  • MMS Android - 电话
  • FTP Android - 网址
  • PROFILE Android - 网址
  • BLOG Android - 网址

这些是系统标签，但您也可以使用任何想要的自定义标签。

组对象结构

{
	id: string,
	name: string,
	addMember: (constact: Contact) => void
	removeMember: (constact: Contact) => void

}

GetFetchResult 对象结构

Contacts 类的 getContactById() 方法返回的对象。

{
  data: Contact[];
  response: string;
}

iOS 联系人对象

有关可用的属性，请参阅 Apple 文档：https://developer.apple.com/library/mac/documentation/Contacts/Reference/CNContact_Class/index.html#//apple_ref/occ/cl/CNContact

注意：该插件使用联系人框架，并且仅在 iOS 9.0 及以上版本中受支持！

致谢

所有荣誉都归原作者 Ryan Lebel，他创建了 nativescript-contacts。

许可

Apache License Version 2.0