
本文由 CocoaChina 譯者 lynulzy 翻譯,作者 Ed Sasena,原文 Getting Started with MagicalRecord(轉載請保留內容與所有連結的完整性)。
Core Data 是 Apple 內建的資料持久化解決方案,iOS 與 OS X 通用。即便 Apple 一直以「讓開發更簡單」為目標,Core Data 對有經驗的開發者也不算友善。
更麻煩的是,即使你熟悉它,很多日常任務寫起來仍然笨重瑣碎。好消息是 MagicalPanda 開源了 Core Data 的三方庫 MagicalRecord,它把設定、查詢、更新這些樣板程式碼收攏成便利方法,設計靈感來自經典的 Active Record 模式。
本教程會帶你實作一個 BeerTracker:記錄你最喜歡的啤酒,可新增、評分、寫評論、拍照。閱讀前建議具備基本的 Core Data 基礎。
下載起始專案,雙擊 BeerTracker.xcworkspace 開啟。

執行後會看到幾個與 MagicalRecord 相關的警告,暫時可以忽略。

這個 App 由一個帶導航欄的清單頁、搜尋框與排序用的分段控制項組成。點擊「+」會進入新增頁面,但目前資料不會被保存。
展開專案中的 BeerTracker 資料夾:

你會看到 Core Data 模型存在,卻沒有任何使用它的程式碼。接下來我們要做的,就是用 MagicalRecord 操作這個模型,而不必手寫一堆框架程式碼。
開啟 Pods 專案的 Pods 資料夾:

打開 Shorthand 下的 NSManagedObjectModel+MagicalRecord.h,會發現方法名都帶有 MR_ 前綴——因為 MagicalRecord 是對 Core Data 類別的擴充,這個命名空間可避免與既有方法衝突。
再看同一層 Support Files 裡的 Pods-BeerTracker-MagicalRecord-prefix.pch,有兩行值得注意:
#define MR_SHORTHAND 0 #import "CoreData+MagicalRecord.h"
第一行讓本工程不使用 MR_ 前綴(原理可參考 MagicalRecord+ShorthandSupport.m);第二行讓整個專案都能使用 MagicalRecord 的 API。
在 Beer.swift 的 class 宣告前加上:
@objc(Beer)
這樣 Beer 模型就能被 Objective-C runtime 與 Core Data 正確識別。BeerDetails.swift 也照同樣方式加上 @objc(BeerDetails)。
接著初始化 Core Data Stack。在 AppDelegate.swift 的 application(_:didFinishLaunchingWithOptions:) 中,return 之前加上一行:
MagicalRecord.setupCoreDataStackWithStoreNamed("Beer")
過去設定 stack 需要寫一大段程式碼,這裡一行就結束了。
MagicalRecord 提供多種初始化方式,可依需求挑選:
前提是模型檔名與專案名稱一致;若不一致(本教程即為此情況),就要用 setupCoreDataStackWithStoreNamed(_:) 或 setupCoreDataStackWithAutoMigratingSqliteStoreNamed(_:) 明確指定名稱。使用自動遷移版本時,MagicalRecord 會在满足條件的前提下處理舊模型到新模型的轉換。
編譯執行,外觀應該沒變化——所有改變都在背後的資料層。
在 BeerDetailViewController.swift 加上屬性:
var currentBeer: Beer!
並在 viewDidLoad() 末尾補上:
if let beer = currentBeer {
// 已有 beer:編輯模式
} else {
// 沒有 beer:新增模式
currentBeer = Beer.createEntity() as! Beer
currentBeer.name = ""
}
這個頁面由 BeerListViewController 觸發,途徑有二:點擊清單中的項目(編輯),或點擊「+」(新增)。程式碼檢查 currentBeer 是否已存在,不存在就建立一個新物件。
接著處理詳情實體:
let details: BeerDetails? = currentBeer.beerDetails
if let bDetails = details {
// 已有詳情:編輯模式
} else {
// 無詳情:新增模式,或編輯一個尚無詳情的 beer
currentBeer.beerDetails = BeerDetails.createEntity() as! BeerDetails
}
編譯執行確認無誤。畫面看起來沒變,耐心一些——好程式碼像好酒,需要時間。
在 viewDidLoad() 中補上名稱欄位:
if let bName = currentBeer.name {
beerNameTextField.text = bName
}
再補上備註、評分與圖片:
if let bdNote = details?.note {
beerNotesView.text = bdNote
}
let theRatingControl = ratingControl()
cellNameRatingImage.addSubview(theRatingControl)
if let bdRating = details?.rating {
theRatingControl.rating = Int(bdRating)
} else {
theRatingControl.rating = 0 // 新增模式
}
if let beerImagePath = details?.image {
if let bImage = UIImage(contentsOfFile: beerImagePath) {
showImage(bImage)
}
}
最後設定標題:
title = (currentBeer.name == "") ? "New Beer" : currentBeer.name
點擊「+」時會觸發 prepareForSegue(_:sender:),其中带 addBeer 標識的分支負責建立一個在點擊 Done 時呼叫 addNewBeer 的動作。addNewBeer() 會把詳情頁 pop 掉,進而觸發 viewWillDisappear,也就會呼叫 saveContext()。
在 saveContext() 中加入:
NSManagedObjectContext.defaultContext().saveToPersistendStoreAndWait()
這一行背後做了很多事:AppDelegate 中設定的 Core Data Stack 會建立一個全域可用的 defaultContext,createEntity() 建立的物件預設被插入其中,而任何 managedObjectContext 都能透過這個方法保存。
接著把使用者輸入寫進屬性。textFieldDidEndEditing(_:) 中:
currentBeer.name = textField.text
textViewDidEndEditing(_:) 末尾:
if textView.text != "" {
currentBeer.beerDetails.note = textView.text
}
updateRating() 中:
currentBeer.beerDetails.rating = ratingControl().rating
在 imagePickerController(_:didFinishPickingMediaWithInfo:) 中:
// 1. 先清掉舊圖
if let imageToDelete = currentBeer.beerDetails.image {
ImageSaver.deleteImageAtPath(imageToDelete)
}
// 2. 存檔並預覽
if ImageSaver.saveImageToDisk(image!, andToBeer: currentBeer) {
showImage(image!)
}
接著補完 ImageSaver.swift 中的方法簽名,把參數型別收緊為 Beer:
class func saveImageToDisk(image: UIImage, andToBeer beer: Beer?) -> Bool?
並在 else 之前加上:
beer.beerDetails.image = pathName
注意這裡存的是圖片路徑,而非圖片的二進位資料。
在 BeerListViewController.swift 加上屬性並在 fetchAllBeers() 末尾補上:
var beers: [Beer]! let sortKey = NSUserDefaults.standardUserDefaults().objectForKey(wbSortKey) as? String let ascending = (sortKey == sortKeyRating) ? false : true beers = Beer.findAllSortedBy(sortKey, ascending: ascending) as! [Beer]
findAllSortedBy(_:ascending:) 是 MagicalRecord 眾多查詢方法之一,更多可參考 NSManagedObject+MagicalFinders.m。
接著在 tableView(_:numberOfRowsInSection:) 回傳 beers.count,並在 configureCell(_:atIndex:) 開頭補上:
let currentBeer = beers[indexPath.row] cell.textLabel?.text = currentBeer.name
編譯執行,試著新增一筆:點「+」→ 輸入名稱 → 點 Done,返回後就會看到它出現在清單中。

