KBContactsSelection 是一个独立的 UI 和逻辑组件，允许您轻松地在通讯录中搜索和选择联系人，并将结果重定向到邮件或消息。

展示

注意带有电话号码、电子邮件和最终重定向差异的优雅解决方案。

安装

KBContactsSelection 通过 CocoaPods 提供。要使用它，只需在 Podfile 中添加一行

pod 'KBContactsSelection'

然后添加所需的 import

#import "KBContactsSelectionViewController.h"

配置

库的公共元素是 KBContactsSelectionViewController 类。它包含一个方便的方法来创建自身的实例，并带有适当的配置

+ (KBContactsSelectionViewController*)contactsSelectionViewControllerWithConfiguration:(void (^)(KBContactsSelectionConfiguration* configuration))configurationBlock;

最简单的使用方法看起来像这样

KBContactsSelectionViewController *vc = [KBContactsSelectionViewController contactsSelectionViewControllerWithConfiguration:nil];

[self presentViewController:vc animated:YES completion:nil];

它使用采用了优雅方式的应用 blocks 的 Objective-c Builder 模式。这种解决方案的灵感来自 这里。

KBContactsSelectionViewController 是全屏视图控制器，它可以被推入导航堆栈或显示出来。

KBContactsSelectionConfiguration 类负责设置基本和高级属性

外观与感觉

UIColor *tintColor;
BOOL shouldShowNavigationBar;
NSString * title;

联系人的行为

enum KBContactsSelectionMode mode;
BOOL skipUnnamedContacts;
KBContactValidation contactEnabledValidation;

可定制动作

NSString * selectButtonTitle;
KBContactSelectionHandler customSelectButtonHandler;

定义文本/电子邮件

configuration.mailBody = @"Some mail body";
configuration.mailIsHTML = false;
configuration.mailSubject = @"Important Subject";
configuration.messageBody = @"This is text content";

tintColor 负责设置导航栏的 tintColor、表格视图的 sectionIndexColor 和搜索栏的 tintColor。

shouldShowNavigationBar 隐藏 KBContactsSelectionViewController 的导航栏，应在您推送此视图控制器而不是显示它时设置。

title 可以在显示控制器之前设置。它将为 navigationBar 设置 title。

mode 可设置为掩码一个或两个值：KBContactsSelectionModeMessages 和/或 KBContactsSelectionModeEmail。它们影响显示的数据（电子邮件或电话号码）和选择联系人的最终导航（消息或邮件应用）。为了显示具有电子邮件或电话号码（或两者）的联系人，可以将此变量设置为组合掩码 KBContactsSelectionModeMessages | KBContactsSelectionModeEmail

skipUnnamedContacts 将自动过滤掉所有未设置首名或姓氏的联系人。

searchByKeywords 允许使用关键字搜索名称（搜索 'f b' 将会过滤出 'Felipe Baytelman' 和 'Bruno Finstein'）。

contactEnabledValidation 可用于手动启用/禁用列表中的联系人生成方案，使用自定义块 BOOL(^KBContactValidation)(APContact * contact)。当定义此块时，它将针对每个联系人生成方案进行调用。

selectButtonTitle 允许您自定义 text 的选择按钮。使用默认的 nil 将显示本地化的“选择”版本。

customSelectButtonHandler 允许在用户点击选择按钮时调用自定义操作（块）。默认情况下，当此值为 nil 时，将提示电子邮件生成器或提供短信消息生成器（取决于选中的 mode）。如果定义了 customSelectButtonHandler（《void(^KBContactSelectionHandler)(NSArray * selectedContacts)），它将被以 APContact 对象的 NSArray 进行调用。

使用示例

带有电话号码推送 KBContactsSelectionViewController

KBContactsSelectionViewController *vc = [KBContactsSelectionViewController contactsSelectionViewControllerWithConfiguration:^(KBContactsSelectionConfiguration *configuration) {
    configuration.mode = KBContactsSelectionModeMessages;
    configuration.shouldShowNavigationBar = NO;
    configuration.tintColor = [UIColor colorWithRed:11.0/255 green:211.0/255 blue:24.0/255 alpha:1];
}];

[self.navigationController pushViewController:vc animated:YES];

使用电子邮件呈现 KBContactsSelectionViewController

KBContactsSelectionViewController *vc = [KBContactsSelectionViewController contactsSelectionViewControllerWithConfiguration:^(KBContactsSelectionConfiguration *configuration) {
    configuration.tintColor = [UIColor orangeColor];
    configuration.mode = KBContactsSelectionModeEmail;
}];

[self presentViewController:vc animated:YES completion:nil];

启用特定联系人和自定义选择操作

此示例将启用对应于带有照片的联系人行。

KBContactsSelectionViewController *vc = [KBContactsSelectionViewController contactsSelectionViewControllerWithConfiguration:^(KBContactsSelectionConfiguration *configuration) {
    configuration.tintColor = [UIColor orangeColor];
    configuration.mode = KBContactsSelectionModeEmail;
    configuration.skipUnnamedContacts = YES;
    configuration.contactEnabledValidation = ^BOOL(APContact * contact) {
        return contact.photo != nil;
    };
}];

