Buscar pacotes, repositórios e categorias de apps

Capa de flutter_contacts
Detalhes do pacotev2.6.0

flutter_contacts

Gerenciamento rápido e completo de contatos para Android, iOS e macOS — todos os campos, grupos, contas, vCards, diálogos nativos, ouvintes, contatos do SIM e bloqueio de números.

AndroidiOSmacOS
Downloads em 30 dias
373 mil
Curtidas
503
Pontos Pub
160

Instalar pacote

flutter pub add flutter_contacts

Visão geral do pacote

Orientação gerada a partir de informações públicas. Apenas para referência.

flutter_contacts é um pacote abrangente de gerenciamento de contatos para aplicativos Flutter voltados para Android, iOS e macOS. Permite que desenvolvedores acessem e gerenciem contatos com suporte completo para todos os campos, grupos de contatos, múltiplas contas, importação/exportação de vCard, diálogos nativos de contatos, ouvintes em tempo real, contatos do cartão SIM e bloqueio de números de telefone. O pacote oferece uma experiência fluida e nativa da plataforma, ao mesmo tempo que abstrai APIs subjacentes complexas. É ideal para aplicativos que exigem integração profunda com o sistema de contatos do dispositivo.

Casos de uso

  • Seletor de contatos em aplicativos de mensagens
  • Sincronizando contatos do usuário com os dados do aplicativo
  • Importação/exportação de vCards
  • Gerenciar grupos de contatos
  • Bloquear números indesejados
  • Exibindo contatos do SIM

Principais recursos

  • Acesso completo ao campo de contato
  • Suporte para grupos de contatos e contas
  • Importação/exportação de vCard
  • Diálogos nativos de contato
  • ouvintes de contato em tempo real
  • Contato do suporte SIM

Indicado para

  • Aplicativos de mensagens e chamadas
  • CRM e ferramentas de negócios
  • Plataformas de redes sociais
  • Serviços de sincronização de contatos
  • Aplicativos que precisam de bloqueio de número

Considerações

  • Requer permissões apropriadas em cada plataforma
  • Pode ser necessário configuração adicional para declarações de privacidade do iOS
  • O desempenho depende do tamanho do banco de dados de contatos do dispositivo
  • Limitado ao sistema nativo de contatos (sem sincronização em nuvem)
  • Não adequado para recursos não relacionados ao contato

README original

Snapshot do README original do repositório-fonte vinculado. Consulte o repositório para o conteúdo mais recente.

📞 Flutter Contacts

The fastest, most complete Flutter plugin for native contacts 🚀

Get, create, update, and delete contacts with comprehensive property support. Includes groups, accounts, vCard import/export, native dialogs, real-time change listeners, permissions management, and platform-specific APIs across Android, iOS, and macOS.

pub version pub likes pub dm license

💜 Sponsored by Quis Contacts — a modern, private contacts app from the makers of this plugin.

Website App Store Google Play


⚡ Why Flutter Contacts?

  • 🏆 Benchmarks: up to 7x faster reads, 100x faster bulk operations
  • 📈 Scalable - handles 10,000+ contacts smoothly via batch operations
  • 🛡️ Read/write with comprehensive property support
  • 🔍 Efficient filtering by name, phone, email, group, and more
  • 👥 Accounts & Groups for multi-account contact management
  • 📇 vCard import/export supporting all properties and formats
  • 🔔 Real-time change listeners with change tracking
  • 🎨 Native dialogs for picking, viewing, editing contacts
  • 📱 Android-specific APIs - Blocked Numbers, Ringtones, SIM contacts
  • 🌍 Cross-platform - Android, iOS, and macOS

🚀 Quick Start

1. Add Dependency
dependencies:
  flutter_contacts: ^2.0.0
2. Configure Permissions

Android (android/app/src/main/AndroidManifest.xml):

<uses-permission android:name="android.permission.READ_CONTACTS"/>
<uses-permission android:name="android.permission.WRITE_CONTACTS"/>

iOS (ios/Runner/Info.plist):

<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to...</string>
iOS Notes Entitlement

To access contact notes on iOS, add the com.apple.developer.contacts.notes entitlement and set FlutterContacts.config.enableIosNotes = true. See Apple's documentation.

3. Basic Usage
import 'package:flutter_contacts/flutter_contacts.dart';

// Request permissions
final status = await FlutterContacts.permissions.request(PermissionType.readWrite);
if (status == PermissionStatus.granted) {
  // Get all contacts (fast - defaults to IDs and display names only)
  List<Contact> contacts = await FlutterContacts.getAll();

  // Get a specific contact with all properties
  Contact? contact = await FlutterContacts.get(
    contacts.first.id!,
    properties: ContactProperties.all,
  );
}

