連絡先

連絡先

contacts オブジェクトを通じて、デバイスの連絡先データベースにアクセスできます。

メソッド

引数

オブジェクト


contacts.create

新しいContactオブジェクトを作成します。

var contact = navigator.service.contacts.create(properties);

概要

contacts.create関数は新しいContactオブジェクトを同期的に作成します。

contacts.create関数で作成したContactオブジェクトは、デバイスのデータベースには残りません。デバイスに保存するには、 Contact.save 関数を使用します。

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

使用例

var myContact = navigator.service.contacts.create({"displayName": "Test User"});

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        var myContact = navigator.service.contacts.create({"displayName": "Test User"});
        myContact.gender = "男性";
        console.log("連絡先, " + myContact.displayName + ", は " + myContact.gender + " gender");
    }


    </script>
  </head>
  <body onload="onLoad()">
    <h1>サンプル</h1>
    <p>連絡先を作成します</p>
  </body>
</html>

contacts.find

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

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

概要

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

このメソッドを使用する際は contactFields パラメータに検索フィールドを指定します。 そして、 contactFields パラメータに渡したフィールドだけが Contact オブジェクトのプロパティとして contactSuccess コールバック関数に送られます。 contactFields パラメータが空の場合は id プロパティのみをもつ Contact オブジェクト配列が作成されます。

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

パラメータ

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

使用例

function onSuccess(contacts) {
    alert('検索結果: ' + contacts.length + ' contacts.');
};

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

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

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // 全てのフィールドから'Bob'という名前の連絡先を検索
        var options = new ContactFindOptions();
        options.filter="Bob"; 
        var fields = ["displayName", "name"];
        navigator.service.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() {
        alert('エラーが発生しました。');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <h1>サンプル</h1>
    <p>連絡先を検索します</p>
  </body>
</html>

iOS に関する注意点


Contact

連絡先に格納された情報を表します。

プロパティ

メソッド

詳細

Contact オブジェクトはユーザーの連絡先を格納します。連絡先はデバイスの連絡先データベースから作成したり、保存することが可能です。 contact.find 関数を実行することで、連絡先データベースからデータを検索し、取得することもできます。

注意: プラットフォームによっては、いくつかのフィールドがサポートされていない場合があります。プラットフォームごとの注意点に詳細を記載しています。

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

保存する例

function onSuccess(contacts) {
    alert("保存に成功しました。");
};

function onError(contactError) {
    alert("エラー = " + contactError.code);
};

// 新しい連絡先オブジェクトを作成
var contact = navigator.service.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";       //すべてのデバイスに対応するため、両方の項目をセット

// その他のフィールドを作成
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// デバイスに保存
contact.save(onSuccess, onError);

コピーを行う例

// Contact オブジェクトをコピー
var clone = contact.clone();
clone.name.givenName = "John";
console.log("コピー前の名前 = " + contact.name.givenName);
console.log("Cloneを実施した後の名前 = " + clone.name.givenName);

削除を行う例

function onSuccess() {
    alert("削除に成功しました。");
};

function onError(contactError) {
    alert("エラー = " + contactError.code);
};

// デバイスから連絡先を削除
contact.remove(onSuccess,onError);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>コンタクトの使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // 作成
        var contact = navigator.service.contacts.create();
        contact.displayName = "Plumber";
        contact.nickname = "Plumber";       //全てのデバイスに対応するため、両方の項目をセット
        var name = new ContactName();
        name.givenName = "Jane";
        name.familyName = "Doe";
        contact.name = name;

        // 保存
        contact.save(onSaveSuccess,onSaveError);

        // クローンを作成
        var clone = contact.clone();
        clone.name.givenName = "John";
        console.log("元の連絡先 = " + contact.name.givenName);
        console.log("クローンの連絡先 = " + clone.name.givenName); 

        // 削除
        contact.remove(onRemoveSuccess,onRemoveError);
    }

    // onSaveSuccess: 現在の連絡先を取得
    //
    function onSaveSuccess(contacts) {
        alert("保存に成功しました。");
    }

    // onSaveError: 連絡先の取得に失敗
    //
    function onSaveError(contactError) {
        alert("エラー = " + contactError.code);
    }

    // onRemoveSuccess: 現在の連絡先の取得
    //
    function onRemoveSuccess(contacts) {
        alert("削除に成功しました。");
    }

    // onRemoveError: 連絡先の取得に失敗
    //
    function onRemoveError(contactError) {
        alert("エラー = " + contactError.code);
    }

    </script>
  </head>
  <body onload="onLoad()">
    <h1>使用例</h1>
    <p>連絡先を検索</p>
  </body>
