Expo 联系人（旧版）

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

Android

iOS

Included in Expo Go

GitHub

npm

更新日志

Recommended version:

~57.0.5

重要 expo-contacts 库中包含 Contacts API 的 legacy 版本。它可以与从根目录导出的基于类的 expo-contacts API 一起使用。要使用旧版 API，请从 expo-contacts/legacy 导入。

expo-contacts 提供对设备系统联系人的访问，允许你获取联系人信息，以及添加、编辑或删除联系人。

在 iOS 上，联系人具有多层级分组系统，你也可以通过此 API 访问。

安装

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.

应用配置中的配置

如果你在项目中使用配置插件（持续原生生成（CNG）），可以使用 expo-contacts 内置的配置插件来进行配置。该插件允许你配置一些无法在运行时设置的属性，这些属性需要重新构建新的应用二进制文件后才会生效。如果你的应用不使用 CNG，那么你需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-contacts",
        {
          "contactsPermission": "允许 $(PRODUCT_NAME) 访问你的联系人。"
        }
      ]
    ]
  }
}

Configurable properties

Name	Default	Description
`contactsPermission`	`"允许 $(PRODUCT_NAME) 访问你的联系人"`	Only for: iOS 设置 `NSContactsUsageDescription` 权限消息的字符串。

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

如果你没有使用持续原生生成（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>

用法

基本联系人用法

import { useEffect } from 'react';
import { StyleSheet, View, Text } from 'react-native';
import * as Contacts from 'expo-contacts/legacy';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await Contacts.requestPermissionsAsync();
      if (status === 'granted') {
        const { data } = await Contacts.getContactsAsync({
          fields: [Contacts.Fields.Emails],
        });

        if (data.length > 0) {
          const contact = data[0];
          console.log(contact);
        }
      }
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>联系人模块示例</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'center',
  },
});

API

import * as Contacts from 'expo-contacts/legacy';

Component

`ContactAccessButton`

iOS 18.0+

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.

ContactAccessButtonProps

`backgroundColor`

iOS 18.0+

Optional • Type: ColorValue

A color of the button's background. Provided color should not be transparent, otherwise it may not satisfy platform requirements for button legibility.

`caption`

iOS 18.0+

Optional • Literal type: string

When 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'

`ignoredEmails`

iOS 18.0+

Optional • Type: string[]

An array of email addresses. The search omits contacts matching query that also match any email address in this array.

`ignoredPhoneNumbers`

iOS 18.0+

Optional • Type: string[]

An array of phone numbers. The search omits contacts matching query that also match any phone number in this set.

`query`

iOS 18.0+

Optional • Type: string

A 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.

`textColor`

iOS 18.0+

Optional • Type: ColorValue

A 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.

`tintColor`

iOS 18.0+

Optional • Type: ColorValue

A tint color of the button and the modal that is presented when there is more than one match.

Inherited props

ViewProps

Static methods

`isAvailable()`

Android

iOS

Returns a boolean whether the ContactAccessButton is available on the platform. This is true only on iOS 18.0 and newer.

Returns:

boolean

Constants

`Contacts（旧版）.onContactsChangeEventName`

Android

iOS

Type: 'onContactsChange'

Methods

`Contacts（旧版）.addContactAsync(contact, containerId)`

Android

iOS

Parameter	Type
contact	`Contact`
containerId(optional)	`string`

Returns:

Promise<string>

`Contacts（旧版）.addExistingContactToGroupAsync(contactId, groupId)`

Android

iOS

Parameter	Type
contactId	`string`
groupId	`string`

Returns:

Promise<any>

`Contacts（旧版）.addExistingGroupToContainerAsync(groupId, containerId)`

Android

iOS

Parameter	Type
groupId	`string`
containerId	`string`

Returns:

Promise<any>

`Contacts（旧版）.createGroupAsync(name, containerId)`

Android

iOS

