1. 插件介绍

flutter_contacts 是一个功能强大的 Flutter 联系人管理插件，允许开发者在应用中轻松实现联系人的读取、创建、更新和删除等操作。该插件已适配鸿蒙平台，支持鸿蒙系统的联系人管理功能，包括基本信息（姓名、电话、邮箱）、地址、组织、网站、社交媒体、事件和备注等。

2. 安装与配置

2.1 添加依赖

由于这是一个自定义修改版本，需要通过 Git 方式引入依赖。在项目的 pubspec.yaml 文件中添加以下配置：

dependencies:
  flutter_contacts:
    git:
      url: "https://gitcode.com/openharmony-sig/flutter_contacts"

然后执行以下命令获取依赖：

flutter pub get

2.2 权限配置

鸿蒙平台需要配置联系人读写权限，并且需要将应用权限级别调整为 system_basic。

2.2.1 配置 module.json5

在项目的 entry/src/main/module.json5 文件中添加以下权限配置：

"requestPermissions": [
  {
    "name": "ohos.permission.READ_CONTACTS",
    "reason": "读取联系人信息",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  },
  {
    "name": "ohos.permission.WRITE_CONTACTS",
    "reason": "写入联系人信息",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

2.2.2 调整应用权限级别

将应用权限级别从默认的 normal 调整为 system_basic，以解决安装错误 9568289。

2.2.3 添加权限说明

在 entry/src/main/resources/base/element/string.json 文件中添加权限说明：

{
  "string": [
    {
      "name": "contacts_read_reason",
      "value": "需要读取联系人信息"
    },
    {
      "name": "contacts_write_reason",
      "value": "需要写入联系人信息"
    }
  ]
}

3. API 使用示例

3.1 引入包

import 'package:flutter_contacts/flutter_contacts.dart';

3.2 请求权限

bool permissionGranted = await FlutterContacts.requestPermission();
if (!permissionGranted) {
  // 权限未授予，处理权限请求失败逻辑
  return;
}

3.3 获取所有联系人

// 获取所有联系人，仅包含ID和显示名称
List<Contact> contacts = await FlutterContacts.getContacts();

// 获取所有联系人，包含属性信息
List<Contact> contactsWithProperties = await FlutterContacts.getContacts(
  withProperties: true,
  withThumbnail: true,
);

// 遍历联系人
for (var contact in contactsWithProperties) {
  print('联系人: ${contact.displayName}');
  for (var phone in contact.phones) {
    print('电话: ${phone.number} (${phone.label})');
  }
  for (var email in contact.emails) {
    print('邮箱: ${email.address} (${email.label})');
  }
}

3.4 根据ID获取单个联系人

String contactId = 'your_contact_id';
Contact? contact = await FlutterContacts.getContact(contactId, withProperties: true);
if (contact != null) {
  print('联系人详情: ${contact.displayName}');
  // 处理联系人信息
}

3.5 创建新联系人

// 创建联系人对象
final newContact = Contact(
  name: Name(first: '张', last: '三'),
  phones: [Phone(number: '13800138000', label: PhoneLabel.mobile)],
  emails: [Email(address: 'zhangsan@example.com', label: EmailLabel.home)],
  addresses: [
    Address(
      street: '中关村大街1号',
      city: '北京',
      state: '北京市',
      postalCode: '100080',
      country: '中国',
      label: AddressLabel.home,
    ),
  ],
  organizations: [
    Organization(
      company: '鸿蒙科技',
      title: '工程师',
    ),
  ],
);

// 插入联系人
final insertedContact = await FlutterContacts.insertContact(newContact);
print('创建的联系人ID: ${insertedContact.id}');

3.6 更新联系人

// 先获取要更新的联系人
Contact? contact = await FlutterContacts.getContact('contact_id', withProperties: true);
if (contact != null) {
  // 更新联系人信息
  contact.name = Name(first: '李', last: '四');
  contact.phones = [
    Phone(number: '13900139000', label: PhoneLabel.mobile),
  ];

  // 保存更新
  final updatedContact = await FlutterContacts.updateContact(contact);
  print('更新后的联系人: ${updatedContact.displayName}');
}

3.7 删除联系人

// 先获取要删除的联系人
Contact? contact = await FlutterContacts.getContact('contact_id');
if (contact != null) {
  // 删除联系人
  await FlutterContacts.deleteContact(contact);
  print('联系人已删除');
}

3.8 获取联系人组

// 获取所有联系人组
List<Group> groups = await FlutterContacts.getGroups();
for (var group in groups) {
  print('组名: ${group.name}, ID: ${group.id}');
}

4. 功能特点与限制

4.1 支持的功能

• ✅ 联系人基本信息管理（姓名、电话、邮箱）
• ✅ 地址信息管理
• ✅ 组织与工作信息管理
• ✅ 网站链接管理
• ✅ 社交媒体信息管理
• ✅ 事件与生日管理
• ✅ 联系人备注管理
• ✅ 联系人组查询
• ✅ 联系人缩略图获取

4.2 限制

• ❌ 不支持联系人组的创建、更新和删除
• ❌ 不支持获取联系人高清照片
• ❌ 部分属性的自定义标签可能存在兼容性问题

5. 兼容性说明

项目	版本
Flutter	3.7.12-ohos-1.0.6
鸿蒙 SDK	5.0.0(12)
DevEco Studio	5.0.13.200
鸿蒙 ROM	5.1.0.120 SP3

6. 总结

flutter_contacts 插件为鸿蒙平台提供了完整的联系人管理功能，支持联系人的增删改查操作以及各种联系人属性的管理。通过简单的 API 调用，开发者可以轻松地在鸿蒙应用中实现联系人管理功能。

使用该插件时需要注意：

1. 正确配置联系人读写权限
2. 将应用权限级别调整为 system_basic
3. 注意鸿蒙平台的功能限制，特别是联系人组管理和高清照片获取方面

通过本文的指南，开发者可以快速上手 flutter_contacts 插件在鸿蒙平台的使用，为应用添加强大的联系人管理功能。