スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いのAIツールに Capgo のスキルを追加してください：

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

次に、以下のプロンプトを使用します：

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

ネイティブの連絡先ピッカーを使用して、連絡先を1件選択します。

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

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

pickContacts

ネイティブの連絡先ピッカーを使用して、1つ以上の連絡先を選択します。

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[];
}

Source of Truth

このページはプラグインの src/definitions.tsから生成されています。upstream で公開 API が変更されたら、再度 sync を実行してください。

Getting Startedの続きを進める

使用している場合 スタートガイド ダッシュボードと API の運用を計画するには、これを次と連携させます @capgo/capacitor-contacts の使用方法 @capgo/capacitor-contacts を使用してネイティブ機能を利用する場合: API の概要 「API の概要」の実装の詳細については、 はじめに 「はじめに」における実装の詳細については、 API キー および「API Keys」の実装の詳細については、 デバイス 実装の詳細については Devices を参照してください。