Parameter	Type
name(optional)	`string`
containerId(optional)	`string`

Returns:

Promise<string>

`Contacts（旧版）.getContactByIdAsync(id, fields)`

Android

iOS

Parameter	Type
id	`string`
fields(optional)	`FieldType[]`

Returns:

Promise<ExistingContact | undefined>

`Contacts（旧版）.getContactsAsync(contactQuery)`

Android

iOS

Parameter	Type
contactQuery(optional)	`ContactQuery`

Returns:

Promise<ContactResponse>

`Contacts（旧版）.getContainersAsync(containerQuery)`

Android

iOS

Parameter	Type
containerQuery	`ContainerQuery`

Returns:

Promise<Container[]>

`Contacts（旧版）.getDefaultContainerIdAsync()`

Android

iOS

Returns:

Promise<string>

`Contacts（旧版）.getGroupsAsync(groupQuery)`

Android

iOS

Parameter	Type
groupQuery	`GroupQuery`

Returns:

Promise<Group[]>

`Contacts（旧版）.getPagedContactsAsync(contactQuery)`

Android

iOS

Parameter	Type
contactQuery(optional)	`ContactQuery`

Returns:

Promise<ContactResponse>

`Contacts（旧版）.getPermissionsAsync()`

Android

iOS

Returns:

Promise<ContactsPermissionResponse>

`Contacts（旧版）.hasContactsAsync()`

Android

iOS

Returns:

Promise<boolean>

`Contacts（旧版）.isAvailableAsync()`

Android

iOS

Returns:

Promise<boolean>

`Contacts（旧版）.presentAccessPickerAsync()`

Android

iOS

Returns:

Promise<string[]>

`Contacts（旧版）.presentContactPickerAsync()`

Android

iOS

Returns:

Promise<ExistingContact | null>

`Contacts（旧版）.presentFormAsync(contactId, contact, formOptions)`

Android

iOS

Parameter	Type
contactId(optional)	`string \| null`
contact(optional)	`Contact \| null`
formOptions(optional)	`FormOptions`

Returns:

Promise<any>

`Contacts（旧版）.removeContactAsync(contactId)`

Android

iOS

Parameter	Type
contactId	`string`

Returns:

Promise<any>

`Contacts（旧版）.removeContactFromGroupAsync(contactId, groupId)`

Android

iOS

Parameter	Type
contactId	`string`
groupId	`string`

Returns:

Promise<any>

`Contacts（旧版）.removeGroupAsync(groupId)`

Android

iOS

Parameter	Type
groupId	`string`

Returns:

Promise<any>

`Contacts（旧版）.requestPermissionsAsync()`

Android

iOS

Returns:

Promise<ContactsPermissionResponse>

`Contacts（旧版）.shareContactAsync(contactId, message, shareOptions)`

Android

iOS

Parameter	Type
contactId	`string`
message	`string`
shareOptions(optional)	`ShareOptions`

Returns:

Promise<any>

`Contacts（旧版）.updateContactAsync(contact)`

Android

iOS

Parameter	Type
contact	`{ id: string } & Partial<ExistingContact>`

Returns:

Promise<string>

`Contacts（旧版）.updateGroupNameAsync(groupName, groupId)`

Android

iOS

Parameter	Type
groupName	`string`
groupId	`string`

Returns:

Promise<any>

`Contacts（旧版）.writeContactToFileAsync(contactQuery)`

Android

iOS

Parameter	Type
contactQuery(optional)	`ContactQuery`

Returns:

Promise<string | undefined>

Event subscriptions

`Contacts（旧版）.addContactsChangeListener(listener)`

Android

iOS

Parameter	Type
listener	`() => void`

Returns:

EventSubscription

Types

`Address`

Android

iOS

