Skip to content

Latest commit

 

History

History
491 lines (395 loc) · 16.4 KB

04.cordova-plugin-contacts.md

File metadata and controls

491 lines (395 loc) · 16.4 KB
Raw

cordova-plugin-contacts

插件定义了一个全局对象navigator.contacts，提供对通讯录的访问和操作。该对象只有在deviceready事件触发以后生效。

安装

    cordova plugin add cordova-plugin-contacts

contacts对象

contacts对象提供了以下方法:

  • navigator.contacts.create
  • navigator.contacts.find
  • navigator.contacts.pickContact

contacts注入的对象

  • Contact
  • ContactName
  • ContactField
  • ContactAddress
  • ContactOrganization
  • ContactFindOptions
  • ContactError
  • ContactFieldType

navigator.contacts.create

navigator.contacts.create方法用于返回一个Contact实例，该实例并不会被添加到手机通讯录里面，因此你需要使用Contact.save。

Supported Platforms

  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8

例子

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

navigator.contacts.find

navigator.contacts.find查询设备通讯里匹配的Contact对象，检索成功后会将结果以参数的形式返回到successCallback。
__contactFields__用于指定需要匹配的字段，空字符串会导致错误，"*" 会匹配所有字段。

__contactFindOptions.filter__用于查询过滤设置，该值用于和__contactFields__字段的数据进行比对，使用__contactFindOptions.desiredFields__来控制哪些contact属性被返回。

__contactFields__和__contactFindOptions.desiredFields__的值在ContactFieldType定义.

参数

  • contactFields: 查询时匹配的字段。字符串数组格式。(DOMString[])
  • contactSuccess: 查询成功时的回调函数。
  • contactError: 查询失败的时候的回调函数。可选参数，但是我建议你至少要打印errorLog。以免出错的时候蒙圈。
  • contactFindOptions: 可选参数，用于设置查询过滤条件以及返回的字段信息等。
    • filter: 查找数据的关键字。(DOMString) (Default: "")
    • multiple: 是否允许返回多个contact对象，(Boolean) (Default: false)
    • desiredFields: 结果集中包含哪些字段。(DOMString[])
    • hasPhoneNumber(Android only): 只返回有电话号码的contact对象。(Boolean) (Default: false)

Supported Platforms

  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows (Windows Phone 8.1 and Windows 10)

例子

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

navigator.contacts.pickContact

navigator.contacts.pickContact用于抓取指定的联系人，将联系人信息以contact对象的方式返回给contactSuccess。

参数

  • contactSuccess: 操作成功的回调函数。
  • contactError: 操作失败的回调函数，可选参数。

Supported Platforms

  • Android
  • iOS
  • Windows Phone 8
  • Windows 8
  • Windows

实例

    navigator.contacts.pickContact(function(contact){
		console.log('The following contact has been selected:' + JSON.stringify(contact));
	},function(err){
		console.log('Error: ' + err);
	});

Android注意事项

该api会启动另一个Activity，它通过resume事件来返回结果，因此你必须像下面这样来取得你的结果。

    function onResume(resumeEvent) {
        if(resumeEvent.pendingResult) {
            if(resumeEvent.pendingResult.pluginStatus === "OK") {
                var contact = navigator.contacts.create(resumeEvent.pendingResult.result);
                successCallback(contact);
            } else {
                failCallback(resumeEvent.pendingResult.result);
            }
        }
    }

Contact

Contact对象代表一个用户的联系人，我们可以创建联系人，存储或者是从通讯录删除对应的联系人，我们也可以通过navigator.contacts.find从设备通讯录中取得一个contact对象如果他存在的话。

NOTE: 并不是所有设备都支持contact的所有属性，所以要确认各个平台的注意事项。

属性

  • id: 唯一标识符. (DOMString)
  • displayName: 通讯录显示的名称。(DOMString)
  • name: 全名。 (ContactName)
  • nickname: 昵称。 (DOMString)
  • phoneNumbers: 包含所有电话号码的数组。(ContactField[])
  • emails: 包含所有email的数组。 (ContactField[])
  • addresses: 包含所有地址的数组。 (ContactAddress[])
  • ims: 包含所有IM地址的数组。 (ContactField[])
  • organizations: 包含联系人的所有组织信息。(ContactOrganization[])
  • birthday: 生日。 (Date)
  • note: 备注 (DOMString)
  • photos: 头像数组。 (ContactField[])
  • categories: 分类信息。 (ContactField[])
  • urls: 联系人的web网页信息 (ContactField[])

方法

  • clone: 对contact对象进行深拷贝，id是null。
  • remove: 从物理设备删除这个联系人，除非发生错误ContactError。
  • save: 保存当前contact对象到设备通讯录，如果相同id的联系人存在则进行更新。

Supported Platforms

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows 8
  • Windows

实例

    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 Example

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

Remove Example

    function onSuccess() {
        alert("Removal Success");
    };

    function onError(contactError) {
        alert("Error = " + contactError.code);
    };

    // remove the contact from the device
    contact.remove(onSuccess,onError);

Android 2.X Quirks

  • categories: 在Android 2.X设备上为null。

iOS Quirks

  • displayName: iOS不支持该属性，会返回null。除非没有设置ContactName，这时会返回nickname或者""。
  • birthday: 必须以JavaScript Date对象的形式赋值,返回值也是一样的。
  • photos: 返回图片的在临时目录URL，但是当程序关闭的时候，该URL对应的临时文件会失效。
  • categories: 不支持返回null。

ContactAddress

ContactAddress用于存储联系人地址。Contact对象可能会包含多个ContactAddress。