</html>

Android 2.X に関する注意点

下記のプロパティはAndroid 2.xではサポートされておらず、常にnullを返します。

revision, gender, categories, timezone

Android 1.X に関する注意点

下記のプロパティはAndroid 1.xではサポートされておらず、常にnullを返します。

name, nickname, revision, birthday, gender, photos ,categories, urls, timezone

BlackBerry WebWorks に関する注意点

下記のプロパティはBlack Berry WebWorksではサポートされておらず、常にnullを返します。

nickname, ims, revision, gender, timezone

下記のプロパティはBlack Berry WebWorksで部分的にサポートされています。

phoneNumbers: 電話番号はそれぞれのtypeに従って下記のフィールドに保存されます。

-typeがhomeの場合: homePhone1, homePhone2 -typeがworkの場合: workPhone1, workPhone2 -typeがmobileの場合: mobilePhone -typeがfaxの場合: faxPhone -typeがpagerの場合: pagerPhone -typeが上記以外の場合: otherPhone

email: Eメールは3つまでそれぞれ、email1, email2, email3フィールドに保存されます。 addresses: 住所は2つまでそれぞれ、homeAddress, workAddressフィールドに保存されます。 organizations: 組織の名前とタイトルはそれぞれ、compay, titleフィールドに保存されます。 photos: サムネイルサイズの写真のみサポートされています。連絡先に写真を登録する場合、64bitにかけたイメージか、イメージの場所を指定するURLを渡します。写真はBlack Berryに保存される前に縮小されます。 categories: 'Bussiness' と 'Personal' カテゴリのみサポートされています。 url: URLはBlack Berryのwebpageフィールドに保存されます。

下記のプロパティはBlack Berry WebWorksでサポートされています。

id: 連絡先が保存されたときにデバイスより割り当てられます。 displayname: BlackBerryのuser1フィールドに保存されます。

iOS に関する注意点


ContactAddress

Contact オブジェクトの住所プロパティを表します。

プロパティ

詳細

ContactAddress オブジェクトは連絡先の住所に関するプロパティを表します。 Contact オブジェクトは、複数の住所が格納された ContactAddress[] 配列を保持しています。

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

使用例

// すべての連絡先の住所情報を取得し、表示します
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].addresses.length; j++) {
            alert("住所: " + contacts[i].addresses[j].formatted + "\n" + 
                    "番地: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                    "都市: "  + contacts[i].addresses[j].locality + "\n" + 
                    "地域: "  + contacts[i].addresses[j].region + "\n" + 
                    "郵便番号: "  + contacts[i].addresses[j].postalCode + "\n" + 
                    "国: "  + contacts[i].addresses[j].country);
        }
    }
};

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

// 連絡先を検索します
var options = new ContactFindOptions();
options.filter=""; 
var filter = ["displayName","addresses"];
navigator.service.contacts.find(filter, onSuccess, onError, options);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // 全ての連絡先を検索します。
        var options = new ContactFindOptions();
        options.filter=""; 
        var filter = ["displayName","addresses"];
        navigator.service.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: 現在の連絡先を取得
    //
    function onSuccess(contacts) {
        // 全ての連絡先の住所を表示します。
        for (var i=0; i<contacts.length; i++) {
            for (var j=0; j<contacts[i].addresses.length; j++) {
                alert("住所: " + contacts[i].addresses[j].formatted + "\n" + 
                        "番地: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                        "都市: "  + contacts[i].addresses[j].locality + "\n" + 
                        "地域: "  + contacts[i].addresses[j].region + "\n" + 
                        "郵便番号: "  + contacts[i].addresses[j].postalCode + "\n" + 
                        "国: "  + contacts[i].addresses[j].country);
            }
        }
    };

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

    </script>
  </head>
  <body onload="onLoad()">
    <h1>使用例</h1>
    <p>連絡先を検索</p>
  </body>