Property	Type	Description
city(optional)	`string`	City name.
country(optional)	`string`	Country name
id(optional)	`string`	Unique ID. This value will be generated by the OS.
isoCountryCode(optional)	`string`	Standard country code.
label	`string`	Localized display name.
neighborhood(optional)	`string`	Neighborhood name.
poBox(optional)	`string`	P.O. Box.
postalCode(optional)	`string`	Local post code.
region(optional)	`string`	Region or state name.
street(optional)	`string`	Street name.

`CalendarFormatType`

Android

iOS

Literal type: union

Acceptable values are: CalendarFormats | {CalendarFormats}

`Contact`

Android

iOS

Property	Type	Description
addresses(optional)	`Address[]`	Locations.
birthday(optional)	`Date`	Birthday information in Gregorian format.
company(optional)	`string`	Organization the entity belongs to.
contactType	`ContactType`	Denoting a person or company.
dates(optional)	`Date[]`	A labeled list of other relevant user dates in Gregorian format.
department(optional)	`string`	Job department.
emails(optional)	`Email[]`	Email addresses.
firstName(optional)	`string`	Given name.
image(optional)	`Image`	Thumbnail image. On iOS it size is set to 320×320px, on Android it may vary.
imageAvailable(optional)	`boolean`	Used for efficient retrieval of images.
instantMessageAddresses(optional)	`InstantMessageAddress[]`	Instant messaging connections.
isFavorite(optional)	`boolean`	Only for: Android Whether the contact is starred.
jobTitle(optional)	`string`	Job description.
lastName(optional)	`string`	Last name.
maidenName(optional)	`string`	Maiden name.
middleName(optional)	`string`	Middle name
name	`string`	Full name with proper format.
namePrefix(optional)	`string`	Dr., Mr., Mrs., and so on.
nameSuffix(optional)	`string`	Jr., Sr., and so on.
nickname(optional)	`string`	An alias to the proper name.
nonGregorianBirthday(optional)	`Date`	Only for: iOS Birthday that doesn't conform to the Gregorian calendar format, interpreted based on the calendar `format` setting.
note(optional)	`string`	Additional information. The `note` field requires your app to request additional entitlements. The Expo Go app does not contain those entitlements, so in order to test this feature you will need to request the entitlement from Apple, set the `ios.accessesContactNotes` field in app config to `true`, and create your development build.
phoneNumbers(optional)	`PhoneNumber[]`	Phone numbers.
phoneticFirstName(optional)	`string`	Pronunciation of the first name.
phoneticLastName(optional)	`string`	Pronunciation of the last name.
phoneticMiddleName(optional)	`string`	Pronunciation of the middle name.
rawImage(optional)	`Image`	Raw image without cropping, usually large.
relationships(optional)	`Relationship[]`	Names of other relevant user connections.
socialProfiles(optional)	`SocialProfile[]`	Only for: iOS Social networks.
urlAddresses(optional)	`UrlAddress[]`	Associated web URLs.

`ContactQuery`

Android

iOS

Property	Type	Description
containerId(optional)	`string`	Only for: iOS Get all contacts that belong to the container matching this ID.
fields(optional)	`FieldType[]`	If specified, the defined fields will be returned. If skipped, all fields will be returned.
groupId(optional)	`string`	Only for: iOS Get all contacts that belong to the group matching this ID.
id(optional)	`string \| string[]`	Get contacts with a matching ID or array of IDs.
name(optional)	`string`	Get all contacts whose name contains the provided string (not case-sensitive).
pageOffset(optional)	`number`	The number of contacts to skip before gathering contacts.
pageSize(optional)	`number`	The max number of contacts to return. If skipped or set to `0` all contacts will be returned.
rawContacts(optional)	`boolean`	Only for: iOS Prevent unification of contacts when gathering. Default:`false`
sort(optional)	`ContactSort`	Sort method used when gathering contacts.

`ContactResponse`

Android

iOS

