flutter_contacts는 Android, iOS 및 macOS를 대상으로 하는 Flutter 애플리케이션을 위한 포괄적인 연락처 관리 패키지입니다. 모든 필드, 연락처 그룹, 여러 계정, vCard 가져오기/내보내기, 네이티브 연락처 다이얼로그, 실시간 리스너, SIM 카드 연락처 및 전화번호 차단을 완전히 지원합니다. 복잡한 하위 API를 추상화하면서 플랫폼에 맞는 원활한 경험을 제공합니다. 장치의 연락처 시스템과 깊이 통합이 필요한 앱에 이상적입니다.
사용 사례
메시지 앱에서 연락처 선택기
사용자 연락처를 앱 데이터와 동기화 중
vCard 가져오기/내보내기
연락처 그룹 관리
원하지 않는 번호 차단
SIM 연락처 표시
주요 기능
완전한 연락처 필드 접근
연락처 그룹 및 계정 지원
vCard 가져오기/내보내기
네이티브 연락처 대화상자
실시간 연락처 리스너
SIM 고객 지원 연락
적합한 대상
메시징 및 통화 앱
CRM 및 비즈니스 도구
소셜 네트워킹 플랫폼
연락처 동기화 서비스
번호 차단이 필요한 앱
고려 사항
각 플랫폼에서 적절한 권한이 필요합니다
iOS 개인정보 선언을 위해 추가 설정이 필요할 수 있습니다
성능은 장치 연락처 데이터베이스 크기에 따라 달라집니다
네이티브 연락처 시스템에 제한됨(클라우드 동기화 없음)
비접촉 관련 기능에 적합하지 않습니다
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
📞 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.
💜 Sponsored by Quis Contacts — a modern, private contacts app from the makers of this plugin.
⚡ 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
<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 permissionsfinal status = awaitFlutterContacts.permissions.request(PermissionType.readWrite);
if (status == PermissionStatus.granted) {
// Get all contacts (fast - defaults to IDs and display names only)List<Contact> contacts = awaitFlutterContacts.getAll();
// Get a specific contact with all propertiesContact? contact = awaitFlutterContacts.get(
contacts.first.id!,
properties: ContactProperties.all,
);
}
By default, get() and getAll() fetch only ID and display name. Specify properties for additional fields.
// List view: display name is always fetched, add thumbnailsawaitFlutterContacts.getAll(
properties: {ContactProperty.photoThumbnail},
);
// Detail view: all propertiesawaitFlutterContacts.get(contactId, properties: ContactProperties.all);
🔒 Data Integrity
Only fetched properties can be updated. This prevents accidental data loss.
// Fetch name + phone onlyvar contact = awaitFlutterContacts.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'));
awaitFlutterContacts.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):
// Single contact with all propertiesContact? contact = awaitFlutterContacts.get(id, properties: ContactProperties.all);
// All contacts with filteringList<Contact> contacts = awaitFlutterContacts.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.
bool has = awaitFlutterContacts.permissions.has(PermissionType.read);
PermissionStatus status = awaitFlutterContacts.permissions.check(PermissionType.read);
PermissionStatus result = awaitFlutterContacts.permissions.request(PermissionType.readWrite);
awaitFlutterContacts.permissions.openSettings();
Types:PermissionType.read, .write, .readWrite (on iOS, all are equivalent).
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}');
}
});
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.
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:
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.
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.
🙏 Acknowledgments
Special thanks to all contributors and users who have helped shape this plugin.