flutter_native_contacts 是一个用于在 Flutter 应用中访问和管理设备原生联系人的插件。它允许你读取、添加、更新和删除设备上的联系人信息。以下是如何使用 flutter_native_contacts 插件的基本步骤。

1. 添加依赖

首先，你需要在 pubspec.yaml 文件中添加 flutter_native_contacts 插件的依赖。

dependencies:
  flutter:
    sdk: flutter
  flutter_native_contacts: ^1.0.0  # 请使用最新版本

然后运行 flutter pub get 来获取依赖。

2. 请求权限

在访问设备联系人之前，你需要请求相应的权限。在 Android 上，你需要 READ_CONTACTS 和 WRITE_CONTACTS 权限；在 iOS 上，你需要 NSContactsUsageDescription 权限。

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

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

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

<key>NSContactsUsageDescription</key>
<string>We need access to your contacts to manage them.</string>

3. 使用插件

以下是一些常见的使用场景和代码示例。

3.1 获取联系人列表

你可以使用 getContacts 方法来获取设备上的联系人列表。

import 'package:flutter_native_contacts/flutter_native_contacts.dart';

Future<void> fetchContacts() async {
  try {
    List<Contact> contacts = await FlutterNativeContacts.getContacts();
    for (var contact in contacts) {
      print('Name: ${contact.displayName}');
      print('Phone: ${contact.phones}');
      print('Email: ${contact.emails}');
    }
  } catch (e) {
    print('Error fetching contacts: $e');
  }
}

3.2 添加联系人

你可以使用 addContact 方法来添加一个新的联系人。

import 'package:flutter_native_contacts/flutter_native_contacts.dart';

Future<void> addNewContact() async {
  Contact newContact = Contact(
    displayName: 'John Doe',
    phones: [PhoneNumber(label: 'Mobile', number: '1234567890')],
    emails: [Email(label: 'Work', address: 'john.doe@example.com')],
  );

  try {
    await FlutterNativeContacts.addContact(newContact);
    print('Contact added successfully');
  } catch (e) {
    print('Error adding contact: $e');
  }
}

3.3 更新联系人

你可以使用 updateContact 方法来更新现有的联系人。

import 'package:flutter_native_contacts/flutter_native_contacts.dart';

Future<void> updateExistingContact(Contact contact) async {
  contact.displayName = 'Jane Doe';
  contact.phones[0].number = '0987654321';

  try {
    await FlutterNativeContacts.updateContact(contact);
    print('Contact updated successfully');
  } catch (e) {
    print('Error updating contact: $e');
  }
}

3.4 删除联系人

你可以使用 deleteContact 方法来删除一个联系人。

import 'package:flutter_native_contacts/flutter_native_contacts.dart';

Future<void> deleteExistingContact(Contact contact) async {
  try {
    await FlutterNativeContacts.deleteContact(contact);
    print('Contact deleted successfully');
  } catch (e) {
    print('Error deleting contact: $e');
  }
}

4. 处理权限

在访问联系人之前，你需要确保应用已经获得了必要的权限。你可以使用 permission_handler 插件来请求权限。

import 'package:permission_handler/permission_handler.dart';

Future<void> requestContactsPermission() async {
  var status = await Permission.contacts.status;
  if (!status.isGranted) {
    status = await Permission.contacts.request();
    if (status.isGranted) {
      print('Contacts permission granted');
    } else {
      print('Contacts permission denied');
    }
  }
}

5. 完整示例

以下是一个完整的示例，展示了如何获取联系人列表并显示在 ListView 中。

import 'package:flutter/material.dart';
import 'package:flutter_native_contacts/flutter_native_contacts.dart';
import 'package:permission_handler/permission_handler.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: ContactsScreen(),
    );
  }
}

class ContactsScreen extends StatefulWidget {
  [@override](/user/override)
  _ContactsScreenState createState() => _ContactsScreenState();
}

class _ContactsScreenState extends State<ContactsScreen> {
  List<Contact> contacts = [];

  [@override](/user/override)
  void initState() {
    super.initState();
    requestContactsPermission().then((_) {
      fetchContacts();
    });
  }

  Future<void> requestContactsPermission() async {
    var status = await Permission.contacts.status;
    if (!status.isGranted) {
      status = await Permission.contacts.request();
      if (status.isGranted) {
        print('Contacts permission granted');
      } else {
        print('Contacts permission denied');
      }
    }
  }

  Future<void> fetchContacts() async {
    try {
      List<Contact> fetchedContacts = await FlutterNativeContacts.getContacts();
      setState(() {
        contacts = fetchedContacts;
      });
    } catch (e) {
      print('Error fetching contacts: $e');
    }
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Contacts'),
      ),
      body: ListView.builder(
        itemCount: contacts.length,
        itemBuilder: (context, index) {
          var contact = contacts[index];
          return ListTile(
            title: Text(contact.displayName ?? 'No Name'),
            subtitle: Text(contact.phones.isNotEmpty ? contact.phones[0].number : 'No Phone'),
          );
        },
      ),
    );
  }
}