Contacts
The Contacts plugin provides access to read, write, or select device contacts.
#
InstallationIf you have not already setup Ionic Enterprise in your app, follow the one-time setup steps.
Next, install the plugin:
- Capacitor
- Cordova
#
UsageThe Contacts plugin ship with a native Angular & es2015+/Typescript wrappers as well as being available on window.
#
Index#
Classes- Contact
- ContactAddress
- ContactError
- ContactField
- ContactFindOptions
- ContactName
- ContactOrganization
- Contacts
#
Type aliases#
Type aliases#
ContactFieldTypeƬ ContactFieldType: "" | "addresses" | "birthday" | "categories" | "country" | "department" | "displayName" | "emails" | "name.familyName" | "name.formatted" | "name.givenName" | "name.honorificPrefix" | "name.honorificSuffix" | "id" | "ims" | "locality" | "name.middleName" | "name" | "nickname" | "note" | "organizations" | "phoneNumbers" | "photos" | "postalCode" | "region" | "streetAddress" | "title" | "urls"*
Support for searching varies between platforms. iOS only supports the following types for a text search:
- 'name'
- 'emails'
- 'phoneNumbers'
In addition, the wildcard '*' character is required to return all contacts.
Android supports all defined fields.
#
ContactContains information about a single contact.
#
Constructors#
constructor+ new Contact(id?
: undefined | string, displayName?
: undefined | string, name?
: ContactName, nickname?
: undefined | string, phoneNumbers?
: ContactField[], emails?
: ContactField[], addresses?
: ContactAddress[], ims?
: ContactField[], organizations?
: ContactOrganization[], birthday?
: Date | string | null, note?
: undefined | string, photos?
: ContactField[], categories?
: ContactField[], urls?
: ContactField[]): Contact
Parameters:
Name | Type |
---|---|
id? | undefined | string |
displayName? | undefined | string |
name? | ContactName |
nickname? | undefined | string |
phoneNumbers? | ContactField[] |
emails? | ContactField[] |
addresses? | ContactAddress[] |
ims? | ContactField[] |
organizations? | ContactOrganization[] |
birthday? | Date | string | null |
note? | undefined | string |
photos? | ContactField[] |
categories? | ContactField[] |
urls? | ContactField[] |
Returns: Contact
#
PropertiesOptional
addresses#
• addresses? : ContactAddress[] | null
An array of all the contact's addresses.
Optional
birthday#
• birthday? : Date | string | null
The birthday of the contact.
Optional
categories#
• categories? : ContactField[] | null
An array of all the user-defined categories associated with the contact.
Optional
displayName#
• displayName? : string | null
The name of this Contact, suitable for display to end users.
Optional
emails#
• emails? : ContactField[] | null
An array of all the contact's email addresses.
Optional
id#
• id? : string | null
A globally unique identifier.
Optional
ims#
• ims? : ContactField[] | null
An array of all the contact's IM addresses.
Optional
name#
• name? : ContactName | null
An object containing all components of a persons name.
Optional
nickname#
• nickname? : string | null
A casual name by which to address the contact.
Optional
note#
• note? : string | null
A note about the contact on Android.
Optional
organizations#
• organizations? : ContactOrganization[] | null
An array of all the contact's organizations.
Optional
phoneNumbers#
• phoneNumbers? : ContactField[] | null
An array of all the contact's phone numbers.
Optional
photos#
• photos? : ContactField[] | null
An array of the contact's photos.
Optional
rawId#
• rawId? : string | null
A globally unique identifier on Android.
Optional
urls#
• urls? : ContactField[] | null
An array of web pages associated with the contact.
#
Methods#
clone▸ clone(): Contact
Creates a deep copy of this Contact. With the contact ID set to null.
Returns: Contact
copy of this Contact
#
display▸ display(allowEdit?
: undefined | false | true): Promise‹any›
iOS only Display a contact in the native Contact Picker UI
Parameters:
Name | Type | Description |
---|---|---|
allowEdit? | undefined | false | true | true display the contact and allow editing it false (default) display contact without editing |
Returns: Promise‹any›
#
remove▸ remove(): Promise‹any›
Removes contact from device storage.
Returns: Promise‹any›
#
save▸ save(): Promise‹any›
Persists contact to device storage.
Returns: Promise‹any›
#
ContactaddressContact address.
#
Constructors#
constructor+ new ContactAddress(pref?
: undefined | false | true, type?
: undefined | string, formatted?
: undefined | string, streetAddress?
: undefined | string, locality?
: undefined | string, region?
: undefined | string, postalCode?
: undefined | string, country?
: undefined | string): ContactAddress
Parameters:
Name | Type |
---|---|
pref? | undefined | false | true |
type? | undefined | string |
formatted? | undefined | string |
streetAddress? | undefined | string |
locality? | undefined | string |
region? | undefined | string |
postalCode? | undefined | string |
country? | undefined | string |
Returns: ContactAddress
#
PropertiesOptional
country#
• country? : string | null
The country name.
Optional
formatted#
• formatted? : string | null
The full address formatted for display.
Optional
id#
• id? : string | null
unique identifier, should only be set by native code
Optional
locality#
• locality? : string | null
The city or locality.
Optional
postalCode#
• postalCode? : string | null
The zip code or postal code.
Optional
pref#
• pref? : undefined | false | true
Set to true if this ContactAddress contains the user's preferred value.
Optional
region#
• region? : string | null
The state or region.
Optional
streetAddress#
• streetAddress? : string | null
The full street address.
Optional
type#
• type? : string | null
A string indicating what type of field this is, home for example.
#
ContacterrorContactError. An error code assigned by an implementation when an error has occurred
#
Constructors#
constructor+ new ContactError(code
: number): ContactError
Parameters:
Name | Type |
---|---|
code | number |
Returns: ContactError
#
Properties#
code• code: number
Error code
Optional
message#
• message? : undefined | string
Error message
Static
INVALID_ARGUMENT_ERROR#
▪ INVALID_ARGUMENT_ERROR: number = 1
Static
IO_ERROR#
▪ IO_ERROR: number = 4
Static
NOT_SUPPORTED_ERROR#
▪ NOT_SUPPORTED_ERROR: number = 5
Static
OPERATION_CANCELLED_ERROR#
▪ OPERATION_CANCELLED_ERROR: number = 6
Static
PENDING_OPERATION_ERROR#
▪ PENDING_OPERATION_ERROR: number = 3
Static
PERMISSION_DENIED_ERROR#
▪ PERMISSION_DENIED_ERROR: number = 20
Static
TIMEOUT_ERROR#
▪ TIMEOUT_ERROR: number = 2
Static
UNKNOWN_ERROR#
▪ UNKNOWN_ERROR: number = 0
Error codes
#
ContactfieldGeneric contact field.
#
Constructors#
constructor+ new ContactField(type?
: undefined | string, value?
: undefined | string, pref?
: undefined | false | true): ContactField
Parameters:
Name | Type |
---|---|
type? | undefined | string |
value? | undefined | string |
pref? | undefined | false | true |
Returns: ContactField
#
PropertiesOptional
id#
• id? : string | null
unique identifier, should only be set by native code
Optional
pref#
• pref? : undefined | false | true
Set to true if this ContactField contains the user's preferred value.
Optional
type#
• type? : string | null
A string that indicates what type of field this is, home for example.
Optional
value#
• value? : string | null
The value of the field, such as a phone number or email address.
#
ContactfindoptionsContactFindOptions. Search options to filter
#
Constructors#
constructor+ new ContactFindOptions(filter?
: undefined | string, multiple?
: undefined | false | true, desiredFields?
: string[], hasPhoneNumber?
: undefined | false | true): ContactFindOptions
Parameters:
Name | Type |
---|---|
filter? | undefined | string |
multiple? | undefined | false | true |
desiredFields? | string[] |
hasPhoneNumber? | undefined | false | true |
Returns: ContactFindOptions
#
PropertiesOptional
desiredFields#
• desiredFields? : string[]
Contact fields to be returned back. If specified, the resulting Contact object only features values for these fields.
Optional
filter#
• filter? : undefined | string
The search string used to find navigator.contacts.
Optional
hasPhoneNumber#
• hasPhoneNumber? : undefined | false | true
(Android only): Filters the search to only return contacts with a phone number informed.
Optional
multiple#
• multiple? : undefined | false | true
Determines if the find operation returns multiple navigator.contacts. Defaults to false.
#
ContactnameContact name.
#
Constructors#
constructor+ new ContactName(formatted?
: undefined | string, familyName?
: undefined | string, givenName?
: undefined | string, middleName?
: undefined | string, honorificPrefix?
: undefined | string, honorificSuffix?
: undefined | string): ContactName
Parameters:
Name | Type |
---|---|
formatted? | undefined | string |
familyName? | undefined | string |
givenName? | undefined | string |
middleName? | undefined | string |
honorificPrefix? | undefined | string |
honorificSuffix? | undefined | string |
Returns: ContactName
#
PropertiesOptional
familyName#
• familyName? : string | null
The contact's family name.
Optional
formatted#
• formatted? : string | null
The complete name of the contact.
Optional
givenName#
• givenName? : string | null
The contact's given name.
Optional
honorificPrefix#
• honorificPrefix? : string | null
The contact's prefix (example Mr. or Dr.)
Optional
honorificSuffix#
• honorificSuffix? : string | null
The contact's suffix (example Esq.).
Optional
middleName#
• middleName? : string | null
The contact's middle name.
#
ContactorganizationContact organization.
#
Constructors#
constructor+ new ContactOrganization(type?
: undefined | string, name?
: undefined | string, department?
: undefined | string, title?
: undefined | string, pref?
: undefined | false | true): ContactOrganization
Parameters:
Name | Type |
---|---|
type? | undefined | string |
name? | undefined | string |
department? | undefined | string |
title? | undefined | string |
pref? | undefined | false | true |
Returns: ContactOrganization
#
PropertiesOptional
department#
• department? : string | null
The department the contract works for.
Optional
id#
• id? : string | null
unique identifier, should only be set by native code
Optional
name#
• name? : string | null
The name of the organization.
Optional
pref#
• pref? : undefined | false | true
Set to true if this ContactOrganization contains the user's preferred value.
Optional
title#
• title? : string | null
The contact's title at the organization.
Optional
type#
• type? : string | null
A string that indicates what type of field this is, home for example.
#
ContactsAccess and manage Contacts on the device.
#
Methods#
create▸ create(properties?
: any): Contact
This function creates a new contact, but it does not persist the contact to device storage. To persist the contact to device storage, invoke contact.save().
Parameters:
Name | Type | Description |
---|---|---|
properties? | any | an object whose properties will be examined to create a new Contact |
Returns: Contact
new Contact object
#
find▸ find(fields
: ContactFieldType[], options?
: ContactFindOptions): Promise‹Contact[]›
Returns an array of Contacts matching the search criteria.
Parameters:
Name | Type | Description |
---|---|---|
fields | ContactFieldType[] | that should be searched (see platform specific notes) |
options? | ContactFindOptions | that can be applied to contact searching |
Returns: Promise‹Contact[]›
a promise that resolves with the array of Contacts matching search criteria
#
newContactUI▸ newContactUI(): Promise‹string›
iOS only Create a contact using the iOS Contact Picker UI
returns: a promise that resolves with the id of the created contact as param to successCallback
Returns: Promise‹string›
#
pickContact▸ pickContact(): Promise‹Contact›
This function picks contact from phone using contact picker UI
Returns: Promise‹Contact›
a promise that resolves with the selected Contact object
#
Changelog#
[1.1.2] (2020-06-10)#
Bug Fixes- ios: Adding additional search predicates on iOS
#
[1.1.1] (2020-05-28)#
Bug Fixes- ios: make wildcard return all contacts
#
[1.1.0] (2020-04-24)#
Features- ios: enable wildcard fetch-all contacts
#
[1.0.6] (2020-02-07)#
Bug Fixes- ios: make save work on existing contacts
#
[1.0.5] (2019-11-22)#
Bug Fixes- prevent devideready block when package is not installed as plugin
#
[1.0.4] (2019-11-08)#
Bug Fixes- ios: make pickContact prompt for permission if not granted
#
[1.0.3] (2019-11-04)#
Bug Fixes- make plugin don't break web context
#
[1.0.2] (2019-10-02)#
Bug Fixes- ios: remove contact notes code to work on iOS 13
#
1.0.1 (2019-09-20)#
Bug Fixes- plugin files not included on published package