這個外掛程式定義了一個全域 navigator.contacts 物件，提供對設備連絡人資料庫的訪問。
雖然該物件附加到全球範圍內 導航器，它不可用直到 deviceready 事件之後。
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
console.log(navigator.contacts);
}
警告： 連絡人資料的收集和使用提出了重要的隱私問題。 您的應用程式的隱私權原則應該討論應用程式如何使用連絡人資料和它是否被共用與任何其他締約方。 聯繫資訊被認為是敏感，因為它揭示了的人與人溝通了。 因此，除了隱私權原則的應用程式，您應強烈考慮提供時間只是通知之前應用程式訪問或使用連絡人的資料，如果設備作業系統不已經這樣做了。 該通知應提供相同的資訊，如上所述，以及獲取該使用者的許可權 （例如，通過提出選擇 確定 並 不感謝）。 請注意一些應用程式市場可能需要應用程式提供只是時間的通知，並獲得使用者的許可才能訪問連絡人資料。 周圍的連絡人資料可以説明避免使用者混淆使用和連絡人資料感知的濫用的清楚和容易理解的使用者體驗。 有關詳細資訊，請參閱隱私指南。
這就要求科爾多瓦 5.0 + (當前穩定 v1.0.0)
cordova plugin add cordova-plugin-contacts
舊版本的科爾多瓦仍可以安裝通過棄用id (陳舊 v0.2.16)
cordova plugin add org.apache.cordova.contacts
它也是可以直接通過回購 url 安裝 (不穩定)
cordova plugin add https://github.com/apache/cordova-plugin-contacts.git
在 清單檔 中所述創建 www/manifest.webapp。 添加相關的許可權。 也是需要的 web 應用程式類型更改為“privileged”— — 顯化的文檔。 警告： 所有的特權應用程式強制執行禁止內聯腳本的 內容的安全性原則。 在另一種方式初始化您的應用程式。
"type": "privileged",
"permissions": {
"contacts": {
"access": "readwrite",
"description": "Describe why there is a need for such permission"
}
}
**之前 Windows 10:**從發現和pickContact方法返回任何連絡人是唯讀，因此您的應用程式不能修改它們。 僅在 Windows Phone 8.1 設備上可用的 find 方法。
**Windows 10 及以上:**連絡人可能保存，並將保存到應用程式本地連絡人存儲。 連絡人也會被刪除。
Windows 8 連絡人是唯讀的。 透過科爾多瓦 API 接觸的不是可查詢/搜索，您應通知使用者挑選連絡人作為調用 contacts.pickContact，將會打開 ‘人’ 的應用程式，使用者必須選擇一個連絡人。 返回任何連絡人是唯讀，因此您的應用程式不能修改它們。
navigator.contacts.create 方法是同步的並返回一個新的 Contact 物件。
此方法將不會保留在設備連絡人資料庫中，需要調用 Contact.save 方法的聯繫物件。
var myContact = navigator.contacts.create({"displayName": "Test User"});
navigator.contacts.find 方法以非同步方式，執行設備連絡人資料庫查詢並返回 Contact 物件的陣列。 生成的物件被傳遞到由 contactSuccess 參數指定的 contactSuccess 回呼函數。
contactFields 參數指定的欄位用作搜索限定詞。 長度為零的 contactFields 參數是不正確並導致 ContactError.INVALID_ARGUMENT_ERROR。 contactFields 值為 "*" 搜索所有連絡人欄位。
在連絡人資料庫查詢時，contactFindOptions.filter 字串可以用作搜索篩選器。 如果提供，不區分大小寫，部分值匹配被適用于在 contactFields 參數中指定的每個欄位。 如果存在匹配的 任何 指定的欄位，則返回連絡人。 使用 contactFindOptions.desiredFields 參數來控制哪些連絡人屬性必須回來。
contactFields： ‘連絡人’ 欄位用作搜索限定詞。(DOMString[]) [Required]
contactSuccess： 從資料庫返回的成功回呼函數調用時使用的連絡人物件的陣列。[Required]
contactError： 錯誤回呼函數，當發生錯誤時調用。[可選]
contactFindOptions： 搜索選項來篩選 navigator.contacts。[Optional]
鍵包括：
filter： 用來找到 navigator.contacts 的搜索字串。() DOMString（預設： "")
multiple： 確定是否查找操作返回多個 navigator.contacts。(布林值)（預設值： false)
Contact 物件只有這些欄位的功能值。(DOMString[]) [Optional]function onSuccess(contacts) {
alert('Found ' + contacts.length + ' contacts.');
};
function onError(contactError) {
alert('onError!');
};
// find all contacts with 'Bob' in any name field
var options = new ContactFindOptions();
options.filter = "Bob";
options.multiple = true;
options.desiredFields = [navigator.contacts.fieldType.id];
var fields = [navigator.contacts.fieldType.displayName, navigator.contacts.fieldType.name];
navigator.contacts.find(fields, onSuccess, onError, options);
__contactFields__不受支援，將被忽略。find方法將始終嘗試匹配名稱、 電子郵件地址或電話號碼的連絡人。navigator.contacts.pickContact 方法啟動連絡人選取器來選擇一個連絡人。 將生成的物件傳遞給 contactSuccess 參數所指定的 contactSuccess 回呼函數。
contactSuccess： 成功使用單個連絡人物件調用的回呼函數。[要求]
contactError： 錯誤回呼函數，當發生錯誤時調用。[可選]
navigator.contacts.pickContact(function(contact){
console.log('The following contact has been selected:' + JSON.stringify(contact));
},function(err){
console.log('Error: ' + err);
});
Contact 物件表示使用者的連絡人。 可以創建、 存儲，或從設備的連絡人資料庫中刪除連絡人。 連絡人可以也被 （單獨或批量） 從資料庫中檢索通過調用 navigator.contacts.find 方法。
注： 並不是所有上面列出的連絡人欄位支援的每個設備的平臺。請檢查每個平臺 的怪癖 節瞭解詳細資訊。
id： 一個全域唯一識別碼。() DOMString
displayName： 此連絡人，適合於向最終使用者顯示的名稱。() DOMString
name： 一個物件，包含所有元件的一個人的名字。（連絡人姓名）
nickname： 休閒的位址連絡人名稱。() DOMString
phoneNumbers： 陣列的所有連絡人的電話號碼。(ContactField[])
emails： 所有連絡人的電子郵件地址的陣列。(ContactField[])
addresses： 該連絡人的所有位址的陣列。(ContactAddress[])
ims： 所有連絡人的 IM 位址的陣列。(ContactField[])
organizations： 該連絡人的所有組織的陣列。(ContactOrganization[])
birthday： 連絡人的生日。(Date)
note： 注意有關的聯繫。() DOMString
photos： 陣列的連絡人的照片。(ContactField[])
categories： 陣列與連絡人關聯的所有使用者定義的類別。(ContactField[])
url： 陣列與連絡人關聯的 web 頁。(ContactField[])
clone： 返回一個新的 Contact 物件就是調用物件的深層副本 id 屬性設置為null.
remove： 從設備的連絡人資料庫中刪除連絡人，否則執行錯誤回檔與 ContactError 物件。
save： 將一個新的連絡人保存到設備的連絡人資料庫中，或更新現有的連絡人，如果已存在具有相同 id 的連絡人。
function onSuccess(contact) {
alert("Save Success");
};
function onError(contactError) {
alert("Error = " + contactError.code);
};
// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber"; // specify both to support all devices
// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;
// save to device
contact.save(onSuccess,onError);
// clone the contact object
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);
function onSuccess() {
alert("Removal Success");
};
function onError(contactError) {
alert("Error = " + contactError.code);
};
// remove the contact from the device
contact.remove(onSuccess,onError);
null.categories： 部分支援。返回欄位pref和typenull
ims： 不支援
photos： 不支援
displayName： 上返回的 iOS 不支援 null 除非有沒有 ContactName 指定，在這種情況下它將返回複合名稱，nickname或 "" ，分別。
birthday： 必須輸入 JavaScript 作為 Date 物件，它將返回相同的方式。
photos： 返回到圖像中，存儲在應用程式的臨時目錄中檔的 URL。當應用程式退出時刪除臨時目錄的內容。
categories： 目前不支援此屬性，返回null.
displayName： 當創建一個連絡人，提供的顯示名稱參數不同于顯示名稱的值檢索查找連絡人時。
url： 當創建一個連絡人，使用者可以輸入和保存多個 web 位址，但只有一個是可用的搜索連絡人時。
phoneNumbers：pref選項不受支援。 在type操作中不是支援的find。 只有一個 phoneNumber 允許的每個type.
emails：pref選項不受支援。家庭和個人使用引用同一電子郵件項。只有一項是允許的每個type.
addresses： 僅支援的工作和家庭/個人type。家庭和個人type引用相同的位址條目。只有一項是允許的每個type.
organizations： 唯一一個允許的和不支援的pref、type和department的屬性。
note： 不支援，返回null.
ims： 不受支援，返回null.
birthdays: 不受支援，返回null.
categories： 不受支援，返回null.
remove: 不支援方法
photos： 返回到圖像中，存儲在應用程式的臨時目錄中檔的 URL。
birthdays: 不受支援，返回null.
categories： 不受支援，返回null.
remove: 方法只支援 Windows 10 或以上。
ContactAddress 物件存儲單個位址的連絡人的屬性。 Contact 物件可能包括多個位址 ContactAddress [] 陣列中。
pref： 設置為 true 如果這個 ContactAddress 包含使用者的首選的價值。（Boolean）
type： 一個字串，例如指示哪種類型的欄位，這是home。() DOMString
formatted： 顯示格式的完整位址。() DOMString
streetAddress： 完整的街道位址。() DOMString
locality： 城市或地點。() DOMString
region： 國家或地區。() DOMString
postalCode： 郵遞區號。() DOMString
country： 國家名稱。() DOMString
// display the address information for all contacts
function onSuccess(contacts) {
for (var i = 0; i < contacts.length; i++) {
for (var j = 0; j < contacts[i].addresses.length; j++) {
alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
"Type: " + contacts[i].addresses[j].type + "\n" +
"Formatted: " + contacts[i].addresses[j].formatted + "\n" +
"Street Address: " + contacts[i].addresses[j].streetAddress + "\n" +
"Locality: " + contacts[i].addresses[j].locality + "\n" +
"Region: " + contacts[i].addresses[j].region + "\n" +
"Postal Code: " + contacts[i].addresses[j].postalCode + "\n" +
"Country: " + contacts[i].addresses[j].country);
}
}
};
function onError(contactError) {
alert('onError!');
};
// find all contacts
var options = new ContactFindOptions();
options.filter = "";
var filter = ["displayName", "addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);
false Android 2.X 的設備上。pref： 在返回的黑莓設備上不支援false.
type： 部分支援。只有一個Word和Home類型位址可以存儲每個連絡人。
formatted： 部分支援。返回的串聯的所有黑莓手機位址欄位。
streetAddress： 支援。返回和串聯組成的黑莓address1 address2位址欄位。
locality： 支援。黑莓手機city位址欄位中存儲。
region： 支援。黑莓stateProvince位址欄位中存儲。
postalCode： 支援。黑莓zipPostal位址欄位中存儲。
country： 支援。
pref： 不支援在 iOS 設備上，返回false.
formatted： 目前不支援。
當發生錯誤時，通過 contactError 回呼函數為使用者情況下會返回的 ContactError 物件。
ContactError.UNKNOWN_ERROR (code 0)ContactError.INVALID_ARGUMENT_ERROR (code 1)ContactError.TIMEOUT_ERROR (code 2)ContactError.PENDING_OPERATION_ERROR (code 3)ContactError.IO_ERROR (code 4)ContactError.NOT_SUPPORTED_ERROR (code 5)ContactError.PERMISSION_DENIED_ERROR (code 20)ContactField 物件是可重用的元件代表一般連絡人欄位。 每個 ContactField 物件包含一個 value、 type 和 pref 的屬性。 Contacat 物件將幾個屬性存儲在 ContactField [] 陣列，例如電話號碼和電子郵件地址。
在大多數情況下，沒有預先確定的 ContactField 物件的 type 屬性值。 例如，一個電話號碼可以指定 type 值的 home、 work、 mobile、 iPhone 或由一個特定的設備平臺接觸資料庫系統支援的任何其他值。 然而，為 photos 照片 欄位中，type 欄位指示返回圖像的格式： 當 value 屬性包含一個指向的照片圖像或 base64 URL 時的 value 包含 string base64 編碼的圖像的 url。
type： 一個字串，例如指示哪種類型的欄位，這是home。() DOMString
value： 欄位的值，如電話號碼或電子郵件地址。() DOMString
pref： 設置為 true 如果這個 ContactField 包含使用者的首選的價值。（布林）
// create a new contact
var contact = navigator.contacts.create();
// store contact phone numbers in ContactField[]
var phoneNumbers = [];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;
// save the contact
contact.save();
false.type： 部分支援。使用的電話號碼。
value： 支援。
pref: 不受支援，返回false.
false.false.false.包含不同種類的 Contact 物件名稱有關的資訊。
formatted： 該連絡人的完整名稱。() DOMString
familyName： 連絡人的姓氏。() DOMString
givenName： 連絡人的名字。() DOMString
middleName： 連絡人的中間名。() DOMString
honorificPrefix： 連絡人的首碼 （例如先生或博士） (DOMString)
honorificSuffix： 連絡人的尾碼 （例如某某某）。() DOMString
function onSuccess(contacts) {
for (var i = 0; i < contacts.length; i++) {
alert("Formatted: " + contacts[i].name.formatted + "\n" +
"Family Name: " + contacts[i].name.familyName + "\n" +
"Given Name: " + contacts[i].name.givenName + "\n" +
"Middle Name: " + contacts[i].name.middleName + "\n" +
"Suffix: " + contacts[i].name.honorificSuffix + "\n" +
"Prefix: " + contacts[i].name.honorificSuffix);
}
};
function onError(contactError) {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter = "";
filter = ["displayName", "name"];
navigator.contacts.find(filter, onSuccess, onError, options);
honorificPrefix ， givenName ， middleName ， familyName ，和honorificSuffix.formatted： 部分支援。返回的串聯的黑莓手機firstName和lastName欄位。
familyName： 支援。黑莓lastName欄位中存儲。
givenName： 支援。黑莓firstName欄位中存儲。
middleName: 不受支援，返回null.
honorificPrefix: 不受支援，返回null.
honorificSuffix: 不受支援，返回null.
honorificPrefix ， givenName ， middleName ， familyName ，和honorificSuffix.formatted： 這是唯一名稱屬性，並且是相同的 displayName ，和nickname
familyName： 不支援
givenName： 不支援
middleName： 不支援
honorificPrefix: 不支援
honorificSuffix: 不支援
displayNameContactOrganization 物件存儲連絡人的組織屬性。Contact 物件將一個或多個 ContactOrganization 物件存儲在一個陣列中。
pref： 設置為 true 如果這個 ContactOrganization 包含使用者的首選的價值。（布林）
type： 一個字串，例如指示哪種類型的欄位，這是回家。_(DOMString)
name： 組織的名稱。() DOMString
department： 合同工作為的部門。() DOMString
title： 在組織連絡人的標題。() DOMString
function onSuccess(contacts) {
for (var i = 0; i < contacts.length; i++) {
for (var j = 0; j < contacts[i].organizations.length; j++) {
alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
"Type: " + contacts[i].organizations[j].type + "\n" +
"Name: " + contacts[i].organizations[j].name + "\n" +
"Department: " + contacts[i].organizations[j].department + "\n" +
"Title: " + contacts[i].organizations[j].title);
}
}
};
function onError(contactError) {
alert('onError!');
};
var options = new ContactFindOptions();
options.filter = "";
filter = ["displayName", "organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);
false.pref： 不支援的黑莓手機，返回false.
type： 不支援的黑莓手機，返回null.
name： 部分支援。第一次組織名稱存儲在黑莓company欄位中。
department: 不受支援，返回null.
title： 部分支援。第一次組織標題存儲在欄位中黑莓jobTitle。
pref： 不支援
type： 不支援
department： 不支援
欄位name和title存儲在org和jobTitle.
pref： 不支援在 iOS 設備上，返回false.
type： 不支援在 iOS 設備上，返回null.
name： 部分支援。第一次組織名稱存儲在 iOS kABPersonOrganizationProperty欄位中。
department： 部分支援。第一部門名稱存儲在 iOS kABPersonDepartmentProperty欄位中。
title： 部分支援。第一個標題存儲在 iOS kABPersonJobTitleProperty欄位中。
pref: 不受支援，返回false.
type： 不受支援，返回null.