📂 See example/ for a minimal example, or flutter_contacts_example for a full-fledged contacts app.


🧠 Core Concepts

📐 API Structure
Category API Purpose
Core CRUD FlutterContacts.get(), .getAll(), .create(), .createAll(), .update(), .updateAll(), .delete(), .deleteAll() Contact operations
Feature APIs FlutterContacts.accounts, .groups, .permissions, .vCard, .native, .config Specialized features
Platform APIs FlutterContacts.sim (Android), .profile (Android/macOS), .blockedNumbers (Android), .ringtones (Android) Platform-specific
Streams FlutterContacts.onDatabaseChange, .onContactChange Real-time notifications
⚡ Selective Fetching

By default, get() and getAll() fetch only ID and display name. Specify properties for additional fields.

// List view: display name is always fetched, add thumbnails
await FlutterContacts.getAll(
  properties: {ContactProperty.photoThumbnail},
);

// Detail view: all properties
await FlutterContacts.get(contactId, properties: ContactProperties.all);
🔒 Data Integrity

Only fetched properties can be updated. This prevents accidental data loss.

// Fetch name + phone only
var contact = await FlutterContacts.get(id, properties: {ContactProperty.name, ContactProperty.phone});

// Only name and phone are saved; email changes would be ignored
contact = contact.copyWith(name: Name(first: 'Jane'));
await FlutterContacts.update(contact);
Unified Contact Model

On Android, multiple "raw contacts" from different accounts are automatically merged into unified contacts. On iOS, the same merging happens behind the scenes. The plugin provides a single, consistent API across both platforms.

Accounts & Groups

Accounts (containers on iOS) organize contacts by source - Google, iCloud, local device. Groups (labels on Android) organize contacts within an account. When creating a contact, you can specify which account to use; otherwise, it uses the default.


📊 Performance Benchmarks

Tested with ~2,000 contacts on real devices (iPhone 7, Pixel 6):

                          Fetch all contacts: ID + display name (ms)

                          ━━━━━━━━━━━━ iOS ━━━━━━━━━━━━  ━━━━━━━━━━ Android ━━━━━━━━━━━

                          ◀─── faster  slower ───▶        ◀─── faster slower ───▶
flutter_contacts v2       █████░░░░░░░░░░░░░░░░░░░  117   ██████████░░░░░░░░░░░░░   424
fast_contacts             █████░░░░░░░░░░░░░░░░░░░  127   ███████░░░░░░░░░░░░░░░░   304
contacts_service_plus     █████████████░░░░░░░░░░░  462   ███████████████░░░░░░░░   668
flutter_contacts v1       ███████████████████████░  803   ███████████████████████  1075
V2 vs V1 iOS Android
Read speed 1.6–7x faster 2–5x faster
Bulk create 4x faster 5x faster
Bulk delete 34x faster 140x faster

See the benchmark repository for detailed methodology and feature comparison.


📚 Core API

Read
// Single contact with all properties
Contact? contact = await FlutterContacts.get(id, properties: ContactProperties.all);

// All contacts with filtering
List<Contact> contacts = await FlutterContacts.getAll(
  properties: {ContactProperty.name, ContactProperty.phone},
  filter: ContactFilter.name('John'),
  limit: 100,
);

Both get() and getAll() default to fetching only ID + display name. Specify properties for additional fields.

Properties: name, phone, email, address, organization, website, socialMedia, event, relation, note, photoThumbnail, photoFullRes, favorite (Android), ringtone (Android), sendToVoicemail (Android), timestamp (Android), identifiers (Android). Use ContactProperties.all for all properties, or ContactProperties.allProperties to exclude photos. Only fetch the properties you need to improve query performance.

Filters: ContactFilter.name(), .phone(), .email(), .group(), .ids(). Phone/email filters use partial match on Android, full match on iOS.

Create
String id = await FlutterContacts.create(contact, account: account);
List<String> ids = await FlutterContacts.createAll([contact1, contact2]);
Update
// Must fetch first (see Data Integrity above)
await FlutterContacts.update(contact);
await FlutterContacts.updateAll([contact1, contact2]);
Delete
await FlutterContacts.delete(id);
await FlutterContacts.deleteAll([id1, id2, id3]);

🔧 Feature APIs

🔐 Permissions
bool has = await FlutterContacts.permissions.has(PermissionType.read);
PermissionStatus status = await FlutterContacts.permissions.check(PermissionType.read);
PermissionStatus result = await FlutterContacts.permissions.request(PermissionType.readWrite);
await FlutterContacts.permissions.openSettings();

