Capacitor Community Contacts の代替

Capacitor community contacts の代替が必要なら、最も完全なドロップイン代替は @capgo/capacitor-contacts。カバーするのは @capacitor-community/contacts （連絡先の読み取り、作成、削除、選択）を行い、さらにIDを変更せずに連絡先を更新する機能、ページネーション、グループ、アカウント、ネイティブの連絡先画面、Androidでの権限不要の選択に対応しています。これはGoogle Playの2027年連絡先ポリシーで重要です。本ガイドでは両者を比較し、すべての呼び出しをマッピングしているので、午後には移行できます。

代替案を探す理由

@capacitor-community/contacts はメンテナンスされており、Capacitor 8 のリリースもあります。単純な読み取りと作成のフローには十分適していますが、多くのチームは次の理由で物足りなくなります：

• 更新メソッドがない。 連絡先の作成と削除は可能ですが、編集はできません。削除して再作成すると連絡先に新しいIDが割り当てられ、保存した参照が壊れ、プラグインが読み取らないデータが失われる可能性があります。
• ページネーションがない。 getContacts は、1回の呼び出しでアドレス帳全体を返します。5,000件の連絡先と写真があるデバイスでは、処理が遅く、メモリ消費も大きくなります。
• Androidでは選択に権限が必要です。 Androidの pickContact は、ピッカーを開く前に連絡先権限グループをリクエストし、その後アドレス帳から連絡先を読み取ります。 Google Playの連絡先権限ポリシーでは、Android 17をターゲットとするアプリは、以下しか保持できません。 READ_CONTACTS コア機能のために。
• グループ、アカウント、ネイティブ画面なし。 グループの一覧表示、新規連絡先の保存先アカウントの選択、システムの「新規連絡先」フォームの起動ができない。

機能比較

インストール

bun add @capgo/capacitor-contacts
bunx cap sync

このプラグインは Android マニフェストに権限を追加しません。使用するもののみを追加してください：

<!-- Needed for getContacts, getContactById, countContacts, groups, accounts -->
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Needed for createContact, updateContactById, deleteContactById, groups writes -->
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

iOS では、 NSContactsUsageDescription まで Info.plist アドレス帳を読み書きする場合に追加してください。選択のみでは不要です。

コールごとの移行ガイド

権限

// Before
import { Contacts } from '@capacitor-community/contacts';
const perm = await Contacts.requestPermissions();
if (perm.contacts !== 'granted') return;

// After
import { CapacitorContacts } from '@capgo/capacitor-contacts';
const status = await CapacitorContacts.requestPermissions({ permissions: ['readContacts'] });
if (status.readContacts !== 'granted' && status.readContacts !== 'limited') {
  await CapacitorContacts.openSettings();
  return;
}

iOS 18 以降では、ユーザーは連絡先の一部へのアクセスのみを許可できます。プラグインはこれを以下のように報告します： limited。許可済みとして扱い、共有された連絡先のみを期待してください。

すべての連絡先を読み取る

// Before: whole address book, projection object
const { contacts } = await Contacts.getContacts({
  projection: { name: true, phones: true, emails: true },
});
const first = contacts[0];
console.log(first.name?.display, first.phones?.[0]?.number);

// After: fields array, paginated
const pageSize = 200;
let offset = 0;
for (;;) {
  const { contacts } = await CapacitorContacts.getContacts({
    fields: ['displayName', 'givenName', 'familyName', 'phoneNumbers', 'emailAddresses'],
    limit: pageSize,
    offset,
  });
  render(contacts);
  if (contacts.length < pageSize) break;
  offset += pageSize;
}

declare function render(list: unknown[]): void;

使用する countContacts() 進捗バーを表示する場合は、最初にこれを実行してください。

1件の連絡先を読み取る

// Before
const { contact } = await Contacts.getContact({
  contactId: id,
  projection: { name: true, phones: true },
});

// After
const { contact } = await CapacitorContacts.getContactById({
  id,
  fields: ['displayName', 'phoneNumbers'],
});
if (!contact) console.log('Not found');

連絡先を作成する

