contacts.find

デバイスの連絡先データベースに問い合わせを行い、 [Contact](Contact/contact.html) オブジェクトを取得します。

navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

概要

contacts.find 関数は、デバイスの連絡先データベースに問い合わせを行い、 [Contact](Contact/contact.html) オブジェクトの配列を返す非同期関数です。 作成されたオブジェクトは contactSuccess に従って [contactSuccess](parameters/contactSuccess.html) コールバック関数に送られます。

このメソッドを使用する際は contactFields パラメーターに検索フィールドを指定します。 contactFields パラメーターに渡したフィールドだけが、 [Contact](Contact/contact.html) オブジェクトのプロパティーとして contactSuccess コールバック関数に渡されます。 contactFields パラメーターが空の場合は、 id プロパティーのみを持つ [Contact](Contact/contact.html) オブジェクト配列が作成されます。 contactFields の値が["*"]の場合は、全ての連絡先フィールドが返されます。

連絡先データベースの問い合わせの際には、 contactFindOptions.filter を用いて検索条件を絞ることが出来ます。このオプションが指定されていた場合、大文字小文字の区別なく、部分一致方式により contactFields パラメーターに指定されたフィールドの検索が行われます。いずれかのフィールドにマッチした内容があった場合、その連絡先情報が返されます。

パラメーター

  • contactFields: 検索条件に格納されるフィールドを指定します。このパラメーターに定義されたフィールドのみが [Contact](Contact/contact.html) オブジェクトにセットされます。 (DOMString[]) [必須]
  • contactSuccess: 連絡先データベースへの問い合わせに成功した場合に呼び出されるコールバック関数を指定します [必須]
  • contactError: エラーコールバック関数を指定します。連絡先データベースへの問い合わせに失敗した場合に呼び出されます [任意]
  • contactFindOptions: 連絡先情報に絞り込み検索を行うための検索オプションを指定します [任意]

サポートされているプラットフォーム

  • Android
  • BlackBerry WebWorks (OS 5.0 以上)
  • iOS
  • Bada 1.2

使用例

function onSuccess(contacts) {
    alert(contacts.length + '  件の連絡先が見つかりました。');
};

function onError(contactError) {
    alert('エラーが発生しました。');
};

// Bob という名前が含まれる全ての連絡先を取得
var options = new ContactFindOptions();
options.filter="Bob";
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

詳細な使用例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact の使用例</title>

    <script type="text/javascript" charset="utf-8" src="cordova-1.7.0.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Cordova の読み込み完了まで待機
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // Cordova 準備完了
    //
    function onDeviceReady() {
        // Bob という名前が含まれる全ての連絡先を取得
        var options = new ContactFindOptions();
        options.filter="Bob";
        var fields = ["displayName", "name"];
        navigator.contacts.find(fields, onSuccess, onError, options);
    }

    // onSuccess: 連絡先の取得に成功した場合
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            console.log("表示名 = " + contacts[i].displayName);
        }
    }

    // onError: 連絡先の取得に失敗した場合
    //
    function onError(contactError) {
        alert('エラーが発生しました。');
    }

    </script>
  </head>
  <body>
    <h1>使用例</h1>
    <p>連絡先の検索</p>
  </body>
</html>