Types: PermissionType.read, .write, .readWrite (on iOS, all are equivalent).

👤 Accounts
List<Account> accounts = await FlutterContacts.accounts.getAll();
Account? defaultAccount = await FlutterContacts.accounts.getDefault();
await FlutterContacts.accounts.showDefaultPicker(); // Android only
👥 Groups
Group? group = await FlutterContacts.groups.get(groupId, withContactCount: true);
List<Group> groups = await FlutterContacts.groups.getAll(accounts: [account]);
Group created = await FlutterContacts.groups.create('Family', account: account);
await FlutterContacts.groups.update(group);
await FlutterContacts.groups.delete(groupId);
await FlutterContacts.groups.addContacts(groupId: groupId, contactIds: [id1, id2]);
await FlutterContacts.groups.removeContacts(groupId: groupId, contactIds: [id1]);
List<Group> contactGroups = await FlutterContacts.groups.getOf(contactId);
📇 vCard
String vCard = FlutterContacts.vCard.export(contact, version: VCardVersion.v3);
String vCards = FlutterContacts.vCard.exportAll([contact1, contact2]);
List<Contact> contacts = FlutterContacts.vCard.import(vCardString);

Supports vCard 2.1, 3.0, and 4.0.

🎨 Native Dialogs (Android & iOS)

System UI for picking, viewing, editing, and creating contacts.

Contact? picked = await FlutterContacts.native.showPicker(
  properties: {ContactProperty.phone},
);
await FlutterContacts.native.showViewer(contactId);
String? editedId = await FlutterContacts.native.showEditor(contactId);
String? createdId = await FlutterContacts.native.showCreator(contact: prefill);

Permissions:

  • showPicker() and showCreator() need no contacts permission on either platform.
  • showPicker(properties: …) is permissionless on iOS. On Android it requires READ_CONTACTS and throws PlatformException if missing.
  • showViewer() and showEditor() are permissionless on Android. On iOS they require NSContactsUsageDescription in Info.plist and a granted read permission.
🔔 Change Listeners
FlutterContacts.onDatabaseChange.listen((_) => refreshUI());

FlutterContacts.onContactChange.listen((changes) {
  for (final change in changes) {
    print('${change.type}: ${change.contactId}');
  }
});
📱 SIM Contacts (Android only)
List<Contact> simContacts = await FlutterContacts.sim.get();

SIM contacts are read-only and typically contain only name and phone.

👤 Profile / "Me" Card (Android & macOS)
Contact? me = await FlutterContacts.profile.get(properties: ContactProperties.all);

Returns the device owner's profile (Android) or "Me" card (macOS). Not available on iOS.

🚫 Blocked Numbers (Android only)

Requires app to be default phone app. See example manifest.

if (await FlutterContacts.blockedNumbers.isAvailable()) {
  bool isBlocked = await FlutterContacts.blockedNumbers.isBlocked('+1234567890');
  List<Phone> blocked = await FlutterContacts.blockedNumbers.getAll();
  await FlutterContacts.blockedNumbers.block('+1234567890');
  await FlutterContacts.blockedNumbers.blockAll([number1, number2]);
  await FlutterContacts.blockedNumbers.unblock('+1234567890');
  await FlutterContacts.blockedNumbers.unblockAll([number1, number2]);
  await FlutterContacts.blockedNumbers.openDefaultAppSettings();
}
🔔 Ringtones (Android only)
String? uri = await FlutterContacts.ringtones.pick(type: RingtoneType.ringtone);
Ringtone? ringtone = await FlutterContacts.ringtones.get(uri, withMetadata: true);
List<Ringtone> all = await FlutterContacts.ringtones.getAll(type: RingtoneType.ringtone);
String? defaultUri = await FlutterContacts.ringtones.getDefaultUri(RingtoneType.ringtone);
await FlutterContacts.ringtones.setDefaultUri(RingtoneType.ringtone, uri);
await FlutterContacts.ringtones.play(uri);
await FlutterContacts.ringtones.stop();
⚙️ Configuration
FlutterContacts.config.enableIosNotes = true; // Requires iOS entitlement

📋 Data Model

See lib/models/ for complete data model documentation.

A Contact contains an id, an auto-generated displayName, and lists of properties (phones, emails, addresses, etc.). Many properties support native labels (home, work, mobile, etc.) and custom labels.

Contact Structure
class Contact {
  final String? id;                         // Stable identifier
  final String? displayName;                // Read-only, auto-generated
  final Photo? photo;
  final Name? name;
  final List<Phone> phones;
  final List<Email> emails;
  final List<Address> addresses;
  final List<Organization> organizations;
  final List<Website> websites;
  final List<SocialMedia> socialMedias;
  final List<Event> events;                 // Birthdays, anniversaries
  final List<Relation> relations;
  final List<Note> notes;