</html>

Android 1.X に関する注意点

以下のプロパティはAndroid1.xではサポートされていません。常にnullを返します。

streetAddress, locality, regiron, postalCode, couuntry

BlackBerry WebWorks に関する注意点

iOS に関する注意点


ContactField

Contact オブジェクトで使用される汎用フィールドに用いられます。 ContactField オブジェクトとして格納されるデータとしては、メールアドレスや電話番号などが挙げられます。

プロパティ

詳細

ContactField オブジェクトは、連絡先の各フィールドを汎用的に格納するためのコンポーネントです。 各 ContactField オブジェクトは、value、type、pref の3つのプロパティを持っています。 Contact オブジェクトは電話番号やメールアドレスなどといった複数のプロパティを ContactFIeld[] 配列に保存しています。

多くの場合 ContactField オブジェクトの type 属性に定義済みの値は存在しません。 たとえば電話番号について type 属性の値としてhome、work、mobile、iPhoneなど、デバイスのプラットフォームに応じて異なった値が格納されます。

ただし photos フィールドに限り type 属性には画像フォーマットが格納されます。 この値が 'url' の場合 value 属性には画像のURLがセットされます。 また、'base64' の場合はBase64形式でエンコードされた画像を表す文字列が格納されます。

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

使用例

// 新しい連絡先を作成
var contact = navigator.service.contacts.create();

// 連絡先の電話番号をContactField[]に格納
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // 適当な電話番号
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;

// 連絡先を保存
contact.save();

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // 新しい連絡先を作成
        var contact = navigator.service.contacts.create();

        // ContactField[] に電話番号を保存
        var phoneNumbers = [3];
        phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
        phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // 適当な電話番号
        phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
        contact.phoneNumbers = phoneNumbers;

        // 連絡先を保存
        contact.save();

        // 連絡先を検索し、名前と電話番号を表示
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","phoneNumbers"];
        navigator.service.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: 現在の連絡先を取得
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            // display phone numbers
            for (var j=0; j<contacts[i].phoneNumbers.length; j++) {
                alert("タイプ: " + contacts[i].phoneNumbers[j].type + "\n" + 
                        "値: "  + contacts[i].phoneNumbers[j].value + "\n" + 
                        "Preferred: "  + contacts[i].phoneNumbers[j].pref);
            }
        }
    };

    // onError: コンタクトの取得に失敗
    //
    function onError() {
        alert('エラーが発生しました。');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <h1>使用例</h1>
    <p>連絡先の検索</p>
  </body>
</html>

Android に関する注意点

BlackBerry WebWorks に関する注意点

iOS に関する注意点


ContactFindOptions

contacts.find 関数の検索結果を絞るために使用するプロパティを表します。

プロパティ

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

使用例

// 呼び出し成功
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert(contacts[i].displayName);
    }
};

// 呼び出し失敗
function onError() {
    alert('エラーが発生しました。');
};

// 検索条件を指定
var options = new ContactFindOptions();
options.filter="";          // 空のサーチは全ての連絡先を返却
options.multiple=true;      // 複数の結果を返却
filter = ["displayName"];   // contact.displayName フィールドを返却

// 検索を実行
navigator.service.contacts.find(filter, onSuccess, onError, options);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // specify contact search criteria
        var options = new ContactFindOptions();
        options.filter="";          // 空のサーチは全ての連絡先を返します。
        options.multiple=true;      // 複数の結果を返却
        filter = ["displayName"];   // contact.displayName フィールドを返却

        // 連絡先を検索
        navigator.service.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: 現在の連絡先を取得
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert(contacts[i].displayName);
        }
    };

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

    </script>
  </head>
  <body onload="onLoad()">
    <h1>使用例</h1>
    <p>連絡先を検索</p>
  </body>