属性

  • pref: 如果包含contact信息则为true。 (boolean)
  • type: 地址的分类，比如_home_。 (DOMString)
  • formatted: 完整的地址格式。 (DOMString)
  • streetAddress: 完整的街道信息。 (DOMString)
  • locality: 城市信息。 (DOMString)
  • region: 地区信息。 (DOMString)
  • postalCode: 邮政编码。 (DOMString)
  • country: 国家名 (DOMString)

Supported Platforms

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows 8
  • Windows

实例

    // 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 = "";
    options.multiple = true;
    var filter = ["displayName", "addresses"];
    navigator.contacts.find(filter, onSuccess, onError, options);

Android 2.X Quirks

  • pref: 在Android 2.X设备上不被支持，返回false。

iOS Quirks

  • pref: 在iOS设备不被支持，返回false。
  • formatted: 不被支持。

ContactError

ContactError在发生错误的时候通过errorCallback取得。

Properties

  • code: 结果为以下的一种情况。

Constants

  • 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.OPERATION_CANCELLED_ERROR (code 6)
  • ContactError.PERMISSION_DENIED_ERROR (code 20)

ContactField

ContactField是一个可以被重复使用的contact字段。每一个ContactField对象包含value, type, pref 。一个 Contact 在ContactField[]中存储多个ContactField比如电话号码，联系地址等。

在大多数情况下，ContactField的__type__属性并没有预设值，比如电话号码的类别可以指定为_home_， home, work, mobile,iPhone, 或者其他的一些被设备支持的属性。不管怎样，Contact的photos字段的类别是image:url。一个保存着URL或者base64数据的字符串。

属性

  • type: 用于存储类别的字符串，比如_home_。 (DOMString)
  • value: 字段的值，比如电话号码，地址。(DOMString)
  • pref: 如果包含信息，该字段为true。(boolean)

Supported Platforms

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows 8
  • Windows

实例

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

Android Quirks

  • pref: Android不支持该属性，始终为false。

iOS Quirks

  • pref: iOS不支持该属性，始终为false。

ContactName

包含联系人对象Contact不同种类的名称。

属性

  • formatted: 完成的联系人名。 (DOMString)
  • familyName: 联系人的家庭人名。 (DOMString)
  • givenName: 联系人的given名。 (DOMString)
  • middleName: 联系人的中间名。 (DOMString)
  • honorificPrefix: 联系人的前缀。 (example Mr. or Dr.) (DOMString)
  • honorificSuffix: 联系人后缀。 (example Esq.). (DOMString)

Supported Platforms

  • Amazon Fire OS
  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows 8
  • Windows

实例

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

Android Quirks

  • formatted: 部分支持，只读属性，内容为honorificPrefix, givenName, middleName, familyName, honorificSuffix的合并字符串。

iOS Quirks

  • formatted: 部分支持，返回名字信息的组合。只读属性。

ContactOrganization

ContactOrganization包含联系人的组织信息，存储于一个ContactOrganization数组中。

属性

  • pref: 如果为true说明里面有信息。 (boolean)
  • type: 一个类别字符串，比如_home_。(DOMString)
  • name: 组织名称。 (DOMString)
  • department: 工作部门。 (DOMString)
  • title: 联系人的部门头衔。 (DOMString)

Supported Platforms

  • Android
  • BlackBerry 10
  • Firefox OS
  • iOS
  • Windows Phone 8
  • Windows (Windows 8.1 and Windows Phone 8.1 devices only)

实例

    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 = "";
    options.multiple = true;
    filter = ["displayName", "organizations"];
    navigator.contacts.find(filter, onSuccess, onError, options);

Android 2.X Quirks

  • pref: 在Android 2.X不被支持，返回false。

iOS Quirks

  • pref: 不被支持，返回false。
  • type: 不被支持，返回null。
  • name: 部分支持，第一个组织明被存储在iOS的__kABPersonOrganizationProperty__字段.
  • department: 部分支持，第一个部门名存储在iOS的__kABPersonDepartmentProperty__字段。
  • title: 部分支持，第一个头衔存储在iOS的__kABPersonJobTitleProperty__字段。

ContactFieldType

ContactFieldType用来定义可能的字段类型。比如'phoneNumbers'和'emails'。我们可以此来指定contacts.find()函数的返回字段，或者用来指定检索匹配的字段。

  • navigator.contacts.fieldType.addresses
  • navigator.contacts.fieldType.birthday
  • navigator.contacts.fieldType.categories
  • navigator.contacts.fieldType.country
  • navigator.contacts.fieldType.department
  • navigator.contacts.fieldType.displayName
  • navigator.contacts.fieldType.emails
  • navigator.contacts.fieldType.familyName
  • navigator.contacts.fieldType.formatted
  • navigator.contacts.fieldType.givenName
  • navigator.contacts.fieldType.honorificPrefix
  • navigator.contacts.fieldType.honorificSuffix
  • navigator.contacts.fieldType.id
  • navigator.contacts.fieldType.ims
  • navigator.contacts.fieldType.locality
  • navigator.contacts.fieldType.middleName
  • navigator.contacts.fieldType.name
  • navigator.contacts.fieldType.nickname
  • navigator.contacts.fieldType.note
  • navigator.contacts.fieldType.organizations
  • navigator.contacts.fieldType.phoneNumbers
  • navigator.contacts.fieldType.photos
  • navigator.contacts.fieldType.postalCode
  • navigator.contacts.fieldType.region
  • navigator.contacts.fieldType.streetAddress
  • navigator.contacts.fieldType.title
  • navigator.contacts.fieldType.urls