Property	Type	Description
data	`ExistingContact[]`	An array of contacts that match a particular query.
hasNextPage	`boolean`	This will be `true` if there are more contacts to retrieve beyond what is returned.
hasPreviousPage	`boolean`	This will be `true` if there are previous contacts that weren't retrieved due to `pageOffset` limit.

`ContactSort`

Android

iOS

String union of SortTypes values.

`ContactsPermissionResponse`

Android

iOS

Type: PermissionResponse extended by:

Property	Type	Description
accessPrivileges(optional)	`'all' \| 'limited' \| 'none'`	Indicates if your app has access to the whole or only part of the contact library. Possible values are: `'all'` if the user granted your app access to the whole contact library `'limited'` if the user granted your app access only to selected contacts (only available on iOS 18+) `'none'`

`ContactType`

Android

iOS

Literal type: union

Acceptable values are: ContactTypes | {ContactTypes}

`Container`

Android

iOS

Property	Type	Description
id	`string`	-
name	`string`	-
type	`ContainerType`	-

`ContainerQuery`

Android

iOS

Property	Type	Description
contactId(optional)	`string`	Query all the containers that parent a contact.
containerId(optional)	`string \| string[]`	Query all the containers that matches ID or an array od IDs.
groupId(optional)	`string`	Query all the containers that parent a group.

`ContainerType`

Android

iOS

Literal type: union

Acceptable values are: ContainerTypes | {ContainerTypes}

`Date`

Android

iOS

Property	Type	Description
day	`number`	Day.
format(optional)	`CalendarFormatType`	Format for the date. This is provided by the OS, do not set this manually.
id(optional)	`string`	Unique ID. This value will be generated by the OS.
label(optional)	`string`	Localized display name.
month	`number`	Month - adjusted for JavaScript `Date` which starts at `0`.
year(optional)	`number`	Year.

`Email`

Android

iOS

Property	Type	Description
email(optional)	`string`	Email address.
id(optional)	`string`	Unique ID. This value will be generated by the OS.
isPrimary(optional)	`boolean`	Flag signifying if it is a primary email address.
label	`string`	Localized display name.

`ExistingContact`

Android

iOS

Type: Contact extended by:

Property	Type	Description
id	`string`	Immutable identifier used for querying and indexing. This value will be generated by the OS when the contact is created.

`FieldType`

Android

iOS

Literal type: union

Acceptable values are: Fields | {Fields}

`FormOptions`

Android

iOS

Property	Type	Description
allowsActions(optional)	`boolean`	Actions like share, add, create.
allowsEditing(optional)	`boolean`	Allows for contact mutation.
alternateName(optional)	`string`	Used if contact doesn't have a name defined.
cancelButtonTitle(optional)	`string`	The name of the left bar button. Only applies when editing an existing contact.
displayedPropertyKeys(optional)	`FieldType[]`	The properties that will be displayed when viewing a contact.
groupId(optional)	`string`	The parent group for a new contact.
isNew(optional)	`boolean`	Present the new contact controller. If set to `false` the unknown controller will be shown.
message(optional)	`string`	The message displayed under the name of the contact. Only applies when editing an existing contact.
preventAnimation(optional)	`boolean`	Prevents the controller from animating in.
shouldShowLinkedContacts(optional)	`boolean`	Show or hide the similar contacts.

`Group`

Android

iOS

Property	Type	Description
id(optional)	`string`	The editable name of a group.
name(optional)	`string`	Immutable id representing the group.

`GroupQuery`

Android

iOS

Property	Type	Description
containerId(optional)	`string`	Query all groups that belong to a certain container.
groupId(optional)	`string`	Query the group with a matching ID.
groupName(optional)	`string`	Query all groups matching a name.

`Image`

Android

iOS

Property	Type	Description
base64(optional)	`string`	Image as Base64 string.
height(optional)	`number`	Only for: iOS Image height
uri(optional)	`string`	A local image URI. Note: If you have a remote URI, download it first using `FileSystem.downloadAsync`.
width(optional)	`number`	Only for: iOS Image width.

