iOS9-CNContactAPI翻译

發表於   |   分類於   |  

本周腾出一些时间翻译了CNContact相关的文档，整理如下：

Introduction

CNContact 是iOS9提供的全新的获取手机通讯录类，提供通讯录中姓名、电话号码等等，并且是线程安全的。CNContact类似于一个复杂的foundation集合，同样的有一个可变类型的子类CNMutableContact。每一份通讯录（其实指每一个联系人）都有唯一的ID，通过identifier属性便可获取到。

Properties

1.标示相关属性

identifier

该设备上通讯录唯一的ID（只读）

Discussion

你可以通过identifier来重新获取通讯录。APP launch过程中就可保存identifier。注意这个identifier在当前设备上是独一无二的。

2.日期相关属性

nonGregorianBirthday

通讯录中阴历生日（只读）

Discussion

NSDateComponents类型的属性，用来表示通讯录中阴历的生日。生日中必须有月和日，年份和闰月属于可选项。日历属性必须有值且必须是阴历。支持阴历的日历有，佛教，中文，伊斯兰教。

dates

包含阳历日期的数组（只读）

Discussion

dates是一个包含CNLabeledValue对象的数组，每一个CNLabeledValue对象都有一个label和value属性。你可以用这个属性才存储阳历日期，例如周年纪念日等等。日历属性可以为空或者是阳历。

3.名字相关属性

namePrefix

通讯录中的名字前缀（只读）

givenName

名字分 姓-名 这里指的是名字，不包含姓. (只读)

Discussion

一个人的名字包含姓氏+名字，given name相当于first name，既不包含姓的名字。

2）middleName

中间的名字（只读）
很多歪果仁的名字都是XX middleName XXX 这样表示的

3）familyName

姓氏（只读）

Discussion

相当于last name，表示姓氏
后续还有很多名字相关属性 都简单易懂 就不一一介绍了

4.地理位置相关

(+)localizedStringForKey:

参数

标识地理位置的key

返回值

通讯录中对应的地理位置

Discussion

这个方法通过通讯录的key返回对应的地理位置

5.通讯录排序

(1)+ descriptorForAllComparatorKeys

获取所有用来通讯录排序比较的key

返回值

有序对比的所有key

Discussion

这个方法会执行CNKeyDescriptor协议的方法，并且可以作为一个数组用在当获取通讯录对应的key

(2)+ comparatorForNameSortOrder:

按照特殊的顺序返回比较器

Parameters

  • sortOrder想要的排序顺序，比如按照名字排序
  • Return Value返回对通讯录排序的NSComparator对象

6.电话号码

1）phoneNumbers

通讯录中被标识为电话号码的数组（只读）

Discussion

这是一个包含CNLabeledValue对象的数组，每一个CNLabeledValue对象有一个label和CNPhoneNumber值,也就是说，要想获得电话号码，需要使用CNPhoneNumber。

7.图片相关属性

1）imageData

通讯录个人照片（只读）

Discussion

建议当你需要获取通讯录中某人照片的时候使用该属性，比方说你需要展示通讯录中个人的照片。

2）thumbnailImageData

通讯录中个人照片的缩略图（只读）

Discussion

thumbnailImageData属性是由imageData衍生而来，包含从名片或者编辑通讯录的时候获取到的imageData。建议当你需要获取通讯录中某人照片缩略图的时候使用该属性，比方说你需要展示通讯录中个人的照片的缩略图。

3）imageDataAvailable

表示一份通讯录中有没有个人照片（只读）

Discussion

这是一个包含CNLabeledValue对象的数组。每一个CNLabeledValue对象都有一个label和CNContactRelation类型的值。其实当填写通讯录名字的时候这个属性便有值了，CNContactRelation就是表示通讯录关系的名字。

8.标识值属性

1）contactRelations

通讯录中的标识关系的数组（只读）

2）instantMessageAddresses

通讯录中标识即时通讯地址的数组（只读）

Discussion

这是一个包含CNLabeledValue对象的数组。每一个CNLabeledValue对象都有一个label和CNInstantMessageAddress类型的值。

9.通讯录谓词

