This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo 联系人
一个可访问手机系统联系人的库。
expo-contacts 提供对设备系统联系人的访问，允许你获取联系人信息，以及添加、编辑或移除联系人。
在 iOS 上，联系人具有一个多层级的分组系统，你也可以通过此 API 访问它。
安装
If you are installing this in an existing React Native app, make sure to install expo in your project.
在 app 配置中进行配置
如果你的项目中使用了配置插件（Continuous Native Generation (CNG)），你可以使用 expo-contacts 内置的 config plugin 来进行配置。该插件允许你配置各种无法在运行时设置、且需要重新构建新的应用二进制文件后才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。
Example app.json with config plugin
Configurable properties
Are you using this library in an existing React Native app?
如果你没有使用 Continuous Native Generation（CNG）（也就是你在手动使用原生 android 和 ios 项目），那么你需要在原生项目中配置以下权限：
-
对于 Android，将
android.permission.READ_CONTACTS和android.permission.WRITE_CONTACTS权限添加到项目的 android/app/src/main/AndroidManifest.xml 中：<uses-permission android:name="android.permission.READ_CONTACTS" /> <uses-permission android:name="android.permission.WRITE_CONTACTS" /> -
对于 iOS，将
NSContactsUsageDescription键添加到项目的 ios/[app]/Info.plist 中：<key>NSContactsUsageDescription</key> <string>允许 $(PRODUCT_NAME) 访问你的联系人</string>
用法
API
import * as Contacts from 'expo-contacts';
Component
Type: React.PureComponent<ContactAccessButtonProps>
Creates a contact access button to quickly add contacts under limited-access authorization.
For more details, you can read the Apple docs about the underlying ContactAccessButton SwiftUI view.
ColorValueA color of the button's background. Provided color should not be transparent, otherwise it may not satisfy platform requirements for button legibility.
stringWhen the query produces a single result, the contact access button shows the caption under the matching contact name. It can be nothing (default), email address or phone number.
Acceptable values are: 'default' | 'email' | 'phone'
string[]An array of email addresses. The search omits contacts matching query that also match any email address in this array.
string[]An array of phone numbers. The search omits contacts matching query that also match any phone number in this set.
stringA string to match against contacts not yet exposed to the app. You typically get this value from a search UI that your app presents, like a text field.
ColorValueA color of the button's title. Slightly dimmed version of this color is used for the caption text. Make sure there is a good contrast between the text and the background, otherwise platform requirements for button legibility may not be satisfied.
ColorValueA tint color of the button and the modal that is presented when there is more than one match.
Static methods
Returns a boolean whether the ContactAccessButton is available on the platform.
This is true only on iOS 18.0 and newer.
booleanMethods
Creates a new contact and adds it to the system.
Note: For Android users, the Expo Go app does not have the required
WRITE_CONTACTSpermission to write to Contacts. You will need to create a development build and add permission in there manually to use this method.
Promise<string>A promise that fulfills with ID of the new system contact.
Example
const contact = { [Contacts.Fields.FirstName]: 'Bird', [Contacts.Fields.LastName]: 'Man', [Contacts.Fields.Company]: 'Young Money', }; const contactId = await Contacts.addContactAsync(contact);
Add a contact as a member to a group. A contact can be a member of multiple groups.
Promise<any>Example
await Contacts.addExistingContactToGroupAsync( '665FDBCFAE55-D614-4A15-8DC6-161A368D', '161A368D-D614-4A15-8DC6-665FDBCFAE55' );
Add a group to a container.
Promise<any>Example
await Contacts.addExistingGroupToContainerAsync( '161A368D-D614-4A15-8DC6-665FDBCFAE55', '665FDBCFAE55-D614-4A15-8DC6-161A368D' );
Create a group with a name, and add it to a container. If the container is undefined, the default container will be targeted.
Promise<string>A promise that fulfills with ID of the new group.
Example
const groupId = await Contacts.createGroupAsync('Sailor Moon');
Used for gathering precise data about a contact. Returns a contact matching the given id.
A promise that fulfills with Contact object with ID matching the input ID, or undefined if there is no match.
Example
const contact = await Contacts.getContactByIdAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55'); if (contact) { console.log(contact); }
Return a list of contacts that fit a given criteria. You can get all of the contacts by passing no criteria.
Promise<ContactResponse>A promise that fulfills with ContactResponse object returned from the query.
Example
const { data } = await Contacts.getContactsAsync({ fields: [Contacts.Fields.Emails], }); if (data.length > 0) { const contact = data[0]; console.log(contact); }
Query a list of system containers.
Promise<Container[]>A promise that fulfills with array of containers that fit the query.
Example
const allContainers = await Contacts.getContainersAsync({ contactId: '665FDBCFAE55-D614-4A15-8DC6-161A368D', });
Get the default container's ID.
Promise<string>A promise that fulfills with default container ID.
Example
const containerId = await Contacts.getDefaultContainerIdAsync();
Checks user's permissions for accessing contacts data.
Promise<ContactsPermissionResponse>A promise that resolves to a ContactsPermissionResponse object.
Returns whether the Contacts API is enabled on the current device. This method does not check the app permissions.
Promise<boolean>A promise that fulfills with a boolean, indicating whether the Contacts API is available on the current device. It always resolves to false on web.
Presents a modal which allows the user to select which contacts the app has access to. Using this function is reasonable only when the app has "limited" permissions.
Promise<string[]>A promise that resolves with an array of contact identifiers that were newly granted to the app. Contacts which the app lost access to are not listed. On platforms other than iOS and below 18.0, the promise rejects immediately.
Presents a native contact picker to select a single contact from the system. On Android, the READ_CONTACTS permission is required. You can
obtain this permission by calling the Contacts.requestPermissionsAsync() method. On iOS, no permissions are
required to use this method.
A promise that fulfills with a single Contact object if a contact is selected or null if no contact is selected (when selection is canceled).
Present a native form for manipulating contacts.
Promise<any>Example
await Contacts.presentFormAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Delete a contact from the system.
Promise<any>Example
await Contacts.removeContactAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Remove a contact's membership from a given group. This will not delete the contact.
Promise<any>Example
await Contacts.removeContactFromGroupAsync( '665FDBCFAE55-D614-4A15-8DC6-161A368D', '161A368D-D614-4A15-8DC6-665FDBCFAE55' );
Delete a group from the device.
Promise<any>Example
await Contacts.removeGroupAsync('161A368D-D614-4A15-8DC6-665FDBCFAE55');
Asks the user to grant permissions for accessing contacts data.
Promise<ContactsPermissionResponse>A promise that resolves to a ContactsPermissionResponse object.
Mutate the information of an existing contact. Due to an iOS bug, nonGregorianBirthday field cannot be modified.
Promise<string>A promise that fulfills with ID of the updated system contact if mutation was successful.
Example
const contact = { id: '161A368D-D614-4A15-8DC6-665FDBCFAE55', [Contacts.Fields.FirstName]: 'Drake', [Contacts.Fields.Company]: 'Young Money', }; await Contacts.updateContactAsync(contact);
Change the name of an existing group.
Promise<any>Example
await Contacts.updateGroupName('Expo Friends', '161A368D-D614-4A15-8DC6-665FDBCFAE55');
Query a set of contacts and write them to a local URI that can be used for sharing.
Promise<string | undefined>A promise that fulfills with shareable local URI, or undefined if there was no match.
Example
const localUri = await Contacts.writeContactToFileAsync({ id: '161A368D-D614-4A15-8DC6-665FDBCFAE55', }); Share.share({ url: localUri, message: 'Call me!' });
Types
Literal type: union
Acceptable values are: CalendarFormats | {CalendarFormats}
String union of SortTypes values.
A parent to contacts. A contact can belong to multiple groups. Here are some query operations you can perform:
- Child Contacts:
getContactsAsync({ groupId }) - Groups From Container:
getGroupsAsync({ containerId }) - Groups Named:
getContainersAsync({ groupName })
Information regarding thumbnail images.
On Android you can get dimensions using
Image.getSizemethod.
Literal type: union
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never' | number
Enums
This format denotes the common calendar format used to specify how a date is calculated in nonGregorianBirthday fields.
Possible fields to retrieve for a contact.
权限
Android
该库会自动向你的应用添加 READ_CONTACTS 和 WRITE_CONTACTS 权限：
iOS
此库使用以下用途说明键：