`InstantMessageAddress`

Android

iOS

Property	Type	Description
id(optional)	`string`	Unique ID. This value will be generated by the OS.
label	`string`	Localized display name.
localizedService(optional)	`string`	Localized name of app.
service(optional)	`string`	Name of instant messaging app.
username(optional)	`string`	Username in IM app.

`PermissionExpiration`

Android

iOS

Literal type: union

Permission expiration time. Currently, all permissions are granted permanently.

Acceptable values are: 'never' | number

`PermissionResponse`

Android

iOS

An object obtained by permissions get and request functions.

Property	Type	Description
canAskAgain	`boolean`	Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission.
expires	`PermissionExpiration`	Determines time when the permission expires.
granted	`boolean`	A convenience boolean that indicates if the permission is granted.
status	`PermissionStatus`	Determines the status of the permission.

`PhoneNumber`

Android

iOS

Property	Type	Description
countryCode(optional)	`string`	Country code. Example `us`
digits(optional)	`string`	Phone number without format. Example `8674305`
id(optional)	`string`	Unique ID. This value will be generated by the OS.
isPrimary(optional)	`boolean`	Flag signifying if it is a primary phone number.
label	`string`	Localized display name.
number(optional)	`string`	Phone number.

`Relationship`

Android

iOS

Property	Type	Description
id(optional)	`string`	Unique ID. This value will be generated by the OS.
label	`string`	Localized display name.
name(optional)	`string`	Name of related contact.

`SocialProfile`

Android

iOS

Property	Type	Description
id(optional)	`string`	Unique ID. This value will be generated by the OS.
label	`string`	Localized display name.
localizedProfile(optional)	`string`	Localized profile name.
service(optional)	`string`	Name of social app.
url(optional)	`string`	Web URL.
userId(optional)	`string`	Username ID in social app.
username(optional)	`string`	Username in social app.

`UrlAddress`

Android

iOS

Property	Type	Description
id(optional)	`string`	Unique ID. This value will be generated by the OS.
label	`string`	Localized display name.
url(optional)	`string`	Web URL.

Enums

`CalendarFormats`

Android

iOS

`Buddhist`

iOS

CalendarFormats.Buddhist ＝ "buddhist"

`Chinese`

iOS

CalendarFormats.Chinese ＝ "chinese"

`Coptic`

iOS

CalendarFormats.Coptic ＝ "coptic"

`EthiopicAmeteAlem`

iOS

CalendarFormats.EthiopicAmeteAlem ＝ "ethiopicAmeteAlem"

`EthiopicAmeteMihret`

iOS

CalendarFormats.EthiopicAmeteMihret ＝ "ethiopicAmeteMihret"

`Gregorian`

CalendarFormats.Gregorian ＝ "gregorian"

`Hebrew`

iOS

CalendarFormats.Hebrew ＝ "hebrew"

`Indian`

iOS

CalendarFormats.Indian ＝ "indian"

`Islamic`

iOS

CalendarFormats.Islamic ＝ "islamic"

`IslamicCivil`

iOS

CalendarFormats.IslamicCivil ＝ "islamicCivil"

`IslamicTabular`

iOS

CalendarFormats.IslamicTabular ＝ "islamicTabular"

`IslamicUmmAlQura`

iOS

CalendarFormats.IslamicUmmAlQura ＝ "islamicUmmAlQura"

`ISO8601`

iOS

CalendarFormats.ISO8601 ＝ "iso8601"

`Japanese`

iOS

CalendarFormats.Japanese ＝ "japanese"

`Persian`

iOS

CalendarFormats.Persian ＝ "persian"

`RepublicOfChina`

iOS

CalendarFormats.RepublicOfChina ＝ "republicOfChina"

`ContactTypes`

Android

iOS

`Company`

ContactTypes.Company ＝ "company"

