This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo 联系方式 iconExpo 联系方式

提供对手机系统联系人的访问的库。

Android
iOS
Included in Expo Go
Recommended version:
~58.0.6

expo-contacts 提供对设备系统联系人访问的功能,允许你获取联系人信息,以及添加、编辑或删除联系人。 在 iOS 上,联系人具有多层分组系统,你也可以通过此 API 访问这些分组。

安装

🌐 Installation

Terminal
- npx expo install expo-contacts
- yarn expo install expo-contacts
- pnpm expo install expo-contacts
- bun expo install expo-contacts

If you are installing this in an existing React Native app, make sure to install expo in your project.

应用配置中的配置

🌐 Configuration in app config

如果你在项目中使用配置插件(连续原生生成 (CNG)),可以使用其内置的 配置插件 来配置 expo-contacts。该插件允许你配置无法在运行时设置并且需要构建新的应用二进制文件才能生效的各种属性。如果你的应用不使用 CNG,则需要手动配置该库。

🌐 You can configure expo-contacts using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

app.json
{ "expo": { "plugins": [ [ "expo-contacts", { "contactsPermission": "Allow $(PRODUCT_NAME) to access your contacts." } ] ] } }

Configurable properties

NameDefaultDescription
contactsPermission"Allow $(PRODUCT_NAME) to access your contacts"
Only for: 
iOS

A string to set the NSContactsUsageDescription permission message.

Are you using this library in an existing React Native app?

如果你没有使用连续原生生成(CNG)(而是手动使用原生 Android 和 iOS 项目),那么你需要在原生项目中配置以下权限:

🌐 If you're not using Continuous Native Generation (CNG) (you're using native android and ios projects manually), then you need to configure following permissions in your native projects:

  • 对于 Android,在项目的 android/app/src/main/AndroidManifest.xml 中添加 android.permission.READ_CONTACTS 和 android.permission.WRITE_CONTACTS 权限:

    <uses-permission android:name="android.permission.READ_CONTACTS" /> <uses-permission android:name="android.permission.WRITE_CONTACTS" />
  • 对于 iOS,在你的项目 ios/[app]/Info.plist 中添加 NSContactsUsageDescription 键:

    <key>NSContactsUsageDescription</key> <string>Allow $(PRODUCT_NAME) to access your contacts</string>

用法

🌐 Usage

