PhoneGapには、連絡先に関する機能が用意されています。これは、navigator.contactsとして用意されているオブジェクトを利用します。今回は、このオブジェクトを利用した連絡先へのアクセスについて説明しましょう。

まず最初に、Androidでこのnavigator.contactsを利用する場合、連絡先へのアクセス権の設定が必要になる、ということを頭に入れておきましょう。下のリスト欄に、アクセス権のためのタグを用意しました。マニフェストファイルに、必ずこれらを用意しておくようにしてください。

さて、このnavigator.contactsオブジェクトは、連絡先情報の取得と作成を行うためのメソッドを持っています。これらのメソッドを利用して連絡先のオブジェクトを取得し、それを操作する、という形で操作を行います。

では、連絡先の検索から行なってみましょう。検索はnavigator.contactsに用意されている以下のメソッドを使って行います。

変数 = navigator.contacts.find( フィールド , 成功時処理 , 失敗時処理 , オプション );

フィールド――取得する項目の指定です。連絡先のデータから取り出す項目名を配列として用意します。
成功時処理――取得に成功した時に呼び出される処理です。
失敗時処理――取得に失敗した時の例外処理を行うものです。
オプション――検索に必要な設定情報などをまとめたオブジェクトです。

ざっと見て、まず気がつくのは「検索テキストの設定がない」という点でしょう。実は、これは最後のオプションのところに用意します。このオプションの指定では、「ContactFindOptions」というオブジェクトを用意します。これは、コンタクト検索の諸設定を管理するための専用オブジェクトです。new ContactFindOptions();でオブジェクトを作成し、そのオブジェクトに検索のための設定を追記します。

《ContactFindOptions》.filter = 検索テキスト;

「filter」というのは、データを絞り込むための設定情報を管理するプロパティです。ここに、検索対象となるテキストを設定します。これにより、指定された形でフィルターが用意され、連絡先のデータが絞りこまれます。

このfilterという項目からもわかるように、findによる検索は、実は「データのフィルター処理」を行うものなのです。ですから、例えばfilterに値を設定していないと、findですべての項目が取り出せます。「findは、データ全体の中から特定の条件で絞り込んで結果を返すものだ」という点は理解しておくようにしましょう。

このfindメソッドは、非同期で実行されます。データの取得が完了すると、第２引数に用意された関数が呼び出されます。この関数は引数が１つ用意されており、ここに取得した連絡先のオブジェクトの配列が渡されます。このオブジェクトは「Contact」というもので、連絡先の値をプロパティとして用意しています。ここから必要な情報を取り出して利用すれば良いわけです。

※Androidのマニフェスト設定
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />