Flutter联系人管理插件flutter_contacts的使用

简介

flutter_contacts 是一个用于读取、创建、更新、删除和观察 Android 和 iOS 本地联系人的 Flutter 插件。它支持分组、vCard 导入导出以及权限处理。

官方示例代码可以在 example/ 查看，完整的联系人应用示例可以在 example_full/ 查看。

快速开始

安装

iOS

在 Info.plist 文件中添加以下键值对：

<plist version="1.0">
<dict>
    ...
    <key>NSContactsUsageDescription</key>
    <string>Reason we need access to the contact list</string>
</dict>
</plist>

Android

在 AndroidManifest.xml 文件中添加以下权限：

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
    <uses-permission android:name="android.permission.READ_CONTACTS"/>
    <uses-permission android:name="android.permission.WRITE_CONTACTS"/>
    <application ...>
    ...
</manifest>

使用示例

以下是使用 flutter_contacts 插件的基本示例代码：

import 'package:flutter/material.dart';
import 'package:flutter_contacts/flutter_contacts.dart';

void main() => runApp(FlutterContactsExample());

class FlutterContactsExample extends StatefulWidget {
  @override
  _FlutterContactsExampleState createState() => _FlutterContactsExampleState();
}

class _FlutterContactsExampleState extends State<FlutterContactsExample> {
  List<Contact>? _contacts;
  bool _permissionDenied = false;

  @override
  void initState() {
    super.initState();
    _fetchContacts();
  }

  Future _fetchContacts() async {
    if (!await FlutterContacts.requestPermission(readonly: true)) {
      setState(() => _permissionDenied = true);
    } else {
      final contacts = await FlutterContacts.getContacts(withProperties: true, withPhoto: true);
      setState(() => _contacts = contacts);
    }
  }

  @override
  Widget build(BuildContext context) => MaterialApp(
      home: Scaffold(
          appBar: AppBar(title: Text('flutter_contacts_example')),
          body: _body()));

  Widget _body() {
    if (_permissionDenied) return Center(child: Text('Permission denied'));
    if (_contacts == null) return Center(child: CircularProgressIndicator());
    return ListView.builder(
        itemCount: _contacts!.length,
        itemBuilder: (context, i) => ListTile(
            title: Text(_contacts![i].displayName),
            onTap: () async {
              final fullContact = await FlutterContacts.getContact(_contacts![i].id);
              await Navigator.of(context).push(
                  MaterialPageRoute(builder: (_) => ContactPage(fullContact!)));
            }));
  }
}

class ContactPage extends StatelessWidget {
  final Contact contact;
  ContactPage(this.contact);

  @override
  Widget build(BuildContext context) => Scaffold(
      appBar: AppBar(title: Text(contact.displayName)),
      body: Column(children: [
        Text('First name: ${contact.name.first}'),
        Text('Last name: ${contact.name.last}'),
        Text('Phone number: ${contact.phones.isNotEmpty ? contact.phones.first.number : '(none)'}'),
        Text('Email address: ${contact.emails.isNotEmpty ? contact.emails.first.address : '(none)'}'),
      ]));
}

联系人模型简化

联系人模型包含以下属性：

class Contact {
    String id;
    String displayName;
    Uint8List? photo;
    Uint8List? thumbnail;
    Name name;
    List<Phone> phones;
    List<Email> emails;
    List<Address> addresses;
    List<Organization> organizations;
    List<Website> websites;
    List<SocialMedia> socialMedias;
    List<Event> events;
    List<Note> notes;
    List<Group> groups;
}
class Name { String first; String last; }
class Phone { String number; PhoneLabel label; }
class Email { String address; EmailLabel label; }
class Address { String address; AddressLabel label; }
class Organization { String company; String title; }
class Website { String url; WebsiteLabel label; }
class SocialMedia { String userName; SocialMediaLabel label; }
class Event { int? year; int month; int day; EventLabel label; }
class Note { String note; }
class Group { String id; String name; }

注意事项

1. iOS 13+ 的笔记访问：默认情况下禁用笔记访问。如果需要访问，请确保您的应用程序已获得 Apple 的授权，并启用该功能：

   FlutterContacts.config.includeNotesOnIos13AndAbove = true;
   

2. 原始联系人与统一联系人：插件默认返回统一联系人（即将多个来源的联系人合并为一个）。如果您需要原始联系人，请设置：

   FlutterContacts.config.returnUnifiedContacts = false;
   

   但请注意，目前不支持插入、更新或删除原始联系人。

功能请求

以下是一些未来可能实现的功能：

• 读写自定义铃声
• 屏蔽联系人
• 支持 SIM 卡中的联系人
• 更多的 Android 原始账户信息

通过以上内容，您可以快速上手并使用 flutter_contacts 插件来管理和操作设备上的联系人数据。