flutter_contacts：高性能 Flutter 联系人管理插件

dependencies:
  flutter_contacts: ^2.0.0

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

<key>NSContactsUsageDescription</key>
<string>我们需要访问您的联系人...</string>

import 'package:flutter_contacts/flutter_contacts.dart';

// 请求权限
final status = await FlutterContacts.permissions.request(
  PermissionType.readWrite,
);

if (status == PermissionStatus.granted) {
  // 获取所有联系人（默认只获取 ID 和显示名称）
  List<Contact> contacts = await FlutterContacts.getAll();

  // 获取指定联系人的所有属性
  Contact? contact = await FlutterContacts.get(
    contacts.first.id!,
    properties: ContactProperties.all,
  );
}

// 列表视图：只获取缩略图，提高性能
final contacts = await FlutterContacts.getAll(
  properties: {ContactProperty.photoThumbnail},
);

// 渲染联系人列表
ListView.builder(
  itemCount: contacts.length,
  itemBuilder: (context, index) {
    final contact = contacts[index];
    return ListTile(
      leading: contact.photoThumbnail != null
          ? Image.memory(contact.photoThumbnail!)
          : CircleAvatar(child: Text(contact.displayName[0])),
      title: Text(contact.displayName),
    );
  },
);

final contact = Contact(
  name: Name(first: '张', last: '三'),
  phones: [Phone('13800138000', label: PhoneLabel.mobile)],
  emails: [Email('zhangsan@example.com', label: EmailLabel.work)],
);

final id = await FlutterContacts.create(contact);

// 先获取联系人（指定需要的属性）
var contact = await FlutterContacts.get(
  id,
  properties: {ContactProperty.name, ContactProperty.phone},
);

// 更新属性
contact = contact.copyWith(
  name: Name(first: '李', last: '四'),
);

// 保存更新
await FlutterContacts.update(contact);

// 按姓名筛选
final results = await FlutterContacts.getAll(
  filter: ContactFilter.name('张三'),
  limit: 100,
);

// 按手机号筛选（Android 支持部分匹配，iOS 需要完整匹配）
final byPhone = await FlutterContacts.getAll(
  filter: ContactFilter.phone('1380013'),
);

// 按群组筛选
final byGroup = await FlutterContacts.getAll(
  filter: ContactFilter.group(groupId),
);

// 批量创建
final ids = await FlutterContacts.createAll([contact1, contact2, contact3]);

// 批量更新
await FlutterContacts.updateAll([contact1, contact2]);

// 批量删除
await FlutterContacts.deleteAll([id1, id2, id3]);

// 导出为 vCard
final vCardString = await FlutterContacts.vCard.export(contact);

// 从 vCard 导入
final importedContacts = await FlutterContacts.vCard.import(vCardString);

// 监听数据库变更
FlutterContacts.onDatabaseChange.listen((event) {
  print('联系人数据库已变更: ${event.type}');
  // 刷新联系人列表
});

// 监听特定联系人变更
FlutterContacts.onContactChange.listen((event) {
  print('联系人 ${event.contactId} 已 ${event.type}');
});