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.
#
Contacts#
Index#
Classes- Contact
- ContactAddress
- ContactError
- ContactField
- ContactFindOptions
- ContactName
- ContactOrganization
- Contacts
#
Type aliases#
Classes#
ContactContact:
Contains information about a single contact.
#
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 |
---|---|
Optional id | undefined | string |
Optional displayName | undefined | string |
Optional name | ContactName |
Optional nickname | undefined | string |
Optional phoneNumbers | ContactField[] |
Optional emails | ContactField[] |
Optional addresses | ContactAddress[] |
Optional ims | ContactField[] |
Optional organizations | ContactOrganization[] |
Optional birthday | Date | string | null |
Optional note | undefined | string |
Optional photos | ContactField[] |
Optional categories | ContactField[] |
Optional urls | ContactField[] |
Returns: Contact
<Optional>
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.
#
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 |
---|---|---|
Optional 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
>
#
ContactAddressContactAddress:
Contact address.
#
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 |
---|---|
Optional pref | undefined | false | true |
Optional type | undefined | string |
Optional formatted | undefined | string |
Optional streetAddress | undefined | string |
Optional locality | undefined | string |
Optional region | undefined | string |
Optional postalCode | undefined | string |
Optional country | undefined | string |
Returns: ContactAddress
<Optional>
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:
ContactError. An error code assigned by an implementation when an error has occurred
constructor:
#
constructor⊕ new ContactError(code: number
): ContactError
Parameters:
Name | Type |
---|---|
code | number |
Returns: ContactError
#
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
#
ContactFieldContactField:
Generic contact field.
#
constructor⊕ new ContactField(type?: undefined
| string
, value?: undefined
| string
, pref?: undefined
| false
| true
): ContactField
Parameters:
Name | Type |
---|---|
Optional type | undefined | string |
Optional value | undefined | string |
Optional pref | undefined | false | true |
Returns: ContactField
<Optional>
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:
ContactFindOptions. Search options to filter
#
constructor⊕ new ContactFindOptions(filter?: undefined
| string
, multiple?: undefined
| false
| true
, desiredFields?: string
[], hasPhoneNumber?: undefined
| false
| true
): ContactFindOptions
Parameters:
Name | Type |
---|---|
Optional filter | undefined | string |
Optional multiple | undefined | false | true |
Optional desiredFields | string [] |
Optional hasPhoneNumber | undefined | false | true |
Returns: ContactFindOptions
<Optional>
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.
#
ContactNameContactName:
Contact name.
#
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 |
---|---|
Optional formatted | undefined | string |
Optional familyName | undefined | string |
Optional givenName | undefined | string |
Optional middleName | undefined | string |
Optional honorificPrefix | undefined | string |
Optional honorificSuffix | undefined | string |
Returns: ContactName
<Optional>
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.
#
ContactOrganizationContactOrganization:
Contact organization.
#
constructor⊕ new ContactOrganization(type?: undefined
| string
, name?: undefined
| string
, department?: undefined
| string
, title?: undefined
| string
, pref?: undefined
| false
| true
): ContactOrganization
Parameters:
Name | Type |
---|---|
Optional type | undefined | string |
Optional name | undefined | string |
Optional department | undefined | string |
Optional title | undefined | string |
Optional pref | undefined | false | true |
Returns: ContactOrganization
<Optional>
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.
#
ContactsContacts:
Access and manage Contacts on the device.
#
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 |
---|---|---|
Optional 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 |
Optional 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
#
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"*
#
Changelog#
[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