連絡先
contacts
オブジェクトを通じて、デバイスの連絡先データベースにアクセスできます。
メソッド
引数
オブジェクト
contacts.create
新しいContactオブジェクトを作成します。
var contact = navigator.service.contacts.create(properties);
概要
contacts.create関数は新しいContactオブジェクトを同期的に作成します。
contacts.create関数で作成したContactオブジェクトは、デバイスのデータベースには残りません。デバイスに保存するには、 Contact.save
関数を使用します。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
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 パラメータに指定されたフィールドの検索が行われます。 どれかの フィールドにマッチした内容があった場合、その連絡先情報が戻ります。
パラメータ
-
contactFields: 検索条件に格納されるフィールドを指定します。このパラメータに定義されたフィールドのみが
Contact
オブジェクトにセットされます (DOMString[]) [必須] - contactSuccess: 連絡先データベースへの問い合わせに成功した場合に呼び出されるコールバック関数を指定します [必須]
- contactError: 連絡先データベースへの問い合わせに失敗した場合に呼び出されるコールバック関数を指定します [任意]
- contactFindOptions: 連絡先情報に絞り込み検索を行うための検索オプションを指定します [任意]
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
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 に関する注意点
- 結果が検索されない場合、iOSではnullを返します。その他のプラットフォームは空の配列を返します。
Contact
連絡先に格納された情報を表します。
プロパティ
- id: 固有のIDを表します (DOMString)
- displayname: 連絡先の名称を表します (DOMString)
- name: 個人名に関するオブジェクトを表します (ContactName)
- nickname: ニックネームを表します (DOMString)
- phoneNumbers: すべての電話番号を含む配列を表します (ContactField[])
- emails: すべてのメールアドレスを含む配列を表します (ContactField[])
- addresses: すべての住所を含む配列を表します (ContactAddresses[])
- ims: すべてのIMアドレスを含む配列を表します (ContactField[])
- organizations: すべての組織名を含む配列を表します (ContactOrganization[])
- revision: 最後に編集された日付を表します (DOMString)
- birthday: 誕生日を表します (Date)
- gender: 性別を表します (DOMString)
- note: メモを表します (DOMString)
- photos: すべての写真を含む配列を表します (ContactField[])
- categories: ユーザー定義のカテゴリを表します (ContactField[])
- urls: 関連URLを含む配列を表します (ContactField[])
- timezone: タイムゾーン情報を表します (DOMString)
メソッド
- clone: オブジェクトのディープコピーを行い、新しい Contact オブジェクトを作成します。 id プロパティは null に設定されます
-
remove: オブジェクトを連絡先データベースから削除します。削除が失敗した場合はコールバック関数が呼び出され
ContactError
オブジェクトが返されます。 - save: 新しい連絡先を連絡先データベースに保存します。 id が既に登録されている場合は連絡先データベースを上書きします。
詳細
Contact
オブジェクトはユーザーの連絡先を格納します。連絡先はデバイスの連絡先データベースから作成したり、保存することが可能です。
contact.find
関数を実行することで、連絡先データベースからデータを検索し、取得することもできます。
注意: プラットフォームによっては、いくつかのフィールドがサポートされていない場合があります。プラットフォームごとの注意点に詳細を記載しています。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
保存する例
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 に関する注意点
- displayName: このプロパティはサポートされていません。ContactName が指定されていない場合以外はnullを返します。ContactName が指定されていない場合、合成された名前、nickname、または "" がdiplayNameとしてそれぞれ返されます。
- revision: このプロパティは読み取り専用です。このプロパティはJavaScriptのDateオブジェクトとして返されます。
- birthday: JavaScriptのDateオブジェクトとして指定する必要があります。
- gender: このプロパティはサポートされていません。常にnullを返します。
- photos: 返された写真はアプリの一時ディレクトリに保存され、写真へのFileURLが返されます。一時ディレクトリはアプリケーションを終了する際に削除されます。
- categories: このプロパティはサポートされていません。常にnullを返します。
ContactAddress
Contact
オブジェクトの住所プロパティを表します。
プロパティ
- formatted: 住所全体を表します (DOMString)
- streetAddress: 番地を表します (DOMString)
- locality: 都市名を表します (DOMString)
- region: 地域名を表します (DOMString)
- postalCode: 郵便番号を表します (DOMString)
- country: 国名を表します (DOMString)
詳細
ContactAddress
オブジェクトは連絡先の住所に関するプロパティを表します。
Contact
オブジェクトは、複数の住所が格納された ContactAddress[]
配列を保持しています。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
// すべての連絡先の住所情報を取得し、表示します
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 に関する注意点
- formatted: このプロパティは部分的にサポートされており、BlackBerryのアドレスフィールドの連結を返します。
- streetAddress: このプロパティはサポートされておりBlackBerryのaddress1とaddress2の連結を返します。
- locality: このプロパティはサポートされており、BlackBerryのcityアドレスフィールドに保存されます。
- region: このプロパティはサポートされており、BlackberryのStateProvinceアドレスフィールドに保存されます。
- postalCode:このプロパティはサポートされており、BlackberryのzipPostalアドレスフィールドに保存されます。
- country: このプロパティはBlackBerry WebWorksによりサポートされています。
iOS に関する注意点
- formatted: このプロパティはサポートされていません。
ContactField
Contact
オブジェクトで使用される汎用フィールドに用いられます。
ContactField
オブジェクトとして格納されるデータとしては、メールアドレスや電話番号などが挙げられます。
プロパティ
- type: フィールド名を表します (例: home) (DOMString)
- value: フィールド値を表します (例: 電話番号、メールアドレス) (DOMString)
- pref: データが推奨値を格納していた場合に true がセットされます (boolean)
詳細
ContactField
オブジェクトは、連絡先の各フィールドを汎用的に格納するためのコンポーネントです。
各 ContactField
オブジェクトは、value、type、pref の3つのプロパティを持っています。
Contact
オブジェクトは電話番号やメールアドレスなどといった複数のプロパティを ContactFIeld[]
配列に保存しています。
多くの場合 ContactField
オブジェクトの type 属性に定義済みの値は存在しません。
たとえば電話番号について type 属性の値としてhome、work、mobile、iPhoneなど、デバイスのプラットフォームに応じて異なった値が格納されます。
ただし photos フィールドに限り type 属性には画像フォーマットが格納されます。 この値が 'url' の場合 value 属性には画像のURLがセットされます。 また、'base64' の場合はBase64形式でエンコードされた画像を表す文字列が格納されます。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
// 新しい連絡先を作成
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 に関する注意点
- pref: このプロパティーはAndroidではサポートされていません。常にfalseを返します。
BlackBerry WebWorks に関する注意点
- type: このプロパティーは部分的にサポートされています。電話番号に使われます。
- value: このプロパティーはサポートされています。
- pref: このプロパティーはサポートされていません。常にfalseを返します。
iOS に関する注意点
- pref: このプロパティーはiOSではサポートされておらず、常にfalseを返します。
ContactFindOptions
contacts.find
関数の検索結果を絞るために使用するプロパティを表します。
プロパティ
- filter: 連絡先情報の検索文字列を表します (DOMString) (デフォルト: "")
- multiple: 複数の連絡先を返すかどうかを指定します (Boolean) (デフォルト: true)
- updatedSince: 指定した日にち以降に更新された連絡先のみを返します (Date) (デフォルト: "")
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
// 呼び出し成功
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 に関する注意点
- updatedSince: このプロパティはサポートされていません。
BlackBerry WebWorks に関する注意点
- updatedSince: このプロパティはサポートされていません。
ContactName
Contact
オブジェクトのnameプロパティを格納します。
プロパティ
- formatted: 連絡先のフルネームを表します (DOMString)
- familyName: 連絡先の名字を表します (DOMString)
- givenName: 連絡先の名前を表します (DOMString)
- middleName: 連絡先のミドルネームを表します (DOMString)
- honorificPrefix: 連絡先の接頭敬称を表します (例:Mr. Dr.) (DOMString)
- honorificSuffix: 連絡先の接尾敬称を表します (例:Esq.)(DOMString)
詳細
ContactName
オブジェクトは連絡先の name プロパティの情報を格納します。
サポートされているプラットフォーム
- Android 2.X
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
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 に関する注意点
- formatted: このプロパティは部分的にサポートされています。取得時は、honorifixPrefix、givenName、middleName、familyName、honorificSuffixを連結したものを返しますが、保存は行われません。
BlackBerry WebWorks に関する注意点
- formatted: このプロパティは部分的にサポートされています。 firstName と lastName フィールドの連結を返します。
- familyName: このプロパティはBlackBerry WebWorksでサポートされており、BlackBerry lastName フィールドに保存されます。
- givenName: このプロパティはBlackBerry WebWorksでサポートされており、BlackBerry firstName フィールドに保存されます。
- middleName: このプロパティはBlackBerry WebWorksではサポートされておらず、常にfalseを返します。
- honorificPrefix: このプロパティはBlackBerry WebWorksではサポートされておらず、常にfalseを返します。
- honorificSuffix: このプロパティはBlackBerry WebWorksではサポートされておらず、常にfalseを返します。
iOS に関する注意点
- formatted: このプロパティはiOSで部分的にサポートされています。複合名を返しますが、保存は行われません。
ContactOrganization
Contact
オブジェクトの組織情報を格納します。
プロパティ
- name: 組織名を表します (DOMString)
- department: 部署名を表します (DOMString)
- title: 役職名を表します (DOMString)
詳細
ContactOrganization
オブジェクトは連絡先の組織情報を表します。
Contact
オブジェクトは複数の ContactOrganization
オブジェクトを配列の中に格納します。
サポートされているプラットフォーム
- Android
- BlackBerry WebWorks (OS 5.0 以上)
- iOS
使用例
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 に関する注意点
- title: このプロパティはAndroid 1.Xではサポートされおらず、常にnullを返します。
BlackBerry WebWorks に関する注意点
- name: このプロパティはBlackBerryで部分的にサポートおり、組織名は BlackBerryの company フィールドに保存されます。
- department: このプロパティはBlackBerry WebWorksではサポートされていません。常にnullを返します。
- title: このプロパティはBlackBerryで部分的にサポートされており、役職名はBlackBerryの jobTitle フィールドに保存されます。
iOS に関する注意点
- name: このプロパティはiOSで部分的にサポートされており、組織名はiOSの kABPersonOrganizationProperty フィールドに保存されます。
- department: このプロパティはiOSで部分的にサポートされており、部署名はiOSの kABPersonDepartmentProperty フィールドに保存されます。
- title: このプロパティはiOSで部分的にサポートされており、役職名はiOSの kABPersonJobTitleProperty フィールドに保存されます。
ContactError
エラーが発生した時に contactError
コールバック関数に渡されるオブジェクトです。
パラメータ
- code: 下記のいずれかのエラーコードが格納されます。
コンタクト
ContactError.UNKNOWN_ERROR
ContactError.INVALID_ARGUMENT_ERROR
ContactError.NOT_FOUND_ERROR
ContactError.TIMEOUT_ERROR
ContactError.PENDING_OPERATION_ERROR
ContactError.IO_ERROR
ContactError.NOT_SUPPORTED_ERROR
ContactError.PERMISSION_DENIED_ERROR
詳細
エラーが発生した際に 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: ""
};
オプション
- filter: 絞込検索用の文字列を指定します (DOMString) (Default: "")
- multiple: 検索時に複数の連絡先情報を返すかどうかを指定します (Boolean) (デフォルト: true)
- updatedSince: 指定した日付以降に更新された連絡先のみを返します (Date) (デフォルト: "")
Android に関する注意点
- updatedSince: このプロパティは現在Androidではサポートされていません。
BlackBerry WebWorks に関する注意点
- updatedSince: このプロパティは現在BlackBerry WebWorksではサポートされていません。