</html>

Android に関する注意点

BlackBerry WebWorks に関する注意点


ContactName

Contact オブジェクトのnameプロパティを格納します。

プロパティ

詳細

ContactName オブジェクトは連絡先の name プロパティの情報を格納します。

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

使用例

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert("名前: " + contacts[i].name.formatted + "\n" + 
                "姓: "  + contacts[i].name.familyName + "\n" + 
                "名: "  + contacts[i].name.givenName + "\n" + 
                "ミドルネーム: "  + contacts[i].name.middleName + "\n" + 
                "接頭敬称: "  + contacts[i].name.honorificSuffix + "\n" + 
                "接尾敬称: "  + contacts[i].name.honorificSuffix);
    }
};

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

var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","name"];
navigator.service.contacts.find(filter, onSuccess, onError, options);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName"];
        navigator.service.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: 現在の連絡先を取得
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert("Formatted: " + contacts[i].name.formatted + "\n" + 
                    "名字: "  + contacts[i].name.familyName + "\n" + 
                    "名前: "  + contacts[i].name.givenName + "\n" + 
                    "ミドルネーム: "  + contacts[i].name.middleName + "\n" + 
                    "接頭敬称: "  + contacts[i].name.honorificSuffix + "\n" + 
                    "接尾敬称: "  + contacts[i].name.honorificPrefix);
        }
    };

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

    </script>
  </head>
  <body onload="onLoad()">
    <h1>使用例</h1>
    <p>連絡先を検索</p>
  </body>
</html>

Android に関する注意点

BlackBerry WebWorks に関する注意点

iOS に関する注意点


ContactOrganization

Contact オブジェクトの組織情報を格納します。

プロパティ

詳細

ContactOrganization オブジェクトは連絡先の組織情報を表します。 Contact オブジェクトは複数の ContactOrganization オブジェクトを配列の中に格納します。

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

使用例

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].organizations.length; j++) {
            alert("名前: " + contacts[i].organizations[j].name + "\n" + 
                    "部署: "  + contacts[i].organizations[j].department + "\n" + 
                    "役職: "  + contacts[i].organizations[j].title);
        }
    }
};

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

var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.service.contacts.find(filter, onSuccess, onError, options);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>連絡先の使用例</title>

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

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","organizations"];
        navigator.service.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: 現在の連絡先を取得
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            for (var j=0; j<contacts[i].organizations.length; j++) {
                alert("名前: " + contacts[i].organizations[j].name + "\n" + 
                        "部署: "  + contacts[i].organizations[j].department + "\n" + 
                        "役職: "  + contacts[i].organizations[j].title);
            }
        }
    };

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

    </script>
  </head>
  <body onload="onLoad()">
    <h1>使用例</h1>
    <p>連絡先を検索</p>
  </body>
</html>

Android 1.X に関する注意点

BlackBerry WebWorks に関する注意点

iOS に関する注意点


ContactError

エラーが発生した時に contactError コールバック関数に渡されるオブジェクトです。

パラメータ

コンタクト

詳細

エラーが発生した際に contactError コールバック関数を通して 'ContactError' オブジェクトが返されます。


contactSuccess

contacts.find メソッドの実行に成功した場合に呼び出されるコールバック関数です。

function(contacts) {
    // 処理を記述
}

パラメータ

使用例

function contactSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        console.log("表示名 = " + contacts[i].displayName;
}

contactError

エラーが発生した際に呼び出されるコールバック関数です。

function(error) {
    // エラー処理を記述
}

contactFields

contacts.find メソッドを使用する際の必須パラメータです。 contact.find によって作成される Contact オブジェクトが持つフィールドを指定します。

["name", "phoneNumbers", "emails"]

contactFindOptions

contacts.find メソッドで使用されるオプションのパラメータを表します。連絡先の検索時にフィルターをかける場合に使用します。

{ 
    filter: "",
    multiple: true,
    updatedSince: ""
};

オプション

Android に関する注意点

BlackBerry WebWorks に関する注意点