
本文由 CocoaChina 譯者 WangYue(微博)翻譯
By gabriel theodoropoulos
原文:A First Look at Contacts Framework in iOS 9
iOS 9 為用戶與開發者帶來了大量新技術,也對既有技術做了不少優化。正如我們所見,這個版本既有首次亮相的全新內容,也有對現有框架與類的變更和更新。此外,總令人意外的是,一些老舊的 API 被棄用、不再建議使用,為全新開發或過渡用的新 API 讓路。iOS 9 中的典型例子,便是全新的 Contacts 框架——它以更時髦的模式取代了老舊的 AddressBook 框架,更簡單也更直接。
凡是用過 AddressBook API 的開發者都可以肯定地說,它絕不屬於 iOS SDK 中易用的那一類。總體而言,AddressBook 難以理解和掌握,對新手更是如此。這一切歸咎於歷史原因,而新的 Contacts 框架則更易理解、更易上手。聯系人信息能在很短時間內被獲取、創建或更新,與聯系人相關的開發時間得以大幅縮短,變更與修改也能迅速完成。
在以下段落中,我們將重點介紹 Contacts 框架最重要的部分。我不會展示過多細節,因為你可以在蘋果官方文檔以及 WWDC 2015 Session 223 視頻中找到相關內容。
因此,首先從關鍵之處說起——用戶隱私。用戶常被應用詢問是否有權獲取聯系人信息:若用戶同意,應用便可自由與聯系人數據庫交互;若用戶拒絕,這個決定就必須被應用尊重,絕不能與聯系人數據庫交互。稍後我們會更仔細地探討它,並看到所有可能的場景如何以編程方式處理。不僅如此,要時刻記住用戶始終有權在設備設置中更改應用是否能獲取信息的權限,所以你在執行任何相關任務之前,都應先檢查應用是否具備獲取聯系人信息的權利。
聯系人數據的最大來源一直是設備裡的數據庫。但當應用請求聯系人信息時,Contacts 框架不僅在那裡查找,實際上它還會搜索其他來源,比如你的 iCloud 賬戶(若已連接),然後把從各個來源獲取到的信息整合後返回給應用。這非常有用,因為你不必在搜索設備數據庫之外另建其他搜索方法,一次便能拿到所有數據,再按自己的方式使用。
Contacts 框架提供了服務於各個特定目標的類。它們都很重要,但有一個用得最多,叫做 CNContactStore。這個類以編程方式呈現聯系人數據庫,並提供了許多實現不同任務的方法,例如獲取、保存或更新記錄,權限檢查與權限請求等等。單個聯系人記錄由 CNContact 類呈現,但要記住它是不可變的;若想創建新記錄或更新已有記錄,你必須使用 CNMutableContact 類。此外,與 Contacts 框架打交道時,尤其是獲取聯系人信息,你應始終在後台線程中執行這些任務;若在主線程運行且耗時過長,應用就可能無響應,最終導致糟糕的交互體驗。
把聯系人信息導入應用時,很少需要用到聯系人的所有屬性。從 Contacts 框架要搜索的所有數據源中獲取全部聯系人數據,往往是極其耗資源的進程,因此除非你確定真的會用到每一條數據,否則應避免這樣做。所幸,Contacts 框架提供了獲取部分結果的方法,意味著你可以只取聯系人的部分屬性值而非全部——例如只請求名或姓、家庭地址、家庭電話等,通過排除不需要的數據來節約大量資源。
除了以編程方式獲取聯系人信息的方式外,Contacts 框架還提供了一些可與應用協作的默認 UI,以直觀可視的方式訪問聯系人信息。這些 UI 與「聯系人」應用基本一致:既有一個 contact picker view controller(連同詳細信息卡,可定制到一定程度)用來獲取聯系人及屬性,也有一個 contacts view controller 用來展示聯系人詳情並執行某些操作(例如打電話)。
上述內容的細節將在後文逐一展開。再說一次,更多我展示過或將要展示的內容,請查閱官方文檔。接下來,我們先看 Demo 應用的樣子,再學習 Contacts 框架的各個類。你會發現,與這個新框架交互既簡單又有趣。
Demo APP 快速預覽
通過這個教程的 Demo,我會向你展示這個新框架的方方面面。接下來,我將演示如何:
檢查應用是否被授權獲取聯系人信息,以及如何發起授權請求。
用 3 種不同方法獲取聯系人信息,其中一種用到 picker view controller。
訪問獲取到的聯系人屬性,並合理地格式化它們以便展示。
使用默認的 Contacts UI 來選取、查看甚至編輯聯系人信息。
創建一個新的聯系人記錄。
我把這個 Demo 命名為 Birthdays,因為它旨在展示所有導入應用中的聯系人的生日。聯系人的全名、照片(若有)和家庭郵箱地址也會一併展示。理想狀態下,它本可以做成一個生日提醒器,當然我們不會處理通知、短信發送及其他相關動作。
這個應用基於導航模式,由以下部分組成:
應用啟動時,默認展示 ViewController。它展示了我先前提到的所有導入聯系人的信息,並提供獲取更多聯系人(右上角按鈕)、創建新聯系人(左上角按鈕),以及通過點擊某行查看聯系人詳情的方法。

聯系人詳情將展示在內嵌的 contacts view controller 中。正如你將看到的,你可以展示全部屬性,也可以只挑感興趣的那部分。
獲取聯系人信息是後面頗有意思的部分,我會用 3 種方式向你展示 3 種方法:
第一種:輸入一個聯系人名字(或其一部分),點擊鍵盤上的 return 按鈕後,應用便獲取匹配該名字的聯系人信息。
正如截圖所示,屏幕中間有一個 picker view。我們用它找出生日月份與所選月份匹配的聯系人,並在點擊 Done 按鈕時觸發獲取。
我們用框架提供的默認 picker view controller 直接查看和選擇聯系人信息。注意,這個 controller 裡展示的信息可以定制,其行為也一樣,稍後你會看到具體做法。