若結果不如預期,可用 Xcode 的 Product > Clean 清一次,或直接把 App 從模擬器刪除(長按圖示直到抖動 → 點左上角刪除 → 確認 → 回到模擬器選單 Hardware > Home)。這招後面還會用到。
如果使用者按了「+」卻又改變主意,按下 Cancel 之後,清單裡會多出一筆沒有名稱的空行。

在 cancelAdd() 開頭加上:
currentBeer.deleteEntity()
因為 viewDidLoad() 已經建立了一個新的 Beer 物件,取消時就必須把它刪掉。想知道方法來源,可以高亮名稱 → 右鍵 → Jump to Definition。再次執行取消流程,空行就不會出現了。
先開啟 tableView 的編輯模式,在 tableView(_:commitEditingStyle:forRowAtIndexPath:) 中補上:
// 1. 從陣列移除並刪除實體、儲存 beers.removeAtIndex(indexPath.row).deleteEntity() saveContext() // 2. 暫存要刪除的行 let indexPaths = [indexPath] // 3. 通知 table view 刪除該行 tableView.deleteRowsAtIndexPaths(indexPaths, withRowAnimation: .Automatic) // 4. 重新載入 tableView.reloadData()
saveContext() 同樣要在 BeerListViewController 中補完:
NSManagedObjectContext.defaultContext().saveToPersistendStoreAndWait()
編譯執行,左滑清單中的空行並點 Delete 即可移除。

點擊清單項目卻跳到空白詳情頁?因為列表並沒有把 beer 傳過去。在 prepareForSegue(_:sender:) 中,於 editBeer 分支補上:
let indexPath = tableView.indexPathForSelectedRow() let beerSelected = beers[indexPath!.row] controller!.currentBeer = beerSelected controller!.currentBeer.beerDetails = beerSelected.beerDetails

改名後按 Done,清單會顯示新名稱。
起始專案已內建搜尋框,只差實作。在 performSearch() 中、tableView.reloadData() 之前補上:
let searchText = searchBar.text
let filterCriteria = NSPredicate(format: "name contains[c] %@", searchText)
beers = Beer.findAllSortedBy(sortKeyName, ascending: true,
withPredicate: filterCriteria,
inContext: NSManagedObjectContext.defaultContext()) as? [Beer]
其他查詢方法可參考 MagicalRecord 的標頭檔。

最終版的 AppDelegate.swift 提供兩種預載策略:一是只在首次啟動時寫入(以「是否已有未評論資料」為判斷),二是每次都強制寫入。後者適合當使用者刪掉了部分預設資料、又希望重新補上的情況。
App 啟動時,MagicalRecord 會印出 Core Data Stack 建立過程的四則紀錄;新增或修改 beer 並按下 Done 後,也會輸出保存流程的日誌,例如 defaultContext 在主線程保存、標記為 1 的 context 變更與同步、物件被插入 context 等。
它同樣會回報「沒有變更所以不保存」的情形:編譯執行 → 打開除錯主控台 → 選取既有項目 → 進入詳情頁後直接返回,就會看到:
NO CHANGES IN ** BACKGROUND SAVING (ROOT) ** CONTEXT – NOT SAVING
離開詳情頁會觸發 saveContext(),由於沒有任何改動,MagicalRecord 判斷不必保存便跳過。你不需要自己判斷該不該存,呼叫方法讓它決定就好。這些日誌通常藏著有價值的線索,值得一看。
最終專案可另行下載,卡在某一步時不妨對照。希望這篇教程能說明 MagicalRecord 的易用性——它在削減樣板程式碼上的效果相當明顯,而這套思路可以套用到任何需要持久化的 App。
若想繼續深化 BeerTracker,可以嘗試:
有任何問題歡迎加入討論。