  // Android-specific fields: isFavorite, customRingtone,
  // sendToVoicemail, timestamp, identifiers
  final AndroidData? android;
}
Property Types
// Name
Name(
  first: 'John',
  last: 'Smith',
  middle: 'Q',
  prefix: 'Dr.',
  suffix: 'Jr.',
)

// Phone, Email, Address
Phone('555-1234')
Phone('555-1234', label: Label(PhoneLabel.mobile))
Email('john@example.com', label: Label(EmailLabel.work))
Address(
  street: '123 Main St',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
  label: Label(AddressLabel.home),
)

// Organization
Organization(
  organizationName: 'FlutterCorp',
  jobTitle: 'Software Engineer',
  departmentName: 'Engineering',
)

// Photo
Photo(fullSize: imageBytes)

Address Usage: Prefer component fields (street, city, state, etc.) when creating/editing. The formatted field is available when reading and is guaranteed to be present.

Photo Usage: When creating/updating, set Photo(fullSize: imageBytes) - the system automatically generates the thumbnail. When reading, fetch ContactProperty.photoThumbnail (fast) for contact lists, ContactProperty.photoFullRes (slower) for detail views.

Note: The examples above show common fields. See lib/models/ for the complete list of all available fields and properties.

Labels

Most properties support labels (home, work, mobile, etc.) and custom labels:

// Standard label
Phone('555-1234', label: Label(PhoneLabel.mobile))

// Custom label
Phone('555-1234', label: Label(PhoneLabel.custom, customLabel: 'Emergency'))

Platform Support: Some labels are platform-specific (e.g., PhoneLabel.appleWatch is iOS-only, PhoneLabel.workMobile is Android-only). Unsupported labels are automatically converted to custom labels with the original name preserved.


⚠️ Platform Limitations

iOS & macOS

Not Available:

  • APIs: ringtones, blockedNumbers, sim, profile (iOS), native (macOS)
  • Properties: favorite, ringtone, sendToVoicemail, timestamp, identifiers, debugData (all nested in android field)
  • Fields: Phone.isPrimary, Phone.normalizedNumber, Email.isPrimary, Address.poBox, Address.neighborhood, Organization.jobDescription, Organization.symbol, Organization.officeLocation
  • Some Android-specific labels (auto-converted to custom)

Limits: One organization, one note, one birthday per contact.

Filtering: Phone and email filters only support full match (not partial).

iOS Notes: Requires the com.apple.developer.contacts.notes entitlement and FlutterContacts.config.enableIosNotes = true. See Apple's documentation.

Android

Not Available:

  • Fields: Name.previousFamilyName, Address.isoCountryCode, Address.subAdministrativeArea, Address.subLocality
  • Some iOS-specific labels (auto-converted to custom)

Special Features:

  • SIM Contacts: Read-only, typically name + phone only
  • Blocked Numbers: Requires app to be default phone app

🔄 Migrating from v1

If you're using flutter_contacts v1:

v1 v2
FlutterContacts.getContacts() FlutterContacts.getAll()
FlutterContacts.getContact(id) FlutterContacts.get(id)
contact.insert() FlutterContacts.create(contact)
FlutterContacts.requestPermission() FlutterContacts.permissions.request(PermissionType.readWrite)
FlutterContacts.addListener() FlutterContacts.onDatabaseChange.listen()
contact.toVCard() FlutterContacts.vCard.export(contact)
PhoneLabel.mobile Label(PhoneLabel.mobile)
FlutterContacts.openExternalView(id) FlutterContacts.native.showViewer(id)
FlutterContacts.openExternalPick() FlutterContacts.native.showPicker()
FlutterContacts.openExternalEdit(id) FlutterContacts.native.showEditor(id)
FlutterContacts.openExternalInsert() FlutterContacts.native.showCreator()

🤝 Contributing

We'd love your help making this plugin even better. Found a bug? Have a feature idea? Want to improve the docs?

Every contribution, big or small, makes a difference. Thank you for helping make Flutter Contacts better for everyone.


📄 License

MIT License - see the LICENSE file for details.


💝 Support

Flutter Contacts is maintained in my free time. If this plugin has been helpful for your project, consider supporting its development. Your support helps me continue maintaining and improving it.

ko-fi


🙏 Acknowledgments

Special thanks to all contributors and users who have helped shape this plugin.


Made with ❤️ for the Flutter community

⭐ Star us on GitHub | 📖 Documentation | 🐛 Report Issues

Categorias

Repositório-fonte

Projetos que usam este pacote