NativeScript Contacts

A NativeScript 模块，提供轻松访问 iOS 和 Android 联系人目录的功能。选择一个联系人、更新它、删除它或添加一个新联系人。1.5.0 版本支持与组一起工作。创建一个组、添加和删除联系人到组，并删除一个组。

安装

运行 tns plugin add nativescript-contacts

用法

要使用联系人模块，您必须首先 require() 它。

var contacts = require("nativescript-contacts");

iOS 注意事项

在 app/App_Resources/iOS/Info.plist 中添加以下密钥

<key>NSContactsUsageDescription</key>
<string>Kindly provide permission to access contact on your device.</string>

用户将在应用程序访问联系人时被要求权限。

Android 注意事项

从 API 级别 23 开始，您需要检查适当的权限以访问联系人。因此，您不仅需要在您的清单中具有这些权限

<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.READ_CONTACTS" />
<uses-permission android:name="android.permission.WRITE_CONTACTS" />

您还需要确保每次执行操作本身时都请求这些权限（例如，使用出色的 nativescript-permissions 插件）

const contact = new Contact();
(...)
Permissions.requestPermissions([android.Manifest.permission.GET_ACCOUNTS, android.Manifest.permission.WRITE_CONTACTS], "I need these permissions because I'm cool")
            .then(() => {
                contact.save();
            });

方法

getContact: 选择一个联系人并返回其数据。

var app = require("application");
var contacts = require("nativescript-contacts");

contacts.getContact().then(function(args) {
  /// Returns args:
  /// args.data: Generic cross platform JSON object
  /// args.reponse: "selected" or "cancelled" depending on wheter the user selected a contact.

  if (args.response === "selected") {
    var contact = args.data; //See data structure below

    // lets say you wanted to grab first name and last name
    console.log(contact.name.given + " " + contact.name.family);

    //lets say you want to get the phone numbers
    contact.phoneNumbers.forEach(function(phone) {
      console.log(phone.value);
    });

    //lets say you want to get the addresses
    contact.postalAddresses.forEach(function(address) {
      console.log(address.location.street);
    });
  }
});

保存新联系人

var app = require("application");
var contacts = require("nativescript-contacts");
var imageSource = require("image-source");

var newContact = new contacts.Contact();
newContact.name.given = "John";
newContact.name.family = "Doe";
newContact.phoneNumbers.push({
  label: contacts.KnownLabel.HOME,
  value: "123457890"
}); // See below for known labels
newContact.phoneNumbers.push({ label: "My Custom Label", value: "11235813" });
newContact.photo = imageSource.fromFileOrResource("~/photo.png");
newContact.save();

更新现有联系人

var app = require("application");
var contacts = require("nativescript-contacts");
var imageSource = require("image-source");

contacts.getContact().then(function(args) {
  if (args.response === "selected") {
    var contact = args.data;
    contact.name.given = "Jane";
    contact.name.family = "Doe";

    imageSource
      .fromUrl("http://www.google.com/images/errors/logo_sm_2.png")
      .then(function(src) {
        contact.photo = src;
        contact.save();
      });
  }
});

删除联系人

var app = require("application");
var contacts = require("nativescript-contacts");

contacts.getContact().then(function(args) {
  /// Returns args:
  /// args.data: Generic cross platform JSON object
  /// args.reponse: "selected" or "cancelled" depending on wheter the user selected a contact.

  if (args.response === "selected") {
    var contact = args.data; //See data structure below
    contact.delete();
  }
});

检查联系人是否为统一/链接（iOS 特定）

var app = require("application");
var contacts = require("nativescript-contacts");

contacts.getContact().then(function(args) {
  /// Returns args:
  /// args.data: Generic cross platform JSON object
  /// args.reponse: "selected" or "cancelled" depending on wheter the user selected a contact.

  if (args.response === "selected") {
    var contact = args.data; //See data structure below
    console.log(contact.isUnified() ? 'Contact IS unified' : 'Contact is NOT unified');
  }
});

getContactsByName: 查找所有名称匹配的联系人。返回联系人数据数组。

var app = require("application");
var contacts = require("nativescript-contacts");

