Search docs/

Contacts

v1.0.0

Contents

インストール

Ionic Enterprise Editionのプラグインを利用する場合は、 通常のバージョンでスコープ指定されたプラグインに問題がある可能性があるため、 Ionic Enterprise Cordova CLIを使用していることを確認する必要があります。

npm uninstall -g cordovanpm install -g @ionic-enterprise/cordova

Ionic Enterprise Cordova CLIをインストールしたら、プラグインをインストールできます。

ionic enterprise register --key=YOURPRODUCTKEYionic cordova plugin add @ionic-enterprise/contacts

[

](#ionic-contacts)

This plugin allows to read, write and pick contacts.

[

Usage

](#usage)

The Contacts plugin ship with a native Angular & es2015+/Typescript wrappers as well as being available on window.

// Angular
import { Contacts } from '@ionic-enterprise/contacts/ngx';
import { Contact, ContactName, ContactField  } from '@ionic-enterprise/contacts';

...

constructor(private contacts: Contacts) { }

async createContact() {
  let contact = this.contacts.create();
  contact.name = new ContactName(null, 'Smith', 'John');
  contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
  contact.save().then(
    () => console.log('Contact saved!', contact),
    (error: any) => console.error('Error saving contact.', error)
  );
}

...

// ES2015+/TypeScript
import { Contacts, Contact, ContactName, ContactField } from '@ionic-enterprise/contacts';

let contact = Contacts.create();
contact.name = new ContactName(null, 'Smith', 'John');
contact.phoneNumbers = [new ContactField('mobile', '6471234567')];
contact.save().then(
  () => console.log('Contact saved!', contact),
  (error: any) => console.error('Error saving contact.', error)
);

...

// Vanilla JS
document.addEventListener('deviceready', () => {
  let contact = IonicContacts.create();
  contact.name = {familyName: 'Smith', givenName: 'John'};
  contact.phoneNumbers = {type: 'mobile', value: '6471234567'};
  contact.save().then(
    () => console.log('Contact saved!', contact),
    (error) => console.error('Error saving contact.', error)
  );
});

Index

Classes

Type aliases


Classes

Contact

Contact:

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.


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



ContactAddress

ContactAddress:

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.



ContactError

ContactError:

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



ContactField

ContactField:

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.



ContactFindOptions

ContactFindOptions:

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.



ContactName

ContactName:

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.



ContactOrganization

ContactOrganization:

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.



Contacts

Contacts:

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"*


Other Versions