PhoneGap API中文幫助文檔——Contacts(通訊錄) – iPhone手機開發技術文章 iPhone軟體開發教學課程

contacts對象提供對設備通訊錄數據庫的訪問。
方法:
contacts.create
contacts.find

參數:
contactFields
contactSuccess
contactError
contactFindOptions

對象:
Contact
ContactName
ContactField
ContactAddress
ContactOrganization
ContactFindOptions
ContactError

contacts.create

——————————————————————————–
返回一個新的Contact對象。
    var contact = navigator.service.contacts.create(properties); 
復制代碼說明:
contacts.create是用於創建並返回一個新Contact對象的同步函數。
該方法不會將新創建的Contact對象持久化到設備的通訊錄數據庫。可通過調用Contact.save方法將新建的Contact對象持久化到設備。
支持的平臺:
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例:
    <span style="font-size:13px;">var myContact = navigator.service.contacts.create({"displayName": "Test User"});</span> 
復制代碼完整的范例:
    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 等待加載PhoneGap 

        document.addEventListener("deviceready", onDeviceReady, false); 

     

        // PhoneGap加載完畢 

        function onDeviceReady() { 

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

            myContact.gender = "male"; 

            console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender"); 

        }  

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Create Contact</p> 

    </body> 

    </html></span> 
復制代碼
contacts.find
查詢設備通訊錄數據庫,並返回包含指定字段的一個或多個Contact對象。
navigator.service.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions); 
復制代碼
說明:
contacts.find是一個查詢設備通訊錄數據庫並返回Contact對象數組的同步函數。返回的對象會被傳遞給contactSuccess回調函數的contactSuccess參數。
用戶必須在contactFields參數中指定聯系人的字段作為搜索限定符。系統傳遞給contactSuccess回調函數的Contact對象屬性隻會包含在contactFields參數中定義的字段。如果定義0長度的contactFields參數會導致返回的Contact對象隻填充瞭id屬性。
contactFindOptions.filter字符串可以用來作為查詢通訊錄數據庫時的搜索過濾器。如果設定瞭該參數,系統會對通訊錄數據庫中所有聯系人按照contactFields參數中指定的每個字段進行不區分大小寫的部分值匹配。任何指定的字段符合過濾器所要求的內容的聯系人數據都會被返回。

屬性:

contactFields:Contact字段,用作搜索限定符。在返回的Contact對象中隻有這些字段有值。(DOMString[]類型)[必填]
contactSuccess:通訊錄獲取成功時調用的回調函數,將從通訊錄數據庫獲取的聯系人作為參數。[必填]
contactError:錯誤回調函數,當發生錯誤的時候被調用。[可選]
contactFindOptions:用於過濾通訊錄的搜索選項。[可選]

支持的平臺:
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

 

簡單的范例:
<span style="font-size:13px;">function onSuccess(contacts) { 

    alert('Found ' + contacts.length + ' contacts.'); 

 

function onError() { 

    alert('onError!'); 

 

// 從所有聯系人中查找任意名字字段中包含“Bob”的聯系人 

var options = new ContactFindOptions(); 

options.filter="Bob"; 

var fields = ["displayName", "name"]; 

navigator.service.contacts.find(fields, onSuccess, onError, options);</span><span style="font-family:Tahoma;margin-top:10px; margin-bottom:15px; font-size:20px; font-weight:bold"> 
復制代碼完整的范例:
    <!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 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("Display Name = " + contacts[i].displayName); 

            } 

        } 

     

        // onError: 獲得聯系人失敗 

        function onError() { 

            alert('onError!'); 

        } 

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html> 
復制代碼
Contact
——————————————————————————–
包含描述聯系人的屬性,比如用戶的個人或者商務聯系方式。

屬性:
id:全局唯一標識符。(DOMString類型)
displayname:聯系人顯示名稱,適合向最終用戶展示的聯系人名稱。(DOMString類型)
name:聯系人姓名所有部分的對象。(CantactName類型)
nickname:昵稱,對聯系人的非正式稱呼。(DOMString類型)
phoneNumbers:聯系人所有聯系電話的數組。(ContactField[]類型)
emails:聯系人所有email地址的數組。(ContactField[]類型)
addrsses:聯系人所有聯系地址的數組。(ContactAddresses[]類型)
ims:聯系人所有IM地址的數組。(ContactField[]類型)
organizations:聯系人所屬所有組織的數組。(ContactOrganization[]類型)
birthday:聯系人的生日。(日期類型)
note:聯系人的註釋信息。(DOMString類型)
photos:聯系人所有照片的數組.(ContactField[]類型)
categories:聯系人所屬的所有用戶自定義類別的數組。(ContactField[]類型)
urls:與聯系人相關網頁的數組。(ContactField[]類型)