// Before
const { contactId } = await Contacts.createContact({
  contact: {
    name: { given: 'Ada', family: 'Lovelace' },
    phones: [{ type: PhoneType.Mobile, number: '+44 20 7946 0000' }],
    emails: [{ type: EmailType.Work, address: 'ada@example.com' }],
  },
});

// After
const { id } = await CapacitorContacts.createContact({
  contact: {
    givenName: 'Ada',
    familyName: 'Lovelace',
    phoneNumbers: [{ type: 'MOBILE', value: '+44 20 7946 0000' }],
    emailAddresses: [{ type: 'WORK', value: 'ada@example.com' }],
  },
});

displayName は Capgo プラグインでは読み取り専用です。書き込むと givenName と familyName、デバイスが表示名を整形します。

連絡先を更新する (新規)

await CapacitorContacts.updateContactById({
  id,
  contact: {
    givenName: 'Ada',
    familyName: 'King',
    jobTitle: 'Analyst',
    phoneNumbers: [{ type: 'MOBILE', value: '+44 20 7946 0000' }],
  },
});

IDは変わらないので、保存した参照はそのまま使えます。誤って消してしまわないよう、まず連絡先を読み取り、残したいフィールドを送り返してください。

ユーザーに編集してもらう場合は、システムのエディタを開きます：

await CapacitorContacts.displayUpdateContactById({ id });

連絡先を削除する

// Before
await Contacts.deleteContact({ contactId: id });

// After
await CapacitorContacts.deleteContactById({ id });

連絡先を選択する

// Before: requests the contacts permission on Android first
const { contact } = await Contacts.pickContact({
  projection: { name: true, phones: true },
});

// After: one phone number, no permission on Android or iOS
import { ContactProperty } from '@capgo/capacitor-contacts';

const { contacts } = await CapacitorContacts.pickContacts({
  property: ContactProperty.PhoneNumber,
});
const phone = contacts[0]?.phoneNumbers?.[0]?.value;

ピッカーから連絡先の全レコードを取得する必要がある場合は、呼び出してください pickContact() なしで property。Androidでは、完全な連絡先が返されるのは次の場合のみです： READ_CONTACTS が付与されます。

フィールドマッピング

型の値も変わります。Capgo プラグインでは、次のような大文字の文字列を使います 'MOBILE', 'HOME', 'WORK' 電話とメール用。

1画面ずつ移行する

2つのプラグインは異なるネイティブ名（Contacts と CapacitorContacts）で登録されるため、呼び出し箇所を移行しながら併用できます。小さなアダプターを使えば、アプリの他の部分は変更不要です：

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

export interface AppContact {
  id: string;
  name: string;
  phones: string[];
}

export async function listContacts(limit = 200, offset = 0): Promise<AppContact[]> {
  const { contacts } = await CapacitorContacts.getContacts({
    fields: ['displayName', 'phoneNumbers'],
    limit,
    offset,
  });
  return contacts.map((c) => ({
    id: c.id ?? '',
    name: c.displayName ?? '',
    phones: (c.phoneNumbers ?? []).map((p) => p.value),
  }));
}

最後の呼び出し箇所を移行したら、コミュニティプラグインを削除し、 bunx cap syncを実行し、マージ後の Android マニフェストで必要な権限だけが残っていることを確認します。

トラブルシューティング

getContacts iOS では空のリストを返します。 ユーザーが限定アクセスを許可して連絡先を共有しなかった、またはアクセスを拒否した可能性があります。確認し、 readContacts 提供してください。 openSettings().

作成した連絡先がAndroidの特定のアカウントに表示されない。 を渡す account （ getAccounts()）を、作成する連絡先に含める。

写真があるとリスト表示が遅くなる。 リストビューでは photo をリクエストしない。ユーザーが連絡先を開いたときに getContactById で読み込む。

Play Consoleが READ_CONTACTS. 招待と共有フローを pickContacts({ property }) に移行し、他で不要なら権限を削除する。

リリースする

プラグインの入れ替えはネイティブの変更なので、ストアビルドが必要です。 Capgo のビルド クラウド上でiOSとAndroidのビルドを生成できます。その後、連絡先画面の修正はJavaScriptなので、そのまま配信できます Capgo Live Updates。API の完全版は次にあります: contactsプラグインのドキュメント.