連絡人

連絡人

contacts物件提供對設備的連絡人資料庫的訪問。

重要的隱私注：連絡人資料的收集和使用提出了重要的隱私問題。 您的應用程式的隱私權原則應該討論如何應用程式使用的連絡人資料和它是否被共用與任何其他方。 聯繫資訊被視為敏感，因為它揭示了人與人通信的人們。 因此，除了您的應用程式的隱私權原則，您應強烈考慮提供在您的應用程式訪問或使用連絡人資料 （如果設備作業系統不會這樣做已經） 之前的時間只是通知。 該通知應提供相同的資訊上文指出的並獲取該使用者的許可權 （例如，通過為確定並不感謝提出的選擇）。 請注意有些應用程式市場可能需要您的應用程式提供只是時間的通知，並從訪問連絡人資料之前使用者獲得的許可權。 周圍的連絡人資料將有助於避免使用者混淆使用感知的和濫用的連絡人資料的清晰和易於理解的使用者體驗。 有關詳細資訊，請參閱隱私指南。

方法

參數

物件

訪問功能

從 3.0 版，科爾多瓦作為外掛程式實現了設備級 Api。 使用 CLI 的 plugin 命令，描述在命令列介面，可以添加或刪除一個專案，為此功能：

    $ cordova plugin add org.apache.cordova.contacts
    $ cordova plugin ls
    [ 'org.apache.cordova.contacts' ]
    $ cordova plugin rm org.apache.cordova.contacts

這些命令適用于所有有針對性的平臺，但修改如下所述的特定于平臺的配置設置：

一些平臺可能支援此功能，而無需任何特殊的配置。請參見在概述部分中的平臺支援。

contacts.create

返回一個新的連絡人物件。

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

說明

contacts.create方法是同步的並返回一個新的 Contact 物件。

此方法不會保留連絡人物件在設備的連絡人資料庫中，您需要為其調用 Contact.save 方法。

支援的平臺

快速的示例

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

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        var myContact = navigator.contacts.create({"displayName": "Test User"});
        myContact.note = "This contact has a note.";
        console.log("The contact, " + myContact.displayName + ", note: " + myContact.note);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Create Contact</p>
  </body>
</html>

contacts.find

查詢設備連絡人資料庫，並返回一個或多個 Contact 物件，每個包含指定的欄位。

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

說明

contacts.find方法以非同步方式，執行設備的連絡人資料庫查詢並返回一個陣列的 Contact 物件。 所得到的物件傳遞給 contactSuccess contactSuccess參數所指定的回呼函數。

ContactFields參數指定要搜索的限定詞，作為使用的欄位，只有那些結果傳遞給contactSuccess回呼函數。 零長度contactFields參數是不正確結果在 ContactError.INVALID_ARGUMENT_ERROR 。 ContactFields值為 "*" 返回所有連絡人欄位。

ContactFindOptions.filter字串查詢連絡人資料庫時，可以用作搜索篩選器。 如果提供，不區分大小寫，部分值匹配應用於在contactFields參數中指定的每個欄位。 如果有任何指定的欄位的匹配，則返回該連絡人。

參數

支援的平臺

快速的示例

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;
var fields       = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

完整的示例

<!DOCTYPE html>
<html>
    <head>
        <title>Contact Example</title>
        <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
        <script type="text/javascript" charset="utf-8">

            // Wait for device API libraries to load
            document.addEventListener("deviceready", onDeviceReady, false);

            // device APIs are available

            function onDeviceReady() {
                // find all contacts with 'Bob' in any name field
                var options = new ContactFindOptions();
                options.filter = "Bob";
                var fields = ["displayName", "name"];
                navigator.contacts.find(fields, onSuccess, onError, options);
            }

            // onSuccess: Get a snapshot of the current contacts

            function onSuccess(contacts) {
                for (var i = 0; i < contacts.length; i++) {
                    console.log("Display Name = " + contacts[i].displayName);
                }
            }

            // onError: Failed to get the contacts

            function onError(contactError) {
                alert('onError!');
            }
        </script>
    </head>

    <body>
        <h1>Example</h1>
        <p>Find Contacts</p>
    </body>
</html>

連絡人

包含描述聯繫，如使用者的個人或業務連絡人的屬性。

屬性

方法

詳細資訊