方法:
clone:返回一個新的Contact對象,它是調用對象的深度拷貝,其id屬性被設為null。
remove:從通訊錄數據庫中刪除聯系人。當刪除不成功的時候,觸發以ContactError對象為參數的錯誤處理回調函數。
save:將一個新聯系人存儲到通訊錄數據庫,如果通訊錄數據庫中已經包含與其ID相同的記錄,則更新該已有記錄。

詳述:
Contact對象代表一個用戶聯系人。Contacts可以在設備通訊錄數據庫中被創建,存儲或者刪除,同樣也可以使用 contacts.find方法從數據庫中進行檢索。
備註:並不是所有的設備平臺都支持以上列出的所有聯系人字段。請通過查看每個平臺的特異情況描述部分,瞭解每個平臺分別支持哪些字段。

支持的平臺:
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

Save 簡單的范例:

    <span style="font-size:13px;">function onSuccess(contacts) { 

        alert("Save Success"); 

        } 

     

    function onError(contactError) { 

        alert("Error = " + 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);</span> 
復制代碼Clone 簡單的范例:
<span style="font-size:13px;">// 克隆聯系人對象 

var clone = contact.clone(); 

clone.name.givenName = "John"; 

console.log("Original contact name = " + contact.name.givenName); 

console.log("Cloned contact name = " + clone.name.givenName);</span>
復制代碼Remove 簡單的范例:
function onSuccess() { 

    alert("Removal Success"); 

function onError(contactError) { 

    alert("Error = " + contactError.code); 

// 從設備上刪除該聯系人 

contact.remove(onSuccess,onError);
復制代碼完整的范例:
    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 等待加載PhoneGap 

        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("Original contact name = " + contact.name.givenName); 

            console.log("Cloned contact name = " + clone.name.givenName); 

         

            // 刪除聯系人 

            contact.remove(onRemoveSuccess,onRemoveError); 

        } 

         

            // onSaveSuccess: 返回當前保存成功的聯系人數據的快照 

        function onSaveSuccess(contacts) { 

            alert("Save Success"); 

        } 

         

        // onSaveError: 獲取聯系人數據失敗 

        function onSaveError(contactError) { 

            alert("Error = " + contactError.code); 

        } 

         

        // onRemoveSuccess: 返回當前刪除成功的聯系人數據的快照 

        function onRemoveSuccess(contacts) { 

            alert("Removal Success"); 

        } 

         

        // onRemoveError: 獲取聯系人數據失敗 

        function onRemoveError(contactError) { 

            alert("Error = " + contactError.code); 

        } 

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html></span> 
復制代碼
Android 2.X的特異情況:
categories:Android2.X設備上不支持該屬性,返回值總是null。

Android 1.X的特異情況:
name:Android1.x設備上不支持該屬性,返回值總是null。
nickname:Android1.x設備上不支持該屬性,返回值總是null。
birthday: Android1.x設備上不支持該屬性,返回值總是null。
photos:Android1.x設備上不支持該屬性,返回值總是null。
categories:Android1.x設備上不支持該屬性,返回值總是null。
urls:Android1.x設備上不支持該屬性,返回值總是null。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況:
id:支持,系統在存儲聯系人記錄時自動分配。
displayname:支持,存儲到BlackBerry的user1字段。
nickname:不支持該屬性,返回值總是null。
phoneNumber:部分支持,類型為“home”的電話號碼將被存儲到BlackBerry的homePhone1和homePhone2字段;類型為“work”將被存儲到workPhone1和workPhone2字段;類型為“mobile”將被存儲到mobilePhone;類型為“fax”將被存儲到faxPhone字段;類型為“pager”將被存儲到pagerPhone;如果電話號碼不屬於以上類型則被存儲到otherPhone字段。
emails:部分支持,前三個郵件地址將被分別存儲到BlackBerry的email1、email2和email3這三個字段。
addresses:部分支持,第一和第二個地址將被分別存儲到BlackBerry的homeAddress以及workAddress字段。
ims: 不支持該屬性,返回值總是null。
organizations:部分支持,第一個組織的名稱和職務將被分別存儲到BlackBerry的company和title字段。
photos:部分支持,隻支持一個縮略圖大小的照片。要設置一個聯系人照片的話,可以通過傳遞一個Base64編碼的圖片或一個指向圖片的URL,該圖片在存儲到聯系人數據庫之前會被縮小。聯系人照片會以Base64編碼形式的圖片返回。
categories:部分支持,隻支持“Business”和“Personal”這兩個類別。
urls:部分支持,第一個url將被存儲到BlackBerry的webpage字段。

iOS的特異情況:
displayName:iOS不支持該屬性。除非沒有給聯系人指定ContactName,否則該字段返回值總是null。如果沒有指定ContactName,系統會根據有無設定值的情況依次返回composite name,nickename或空字符串。
birthday:對於輸入而言,必須為其提供一個JavaScript日期對象。同樣其返回值也是JavaScript日期對象。
photos:傳回的照片存儲在應用程序的臨時目錄,同時返回指向該照片的文件URL。臨時目錄在應用程序退出後被刪除。
categories:目前不支持該屬性,返回值總是null。

ContactAddress
——————————————————————————–

包含Contact對象的地址屬性。

屬性:
pref:如果該ContactAddress包含用戶的首選值,則設置為true。(佈爾類型)
type:用來標示該地址對應的類型的字符串(例如:“home”)。(DOMString類型)
formatted:完整的地址顯示格式。(DOMString格式)
streeAddress:完整的街道地址。(DOMString格式)
locality:城市或地區。(DOMString格式)
region:州或省份。(DOMString格式)
postalCode:郵政編碼。(DOMString格式)
country:國傢名稱。(DOMString格式)

詳述:
ContactAddress對象存儲一個聯系人的單個地址。一個Contact對象可以擁有一個或多個地址,這些地址存儲在一個ContactAddress[]數組中。

支持的平臺:
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例:
    <span style="font-size:13px;">// 顯示所有聯系人的地址信息 

    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!'); 

    } 

     

    // 從全部聯系人中查找 

    var options = new ContactFindOptions(); 

    options.filter="";  

    var filter = ["displayName","addresses"]; 

    navigator.contacts.find(filter, onSuccess, onError, options);</span> 
復制代碼完整的范例:
    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 等待加載PhoneGap 

        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("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); 

                } 

            } 

        } 

         

        // onError: 獲取聯系人結果集失敗 

        function onError() { 

            alert('onError!'); 

        } 

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html></span> 
復制代碼
Android 2.X 的特異情況
pref:Android2.X設備上不支持該屬性,返回值總是false。

