Capacitor Community-Kontaktalternative

Wenn Sie ein Capacitor-Community-Kontakt-Alternative benötigen, ist die vollständigste Ersatzlösung @capgo/capacitor-contacts. Sie umfasst, was @capacitor-community/contacts tun kann (Kontakte lesen, erstellen, löschen und auswählen) und fügt das Aktualisieren eines Kontakts ohne Änderung seiner ID, Paginierung, Gruppen, Konten, native Kontaktscreens und Freigabe für das Auswählen auf Android hinzu, was für die Google-Play-Kontakte-Richtlinie 2027 von Bedeutung ist. Diese Anleitung vergleicht beide und kartiert jeden Aufruf, damit Sie in einem Nachmittag migrieren können.

Wozu suchen Sie nach einer Alternative

@capacitor-community/contacts erhalten und verfügt über eine Capacitor 8 Version. Es ist eine gute Wahl für einfache Lesen- und Erstellen-Flows. Teams wachsen normalerweise darüber hinaus, weil folgende Gründe vorliegen:

• Keine Aktualisierungs-Methode. Sie können Kontakte erstellen und löschen, aber nicht bearbeiten. Die Löschung und Neuerstellung gibt dem Kontakt einen neuen ID, was jede Referenz, die Sie gespeichert haben, zerstört und Daten verlieren kann, die der Plugin nicht liest.
• Keine Paginierung. getContacts liefern Sie das gesamte Adressbuch in einem Aufruf. Auf einem Gerät mit 5.000 Kontakten und Fotos ist das langsam und memory-intensiv.
• Die Auswahl erfordert die Berechtigung auf Android. Die Android- pickContact fordert die Kontakte-Berechtigungsgruppe vor der Öffnung des Pickers an, liest dann den Kontakt aus dem Adressbuch. Unter Google Play’s Kontakte-Berechtigungsrichtlinie, können Apps, die sich auf Android 17 richten, nur READ_CONTACTS Core-Funktionen
• Keine Gruppen, Konten oder native Bildschirme. Keine Möglichkeit, Gruppen aufzulisten, das Konto auszuwählen, in das ein neuer Kontakt gespeichert wird, oder das Systemformular für neuen Kontakt zu öffnen.

Vergleich der Funktionen

Installieren

bun add @capgo/capacitor-contacts
bunx cap sync

Der Plugin fügt keine Berechtigungen zu Ihrem Android-Manifest hinzu. Fügen Sie nur das hinzu, was Sie verwenden:

<!-- 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" />

On iOS, fügen Sie NSContactsUsageDescription zu Info.plist Wenn Sie die Adressbuch lesen oder schreiben, benötigen Sie es nicht.

Migrationsschritt für Schritt

Zugriffsrechte

// 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;
}

Ab iOS 18 und später können Benutzer Zugriff auf einen Teil der Kontakte gewähren. Der Plugin meldet das als limitedBehandeln Sie es als gewährt und erwarten Sie nur die geteilten Kontakte.

Alle Kontakte lesen

// 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;

Use countContacts() zuerst, wenn Sie einen Fortschrittsbalken anzeigen möchten.

Einen Kontakt lesen

// 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');

Einen Kontakt erstellen

// 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 ist nur im Capgo-Plugin lesbar. Schreiben givenName und familyName, und das Gerät formatiert den Anzeigename.

Ein Kontakt aktualisieren (neu)

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

Die ID bleibt gleich, daher funktioniert jeder gespeicherte Verweis weiterhin. Lies den Kontakt zuerst und sende die Felder zurück, die du behalten möchtest, damit du nichts versemmst.

Wenn du es vorziehst, dass der Benutzer bearbeitet, öffne den Systemeditor:

await CapacitorContacts.displayUpdateContactById({ id });

Ein Kontakt löschen

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

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

Ein Kontakt auswählen

// 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;

Wenn du den vollständigen Kontakt aus dem Picker benötigst, rufe pickContact() ohne property. Auf Android wird der vollständige Kontakt nur zurückgegeben, wenn READ_CONTACTS Ist gewährt.

Feldzuweisung

Werttypen ändern sich auch: Der Capgo-Plugin verwendet Großbuchstaben wie z.B. 'MOBILE', 'HOME', 'WORK' für Telefone und E-Mails.

Migriere Schritt für Schritt

Die beiden Plugins registrieren sich unter unterschiedlichen Namen (Contacts und CapacitorContacts), so dass sie gemeinsam installiert werden können, während Sie die Aufrufstellen umstellen. Ein kleiner Adapter hält den Rest Ihrer App unverändert:

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),
  }));
}

Wenn das letzte Aufrufort entfernt wird, entfernen Sie die Community-Plugin, führen Sie bunx cap sync, und bestätigen Sie, dass nur die erforderlichen Berechtigungen im kombinierten Android-Manifest verbleiben.

Fehlerbehebung

getContacts gibt auf iOS eine leere Liste zurück. Der Benutzer hat nur begrenzten Zugriff gewährt und keine Kontakte geteilt oder den Zugriff abgelehnt. Überprüfen readContacts und bieten Sie an openSettings().

Der erstellte Kontakt erscheint nicht in einem bestimmten Konto auf Android. Passen Sie ein account (aus getAccounts()) in den Kontakt ein, den Sie erstellen.

Bilder verlangsamen die Listen. Bitten Sie nicht photo in Listenansichten. Laden Sie es mit getContactById wenn der Benutzer einen Kontakt öffnet.

Play Console Flags READ_CONTACTS. Übertragen Sie Einladungs- und Teilen-Flows auf pickContacts({ property }) und entfernen Sie die Berechtigung, wenn nichts anderes erforderlich ist.

Verschicken

Wechseln von Plugins ist eine native Änderung, daher ist eine Store-Build erforderlich. Capgo Build Kann iOS- und Android-Builds im Cloud produzieren. Anschließend können Korrekturen an Ihren Kontaktbildschirmen als JavaScript durchgeführt werden und gehen mit Capgo Live-UpdatesDie vollständige API befindet sich im __CAPGO_KEEP_0__.