対象読者
- スマホアプリに挑戦したいと思っているWeb開発者
- アプリ開発をもっと楽にしたいと思っている方
- 業務スマホアプリを作る開発者
連絡先にアクセスするためのプラグイン
スマホの基本的な機能である連絡先にアクセスするプラグインを紹介します。
インストール
インストールするプラグインは、「cordova-plugin-contacts 」です。インストールはリスト1のように行います。
リスト1 プラグインのインストール
$cordova plugin add cordova-plugin-contacts
プラグインの概要
Contactsプラグインには、端末内の連絡先データを取得する方法として2種類の方法があり、抽出条件を指定して取得する方法、OS標準のUIによる連絡先データ一覧から選択した1件を取得する方法があります。取得だけでなく、データの登録／更新／削除も可能です。これらの利用できるメソッドの関係を示したのが、図1／表1です。
これらメソッドの構文を、以下にまとめます。
| メソッド | 説明 |
|---|---|
| navigator.contacts.create(object) | 連絡先データ（Contactクラス）のインスタンスを作成する。同期メソッドでネイティブコールしない |
| navigator.contact.find(fields,successCallback,errorCallback,options) | 条件（ContactFindOptionsクラス）を指定し、条件に一致する連絡先データを取得する |
| navigator.contacts.pickContact(successCallback) | OSが提供する連絡先一覧のUIを起動し、そこで指定された連絡先データを取得する |
取得した連絡先データはContactクラスのインスタンスとして取得できます。このContactクラスには表2のようなメソッドがあり、これらを使ってデータの追加・更新・削除ができます。
| メソッド | 説明 |
|---|---|
| Contact.save(successCallback,errorCallback) | 内部で管理しているIDがない場合には追加、ある場合には更新する |
| Contact.remove(successCallback,errorCallback) | 指定した連絡先データを削除する |
| Contact.clone() | インスタンスの複製を作る。このとき内部IDはコピーしないのでsaveすると追加になる |
連絡先のプロパティとデータ型
連絡先データは氏名や電話番号などのプロパティ値を持ちますが、それぞれのデータのためにプラグイン側で定義された独自のデータ型が図2のように定義されています。
Contact（連絡先データ）
連絡先を管理するためのクラスです。このクラスには表3に示すプロパティがありますが、iOSとAndroidでは多少管理する項目が異なります。例えば、iOSの場合にはdisplayNameはNULLになり、代わりにname属性を使うことが推奨されるなど少々異なるので注意が必要です。
| プロパティ | 説明 | 型 |
|---|---|---|
| id | データを識別するためのID | DOMString |
| displayName | 表示用の連絡先の名称。iOSでは使用できない | DOMString |
| nickname | 連絡先を示すニックネーム | DOMString |
| name | 名前 | ConstactName |
| birthday | 誕生日 | Date |
| phoneNumbers | 電話番号（配列） | ContactField[] |
| emails | メールアドレス（配列） | ContactField[] |
| photos | 連絡先の写真（配列） | ContactField[] |
| addresses | 住所（配列） | ContactAddress[] |
| ims | インスタントメッセンジャー用のアドレス（配列） | ContactField[] |
| organizations | 組織（配列） | ContactOrganization[] |
| urls | WEBページへのリンク（配列） | ContactField[] |
| categories | ユーザー定義のカテゴリー（配列）。iOSでは使用できない | ContactField[] |
| note | メモ | DOMString |
氏名（ContactName）
連絡先の氏名データを管理するためのクラスです。
| プロパティ | 説明 | 型 |
|---|---|---|
| formatted | フルネームの値 | DOMString |
| familyName | 名前（性） | DOMString |
| givenName | 名前（名） | DOMString |
| middleName | ミドルネーム | DOMString |
| honorificPrefix | 名前の前につける敬称。例）Mr. | DOMString |
| honorificSuffix | 名前の後につける敬称。例）様 | DOMString |
属性用汎用フィールド（ContactField）
電話番号やメールアドレス、写真データなどを管理するための汎用クラスです。例えば、電話番号で自宅用の場合にはtypeにhomeが入るなどのように使用されます。
| プロパティ | 説明 | 型 |
|---|---|---|
| type | 項目のタイプ。例）homeやmobileなど | DOMString |
| value | 項目の値。電話番号やメールアドレスなど | DOMString |
| pref | 優先的に値を指定するフィールドの場合にはtrueを指定 | Boolean |
ContactAddress
住所データを管理するためのクラスです。
| プロパティ | 説明 | 型 |
|---|---|---|
| type | 項目のタイプ。例）homeなど | DOMString |
| formatted | 表示用の住所 | DOMString |
| streetAddress | 番地 | DOMString |
| locality | 市町村 | DOMString |
| region | 都道府県 | DOMString |
| postalCode | 郵便番号 | DOMString |
| country | 国 | DOMString |
| pref | 優先的に値を指定するフィールドの場合にはtrueを指定 | Boolean |
組織用フィールド（ContactOrganization）
組織データを管理するためのクラスです。
| プロパティ | 説明 | 型 |
|---|---|---|
| type | 項目のタイプ。例）customなど | DOMString |
| name | 組織名 | DOMString |
| department | 所属部署 | DOMString |
| title | 役職名等 | DOMString |
| pref | 優先的に値を指定するフィールドの場合にはtrueを指定 | Boolean |