Android 1.X 的特異情況:
pref:Android1.X設備上不支持該屬性,返回值總是false。
type:Android1.X設備上不支持該屬性,返回值總是null。
streetAddress:Android1.X設備上不支持該屬性,返回值總是null。
locality:Android1.X設備上不支持該屬性,返回值總是null。
region:Android1.X設備上不支持該屬性,返回值總是null。
postalCode:Android1.X設備上不支持該屬性,返回值總是null。
country:Android1.X設備上不支持該屬性,返回值總是null。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況:
pref:BlackBerry設備上不支持該屬性,返回值總是false。
type:部分支持,對於一個聯系人對象隻能分別存儲一個“Work”和一個“Home”類型的地址。
formatted:部分支持,將返回所有BlackBerry 地址字段的串聯。
streetAddress:支持,將返回BlackBerry address1和address2兩個地址字段的串聯。
locality:支持,存儲到BlackBerry city字段。
region:支持,存儲到BlackBerry stateProvince字段。
postalCode:支持,存儲到BlackBerry zipPostal字段。
country:支持。

iOS的特異情況:
pref:iOS設備上不支持該屬性,返回值總是false。
formatted:目前不支持。

ContactField

Contact對象中支持的通用字段類型,存儲為ContactField對象的屬性包括:email addresses、phone numbers和urls等。

屬性:
type:說明當前字段類型的字符串(例如:“home”)。(DOMString類型)
value:字段的值(例如:電話號碼或郵件地址)。(DOMString類型)
pref:如果當前ContactField包含用戶的首選項,則設置為true。(佈爾類型)

詳述:
ContactField對象是一個可重用的組件,用於支持通用方式的聯系人字段。每個ContactField對象都包含一個值屬性、一個類型屬性和一個首選項屬性。一個Contact對象將多個屬性分別存儲到多個ContactField[]數組中,例如電話號碼與郵件地址等。
在大多數情況下,ContactField對象中的type屬性並沒有事先確定值。例如,一個電話號碼的type屬性值可以是:“home”、“work”、“mobile”、“iPhone”或其他相應特定設備平臺的聯系人數據庫所支持的值。然而對於Contact對象的photos字段,PhoneGap使用type字段來表示返回的圖像格式。如果value屬性包含的是一個指向照片圖像的URL,PhoneGap對於type會返回“url”;如果value屬性包含的是圖像的Base64編碼字符串,PhoneGap對於type會返回“base64”。