下面介绍获取通讯录内容最重要的方法：
使用断言去匹配通讯录。你只可以在CNContactStore 和 CNContactFetchRequest中使用这些谓词。

1）+ predicateForContactsMatchingName:

返回一个能根据联系人名字找到匹配的通讯的谓词

参数

  • name
  • 要去匹配的通讯录名称

返回值

返回一个用来从CNContactStore获取通讯录的谓词

Discussion

名字的文字数量不限

2）+ predicateForContactsWithIdentifiers:

返回一个能根据特定ID找到匹配的通讯的谓词

参数

  • identifiers
  • 通讯录ID

返回值

返回一个用来从CNContactStore获取通讯录的谓词

3）+ predicateForContactsInGroupWithIdentifier:

返回根据ID获取特殊群的通讯录成员的谓词。

参数

  • groupIdentifier
  • 通讯录群组ID

返回值

返回一个用来从CNContactStore获取通讯录的断言。

4）+ predicateForContactsInContainerWithIdentifier:

返回一个能根据特定容器ID找到匹配的通讯的断言。

参数

  • containerIdentifier
  • 容器ID

返回值

返回一个用来从CNContactStore获取通讯录的断言。

10.可获取局部通讯录信息

1）- isKeyAvailable:

决定是否能够获取特殊关键key的通讯录属性值

返回值

如果可以获取则返回yes，否则返回no。

Discussion

isKeyAvailable: 或者 areKeysAvailable:这两个方法都可以在你不确定是否能够根据key获取到对应的值的时候使用。如果这个方法返回NO，可以通过通讯录ID和其他的key来重新获取。可以通过CNContactPropertyNotFetchedExceptionName来得到没有获取过的属性

2）- areKeysAvailable:

同上

11.Constants相关常量

1）CNContactSortOrder 通讯录顺序

typedef enum: NSInteger {
CNContactSortOrderNone,无序 CNContactSortOrderUserDefault,用户偏好排序
CNContactSortOrderGivenName,名字排序 CNContactSortOrderFamilyName,姓氏排序
}CNContactSortOrder;

2）Exception Handling 异常处理

获取属性值没有获取到的时候抛出异常

  • NSString * const CNContactPropertyNotFetchedExceptionName

3）Identifier

即时获取到的属性ID

  • NSString * const CNContactIdentifierKey 字符串，通讯录唯一的ID

4）Metadata Keys 元数据key

预先定义好的一系列代表通讯录各个属性的key，可以用来对CNContact 对象的键值编码。

  • NSString * const CNContactNamePrefixKey 姓名前缀
  • NSString * const CNContactGivenNameKey 名字
  • NSString * const CNContactMiddleNameKey 中间名字
  • NSString * const CNContactFamilyNameKey 姓氏
  • NSString * const CNContactPreviousFamilyNameKey 少女出嫁前的形式
  • NSString * const CNContactNameSuffixKey 名字后缀
  • NSString * const CNContactNicknameKey 绰号
  • NSString * const CNContactPhoneticGivenNameKey
  • NSString * const CNContactPhoneticMiddleNameKey
  • NSString * const CNContactPhoneticFamilyNameKey
  • NSString * const CNContactOrganizationNameKey
  • NSString * const CNContactDepartmentNameKey 部门名称
  • NSString * const CNContactJobTitleKey 工作职称
  • NSString * const CNContactBirthdayKey 生日
  • NSString * const CNContactNonGregorianBirthdayKey 阴历生日
  • NSString * const CNContactNoteKey
  • NSString * const CNContactImageDataKey 图片数据
  • NSString * const CNContactThumbnailImageDataKey 缩略图数据
  • NSString * const CNContactImageDataAvailableKey 是否能获取图片数据
  • NSString * const CNContactTypeKey 通讯录类型
  • NSString * const CNContactPhoneNumbersKey 电话号码
  • NSString * const CNContactEmailAddressesKey 电子邮件
  • NSString * const CNContactPostalAddressesKey 邮政地址
  • NSString * const CNContactUrlAddressesKey URL地址
  • NSString * const CNContactRelationsKey 通讯录关系
  • NSString * const CNContactSocialProfilesKey 社交个人信息
  • NSString * const CNContactInstantMessageAddressesKey 即时通讯地址