/*
  contactFields contains the fields to retrieve from native backend to reduce processing time
  var contactFields = ['name','organization','nickname','notes','photo','urls','phoneNumbers','emailAddresses','postalAddresses']
*/
var contactFields = ["name", "phoneNumbers"];

contacts.getContactsByName("Hicks", contactFields).then(
  function(args) {
    console.log("getContactsByName Complete");
    console.log(JSON.stringify(args));
    /// Returns args:
    /// args.data: Generic cross platform JSON object, null if no contacts were found.
    /// args.reponse: "fetch"
  },
  function(err) {
    console.log("Error: " + err);
  }
);

getAllContacts: 查找所有联系人。返回联系人数据数组。

var app = require("application");
var contacts = require("nativescript-contacts");

/*
  Optional: contactFields contains the fields to retrieve from native backend to reduce processing time
  var contactFields = ['name','organization','nickname','notes','photo','urls','phoneNumbers','emailAddresses','postalAddresses']

  If not supplied, all available contactFields will be returned.
*/
var contactFields = ["name", "phoneNumbers"];

contacts.getAllContacts(contactFields).then(
  function(args) {
    console.log("getAllContacts Complete");
    console.log(JSON.stringify(args));
    /// Returns args:
    /// args.data: Generic cross platform JSON object, null if no contacts were found.
    /// args.reponse: "fetch"
  },
  function(err) {
    console.log("Error: " + err);
  }
);

getContactById: 根据匹配的标识符查找联系人。返回 GetFetchResult。 (iOS 仅限)

var app = require("application");
var contacts = require("nativescript-contacts");

var contactId = '[Contact Identifier]'; // Assumes this is a valid contact identifier (Contact.id)

contacts.getContactById(contactId).then(
  function(args) {
    console.log("getContactById Complete");
    console.log(JSON.stringify(args));
    /// Returns args:
    /// args.data: Generic cross platform JSON object, null if no contacts were found.
    /// args.reponse: "fetch"
  },
  function(err) {
    console.log("Error: " + err);
  }
);

getGroups: 查找组。返回组数据数组。

var app = require("application");
var contacts = require("nativescript-contacts");

contacts
  .getGroups("Test Group") //[name] optional. If defined will look for group with the specified name, otherwise will return all groups.
  .then(
    function(args) {
      console.log("getGroups Complete");
      console.log(JSON.stringify(args));
      /// Returns args:
      /// args.data: Generic cross platform JSON object, null if no groups were found.
      /// args.reponse: "fetch"

      if (args.data === null) {
        console.log("No Groups Found!");
      } else {
        console.log("Group(s) Found!");
      }
    },
    function(err) {
      console.log("Error: " + err);
    }
  );

保存新组

var app = require("application");
var contacts = require("nativescript-contacts");

var groupModel = new contacts.Group();
groupModel.name = "Test Group";
//Save Argument (boolean)
//iOS: [false=> Use Local Container, true=> Use Default Container]
//Android: will always be true, setting this value will not affect android.
groupModel.save(false);

删除组

var app = require("application");
var contacts = require("nativescript-contacts");

contacts.getGroups("Test Group").then(
  function(args) {
    console.log("getGroups Complete");
    console.log(JSON.stringify(args));
    /// Returns args:
    /// args.data: Generic cross platform JSON object, null if no groups were found.
    /// args.reponse: "fetch"

    if (args.data !== null) {
      console.log("Group(s) Found!");
      args.data[0].delete(); //Delete the first found group
    }
  },
  function(err) {
    console.log("Error: " + err);
  }
);

将成员添加到组

var app = require("application");
var contacts = require("nativescript-contacts");

contacts.getContact().then(function(args) {
  /// Returns args:
  /// args.data: Generic cross platform JSON object
  /// args.reponse: "selected" or "cancelled" depending on wheter the user selected a contact.

  if (args.response === "selected") {
    var contact = args.data; //See data structure below
    contacts.getGroups("Test Group").then(
      function(a) {
        if (a.data !== null) {
          var group = a.data[0];
          group.addMember(contact);
        }
      },
      function(err) {
        console.log("Error: " + err);
      }
    );
  }
});

从组中删除成员

var app = require("application");
var contacts = require("nativescript-contacts");