支持的平臺:
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例:
    <span style="font-size:13px;">// 建立一個新的聯系人記錄 

    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();</span> 
復制代碼完整的范例:
    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 等待加載PhoneGap 

        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++) { 

            // 顯示電話號碼 

                for (var j=0; j< contacts[i].phoneNumbers.length; j++) { 

                    alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" + 

                        "Value: "  + contacts[i].phoneNumbers[j].value + "\n" + 

                        "Preferred: "  + contacts[i].phoneNumbers[j].pref); 

                } 

            } 

        } 

         

        // onError: 獲取聯系人結果集失敗 

        function onError() { 

            alert('onError!'); 

        } 

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html></span> 
復制代碼
Android 的特異情況:
pref:Android設備上不支持該屬性,返回值總是false。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況:
type:部分支持,用於電話號碼。
value:支持。
pref:不支持該屬性,返回值總是false。

iOS的特異情況:
pref:iOS設備上不支持該屬性,返回值總是false。

ContactFindOptions

包含用於contacts.find操作對所有聯系人進行過濾的屬性。

屬性:
filter:用於查找聯系人的搜索字符串。(DOMString類型) (默認值為空字符串)
multiple:決定查收操作是否可以返回多條聯系人記錄。(佈爾類型) (默認值為false)

支持的平臺:
Android
BlackBerry WebWorks (OS 5.0或更高版本)
iOS

簡單的范例:

    <span style="font-size:13px;">// 成功後的回調函數 

    function onSuccess(contacts) { 

        for (var i=0; i< ;contacts.length; i++) { 

            alert(contacts[i].displayName); 

        } 

    } 

     

    // 出錯後的回調函數 

    function onError() { 

        alert('onError!'); 

    } 

     

    // 指定聯系人搜索條件 

    var options = new ContactFindOptions(); 

    options.filter="";          // 空搜索字符串將返回所有聯系人                     

    options.multiple=true;      // 可返回多條記錄 

    filter = ["displayName"];   // 僅返回contact.displayName字段 

     

    // 查找聯系人 

    navigator.service.contacts.find(filter, onSuccess, onError, options);</span> 
復制代碼完整的范例:

    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 等待加載PhoneGap 

        document.addEventListener("deviceready", onDeviceReady, false); 

         

        // PhoneGap加載完畢 

        function onDeviceReady() { 

         

            // 指定聯系人搜索條件 

            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('onError!'); 

        } 

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html></span> 
復制代碼
ContactName
包含Contact對象的名稱屬性。
屬性:
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

簡單的范例:

    <span style="font-size:13px;">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() { 

        alert('onError!'); 

    } 

     

    var options = new ContactFindOptions(); 

    options.filter=""; 

    filter = ["displayName","name"]; 

     

    navigator.service.contacts.find(filter, onSuccess, onError, options);</span> 
復制代碼
完整的范例:

    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head> 

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

        // 等待加載PhoneGap 

        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" + 

                    "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.honorificPrefix); 

            } 

        } 

         

        // onError: 獲取聯系人結果集失敗 

        function onError() { 

            alert('onError!'); 

        } 

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html></span> 
復制代碼
Android 的特異情況:
formatted:部分支持,將返回honorificPrefix、givenName、middleName、familyName和honorificSuffix的串聯結果,但不會單獨存儲。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況:
formatted:部分支持,將返回BlackBerry firstName和lastName兩個字段的串聯結果。
familyName:支持,存放到BlackBerry 的lastName字段。
givenName:支持,存儲到BlackBerry 的firstName字段。
middleName:不支持該屬性,返回值總是null。
honorificPrefix:不支持該屬性,返回值總是null。
honorificSuffix:不支持該屬性,返回值總是null。

iOS的特異情況:
formatted:部分支持,將返回iOS的Composite Name,但不會單獨存儲。

ContactOrganization

——————————————————————————–

包含Contact對象的所屬組織屬性。

屬性:

 

    pref:如果該ContactOrganization包含用戶的首選值,則設置為true。(佈爾類型)

    type:用來標示該所屬組織對應的類型的字符串(例如:“home”)。(DOMString類型)

    name:組織的名稱。(DOMString類型)

    department:聯系人工作的部門。(DOMString類型)

    title:聯系人在所屬組織內的職務。(DOMString類型)

 

詳述:

ContactOrganization對象存儲聯系人的所屬組織屬性,Contact對象通過一個數組存儲一個或多個ContactOrganization對象。