Contact物件表示使用者的連絡人。 可以創建、 存儲，或從設備的連絡人資料庫中刪除的連絡人。 連絡人可以還 (單獨或批量） 從資料庫中檢索通過調用 contacts.find 方法。

注：不是所有的上面列出的連絡人欄位平臺支援的每個設備。請檢查每個平臺的怪癖節瞭解詳細資訊。

支援的平臺

保存快速示例

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

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        // create
        var contact = navigator.contacts.create();
        contact.displayName = "Plumber";
        contact.nickname = "Plumber";                 // specify both to support all devices
        var name = new ContactName();
        name.givenName = "Jane";
        name.familyName = "Doe";
        contact.name = name;

        // save
        contact.save(onSaveSuccess,onSaveError);

        // clone
        var clone = contact.clone();
        clone.name.givenName = "John";
        console.log("Original contact name = " + contact.name.givenName);
        console.log("Cloned contact name = " + clone.name.givenName);

        // remove
        contact.remove(onRemoveSuccess,onRemoveError);
    }

    // onSaveSuccess: Get a snapshot of the current contacts
    //
    function onSaveSuccess(contact) {
        alert("Save Success");
    }

    // onSaveError: Failed to get the contacts
    //
    function onSaveError(contactError) {
        alert("Error = " + contactError.code);
    }

    // onRemoveSuccess: Get a snapshot of the current contacts
    //
    function onRemoveSuccess(contacts) {
        alert("Removal Success");
    }

    // onRemoveError: Failed to get the contacts
    //
    function onRemoveError(contactError) {
        alert("Error = " + contactError.code);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X 的怪癖

黑莓手機 WebWorks （OS 5.0 和更高） 的怪癖

iOS 的怪癖

Windows Phone 7 和 8 怪癖

ContactAddress

包含位址屬性的 Contact 物件。

屬性

詳細資訊

ContactAddress物件存儲的單一位址的連絡人的屬性。 A Contact 物件可能包括多個位址在 ContactAddress[] 陣列。

支援的平臺

快速的示例

// 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);

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        // find all contacts
        var options = new ContactFindOptions();
        options.filter = "";
        var filter = ["displayName", "addresses"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        // display the address information for all 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: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X 的怪癖

黑莓手機 WebWorks （OS 5.0 和更高） 的怪癖

iOS 的怪癖

ContactField

支援泛型欄位在 Contact 物件。某些屬性存儲作為 ContactField 物件包括電子郵件地址、 電話號碼和 Url。

屬性

詳細資訊

ContactField物件是可重用的元件表示泛指連絡人欄位。 每個 ContactField 物件包含 value ， type ，和 pref 屬性。 A Contact 物件存儲中的幾個屬性 ContactField[] 陣列，如電話號碼和電子郵件地址。

在大多數情況下，沒有任何預先確定的值為 ContactField 物件的type屬性。 例如，電話號碼可以指定類型的家庭、工作、移動、 iPhone或由一個特定的設備平臺聯繫資料庫支援的任何其他值的值。 然而，對於 Contact 的照片欄位，類型欄位指示返回圖像的格式： url的值屬性包含的照片圖像或base64的 URL 時的值包含一個 base64 編碼的圖像字串時。

支援的平臺

快速的示例

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

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //

    function onDeviceReady() {
        // 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();

        // search contacts, returning display name and phone numbers
        var options = new ContactFindOptions();
        options.filter = "";
        filter = ["displayName", "phoneNumbers"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    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("Type: "      + contacts[i].phoneNumbers[j].type  + "\n" +
                      "Value: "     + contacts[i].phoneNumbers[j].value + "\n" +
                      "Preferred: " + contacts[i].phoneNumbers[j].pref);
            }
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 的怪癖

黑莓手機 WebWorks （OS 5.0 和更高） 的怪癖

iOS 的怪癖

ContactFindOptions

包含可用於篩選結果的屬性 contacts.find 操作。

屬性

支援的平臺

快速的示例

// success callback
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert(contacts[i].displayName);
    }
};

// error callback
function onError(contactError) {
    alert('onError!');
};

// specify contact search criteria
var options = new ContactFindOptions();
    options.filter="";        // empty search string returns all contacts
    options.multiple=true;    // return multiple results
    filter = ["displayName"]; // return contact.displayName field

    // find contacts
navigator.contacts.find(filter, onSuccess, onError, options);

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        // specify contact search criteria
        var options = new ContactFindOptions();
        options.filter = "";      // empty search string returns all contacts
        options.multiple = true;  // return multiple results
        filter = ["displayName"]; // return contact.displayName field

        // find contacts
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert(contacts[i].displayName);
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

連絡人姓名

包含有關的不同種類的資訊 Contact 物件的名稱。

屬性

詳細資訊

ContactName物件存儲的連絡人的名稱屬性。

支援的平臺

快速的示例

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

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","name"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    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: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 的怪癖

黑莓手機 WebWorks （OS 5.0 和更高） 的怪癖

iOS 的怪癖

ContactOrganization

包含 Contact 物件的組織屬性。

屬性

詳細資訊

ContactOrganization物件存儲的連絡人的組織屬性。A Contact 物件存儲一個或多個 ContactOrganization 陣列中的物件。

支援的平臺

快速的示例

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

完整的示例

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

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

    // Wait for device API libraries to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // device APIs are available
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","organizations"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    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: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X 的怪癖

黑莓手機 WebWorks （OS 5.0 和更高） 的怪癖

iOS 的怪癖

ContactError

A ContactError 物件傳遞給 contactError 回檔時出現錯誤。

屬性

常量

說明

ContactError物件返回到使用者通過 contactError 回呼函數時出現錯誤。

contactSuccess

提供的成功回呼函數 Contact 陣列產生的 contacts.find 操作。

function(contacts) {
    // Do something
}

參數

示例

function contactSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        console.log("Display Name = " + contacts[i].displayName);
    }
}

contactError

聯繫函數的錯誤回呼函數。

function(error) {
    // Handle the error
}

contactFields

所需參數的 contacts.find 方法，用來指定哪些欄位應包含在 Contact 產生的查找操作的物件。

["名稱"、"手機"、"電子郵件"]

contactFindOptions

可選的參數， contacts.find 方法，用於篩選從連絡人資料庫返回的連絡人。

{篩選器：""、 多個： true，} ；

選項