[self presentViewController:vc animated:YES completion:nil];

KBContactsSelectionConfiguration 的每个属性都可以自由修改，尽管建议在呈现的时候不隐藏导航栏，在推送时隐藏。

示例项目

示例项目附加在此存储库中。打开 KBContactsSelectionExample.xcworkspace，通过执行 pod install 安装所有必需的依赖项，并运行与上图中相同的演示。

已知问题

iOS 模拟器显然不支持消息（适当的警告）并且显然在呈现 MFMailComposeViewController 时有一些问题。

KBContactsSelectionExample[20027:5171733] _serviceViewControllerReady:error: Error Domain=_UIViewServiceErrorDomain Code=1 "The operation couldn’t be completed. (_UIViewServiceErrorDomain error 1.)" UserInfo=0x7f95cae243f0 {Canceled=service continuation}

在真实设备上它运行得很好，但在模拟器上失败，可能是一个错误。可以在 StackOverflow 上找到有关此问题的某些线程此处 和 此处。

这就是为什么在 gif 中的呈现电子邮件视图控制器中没有输入接收者。

组件

KBContactsSelectionViewController

是整个库的主要组件，也可能是唯一的显式使用的组件。为了便于使用，它有一些自我描述的公共属性，可以更改其行为。

@property (weak, nonatomic) IBOutlet UITableView *tableView;
@property (weak, nonatomic) IBOutlet UISearchBar *searchBar;
@property (weak, nonatomic) IBOutlet UIBarButtonItem *buttonItemCancel;
@property (weak, nonatomic) IBOutlet UIBarButtonItem *buttonItemSelect;
@property (weak, nonatomic) IBOutlet UINavigationBar *navigationBarSearchContacts;
@property (weak, nonatomic) IBOutlet NSLayoutConstraint *navigationBarSearchContactsHeight;

它负责大多数用户交互：按钮、呈现最终视图控制器、搜索。

额外信息视图

当你需要添加提示或选择摘要时，additionalInfoView 属性允许动态添加此类视图。

@property (strong, nonatomic) UIView * additionalInfoView;

additionalInfoView 将包含在导航栏和搜索栏之间。它将持续即使在搜索期间，使用户能够呈现相关信息。可以在呈现视图控制器之前或之后设置附加信息视图。这是在附加的示例项目中展示的。

此视图将以水平方向拉伸以填满表视图的宽度。垂直方向上，视图控制器将考虑额外视图的高度，将搜索栏向下推，以便正确地适配。如果在视图控制器呈现后设置 additionalInfoView，搜索栏将以动画方式向下推。

以下示例显示了提供给用户上下文或说明的标签。

KBContactsSelectionViewController *vc = [KBContactsSelectionViewController contactsSelectionViewControllerWithConfiguration:^(KBContactsSelectionConfiguration *configuration) {
        configuration.title = @"New Project";
        ...
    };
}];

UILabel * instructionsLabel = [[UILabel alloc] init];
instructionsLabel.text = @"Add new participants to the new project"; 
vc.additionalInfoView = instructionsLabel;

数据源

尽管 KBContactsSelectionViewController 包含了表视图，但它不作为其数据源或代理。它将所有与表视图相关的责任传递给 KBContactsTableViewDataSource 组件。

KBContactsTableViewDataSource

是采用两个协议的对象：<UITableViewDataSource, UITableViewDelegate>，并全面负责表视图的渲染、过滤和捕获联系人。

出于性能考虑，它首先加载所有联系人并存储在不可变数组中，然后按照全名的首字母将联系人分组到字典中，其中键是全名的首字母，值是以该字母开头的所有联系人的排序数组。

搜索是通过创建所有联系人的过滤副本并进行与之前相同的分组来执行的。

所有选定的联系人根据 recordID 字段存储在不同的数组中，以便它们可以在搜索之间持久化。

当按下 Select 按钮时，最初使用的联系人数组将使用所有 recordIds 进行过滤，并显示适当的视图控制器。

KBContactsSelectionConfiguration

已在 配置 部分中描述。

KBContactsSelectionViewControllerDelegate

包含可用来观察联系人修改的两个方法。

- (void) didSelectContact:(APContact *)contact;
- (void) didRemoveContact:(APContact *)contact;

感谢 @benaneesh。

本地化字符串

库在合适的位置使用了 NSLocalizedString 宏，因此您可以生成包含以下字面量的 Localizable.strings 文件。

"Messaging not supported" = "Messaging not supported";
"Messaging on this device is not supported." = "Messaging on this device is not supported.";
"OK" = "OK";
"Search contacts" = "Search contacts";
"Select" = "Select";
"Sending emails from this device is not supported." = "Sending emails from this device is not supported.";

依赖项

KBContactsSelection 使用 APAddressBook 来轻松管理 iOS 地址簿。

许可证

KBContactsSelection 使用 MIT License 许可。有关更多信息，请参阅 LICENSE 文件。