支持的平臺:

 

    Android

    BlackBerry WebWorks (OS 5.0或更高版本)

    iOS

 

簡單的范例:
復制代碼    <span style="font-size:13px;">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() { 

        alert('onError!'); 

    } 

     

    var options = new ContactFindOptions(); 

    options.filter=""; 

    filter = ["displayName","organizations"]; 

    navigator.service.contacts.find(filter, onSuccess, onError, options);</span> 
復制代碼
完整的范例:

    <span style="font-size:13px;"><!DOCTYPE html> 

    <html> 

    <head>     

    <title>Contact Example</title> 

     

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

    <script type="text/javascript" charset="utf-8"> 

     

    // 等待加載PhoneGap 

    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("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); 

            } 

        } 

    } 

     

    // onError:獲取聯系人失敗 

    function onError() { 

        alert('onError!'); 

    }    

     

    </script> 

    </head> 

    <body> 

     <h1>Example</h1> 

     <p>Find Contact</p> 

    </body> 

    </html></span> 
復制代碼
Android 2.X 的特異情況:
pref:Android2.X設備上不支持該屬性,返回值總是false。

Android 1.X 的特異情況:
pref:Android1.X設備上不支持該屬性,返回值總是false。
type:Android1.X設備上不支持該屬性,返回值總是null。
title:Android1.X設備上不支持該屬性,返回值總是null。

BlackBerry WebWorks (OS 5.0或更高版本)的特異情況:
pref:BlackBerry設備上不支持該屬性,返回值總是false。
type:BlackBerry設備上不支持該屬性,返回值總是null。
name:部分支持,第一個組織名稱將被存儲到BlackBerry 的company字段。
department:不支持該屬性,返回值總是null。
title:部分支持,第一個組織職務將被存儲到BlackBerry 的jobTitle字段。

iOS的特異情況:
pref:iOS設備上不支持該屬性,返回值總是false。
type:iOS設備上不支持該屬性,返回值總是null。
name:部分支持,第一個組織名稱將被存放到iOS的kABPersonOrganizationProperty字段。
department:部分支持,第一個部門名字將被存放到iOS的kABPersonDepartmentProperty字段。
title:部分支持,第一個組織職務將被存放到iOS的kABPersonJobTitleProperty字段。

ContactError

——————————————————————————–

當有錯誤發生時,一個ContactError對象會傳遞給contactError回調函數。

屬性:
code:一個在下面常量中定義好的錯誤代碼。

常量:
ContactError.UNKNOWN_ERROR:未知錯誤類型
ContactError.INVALID_ARGUMENT_ERROR:無效參數錯誤類型
ContactError.TIMEOUT_ERROR:請求超時錯誤類型
ContactError.PENDING_OPERATION_ERROR:掛起操作錯誤類型
ContactError.IO_ERROR:輸入輸出錯誤類型
ContactError.NOT_SUPPORTED_ERROR:平臺不支持錯誤類型
ContactError.PERMISSION_DENIED_ERROR:權限被拒絕錯誤類型

說明:
當有錯誤發生時,ContactError對象會通過contactError回調函數返回給用戶。

contactSuccess

——————————————————————————–
contacts.find操作成功時調用的回調函數,同時返回查找到的Contact數組。

簡單的范例:
    <span style="font-size:13px;">function(contacts) {  

        // 後續操作 

    }</span> 
復制代碼參數:
contacts:查找操作返回的聯系人數組。(Contact[]類型)

范例:     <span style="font-size:13px;">function contactSuccess(contacts) {  

        for (var i=0; i< contacts.length; i++) {  

            console.log(“Display Name = ” + contacts[i].displayName;  

        } 

    }</span> 
復制代碼contactError
——————————————————————————–

操作聯系人出錯時的回調函數。

    function(error) {  

        // 錯誤處理  

    } 
復制代碼contactFields

——————————————————————————–

contacts.find方法的必填參數,該參數定義瞭查找操作返回的Contact對象中應該包含哪些字段。
["name", "phoneNumbers", "emails"] 
復制代碼contactFindOptions
——————————————————————————–
contats.find方法的可選參數,通過該參數從通訊錄數據庫中篩選聯系人。

    {   

        filter: "",  

        multiple: true 

    } 
復制代碼選項:
filter:用於查找聯系人的搜索字符串。(DOMString類型) (默認值為空字符串)
multiple:決定查找操作是否可以返回多條聯系人記錄。(佈爾類型) (默認值為false)

 作者:LuoXianXion
 

發佈留言