Contactos de la comunidad de Capacitor

Si necesita una Capacitor comunidad contactos alternativa, la reemplazo más completo es @capgo/capacitor-contactsEs un resumen de @capacitor-community/contacts hace (leer, crear, eliminar y seleccionar contactos) y agrega la actualización de un contacto sin cambiar su ID, paginación, grupos, cuentas, pantallas de contactos nativas y selección sin permisos en Android, lo cual es importante para la política de contactos de Google Play de 2027. Esta guía compara ambos y mapea cada llamada para que pueda migrar en una tarde.

¿Por qué buscar una alternativa

@capacitor-community/contacts se mantiene y tiene una Capacitor 8 de lanzamiento. Es una buena opción para flujos de lectura y creación simples. Los equipos suelen superarlo por estas razones:

• No existe un método de actualización. Puedes crear y eliminar contactos, pero no editar uno. Eliminar y recrear da al contacto un nuevo ID, lo que rompe cualquier referencia que hayas almacenado y puede perder datos que el complemento no lee.
• No existe paginación. getContacts devuelve la libreta de direcciones completa en una sola llamada. En un dispositivo con 5,000 contactos y fotos, eso es lento y pesado en memoria.
• La selección requiere permiso en Android. El Android pickContact solicita el grupo de permisos de contactos antes de abrir el selector, luego lee el contacto desde el libro de direcciones. Política de permisos de Contactos de Google Play, las apps que apunten a Android 17 solo pueden mantener READ_CONTACTS los permisos para características básicas.
• No grupos, cuentas o pantallas nativas. No forma de listar grupos, elegir la cuenta a la que se guarda un nuevo contacto, o abrir la forma de sistema “nuevo contacto”.

Comparación de características

Instalar

bun add @capgo/capacitor-contacts
bunx cap sync

El plugin no agrega permisos a tu archivo Android manifest. Agrega solo lo que usas:

<!-- 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, agrega NSContactsUsageDescription a Info.plist si lee o escribe el libro de direcciones. No es necesario elegir.

Guía de migración, llamada por llamada

Permisos

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

On iOS 18 y posteriores, los usuarios pueden otorgar acceso a un subconjunto de contactos. El plugin informa que como limitedTómalo como concedido y solo espera los contactos compartidos.

Leer todos los contactos

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

Usa countContacts() primero si deseas mostrar una barra de progreso.

Leer un contacto

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

Crea un contacto

// 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 es solo de lectura en el plugin Capgo. Escribe givenName y familyName, y el dispositivo formatea el nombre de la pantalla.

Actualizar un contacto (nuevo)

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

La ID sigue siendo la misma, por lo que cualquier referencia que hayas guardado sigue funcionando. Lee el contacto primero y envía de vuelta los campos que deseas mantener, para que no elimines algo por error.

Si prefieres dejar que el usuario edite, abre el editor del sistema:

await CapacitorContacts.displayUpdateContactById({ id });

Borrar un contacto

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

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

Seleccionar un contacto

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

Si necesitas el registro de contacto completo desde el selector, llama pickContact() sin property. En Android devuelve el contacto completo solo cuando READ_CONTACTS se ha concedido.

Mapa de campos

Tipos de valores cambian también: el plugin Capgo utiliza cadenas de texto en mayúsculas como 'MOBILE', 'HOME', 'WORK' para teléfonos y correos electrónicos.

Migra una pantalla a la vez

Los dos plugins se registran bajo nombres nativos diferentes ("Contacts (cadenas) CapacitorContactsAsí, pueden instalarse juntos mientras se mueven los sitios de llamada. Un pequeño adaptador mantiene el resto de la aplicación sin cambios.

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

When el último sitio de llamada se mueve, elimine el plugin de la comunidad, ejecute bunx cap sync, y verifique el manifiesto Android fusionado para confirmar que solo permanecen las autorizaciones que necesita.

Troubleshooting

getContacts devuelve una lista vacía en iOS. El usuario otorgó acceso limitado y compartió ningún contacto, o denegó el acceso. Verifique readContacts y ofrezca openSettings().

El contacto creado no se muestra en una cuenta específica en Android. Proporcione un account (de getAccounts()) en el contacto que crea.

Las fotos ralentizan las listas. No solicite photo en listas de visualización. Cargue con getContactById cuando el usuario abre un contacto.

banderas de la consola de Play READ_CONTACTS. Mover flujos de invitación y compartir a pickContacts({ property }) y eliminar la autorización si no es necesario.

Enviar

Cambiar plugins es un cambio nativo, por lo que necesita una compilación de la tienda. Capgo Construcción Puede producir compilaciones de iOS y Android en la nube. Después de eso, los ajustes a sus pantallas de contacto son JavaScript y pueden salir con . La versión completa de Capgo se encuentra enEl full API está en el __CAPGO_KEEP_0__.