這就是 picker view controller,只展示具有有效生日日期的聯系人集合:

應用的最後一部分是創建新聯系人。這是個簡單任務,得益於 Demo,我們將用下面的 view controller 鍵入待創建聯系人的姓名、家庭郵箱與生日(這裡不處理圖片,因為此刻它並非重點)。

Demo 的示范數據(示范聯系人)將採用模擬器數據庫保存的默認聯系人,這些信息足以實現我們的目的,也非常好用。當然,你也可以使用設備裡的聯系人,或往模擬器中新增。默認情況下,模擬器聯系人不包含圖片,但你可以輕易在圖片庫裡找到並添加。
像往常一樣,你可以在這裡下載後文要用到的初始工程。下載完成後打開,瀏覽一下已添加的文件,準備好後便可開始下面的部分。
Contact Store 類
與聯系人打交道時,有一個你會一直用到的最基礎類,就是 CNContactStore。這個類實際上呈現了設備上的聯系人數據庫,負責管理應用與數據庫之間的所有交互,進一步說,它管理著所有關於拉取(fetching)、保存(saving)和更新(updating)聯系人與群組記錄的工作。簡而言之,它就是大多數聯系人交互的起點,這一點你馬上會在代碼中體會到。
此外,正如我在開頭提到的,用戶隱私是 iOS 的重要組成部分,處理時要格外注意。眾所周知,用戶可在第三方應用中選擇允許或拒絕它們使用聯系人信息,因此確保你的應用隨時都被授權這麼做非常重要。借助 CNContactStore,你可以查看應用的當前授權狀態(current authorization status)。始終牢記:用戶可隨時通過設置禁止你的應用獲取聯系人數據,儘管它起初是被允許的,所以務必確認任務能否執行,並在每種情形下引導應用朝正確方向發展。未被妥善處理的情形最終會導致糟糕的用戶體驗,而這正是你必須避免的。本教程會嚴格考慮 Demo 是否被授權的情況,甚至從這部分就開始。你馬上要寫的代碼,可以隨時在你的工程裡自由使用。
你馬上會看到,在下面這些場景中(有別於其他場景)contacts store 類都是必須的:
獲取聯系人信息時
創建、保存和更新一個聯系人時
使用 Contact Picker view controller 選擇聯系人時
牢記這一點後,我們初始化一個 CNContactStore 對象,並在整個類中一直使用它。當然,你也可以在需要時隨時創建新對象,但既然這個類代表了聯系人數據庫,又有什麼理由需要多個實例呢?首先打開 AppDelegate.swift,初始化並聲明一個 CNContactStore 屬性。在文件頂部添加:
var contactStore = CNContactStore()
並在類聲明頂部引入框架:
import Contacts
很好!在我們處理應用授權狀態及針對該狀態可做的操作之前,先寫下兩個簡單又方便的方法。注意它們並非繼續項目所必需,不用它們也能完成工作,但把一些實現特定目的的小方法封裝起來,實踐證明非常方便。
第一個小方法,是讓任何類都能簡便訪問應用的 delegate(AppDelegate)。通常,下面的代碼可訪問 app delegate:
UIApplication.sharedApplication().delegate as! AppDelegate
但我個人覺得,每次需要獲取 app delegate 都要寫這麼多代碼,像是被打斷了思路。如果我們編寫下面這個類方法會怎樣?
class func getAppDelegate() -> AppDelegate { return UIApplication.sharedApplication().delegate as! AppDelegate }這樣,我們就能以更簡便的方式訪問 app delegate 的任何屬性或方法。例如,可在工程任意類中獲取 contacts store 屬性:
AppDelegate.getAppDelegate().contactStore
第二個便捷方法,是一個展示提示信息的 controller,提示文本通過參數傳入。實現並不複雜,但有個特殊之處要注意:提示 controller 必須由某個 view controller 展示,而 app delegate 並非 view controller。
為解決這個問題,我們需要找到當前 app window 上最頂層的 view controller,再在它上面展示提示 controller。實現如下:
func showMessage(message: String) { let alertController = UIAlertController(title: "Birthdays", message: message, preferredStyle: UIAlertControllerStyle.Alert) let dismissAction = UIAlertAction(title: "OK", style: UIAlertActionStyle.Default){ (action) -> Void in } alertController.addAction(dismissAction) let pushedViewControllers = (self.window?.rootViewController as! UINavigationController).viewControllers let presentedViewController = pushedViewControllers[pushedViewControllers.count - 1] presentedViewController.presentViewController(alertController, animated: true, completion: nil) }現在做一件重要的事——處理應用的授權狀態。它由 CNAuthorizationStatus 枚舉呈現,屬於 CNContactStore 類,包含以下 4 種值:
NotDetermined:表示用戶迄今尚未允許或拒絕對聯系人數據庫的訪問,應用首次安裝時即為此狀態。
Restricted:表示應用不僅不能訪問聯系人數據,用戶也無權在設置中修改該權限,這可能是其他活躍限制(如家長控制)所致。
Denied:表示用戶已選擇不允許訪問聯系人信息,而這只能由用戶本人更改。
Authorized:這是所有應用的理想狀態,此時可自由訪問數據庫並執行需要聯系人數據的任務。
有一點必須弄清楚:安裝應用後,用戶第一次(且仅第一次)試圖與聯系人數據交互(例如獲取聯系人信息)時,iOS 會彈出一個預定義提示 controller 請求授權:

若用戶允許,一切順利;若用戶拒絕,那麼所有基於聯系人信息的功能都無法執行。在我們的 Demo 中,這種情形下我們將展示一個自定義提示(用上面已實現的方法),告知用戶必須在設置裡允許訪問聯系人信息的權限。我們會即將實現的新方法裡處理這種情況,並在該方法中兼顧所有可能的授權狀態。先看看這個方法長什麼樣,稍後再詳細講解:
func requestForAccess(completionHandler: (accessGranted: Bool) -> Void) { let authorizationStatus = CNContactStore.authorizationStatusForEntityType(CNEntityType.Contacts) switch authorizationStatus { case .Authorized: completionHandler(accessGranted: true) case .Denied, .NotDetermined: self.contactStore.requestAccessForEntityType(CNEntityType.Contacts, completionHandler: {(access, accessError) -> Void in if access { completionHandler(accessGranted: access) } else { if authorizationStatus == CNAuthorizationStatus.Denied { dispatch_async(dispatch_get_main_queue(), {() -> Void in let message = "\(accessError!.localizedDescription)\n\nPlease allow the app to access your contacts through the Settings." self.showMessage(message) }) } } }) default: completionHandler(accessGranted: false) } }查看上面的方法,你會看到它包含一個 completion handler:應用被允許訪問時返回 true,反之返回 false。有些狀態很簡單,比如 Authorized 或 Restricted,此時 completion handler 的取值一目了然;而有意思的是,Denied 與 NotDetermined 被放在同一個 case 裡處理,並都調用了 requestAccessForEntityType:completionHandler: 請求訪問權限。對於單純的 Denied 情況,先前說的自定義消息將會被展示。
注意,requestAccessForEntityType:completionHandler: 和 authorizationStatusForEntityType: 都需要一個 CNEntityType 參數。它是個枚舉,只包含一個叫 Contacts 的值,實際上指明了我們要求訪問的實體。
從現在起,這個方法將被多次使用,下一部分馬上就要用到。每當我們要對聯系人信息做相關操作時,都會用到它,以確保了解操作能否繼續,並處理每個可能遇到的情況,避免糟糕的用戶體驗。看來一切都已就緒,因為我們準備好了一些可重複使用的代碼,隨著深入,它們會越發便利。
使用 Predicates 獲取聯系人信息
正如本教程開頭提到的,我們將用 3 種不同方法獲取聯系人信息。其中一種,是在文本輸入框裡輸入想獲取的聯系人(們)姓名(名或姓)的一部分或全部,再向 Contacts 框架獲取結果。我們從這裡開始,其關鍵方法是 unifiedContactsMatchingPredicate:keysToFetch:error:。
這個方法屬於 CNContactStore,需要 2 個重要參數:
Predicate:一個 NSPredicate 對象,作為返回結果的過濾器。必須強調:只有從 CNContact 類獲得的 predicates 才會被接受,你自己創建的普通 predicates 則不行。在所有支持獲取 predicate 的 CNContact 類方法中,我們將使用 predicateForContactsMatchingName:。
keysToFetch:通過設置它,你指定想獲取的聯系人部分信息。它是一個數組,包含描述被搜索聯系人(CNContact 對象)屬性值的字符串。框架提供了預定義的常量字符串作為鍵值(keys)。
注意:這個方法可能拋出 exception,因此必須在帶 try 關鍵字的 do-catch 聲明中調用,錯誤情況由 catch 處理。它的返回值,是所有符合給定 predicate 的 CNContact 對象數組,或出錯時返回 nil。
記住這些後,就繼續實現。這次打開 AddContactViewController.swift,直接找到文件頂部,引入 Contacts 框架(否則什麼都做不了)。
import Contacts
接著找到 textFieldShouldReturn: 代理方法。首先使用在 app delegate 中創建的最後一個方法,查看應用是否有獲取權限以便繼續:
func textFieldShouldReturn(textField: UITextField) -> Bool { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { } } return true }若已授權,我們便可準備匹配 predicate 與 keys,同時聲明其他變量:一個存儲結果(若有)的數組,一個字符串用來存儲沒有匹配結果或獲取失敗時要展示的自定義消息。
func textFieldShouldReturn(textField: UITextField) -> Bool { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { let predicate = CNContact.predicateForContactsMatchingName(self.txtLastName.text!) let keys = [CNContactGivenNameKey, CNContactFamilyNameKey, CNContactEmailAddressesKey, CNContactBirthdayKey] var contacts = [CNContact]() var message: String! } } return true }注意我們是怎樣指明 predicate 與 keys 數組的,然後繼續。下一步,我們試圖獲取聯系人數據,若成功,一開始創建的 contacts 數組便會被填滿返回結果;若沒找到或獲取失敗,則展示自定義消息。有了這些,這個方法的實現基本完成:
func textFieldShouldReturn(textField: UITextField) -> Bool { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { let predicate = CNContact.predicateForContactsMatchingName(self.txtLastName.text!) let keys = [CNContactGivenNameKey, CNContactFamilyNameKey, CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey] var contacts = [CNContact]() var message: String! let contactsStore = AppDelegate.getAppDelegate().contactStore do { contacts = try contactsStore.unifiedContactsMatchingPredicate(predicate, keysToFetch: keys) if contacts.count == 0 { message = "No contacts were found matching the given name." } } catch { message = "Unable to fetch contacts." } if message != nil { dispatch_async(dispatch_get_main_queue(), {() -> Void in AppDelegate.getAppDelegate().showMessage(message) }) } else { } } } return true }如你所見,我們在 else 裡什麼都沒實現,但馬上就會回來補上缺失的代碼。這部分最重要的是理解我們如何獲取匹配給出名字的聯系人信息,以及在非預想情況下如何處理。
展示獲取到的聯系人
最好的情況,是我們的獲取操作返回了匹配的聯系人,接著就有必要在 ViewController 的 tableview 中展示它們。但第一步,是告訴 ViewController 聯系人已被獲取,而這發生在 AddContactViewController 裡。最好且最簡單的實現,是採用熟悉的 Delegate 模式。因此,我們沿著這個思路填補應用中的銜接點。
在 AddContactViewController.swift 中,於類上方創建下面這個只有一個方法的協議:
protocol AddContactViewControllerDelegate { func didFetchContacts(contacts: [CNContact]) }通過這個代理方法,我們不僅能讓 ViewController 知道聯系人已被獲取,還能借此傳遞新獲取的聯系人信息。接著,在 AddContactViewController 裡添加代理聲明:
var delegate: AddContactViewControllerDelegate!
回想一下,我們在 textFieldShouldReturn: 最後的 else 裡留了空白,現在是時候補上缺失代碼了。實際上只缺兩行:一是調用剛聲明的 delegate 方法,二是在 navigation controller 中彈出 view controller。
func textFieldShouldReturn(textField: UITextField) -> Bool { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { ... if message != nil { ... } else { dispatch_async(dispatch_get_main_queue(), {() -> Void in self.delegate.didFetchContacts(contacts) self.navigationController?.popViewControllerAnimated(true) }) } } } return true }如你所見,處理涉及 UI 的操作時,我們都會使用主線程。這是個不容忘記的重要細節,否則 UI 無法在合適的時間更新,你就會遭遇應用的非預期反應。
現在轉到 ViewController.swift 處理獲取到的聯系人。首先,這個類裡也必須引入 Contacts 框架。
import Contacts
接著,我們需要採用新建的自定義協議,因此在類名後加上協議名:
class ViewController: UIViewController, UITableViewDelegate, UITableViewDataSource, AddContactViewControllerDelegate
現在,需要聲明一個 CNContact 對象的數組。它會保存所有從獲取請求得到的聯系人,並作為我們 tableview 的 datasource。在 ViewController 頂部添加:
var contacts = [CNContact]()
還有,必須更新 tableview 要展示的行數:
func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int { return contacts.count }在我們實現先前聲明的 delegate 方法之前,必須聲明 ViewController 是 AddContactViewControllerDelegate 的 delegate。這會在 prepareForSegue: 中實現:
override func prepareForSegue(segue: UIStoryboardSegue, sender: AnyObject?) { if let identifier = segue.identifier { if identifier == "idSegueAddContact" { let addContactViewController = segue.destinationViewController as! AddContactViewController addContactViewController.delegate = self } } }最後,實現我們自定義的 delegate 方法。在裡面,我們一個個取出返回的聯系人,把它們都加進 contacts 數組,最後重新加載 tableview 以展示最新信息。
func didFetchContacts(contacts: [CNContact]) { for contact in contacts { self.contacts.append(contact) } tblContacts.reloadData() }現在來展示聯系人信息。每個 cell 將展示聯系人的姓與名,有出生日期就展示,沒有則展示簡短提示,若有圖像和家庭郵箱也一併展示。下面的實現後文還會略作調整,但已足以讓你了解聯系人屬性是如何被獲取的:
func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCellWithIdentifier("idCellContactBirthday") as! ContactBirthdayCell let currentContact = contacts[indexPath.row] cell.lblFullname.text = "\(currentContact.givenName) \(currentContact.familyName)" // Set the birthday info. if let birthday = currentContact.birthday { cell.lblBirthday.text = "\(birthday.year)-\(birthday.month)-\(birthday.day)" } else { cell.lblBirthday.text = "Not available birthday data" } // Set the contact image. if let imageData = currentContact.imageData { cell.imgContactImage.image = UIImage(data: imageData) } // Set the contact's home email address. var homeEmailAddress: String! for emailAddress in currentContact.emailAddresses { if emailAddress.label == CNLabelHome { homeEmailAddress = emailAddress.value as! String break } } if homeEmailAddress != nil { cell.lblEmail.text = homeEmailAddress } else { cell.lblEmail.text = "Not available home email" } return cell }讓我們過一遍上述步驟。首先,把姓與名連接起來設置聯系人全名(稍後我會展示另一種獲取全名的方法,這裡先用此法)。接著設置生日信息,若有生日就用最簡單的方式展示(這只是臨時方案,稍後會用更合適的方法構建)。要特別注意,生日信息並非 NSDate 對象,而是一個 NSDateComponents 對象,它可以轉為 NSDate,再轉為 String。下面設置圖像數據,若不存在,你會看到我在自定義 cell 的 xib 中加的 imgContactImage 背景色。最後設置家庭郵件地址,我們用一個循環遍歷所有郵件地址直到找到目標——這是因為 emailAddresses 屬性包含了所有以郵箱地址為標簽值(labeled values)的 CNLabeledValue 對象。
如果你現在運行應用,根據輸入的名字,上面的實現可能有用,也可能沒用;在第二種情況下應用會崩潰,但你無需擔心,我們稍後會改進。我故意沒給你展示最終版,就是為了讓你更清楚地看到一切是怎樣運作的。
重新獲取聯系人
應用可能崩潰的原因,是並非所有你要獲取的聯系人屬性都存在。為此,CNContact 類提供了一個叫 isKeyAvailable: 的方法,它必須在你訪問任何聯系人屬性之前調用。例如,在展示生日、圖片和郵箱前,應添加如下檢查:
if currentContact.isKeyAvailable(CNContactBirthdayKey) { ... } if currentContact.isKeyAvailable(CNContactImageDataKey) { ... } if currentContact.isKeyAvailable(CNContactEmailAddressesKey) { ... }若某個 key 沒被找到,就必須重新獲取這個聯系人再展示。這正是我們現在要做的——在 ViewController 裡創建一個新方法。但在此之前,先用 isKeyAvailable: 修補一下展示聯系人的實現。實際上,與其為上述每個屬性加三個判斷,不如只寫一個判斷:一旦有缺失,就調用即將實現的方法重新獲取。我故意沒提聯系人姓名這個關鍵詞,因為後文會詳談。
func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCellWithIdentifier("idCellContactBirthday") as! ContactBirthdayCell let currentContact = contacts[indexPath.row] cell.lblFullname.text = "\(currentContact.givenName) \(currentContact.familyName)" if !currentContact.isKeyAvailable(CNContactBirthdayKey) || !currentContact.isKeyAvailable(CNContactImageDataKey) || !currentContact.isKeyAvailable(CNContactEmailAddressesKey) { refetchContact(contact: currentContact, atIndexPath: indexPath) } else { // Set the birthday info. if let birthday = currentContact.birthday { cell.lblBirthday.text = "\(birthday.year)-\(birthday.month)-\(birthday.day)" } else { cell.lblBirthday.text = "Not available birthday data" } // Set the contact image. if let imageData = currentContact.imageData { cell.imgContactImage.image = UIImage(data: imageData) } // Set the contact's work email address. var homeEmailAddress: String! for emailAddress in currentContact.emailAddresses { if emailAddress.label == CNLabelHome { homeEmailAddress = emailAddress.value as! String break } } if homeEmailAddress != nil { cell.lblEmail.text = homeEmailAddress } else { cell.lblEmail.text = "Not available home email" } } return cell }上面調用的方法,就是我們馬上要實現的。這裡的判斷邏輯應當一目了然。通過這個改動,即便結果中包含不可用的鍵值,應用也不會再崩潰。
現在看新方法:
func refetchContact(contact contact: CNContact, atIndexPath indexPath: NSIndexPath) { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { let keys = [CNContactGivenNameKey, CNContactFamilyNameKey, CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey] do { let contactRefetched = try AppDelegate.getAppDelegate().contactStore.unifiedContactWithIdentifier(contact.identifier, keysToFetch: keys) self.contacts[indexPath.row] = contactRefetched dispatch_async(dispatch_get_main_queue(), {() -> Void in self.tblContacts.reloadRowsAtIndexPaths([indexPath], withRowAnimation: UITableViewRowAnimation.Automatic) }) } catch { print("Unable to refetch the contact: \(contact)", separator: "", terminator: "\n") } } } }首先檢查應用是否被授權訪問數據庫,接著指定想獲取的鍵值,然後重新針對該聯系人獲取。這次我們用了一個新方法 unifiedContactWithIdentifier:keysToFetch:,它用於獲取滿足標識符參數值的特定聯系人。結果返回後,我們用新信息替換數組中的舊信息,最後重新加載 tableview 的特定行。
如果想,可以再運行試試。萬一某些信息沒獲取到,你最好始終做一下重新獲取,以確保應用不會給用戶任何「驚喜」。
格式化輸出結果
正如你目前所見,在 cell 上展示生日前,我們還沒做合適的格式轉換,只是鏈接並展示了生日屬性。現在,學會了先前的重要知識後,是時候處理這個問題了。
我們將在 ViewController 中創建一個新的自定義方法來修補生日。在裡面,我們用一個 NSDateFormatter 把日期信息轉為本地化字符串,但首先,必須把日期組件(即日期部分)轉成 NSDate 對象。看看這個新方法:
func getDateStringFromComponents(dateComponents: NSDateComponents) -> String! { if let date = NSCalendar.currentCalendar().dateFromComponents(dateComponents) { let dateFormatter = NSDateFormatter() dateFormatter.locale = NSLocale.currentLocale() dateFormatter.dateStyle = NSDateFormatterStyle.MediumStyle let dateString = dateFormatter.stringFromDate(date) return dateString } return nil }方法的參數是 NSDateComponents 表示的日期(這裡就是出生日期),返回值自然是字符串。把 dateComponents 轉為 NSDate 用不到一行代碼:我們用 NSCalendar 類完成轉換,得到 date 後交由即將初始化的 date formatter 處理。給 date formatter 設置當前地理信息是必須的,這樣才能獲得本地化的日期描述。最終,我們給日期設置一個偏好的格式(不太長也不太短),再執行最終轉換,把結果返回給調用者。
現在修復日期展示,僅需調用上面的函數:
func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell { ... if !currentContact.isKeyAvailable(CNContactBirthdayKey) || !currentContact.isKeyAvailable(CNContactImageDataKey) || !currentContact.isKeyAvailable(CNContactEmailAddressesKey) { refetchContact(contact: currentContact, atIndexPath: indexPath) } else { // Set the birthday info. if let birthday = currentContact.birthday { cell.lblBirthday.text = getDateStringFromComponents(birthday) } ... } return cell }很好,生日現在將以更美觀時尚的方式展現。
接著看看姓與名的展示。CNContact 類提供了內嵌格式轉換器,能幫我們輕鬆格式化兩種數據:聯系人全名(CNContactFormatter)與地址(CNPostalAddressFormatter)。我們現在用第一個,讓聯系人全名自動被框架格式化。
最後一次更改聯系人展示方法:
func tableView(tableView: UITableView, cellForRowAtIndexPath indexPath: NSIndexPath) -> UITableViewCell { let cell = tableView.dequeueReusableCellWithIdentifier("idCellContactBirthday") as! ContactBirthdayCell let currentContact = contacts[indexPath.row] cell.lblFullname.text = CNContactFormatter.stringFromContact(currentContact, style: .FullName) ... return cell }如你所見,這行 cell.lblFullname.text = "\(currentContact.givenName) \(currentContact.familyName)" 已被替換為:
cell.lblFullname.text = CNContactFormatter.stringFromContact(currentContact, style: .FullName)
顯然,我們不再需要手動鏈接姓與名來拼出全名了,CNContactFormatter 幫我們完成了,而且它輸出的還是本地化字符串(會依據設備本地化設置,以適當順序排列名字部分)。
不過,上面的操作會引出一些複雜情況,因為聯系人格式器需要訪問與一個聯系人名字相關的所有關鍵字,哪怕是那些我們沒在獲取數組裡指定的。但我們不必一個個寫下它們——所有相關關鍵字都由一個 key descriptor 指定,它替代了關鍵字數組裡的所有單個關鍵字。
更具體地說,找到 AddContactViewController 文件,在 textFieldShouldReturn: 裡,把下面這行:
let keys = [CNContactGivenNameKey, CNContactFamilyNameKey, CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey]
替換成使用 key descriptor 的代碼:
let keys = [CNContactFormatter.descriptorForRequiredKeysForStyle(CNContactFormatterStyle.FullName), CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey]
這個 descriptor 的組織方式很講究,正如上面展示的那樣,其餘關鍵字保持不變。
同樣的改動必須在 refetchContact: 方法(ViewController 裡)中執行,你只需用上面那行替換關鍵字數組的定義即可:
func refetchContact(contact contact: CNContact, atIndexPath indexPath: NSIndexPath) { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { let keys = [CNContactFormatter.descriptorForRequiredKeysForStyle(CNContactFormatterStyle.FullName), CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey] ... } } }通過這些處理,我們已在代碼裡完成了所有與格式相關的改動。當然,你也可以仍用單個關鍵字來獲取單個名字信息,這取決於你的需求。
使用自定義過濾器獲取聯系人
本教程最先展示的內容之一,就是如何用 predicates 獲取聯系人。我們用 Contacts 框架的 predicate 獲取匹配某名字的聯系人,但這個方法有個普遍劣勢:我們只能使用框架的內嵌 predicates,而不能用自己的。那麼,如何通過自定義過濾器獲取聯系人?
對我們的 Demo 而言,這個問題可以更具體化:我們能否基於聯系人的生日月份來獲取聯系人?在 AddContactViewController 中有一個展示所有月份的 picker view,我們現在想做的是:選取一個月份,點擊 Done,然後得到生日月份與所選月份相同的聯系人。
你可能猜到,有一個解法是「添加」自定義過濾器,但整個過程比起用 predicates 更多一點人工操作。總體上,我們將採用的方法是蘋果在這種情況下推薦的:基於 CNContactStore 的 enumerateContactsWithFetchRequest(_:usingBlock:) 方法。它獲取所有聯系人,因此自定義標準可以在 block(或閉包)裡通過比較屬性值或應用其他自定義邏輯來設置,最終保留你真正需要的那部分。
在我們的情形下需檢查兩件事:其一,確保每個聯系人的生日日期都被設置,以避免不想要的崩潰;其二,只把生日月份與 picker view 裡選中的月份比較,若匹配則把該聯系人保留到數組裡。這其實很簡單,因為生日由 NSDateComponents 呈現,我們可直接訪問月份信息。其餘更簡單,所有要展示的內容都在前面講過了。我們只在 AddContactViewController 文件的 performDoneItemTap 自定義方法裡寫入新代碼,因為我們只想在 view controller 的 Done 按鈕被按下時,才獲取基於月份選擇的聯系人。
請看:
func performDoneItemTap() { AppDelegate.getAppDelegate().requestForAccess {(accessGranted) -> Void in if accessGranted { var contacts = [CNContact]() let keys = [CNContactFormatter.descriptorForRequiredKeysForStyle(CNContactFormatterStyle.FullName), CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey] do { let contactStore = AppDelegate.getAppDelegate().contactStore try contactStore.enumerateContactsWithFetchRequest(CNContactFetchRequest(keysToFetch: keys)) {(contact, pointer) -> Void in if contact.birthday != nil && contact.birthday!.month == self.currentlySelectedMonthIndex { contacts.append(contact) } } dispatch_async(dispatch_get_main_queue(), {() -> Void in self.delegate.didFetchContacts(contacts) self.navigationController?.popViewControllerAnimated(true) }) } catch let error as NSError { print(error.description, separator: "", terminator: "\n") } } } }如你所見,結束時我們調用了 delegate,讓新聯系人在 ViewController 的 tableview 中更新,然後彈出 view controller。這段代碼在很多場景下都適用,因為你要做的僅是改動 block 裡過濾標準的參數。
Contact Picker View Controller
目前我們所有的聯系人管理都是編程式的,但故事還沒結束。Contacts 框架提供了 view controllers(UI),讓你能直接、可視地訪問聯系人信息並立即與它交互。這些 UI 與「聯系人」應用裡的非常相似:一個 picker controller 用來選擇一條或多條聯系人記錄,一個 view controller 用來查看詳情,還有一個表單用來編輯信息。選擇聯系人時,重寫默認行為是被允許的,且有 delegate 方法讓你自己處理結果。
這部分,我們將展示如何用 picker view controller 選擇並導入聯系人記錄到自己的應用。要做的準備不多,但定制化程度取決於各應用的需要。Contacts 框架允許設置三種可選 predicates,用來限制聯系人的展示並改變默認行為:
predicateForEnablingContact:這可能是你用得最多的。有了它,你可以指定 picker controller 裡哪些聯系人可用,用來過濾出需要的聯系人,比如只讓那些有有效生日日期的聯系人可被選擇。
predicateForSelectionOfContact:有了它,你可以控制 picker view controller 在哪種條件下返回被選中的聯系人,以及對其他選中模式,什麼時候展示 details view controller。
predicateForSelectionOfProperty:用它,你可以指定某屬性的默認響應是否應被執行(比如點擊電話號碼時是否創建打電話行為),還是被點擊的屬性是否應被返回。
這裡我們只用第一個 predicate,向 picker view controller 請求:只允許那些有生日日期的聯系人可用。用另外兩個並不難,只是這裡不需要;為給你參考,我推薦查閱相關文檔。
回到應用,打開 AddContactViewController.swift,找到最頂端,引入 ContactsUI 框架:
import ContactsUI
接著,採用 CNContactPickerDelegate 協議,以便處理返回的記錄:
class AddContactViewController: UIViewController, UITextFieldDelegate, UIPickerViewDelegate, CNContactPickerDelegate
從現在起,我們的工作在 showContacts: IBAction 裡進行。這個方法會讓 AddContactViewController 底部的按鈕生效。實現如下:
@IBAction func showContacts(sender: AnyObject) { let contactPickerViewController = CNContactPickerViewController() contactPickerViewController.predicateForEnablingContact = NSPredicate(format: "birthday != nil") contactPickerViewController.delegate = self presentViewController(contactPickerViewController, animated: true, completion: nil) }就這麼簡單!在本 Demo 中,點擊聯系人時我們不展示它的詳情卡。但若你想在應用裡這麼做,可以在詳情界面輕鬆控制要展示的屬性:只需在名為 displayedPropertyKeys 的屬性裡,聲明一個你想展示的屬性關鍵字數組。例如,若想在應用中展示詳情,可在展示 picker 前加上這行:
contactPickerViewController.displayedPropertyKeys = [CNContactGivenNameKey, CNContactFamilyNameKey, CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey]
先前我們採用了 CNContactPickerDelegate 協議,現在實現那個必須的 delegate 方法。在裡面,我們會得到被選中的記錄,再通過自定義 delegate 把它們返回給 ViewController:
func contactPicker(picker: CNContactPickerViewController, didSelectContact contact: CNContact) { delegate.didFetchContacts([contact]) navigationController?.popViewControllerAnimated(true) }若想展示詳情並處理返回的屬性值,你需要用 contactPicker:didSelectContactProperty: 這個 delegate 方法。這裡我們不實現它,因為用不到;所有 delegate 方法的集合可在文檔中找到。
可以再次驗證應用了。這次用「Open contacts to select」按鈕展示 picker view controller,你會發現沒有有效生日日期的聯系人不會展示。選擇一個聯系人,你將看到它在 ViewController 的 tableview 中被展示。

Contacts View Controller
目前我們實現了 3 種獲取聯系人並添加到應用的方法,但僅在 tableview 中展示它們顯然不夠——我們要求更多,希望在一個新的 view controller 裡展示被選中的聯系人。實際上,我們不會自定義 view controller,而是使用 Contacts 框架提供的 contact view controller。用它,我們不僅能查看聯系人數據,還能編輯數據,這由 CNContactViewController 實現。
回到 ViewController.swift,處理用戶點擊某個聯系人的情況。在展示 CNContactViewController 之前,我們必須確保該選中聯系人詳情對應的所有關鍵字都可用。儘管我們在展示每行時都檢查了關鍵字是否可用、必要時還會重新獲取,但仍不能百分百排除用戶點擊某行快於重新獲取的情況,因此這個操作必須做。
先前我們用 CNContact 的 isKeyAvailable: 檢查某關鍵字是否可用;除此之外,類還提供了 areKeysAvailable:,我們可用它確保 contacts view controller 需要的所有關鍵字都存在。這個方法只需一個參數——一個關鍵字字符串或字符串描述器(key descriptors 與我們多次用來獲取聯系人的關鍵字字符串類似)。在 CNContactViewController 中,我們必須給 CNContactViewController.descriptorForRequiredKeys() 傳入一個特定關鍵字組成的數組,這個類方法會自動檢查所有關鍵字是否存在。若都存在,我們就展示 contacts view controller;若不存在,我們會像先前那樣,用 descriptorForRequiredKeys() 指明要獲取的關鍵字,再重新獲取聯系人。
另外,貫穿整個 Demo 的、用來獲取聯系人的關鍵字數組,在這裡又一次被證明非常方便——不是在可用性檢查裡,而是在指定哪些屬性該展示在 contacts view controller 裡。你能在下面的實現中看到它是怎樣被使用的。一個額外提示:記住,若你忽略這個屬性,那麼所有聯系人屬性(不僅是我們想展示的)都會被 contacts view controller 展示。
說了這麼多,看看代碼:
func tableView(tableView: UITableView, didSelectRowAtIndexPath indexPath: NSIndexPath) { let selectedContact = contacts[indexPath.row] let keys = [CNContactFormatter.descriptorForRequiredKeysForStyle(CNContactFormatterStyle.FullName), CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactImageDataKey] if selectedContact.areKeysAvailable([CNContactViewController.descriptorForRequiredKeys()]) { let contactViewController = CNContactViewController(forContact: selectedContact) contactViewController.contactStore = AppDelegate.getAppDelegate().contactStore contactViewController.displayedPropertyKeys = keys navigationController?.pushViewController(contactViewController, animated: true) } else { AppDelegate.getAppDelegate().requestForAccess({(accessGranted) -> Void in if accessGranted { do { let contactRefetched = try AppDelegate.getAppDelegate().contactStore.unifiedContactWithIdentifier(selectedContact.identifier, keysToFetch: [CNContactViewController.descriptorForRequiredKeys()]) dispatch_async(dispatch_get_main_queue(), {() -> Void in let contactViewController = CNContactViewController(forContact: contactRefetched) contactViewController.contactStore = AppDelegate.getAppDelegate().contactStore contactViewController.displayedPropertyKeys = keys self.navigationController?.pushViewController(contactViewController, animated: true) }) } catch { print("Unable to refetch the selected contact.", separator: "", terminator: "\n") } } }) } }可以看到,我們簡單地用 contacts view controller 實例的 displayedPropertyKeys 屬性就指定了要展示的屬性值。另一個值得注意的細節,是我們用 contactStore 屬性向 contacts view controller 提供 contact store 實例。若應用中沒有已存在的 CNContactStore 實例,這也不是強制要做的,因為 CNContactViewController 會自動創建一個新的。其餘內容都已討論過。最後,別忘了在文件頂端引入:
import ContactsUI
創建和保存一個新的聯系人
到目前為止,我們已看到這個新聯系人框架的許多特性,但還有一部分尚未討論——如何在代碼裡創建新聯系人並存入數據庫。因此,這部分我們將覆蓋這個方面。我不會花過多篇幅講解如何更新已有記錄,因為它與馬上要看到的任務很類似,我把找出兩者不同點的練習留給你。
除了 CNContact 呈現單個記錄及其所有屬性外,Contacts 框架還提供了另一個類——CNMutableContact。顧名思義,它與第一個類相似,但允許重新給聯系人屬性賦值,從而創建新記錄或更新已有記錄。真正的保存(更新)操作仍由我們熟知的 contact store(CNContactStore)處理,這是創建新聯系人的最後一步。你馬上會看到細節。
總體說,用 CNMutableContact 給記錄設置屬性,包含獲取時的相反操作。意味著:簡單屬性(如名字)只需直接賦值,而特殊屬性則需特殊操作。例如:
設置生日時,需創建並恰當賦值一個 NSDateComponents 對象。
設置聯系人圖像時,需賦值一個 NSData 對象。
設置郵箱時,需為每個郵箱創建一個 CNLabeledValue 對象,再把它們組成數組賦給 emailAddresses 屬性。
這只是幾個例子,當然還有更多需小心對待的屬性,但無論如何,如你將看到的,這些操作都不難。
回到 Demo,這次切換到 CreateContactViewController.swift。在裡面,你會找到一個空的自定義方法 createContact(),接下來要做的事都寫在這裡。簡單說,我們創建一個新的 CNMutableContact 實例,給所有感興趣的屬性賦值,最後用 contact store 把新記錄存入數據庫。看看實現:
func createContact() { let newContact = CNMutableContact() newContact.givenName = txtFirstname.text! newContact.familyName = txtLastname.text! let homeEmail = CNLabeledValue(label: CNLabelHome, value: txtHomeEmail.text!) newContact.emailAddresses = [homeEmail] let birthdayComponents = NSCalendar.currentCalendar().components([NSCalendarUnit.Year, NSCalendarUnit.Month, NSCalendarUnit.Day], fromDate: datePicker.date) newContact.birthday = birthdayComponents do { let saveRequest = CNSaveRequest() saveRequest.addContact(newContact, toContainerWithIdentifier: nil) try AppDelegate.getAppDelegate().contactStore.executeSaveRequest(saveRequest) navigationController?.popViewControllerAnimated(true) } catch { AppDelegate.getAppDelegate().showMessage("Unable to save the new contact.") } }從頭分析:第一步初始化一個後面一直要用的 CNMutableContact 對象。設置姓與名顯然很簡單。接下來,家庭郵箱屬性需創建為 CNLabeledValue 對象(方法如上),創建好後作為郵箱數組的一部分賦給 emailAddresses(本例中沒有其他地址)。最後,基於用戶選擇的日期給新聯系人設置生日——如上所示,用 NSCalendar 從 NSDate 創建 NSDateComponents 非常簡單,注意日曆單元(year、month、day)是如何組合成最終屬性值的。
這段代碼裡最有趣的部分,是新記錄如何被存儲。你可能注意到,有必要先創建一個 CNSaveRequest 對象,再把新聯系人加給它,此時還沒有任何實質的存儲操作。真正的存儲發生在 contact store 對象的 executeSaveRequest: 被調用的那一刻。當新記錄無法存儲時,會向用戶展示一條警告。
運行應用,用 ViewController 左邊的導航欄按鈕創建一個新聯系人,保存記錄,再用前面提到的任一方法搜索它。

重要提示:寫這篇教程時我注意到,在測試中,當創建新記錄並存儲到數據庫後,再想通過應用訪問聯系人詳情(點擊某個聯系人)時,就不再被允許了。調試面板會出現: [CNUI ERROR] error calling service – Couldn't communicate with a helper application. 目前網上還沒有什麼有用的幫助,只是把這作為一個 bug 提交給了 Apple。記住這一點,測試時要避免同時創建聯系人記錄。
總結
到了教程最後,希望我已讓你清楚看到:與新的 Contacts 框架打交道是多麼簡單。如果你以前用過 AddressBook API,就可以證實,這裡的方法與它們相比可謂天翻地覆。你可以盡情使用並改寫、擴展這個 Demo,它始終有提升空間。不過千萬別忘了用戶隱私設置,必須尊重用戶對是否允許應用訪問聯系人信息的選擇。也別錯過官方文檔,你會在那裡找到更多有趣內容。希望你喜歡這個教程並覺得有用;下次見,祝你愉快!
作為參考,你可以在這裡下載完整的 Xcode project。