联系人操作
Contacts manipulations
const contact = await Contact.create({ givenName: 'John', familyName: 'Doe' }); // { givenName: "John", familyName: "Doe"} await contact.setGivenName('Andrew'); // { givenName: "Andrew", familyName: "Doe"} await contact.addPhone({ label: 'work', number: '+12345678912' }); // { givenName: "Andrew", familyName: "Doe", phones: [{label: "work", number: "+12345678912"}]} const phones = await contact.getPhones(); // Changes only the defined fields, leaves the rest unchanged await contact.patch({ phones: [...phones, { label: 'home', number: '+98765432198' }] }); /* { givenName: "Andrew", familyName: "Doe", phones: [ {label: "work", number: "+12345678912"}, {label: "home", number: "+98765432198"} ] } */ // Replaces all fields with the ones defined in the object await contact.update({ givenName: 'John', familyName: 'Doe' }); // { givenName: "John", familyName: "Doe"}
正在获取联系人
Retrieving contacts
const contactDetails = await Contact.getAllDetails([ContactField.FULL_NAME, ContactField.PHONES], { limit: 20, offset: 10, sortOrder: ContactsSortOrder.GivenName, }); // Contact instance can be created from fetched details const contacts = contactDetails.map(item => new Contact(item.id)); const contactsFromGetAll = await Contact.getAll({ limit: 20, offset: 10, sortOrder: ContactsSortOrder.GivenName, });
联系人无限滚动示例
Contacts infinite scroll example
import { Contact, ContactField, PartialContactDetails } from 'expo-contacts'; import { useEffect, useState } from 'react'; import { FlatList, Text, View } from 'react-native'; const FIELDS = [ContactField.FULL_NAME, ContactField.PHONES] as const; export default function InfiniteContacts() { const [contactDetails, setContactDetails] = useState<PartialContactDetails<typeof FIELDS>[]>([]); useEffect(() => { loadMore(); }, []); const loadMore = async () => { const newBatch = await Contact.getAllDetails(FIELDS, { limit: 20, offset: contactDetails.length, }); setContactDetails(prev => [...prev, ...newBatch]); }; return ( <View style={{ flex: 1 }}> <FlatList data={contactDetails} keyExtractor={item => item.id} onEndReached={loadMore} onEndReachedThreshold={0.5} renderItem={({ item }) => ( <View style={{ padding: 10, borderBottomWidth: 1, borderColor: '#ccc' }}> <Text>{item.fullName}</Text> <Text>{item.phones[0]?.number ?? 'No phone number'}</Text> </View> )} /> </View> ); }
编辑联系人表单示例
Edit contact form example
import { Contact, ContactField, ContactPatch } from 'expo-contacts'; import { useEffect, useState } from 'react'; import { Alert, Button, ScrollView, Text, TextInput, View } from 'react-native'; export default function ContactForm() { const [contact, setContact] = useState<Contact | null>(null); const [contactPatch, setContactPatch] = useState<ContactPatch>({}); const [newPhoneInput, setNewPhoneInput] = useState(''); useEffect(() => { Contact.getAll({ limit: 1 }).then(async ([first]) => { if (first) { setContact(first); setContactPatch(await first.getDetails([ContactField.GIVEN_NAME, ContactField.PHONES])); } }); }, []); if (!contactPatch && contact) { return <Text style={{ marginTop: 50 }}>Loading details...</Text>; } const handleChangeName = (text: string) => setContactPatch(prev => ({ ...prev, givenName: text })); const handleAddPhone = () => { if (!newPhoneInput) { return; } setContactPatch(prev => ({ ...prev, phones: [...(prev.phones || []), { label: 'mobile', number: newPhoneInput }], })); setNewPhoneInput(''); }; const handleRemovePhone = (idx: number) => setContactPatch(prev => ({ ...prev, phones: prev.phones?.filter((_, i) => i !== idx), })); const handlePatch = async () => { if (contact) { await contact.patch(contactPatch); } Alert.alert('Contact patched successfully'); }; if (!contact) { return <Text style={{ marginTop: 50 }}>Loading...</Text>; } return ( <ScrollView style={{ padding: 20, paddingTop: 60 }}> <Text style={{ fontWeight: 'bold', marginBottom: 10 }}>Edit ID: {contact.id}</Text> <Text>Name:</Text> <TextInput style={{ borderWidth: 1, padding: 5, marginBottom: 10 }} value={contactPatch.givenName || ''} onChangeText={handleChangeName} /> <Text>Phones:</Text> {contactPatch.phones?.map((phone, index) => ( <View key={index} style={{ flexDirection: 'row', alignItems: 'center', marginBottom: 5 }}> <Text style={{ flex: 1 }}>{phone.number}</Text> <Button title="删除" onPress={() => handleRemovePhone(index)} /> </View> ))} <View style={{ flexDirection: 'row', marginBottom: 20, marginTop: 10 }}> <TextInput style={{ borderWidth: 1, flex: 1, padding: 5, marginRight: 5 }} value={newPhoneInput} onChangeText={setNewPhoneInput} placeholder="New phone..." /> <Button title="添加" onPress={handleAddPhone} /> </View> <Button title="修补联系人" onPress={handlePatch} /> </ScrollView> ); }

应用接口

🌐 API

import { Contact } from 'expo-contacts';

No API data file found, sorry!

权限

🌐 Permissions

安卓

🌐 Android

此库会自动为你的应用添加 READ_CONTACTS 和 WRITE_CONTACTS 权限:

🌐 This library automatically adds READ_CONTACTS and WRITE_CONTACTS permissions to your app:

Android permissionDescription

READ_CONTACTS

Allows an application to read the user's contacts data.

WRITE_CONTACTS

Allows an application to write the user's contacts data.

iOS

该库使用以下用法描述键:

🌐 The following usage description keys are used by this library:

Info.plist keyDescription

NSContactsUsageDescription

A message that tells the user why the app is requesting access to the user’s contacts.