これがないドキュメントの最新バージョンです！ Click here for the latest released version.

Contact

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

プロパティー

id: 固定のIDを表します (DOMString)
displayName: 連絡先の名称を表します (DOMString)
name: 個人名に関するオブジェクトを表します (ContactName)
nickname: ニックネームを表します (DOMString)
phoneNumbers: 連絡先のすべての電話番号の配列を表します (ContactField[])
emails: 連絡先のすべてのメールアドレスの配列を表します (ContactField[])
addresses: 連絡先のすべての住所の配列を表します (ContactAddress[])
ims: 連絡先のすべてのIMアドレスの配列を表します (ContactField[])
organizations: 連絡先のすべての組織名の配列を表します (ContactOrganization[])
birthday: 連絡先の誕生日を表します (Date)
note: 連絡先のメモを表します (DOMString)
photos: 連絡先の写真の配列を表します (ContactField[])
categories: 連絡先のユーザー定義カテゴリーの配列を表します (ContactField[])
urls: 連絡先に関連したURLの配列を表します (ContactField[])

メソッド

clone: オブジェクトのディープコピーを行い、新しい Contact オブジェクトを作成して返します。 id プロパティーは null に設定されます。
remove: オブジェクトを連絡先データベースから削除します。削除が失敗した場合は [ContactError](../ContactError/contactError.html) を伴ったエラーコールバック関数が呼び出されます。
save: 新しい連絡先を連絡先データベースに保存します。 id が既に登録されている場合は連絡先データベースを上書きします。

詳細

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

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

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

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

保存する例

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.8.1.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 に関する注意点

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

Android 1.X に関する注意点

name: このプロパティーは Android 1.X ではサポートされておらず、常に null を返します。
nickname: このプロパティーは Android 1.X ではサポートされておらず、常に null を返します。
birthday: このプロパティーは Android 1.X ではサポートされておらず、常に null を返します。
photos: このプロパティーは Android 1.X ではサポートされておらず、常に null を返します。
categories: このプロパティーは Android 1.X ではサポートされておらず、常に null を返します。
urls: このプロパティーは Android 1.X ではサポートされておらず、常に null を返します。

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

id: サポートされています。連絡先が保存されたときに、デバイスによって割り当てられます。
displayName: サポートされています。 BlackBerry では user1 フィールドとして保存されます。
nickname: このプロパティーはサポートされておらず、常に null を返します。.
phoneNumbers: 部分的にサポートされています。 BlackBerry では、電話番号はもし type が 'home' の場合は homePhone1と homePhone2 に、 type が 'work' の場合は workPhone1 と workPhone2 に、 type が 'mobile' の場合は mobilePhone に、 type が 'fax' の場合は faxPhone に、 type が 'pager' の場合は pagerPhone に、それ以外の場合は otherPhone に保存されます。
emails: 部分的にサポートされています。 BlackBerry では、最初の3メールアドレスが email1, email2, email3 フィールドに保存されます。
addresses: 部分的にサポートされています。 BlackBerry では、最初の2つの住所が homeAddress と workAddress フィールドに保存されます。
ims: このプロパティーはサポートされておらず、常に null を返します。
organizations: 部分的にサポートされています。 BlackBerry では、最初の組織の名前とタイトルが company と title フィールドに保存されます。
photos: 部分的にサポートされています。サムネイルサイズの写真のみサポートされています。連絡先に写真を登録する場合、 Base64 エンコードされたイメージか、イメージの場所を指定する URL を渡します。写真は BlackBerry の連絡先データベースに保存される前に縮小されます。連絡先写真は Base64 エンコードされたイメージとして返されます。
categories: 部分的にサポートされています。 'Business' と 'Personal' カテゴリーのみサポートされています。
urls: 部分的にサポートされています。 BlackBerry では、最初の URL が webpage フィールドに保存されます。

iOS に関する注意点

displayName: このプロパティーは iOS ではサポートされておらず、 ContactName が指定されていない場合限り null を返します。もし ContactName が指定されていない場合、合成された名前、 nickname 、または "" が displayName として返されます。
birthday: 入力として、このプロパティーは JavaScript の Date オブジェクトとして指定する必要があります。 JavaScript の Date オブジェクトとして返されます。
photos: 取得した写真はアプリの一時ディレクトリに保存され、写真への File URL が返されます。一時ディレクトリの中身はアプリを終了する際に削除されます。
categories: このプロパティーはサポートされておらず、常に null を返します。

Bada に関する注意点

displayName: このプロパティーはサポートされていません。
birthday: このプロパティーはサポートされていません。
photos: このプロパティーは写真へのURL1つを格納したリストです。
categories: このプロパティーはサポートされていません。
ims: このプロパティーはサポートされていません。