Contact is group or company.

`Person`

ContactTypes.Person ＝ "person"

Contact is a human.

`ContainerTypes`

Android

iOS

`CardDAV`

ContainerTypes.CardDAV ＝ "cardDAV"

With cardDAV protocol used for sharing.

`Exchange`

ContainerTypes.Exchange ＝ "exchange"

In association with email server.

`Local`

ContainerTypes.Local ＝ "local"

A local non-iCloud container.

`Unassigned`

ContainerTypes.Unassigned ＝ "unassigned"

Unknown container.

`Fields`

Android

iOS

`Addresses`

Fields.Addresses ＝ "addresses"

`Birthday`

Fields.Birthday ＝ "birthday"

`Company`

Fields.Company ＝ "company"

`ContactType`

Fields.ContactType ＝ "contactType"

`Dates`

Fields.Dates ＝ "dates"

`Department`

Fields.Department ＝ "department"

`Emails`

Fields.Emails ＝ "emails"

`ExtraNames`

Fields.ExtraNames ＝ "extraNames"

`FirstName`

Fields.FirstName ＝ "firstName"

`ID`

Fields.ID ＝ "id"

`Image`

Fields.Image ＝ "image"

`ImageAvailable`

Fields.ImageAvailable ＝ "imageAvailable"

`InstantMessageAddresses`

Fields.InstantMessageAddresses ＝ "instantMessageAddresses"

`IsFavorite`

Android

Fields.IsFavorite ＝ "isFavorite"

`JobTitle`

Fields.JobTitle ＝ "jobTitle"

`LastName`

Fields.LastName ＝ "lastName"

`MaidenName`

Fields.MaidenName ＝ "maidenName"

`MiddleName`

Fields.MiddleName ＝ "middleName"

`Name`

Fields.Name ＝ "name"

`NamePrefix`

Fields.NamePrefix ＝ "namePrefix"

`NameSuffix`

Fields.NameSuffix ＝ "nameSuffix"

`Nickname`

Fields.Nickname ＝ "nickname"

`NonGregorianBirthday`

iOS

Fields.NonGregorianBirthday ＝ "nonGregorianBirthday"

`Note`

Fields.Note ＝ "note"

`PhoneNumbers`

Fields.PhoneNumbers ＝ "phoneNumbers"

`PhoneticFirstName`

Fields.PhoneticFirstName ＝ "phoneticFirstName"

`PhoneticLastName`

Fields.PhoneticLastName ＝ "phoneticLastName"

`PhoneticMiddleName`

Fields.PhoneticMiddleName ＝ "phoneticMiddleName"

`RawImage`

Fields.RawImage ＝ "rawImage"

`Relationships`

Fields.Relationships ＝ "relationships"

`SocialProfiles`

iOS

Fields.SocialProfiles ＝ "socialProfiles"

`UrlAddresses`

Fields.UrlAddresses ＝ "urlAddresses"

`PermissionStatus`

Android

iOS

`DENIED`

PermissionStatus.DENIED ＝ "denied"

User has denied the permission.

`GRANTED`

PermissionStatus.GRANTED ＝ "granted"

User has granted the permission.

`UNDETERMINED`

PermissionStatus.UNDETERMINED ＝ "undetermined"

User hasn't granted or denied the permission yet.

`SortTypes`

Android

iOS

`FirstName`

SortTypes.FirstName ＝ "firstName"

Sort by first name in ascending order.

`LastName`

SortTypes.LastName ＝ "lastName"

Sort by last name in ascending order.

`None`

SortTypes.None ＝ "none"

No sorting should be applied.

`UserDefault`

Android

SortTypes.UserDefault ＝ "userDefault"

The user default method of sorting.

权限

Android

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

Android permission	Description
`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

此库使用以下用途描述键：

Info.plist key	Description
`NSContactsUsageDescription`	A message that tells the user why the app is requesting access to the user’s contacts.