Contacts

Contacts

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

メソッド

引数

オブジェクト

パーミッション

Android

app/res/xml/plugins.xml

<plugin name="Contacts" value="org.apache.cordova.ContactManager" />

app/AndroidManifest.xml

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

Bada

manifest.xml

<Privilege>
    <Name>ADDRESSBOOK</Name>
</Privilege>

BlackBerry WebWorks

www/plugins.xml

<plugin name="Contact" value="org.apache.cordova.pim.Contact" />

www/config.xml

<feature id="blackberry.find"        required="true" version="1.0.0.0" />
<feature id="blackberry.identity"    required="true" version="1.0.0.0" />
<feature id="blackberry.pim.Address" required="true" version="1.0.0.0" />
<feature id="blackberry.pim.Contact" required="true" version="1.0.0.0" />

iOS

App/Supporting Files/Cordova.plist

<key>Plugins</key>
<dict>
    <key>Contacts</key>
    <string>CDVContacts</string>
</dict>

webOS

パーミッションの設定は必要ありません。

Windows Phone

Properties/WPAppManifest.xml

<Capabilities>
    <Capability Name="ID_CAP_CONTACTS" />
</Capabilities>

参照: Application Manifest for Windows Phone

contacts.create

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

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

概要

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

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

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

使用例 

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

詳細な使用例 

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

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

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

    // Cordova 準備完了
    //
    function onDeviceReady() {
        var myContact = navigator.contacts.create({"displayName": "Test User"});
        myContact.note = "この連絡先のメモ";
        console.log("連絡先, " + myContact.displayName + ", メモ: " + myContact.note);
    }


    </script>
  </head>
  <body>
    <h1>使用例</h1>
    <p>連絡先を作成します</p>
  </body>
</html>

contacts.find

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

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

概要

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

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

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

パラメーター

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

使用例 

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.9.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>

Contact

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

プロパティー

メソッド

詳細

Contact オブジェクトはユーザーの連絡先を格納します。 連絡先はデバイスの連絡先データベースから作成したり、保存したり、削除することが可能です。 contacts.find 関数を呼ぶことで、連絡先データベースから連絡先を取得することも出来ます。

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

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

保存する例 

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

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

// 新しい連絡先オブジェクトを作成
var contact = navigator.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);

コピーを行う例 

// 連絡先オブジェクトをコピー
var clone = contact.clone();
clone.name.givenName = "John";
console.log("元の名前 = " + contact.name.givenName);
console.log("クローンの名前 = " + clone.name.givenName);

削除を行う例 

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

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

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

詳細な使用例 

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

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

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

    // Cordova 準備完了
    //
    function onDeviceReady() {
        // 作成
        var contact = navigator.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(contact) {
        alert("保存に成功しました。");
    }

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

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

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

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

Android 2.X に関する注意点

Android 1.X に関する注意点

BlackBerry WebWorks (OS 5.0 and higher) に関する注意点

iOS に関する注意点

Bada に関する注意点

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].pref + "\n" +
                    "タイプ: " + contacts[i].addresses[j].type + "\n" +
                    "住所: " + 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(contactError) {
    alert('エラーが発生しました。');
};

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

詳細な使用例 

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

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

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

    // Cordova 準備完了
    //
    function onDeviceReady() {
        // find all contacts
        var options = new ContactFindOptions();
        options.filter="";
        var filter = ["displayName","addresses"];
        navigator.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].pref + "\n" +
                        "タイプ: " + contacts[i].addresses[j].type + "\n" +
                        "住所: " + 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(contactError) {
        alert('エラーが発生しました。');
    }

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

Android 2.X に関する注意点

Android 1.X に関する注意点

BlackBerry WebWorks (OS 5.0 and higher) に関する注意点

iOS に関する注意点

Bada に関する注意点

ContactField

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

プロパティー

詳細

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

多くの場合 ContactField オブジェクトの type 属性に定義済みの値は存在しません。例えば、電話番号について type 属性の値として 'home', 'work', 'mobile', 'iPhone' など、デバイスのプラットフォームに応じて異なった値が格納されます。ただし Contact の photos フィールドに限り、 type 属性には画像フォーマットが格納されます。 Cordova は value 属性が画像への URL を含む場合、 type: 'url' を返します。 value 属性が Base64 形式の画像を含む場合、 type: 'base64' を返します。

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

使用例 

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

// 連絡先の電話番号を ContactField[] に格納
var phoneNumbers = [];
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>
<html>
  <head>
    <title>Contact の使用例</title>

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

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

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

        // 連絡先の電話番号を ContactField[] に格納
        var phoneNumbers = [];
        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.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].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(contactError) {
        alert('エラーが発生しました。');
    }

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

Android に関する注意点

BlackBerry WebWorks (OS 5.0 and higher) に関する注意点

iOS に関する注意点

Bada に関する注意点

ContactFindOptions

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

プロパティー

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

使用例 

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

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

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

// 連絡先を検索します
navigator.contacts.find(filter, onSuccess, onError, options);

詳細な使用例 

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

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

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

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

        // 連絡先を検索します
        navigator.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(contactError) {
        alert('エラーが発生しました。');
    }

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

Bada に関する注意点

filter: このプロパティーには次の値のみ適用できます: "firstName", "lastName", "nickname", "phoneNumber", "email", "address"

ContactName

Contact オブジェクトの名前プロパティーを表します。

プロパティー

詳細

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

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

使用例 

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(contactError) {
    alert('エラーが発生しました。');
};

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

詳細な使用例 

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

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

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

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

    // onSuccess: 連絡先の取得に成功した場合
    //
    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);
        }
    };

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

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

Android に関する注意点

BlackBerry WebWorks (OS 5.0 and higher) に関する注意点

iOS に関する注意点

Bada に関する注意点

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].pref + "\n" +
                    "タイプ: " + contacts[i].organizations[j].type + "\n" +
                    "組織名: " + contacts[i].organizations[j].name + "\n" +
                    "部署名: " + contacts[i].organizations[j].department + "\n" +
                    "役職名: " + contacts[i].organizations[j].title);
        }
    }
};

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

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

詳細な使用例 

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

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

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

    // Cordova 準備完了
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","organizations"];
        navigator.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].pref + "\n" +
                        "タイプ: " + contacts[i].organizations[j].type + "\n" +
                        "組織名: " + contacts[i].organizations[j].name + "\n" +
                        "部署名: " + contacts[i].organizations[j].department + "\n" +
                        "役職名: " + contacts[i].organizations[j].title);
            }
        }
    };

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

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

Android 2.X に関する注意点

Android 1.X に関する注意点

BlackBerry WebWorks (OS 5.0 and higher) に関する注意点

iOS に関する注意点

Bada 2.0 に関する注意点

ContactError

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

プロパティー

定数

概要

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

contactSuccess

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

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 オブジェクトが持つフィールドを指定します。

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

contactFindOptions

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

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

オプション