contacts
  .getGroups("Test Group") //[name] optional. If defined will look for group with the specified name, otherwise will return all groups.
  .then(
    function(args) {
      if (args.data !== null) {
        var group = args.data[0];

        contacts.getContactsInGroup(group).then(
          function(a) {
            /// Returns args:
            /// args.data: Generic cross platform JSON object, null if no groups were found.
            /// args.reponse: "fetch"
            console.log("getContactsInGroup complete");

            if (a.data !== null) {
              a.data.forEach(function(c, idx) {
                group.removeMember(c);
              });
            }
          },
          function(err) {
            console.log("Error: " + err);
          }
        );
      }
    },
    function(err) {
      console.log("Error: " + err);
    }
  );

getContactsInGroup: 获取组中的所有联系人。返回联系人数据数组。

var app = require("application");
var contacts = require("nativescript-contacts");

contacts
  .getGroups("Test Group") //[name] optional. If defined will look for group with the specified name, otherwise will return all groups.
  .then(
    function(args) {
      if (args.data !== null) {
        var group = args.data[0];

        contacts.getContactsInGroup(group).then(
          function(a) {
            console.log("getContactsInGroup complete");
            /// Returns args:
            /// args.data: Generic cross platform JSON object, null if no groups were found.
            /// args.reponse: "fetch"
          },
          function(err) {
            console.log("Error: " + err);
          }
        );
      }
    },
    function(err) {
      console.log("Error: " + err);
    }
  );

单个用户数据结构

{
    id : "",
    name : {
        given: "",
        middle: "",
        family: "",
        prefix: "",
        suffix: "",
        displayname: "",
        phonetic : {
            given: "",
            middle: "",
            family: ""
        }
    },
    nickname : "",
    organization : {
        name: "",
        jobTitle: "",
        department: "",

        // Android Specific properties
        symbol: "",
        phonetic: "",
        location: "",
        type: ""
    },
    notes : "",
    photo: null, // {N} ImageSource instance

    phoneNumbers : [],
    emailAddresses : [],
    postalAddresses : [],
    urls : []
}

电话号码 / 电子邮件地址结构

{
    id: "",
    label: "",
    value: ""
}

网址结构

{
    label: "",
    value: ""
}

邮政地址结构

{
    id: "",
    label: "",
    location: {
        street: "",
        city: "",
        state: "",
        postalCode: "",
        country: "",
        countryCode: ""
    }
}

已知标签（用于网址、地址和电话）

以下常量在 KnownLabel 结构中由插件公开。下面详细说明它们支持哪些类型以及支持哪些平台

• HOME iOS - 电话、电子邮件、邮政、网址 Android - 电话、电子邮件、邮政、网址
• WORK iOS - 电话、电子邮件、邮政、网址 Android - 电话、电子邮件、邮政、网址
• OTHER iOS - 电话、电子邮件、邮政、网址 Android - 电话、电子邮件、邮政、网址
• FAX_HOME iOS - 电话 Android - 电话
• FAX_WORK iOS - 电话 Android - 电话
• PAGER iOS - 电话 Android - 电话
• MAIN iOS - 电话 Android - 电话
• HOMEPAGE iOS - 网址 Android - 网址
• CALLBACK Android - 电话
• CAR Android - 电话
• COMPANY_MAIN Android - 电话
• ISDN Android - 电话
• OTHER_FAX Android - 电话
• RADIO Android - 电话
• TELEX Android - 电话
• TTY_TDD Android - 电话
• WORK_MOBILE Android - 电话
• WORK_PAGER Android - 手机
• ASSISTANT Android - 手机
• MMS Android - 手机
• FTP Android - URL
• PROFILE Android - URL
• BLOG Android - URL

这些是系统标签，但您也可以使用任何您想要的自定义标签。

单组数据结构

{
  id: "";
  name: "";
}

GetFetchResult 数据结构

联系请求返回的对象。

{
  data: Contact[];
  response: string;
}

iOS

查看苹果关于可用属性的文档：https://developer.apple.com/library/mac/documentation/Contacts/Reference/CNContact_Class/index.html#//apple_ref/occ/cl/CNContact

注意：由于插件使用了联系人框架，它仅在 iOS 9.0 及以上版本上受支持！