連絡先データにアクセスするプラグインを使う

Apache Cordovaで本格スマホアプリに挑戦しよう 第11回

サンプルアプリの概要

　では、図3のようなサンプルアプリを通じて、連絡先データの取得、更新、追加、削除を行います。

図3　サンプルアプリの実行結果

連絡先データの取得

　端末内の連絡先データを取得するには、リスト2に示すfindメソッドを利用します。findメソッドの引数は表8で示す項目が指定できます。

リスト2　連絡先セットを取得する（findメソッド）

navigator.contact.find(fields,successCallback,errorCallback,options);

表8　findメソッドの引数

引数名	説明	型
fields	抽出時に検索する項目を指定する。項目名はContactクラスのプロパティ名が利用できる	DOMString[]
successCallback	成功時のコールバック関数。Contactオブジェクトの配列が取得できる	function
errorCallback	失敗時のコールバック関数。ContactErrorオブジェクトが取得できる	function
options	抽出するフィルタ条件を指定（オプション）	ContactFindOptions

　抽出条件を指定するためのContactFindOptionsでは、表9のようなプロパティが指定可能です。

表9　ContactFindOptions

プロパティ	説明
filter	抽出するときの検索キーワードを指定
multiple	複数のデータを抽出する場合にはtrue、1件のみの場合にはfalseを指定
desiredFields	返ってくるContactプロパティを指定。指定がない場合にはすべての項目
hasPhoneNumber	電話番号が指定されている連絡先のみを対象にする場合はtrueを指定（Androidのみ有効）

　リスト3は、すべてのデータを取得するときのサンプルコードです。

リスト3　すべての連絡先データを取得する（www/js/controllers/ContactController.jsの抜粋）

// （1）取得成功時の関数
function onSuccess(contacts) {

    var list = [];
    // （2）取得した結果は配列
    for (var i = 0; i < contacts.length; i++) {
        var item = contacts[i];
        var _item = {};
        // （3）表示名。ただし、iOSの場合等、データがない場合も想定
        if (item.displayName) {
            _item.displayName = item.displayName;
        }
        else if (item.name && item.name.formatted) {
            _item.displayName = item.name.formatted;
        }
        else {
            _item.displayName = "-";
        }
        // : （省略）

        // （4）一覧表示用の配列に追加
        list.push(_item);
    }
    // : （抜粋）
};
// （5）エラー時の処理
function onError(err) {
    window.alert("Error : " + err.code);
};


// （6）抽出の条件を指定
var options = new ContactFindOptions();
options.filter = '';
options.multiple = true;
// （7）検索に使用するフィールドを指定
var fields = ["displayName"];          // 空の配列は指定できない

// （8）データを取得
navigator.contacts.find(
    fields,     // 検索するフィールド
    onSuccess,  // 成功時の処理
    onError,    // 失敗時の処理
    options     // フィルタ等の条件
);

　（1）では取得に成功した場合のコールバック関数を定義しています。取得が成功すると結果は（2）のようにContactクラスの配列データになります。ContactオブジェクトのプロパティではOSによっての違いや、アイテムごとにデータがない場合も考える必要があります。従って、（3）のようにデータがない場合は他のデータを使って表示できるように準備した方が良いでしょう。そして、（4）で表示するデータとして配列データに再度、格納しています。（5）ではエラー時のコールバックを定義しています。エラー時には、表10に示すエラーコード（code）が取得できます。

表10　エラー時のcode値と説明

エラーコード	値	説明
ContactError.UNKNOWN_ERROR	0	原因不明
ContactError.INVALID_ARGUMENT_ERROR	1	引数に間違いがある
ContactError.TIMEOUT_ERROR	2	タイムアウト
ContactError.PENDING_OPERATION_ERROR	3	操作の保留エラー
ContactError.IO_ERROR	4	IOエラー
ContactError.NOT_SUPPORTED_ERROR	5	未サポートエラー
ContactError.OPERATION_CANCELLED_ERROR	6	操作キャンセル時のエラー
ContactError.PERMISSION_DENIED_ERROR	20	権限等で許可されない場合のエラー

　続いて、抽出する際の検索するフィールドを指定します。今回、全てのデータを抽出するので（6）のようにfilterには空文字を設定して指定します。そのため、検索するフィールドはいらないのですが、空の配列が指定できないため、（7）のようにdisplayNameフィールドを指定しています。ただし、今回の指定ではデフォルトと同じなので特に指定をしなくても同じです。そして、（8）のfindメソッドで一覧を取得します。

　また、displayNameもしくはnameが指定するfilterの文字列を含む連絡先のみを取得する場合はリスト4のようにします。

リスト4　指定したキーワードに一致する連絡先を取得する

var options = new ContactFindOptions();
options.multiple = true;
options.filter = "小林";
var fields = ["displayName","name"];

navigator.contacts.find(
    fields,     // 検索するフィールド
    onSuccess,  // 成功時の処理
    onError,    // 失敗時の処理
    options     // フィルタ等の条件
);

　指定した連絡先データを1件のみを取得したい場合にはidを使ってリスト5のようにすれば1件だけ取得できます。

リスト5　指定したIDの連絡先を取得する（www/js/controllers/ContactController.jsの抜粋）

var fields       = [navigator.contacts.fieldType.id];
var options = new ContactFindOptions();
options.filter = id; // "239"などを指定
options.multiple = false;

navigator.contacts.find(
    fields,
    function(contacts){
        // : （抜粋）
    },
    function(err){},
    options
);