NativeScript Contacts

注意：这是 Ryan Lebel 的 'nativescript-contacts' 插件的一个临时分支。它允许在 Android 上添加没有 'Account' 的联系人。一旦主插件包含了这个改进，将废弃此插件。

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

安装

运行 tns plugin add @jorwoody/nativescript-contacts

用法

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

.js

var contacts = require("@jorwoody/nativescript-contacts");

.ts

import * as contacts from "@jorwoody/nativescript-contacts");

iOS 注意事项

将以下键添加到位于 app/App_Resources/iOS/Info.plist 中的 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();
  }
});

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

/*
  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.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);
  }
);

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: ""
}

URL 结构

{
    label: "",
    value: ""
}

邮政地址结构

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

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

以下常量在 KnownLabel 结构中由插件公开。以下列出了它们支持的类型和平台

• HOME iOS - phone, email, postal, url Android - phone, email, postal, url
• WORK iOS - phone, email, postal, url Android - phone, email, postal, url
• OTHER iOS - phone, email, postal, url Android - phone, email, postal, url
• FAX_HOME iOS - phone Android - phone
• FAX_WORK iOS - phone Android - phone
• PAGER iOS - phone Android - phone
• MAIN iOS - phone Android - phone
• HOMEPAGE iOS - url Android - url
• CALLBACK Android - phone
• CAR Android - phone
• COMPANY_MAIN Android - phone
• ISDN Android - phone
• OTHER_FAX Android - phone
• RADIO Android - phone
• TELEX Android - phone
• TTY_TDD Android - phone
• WORK_MOBILE Android - phone
• WORK_PAGER Android - phone
• 助手 Android - 手机
• MMS Android - 手机
• FTP Android - URL
• 配置文件 Android - URL
• 博客 Android - URL

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

单组数据结构

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

iOS

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

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