快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

然后使用以下 prompt：

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-contacts` plugin in my project.

如果你更倾向于手动设置，请运行以下命令安装插件，并参考下文针对各平台的具体说明：

npm install @capgo/capacitor-contacts
npx cap sync

导入

import { CapacitorContacts } from '@capgo/capacitor-contacts';

快速入门

请求访问权限，然后使用合理的分页大小加载联系人，而不是加载整个通讯录。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.requestPermissions();
const { contacts } = await CapacitorContacts.getContacts({ limit: 50, offset: 0 });
// Increase offset by limit for the next page instead of loading the full address book.

常见坑点

• 设计原理: 在弹出对话框前，解释为何需要访问联系人权限。
• 分页加载: 避免一次性加载整个通讯录。
• 写入: 创建联系人需要写入权限。

API 概览

countContacts

统计设备上的联系人总数。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.countContacts();
console.log(result);

createContact

通过代码创建新联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.createContact({ contact: {} });
console.log(result);

createGroup

创建一个新的联系人分组。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.createGroup({ group: { name: 'example' } });
console.log(result);

deleteContactById

通过 ID 删除联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.deleteContactById({ id: 'id-123' });

deleteGroupById

通过 ID 删除分组。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.deleteGroupById({ id: 'id-123' });

displayContactById

使用原生联系人查看器显示联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.displayContactById({ id: 'id-123' });

displayCreateContact

显示原生的创建联系人 UI。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.displayCreateContact();
console.log(result);

displayUpdateContactById

显示指定联系人的原生更新联系人 UI。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.displayUpdateContactById({ id: 'id-123' });

getAccounts

获取设备上所有可用的账户。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getAccounts();
console.log(result);

getContactById

通过 ID 获取特定联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getContactById({ id: 'id-123' });
// The result holds sensitive values: use it without logging it.

getContacts

获取设备上的所有联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getContacts();
// The result holds sensitive values: use it without logging it.

getGroupById

通过 ID 获取特定分组。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getGroupById({ id: 'id-123' });
console.log(result);

getGroups

获取所有联系人分组。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.getGroups();
console.log(result);

isAvailable

检查设备是否支持联系人功能。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.isAvailable();
console.log(result);

isSupported

检查当前平台是否支持该插件。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.isSupported();
console.log(result);

openSettings

打开设备的联系人设置。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.openSettings();

pickContact

使用原生联系人选择器选择单个联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.pickContact();
// The result holds sensitive values: use it without logging it.

pickContacts

使用原生联系人选择器选取一个或多个联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.pickContacts();
// The result holds sensitive values: use it without logging it.

updateContactById

通过 ID 更新现有联系人。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

await CapacitorContacts.updateContactById({
  id: 'id-123',
  contact: {},
});

checkPermissions

检查当前的联系人权限状态。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.checkPermissions();
console.log(result);

requestPermissions

请求访问联系人的权限。

import { CapacitorContacts } from '@capgo/capacitor-contacts';

const result = await CapacitorContacts.requestPermissions();
console.log(result);

类型参考

CountContactsResult

统计联系人后的结果。

export interface CountContactsResult {
  /**
   * Total number of contacts.
   *
   * @since 1.0.0
   */
  count: number;
}

CreateContactOptions

创建联系人的选项。

export interface CreateContactOptions {
  /**
   * Contact information to create. The 'id' field will be generated automatically.
   *
   * @since 1.0.0
   */
  contact: Omit<Contact, 'id'>;
}

CreateContactResult

创建联系人后的结果。

export interface CreateContactResult {
  /**
   * The ID of the newly created contact.
   *
   * @since 1.0.0
   */
  id: string;
}

CreateGroupOptions

创建分组的配置项。

export interface CreateGroupOptions {
  /**
   * Group information to create. The 'id' field will be generated automatically.
   *
   * @since 1.0.0
   */
  group: Omit<Group, 'id'>;
}

CreateGroupResult

创建分组后的返回结果。

export interface CreateGroupResult {
  /**
   * The ID of the newly created group.
   *
   * @since 1.0.0
   */
  id: string;
}

DeleteContactByIdOptions

通过 ID 删除联系人的配置项。

export interface DeleteContactByIdOptions {
  /**
   * The ID of the contact to delete.
   *
   * @since 1.0.0
   */
  id: string;
}

DeleteGroupByIdOptions

通过 ID 删除分组的配置项。

export interface DeleteGroupByIdOptions {
  /**
   * The ID of the group to delete.
   *
   * @since 1.0.0
   */
  id: string;
}

DisplayContactByIdOptions

通过 ID 显示联系人的配置选项。

export interface DisplayContactByIdOptions {
  /**
   * The ID of the contact to display.
   *
   * @since 1.0.0
   */
  id: string;
}

DisplayCreateContactOptions

调用原生创建联系人 UI 的配置选项。

export interface DisplayCreateContactOptions {
  /**
   * Optional pre-filled contact information for the create UI.
   *
   * @since 1.0.0
   */
  contact?: Omit<Contact, 'id'>;
}

DisplayCreateContactResult

调用原生创建联系人 UI 的返回结果。

export interface DisplayCreateContactResult {
  /**
   * The ID of the created contact, if one was created. Undefined if the user cancelled.
   *
   * @since 1.0.0
   */
  id?: string;
}

DisplayUpdateContactByIdOptions

调用原生更新联系人 UI 的配置选项。

export interface DisplayUpdateContactByIdOptions {
  /**
   * The ID of the contact to update.
   *
   * @since 1.0.0
   */
  id: string;
}

GetAccountsResult

获取账户的结果。

export interface GetAccountsResult {
  /**
   * List of accounts available on the device.
   *
   * @since 1.0.0
   */
  accounts: Account[];
}

唯一数据源

本页面由该插件的 src/definitions.ts当上游的公共 API 发生变化时，请重新运行 sync。

继续阅读入门指南

如果你正在使用 快速入门 来规划 dashboard 和 API 操作，请将其连接至 使用 @capgo/capacitor-contacts 在使用 @capgo/capacitor-contacts 时，获取原生能力的方法： API 概览 关于 API 概览中的实现细节， 简介 有关 Introduction 中的实现细节， API 密钥 有关 API Keys 中的实现细节，以及 设备 有关 Devices 中的实现细节。