iCarousel 是 iOS 上最常被拿來做「3D 轉盤式」列表的開源元件之一。它把 UITableView 的「按需載入、視圖回收」思路搬到了 3D 空間,支援線性、圓柱、車輪、封面流、時光機等多種展示樣式,甚至允許你自訂變換矩陣。以下把官方文件重新整理成一份可查閱的參考。
文件特別區分了兩個詞:Supported 代表該版本已通過測試;Compatible 代表理论上可運作(不依賴該版本缺失的 SDK 特性),但已不再進行相容性測試,可能需要小幅修改或修 bug 才能正確執行。
自 1.6.1 版起,iCarousel 透過條件式編譯同時支援 ARC 與非 ARC 專案,不需要把它從 ARC 驗證中排除,也不必用轉換工具處理。
執行緒方面,由於它繼承自 UIView,與所有 UIKit 組件一樣只能從主線程存取。你可以在背景執行緒下載或準備內容,但更新 carousel 之前務必切回主線程。
把 iCarousel 的類別檔案(不含 demo 與素材)拖進專案,然後加入 QuartzCore framework 即可。
若要搭配 Chameleon(iOS 專案移植到 Mac 的轉換庫),在預處理器巨集中加入 USING_CHAMELEON。需要注意的是,tap-to-center 目前無效,捲動必須用雙指手勢而非點擊拖曳,這些限制源自 Chameleon 手勢辨識器的實作。
iCarouselTypeLinear:線性iCarouselTypeRotary / iCarouselTypeInvertedRotary:旋轉 / 反向旋轉iCarouselTypeCylinder / iCarouselTypeInvertedCylinder:圓柱 / 反向圓柱iCarouselTypeWheel / iCarouselTypeInvertedWheel:車輪 / 反向車輪iCarouselTypeCoverFlow / iCarouselTypeCoverFlow2:封面流 / 封面流 2iCarouselTypeTimeMachine / iCarouselTypeInvertedTimeMachine:時光機 / 反向時光機想自己設計樣式,用 iCarouselTypeCustom 搭配 carousel:itemTransformForOffset:baseTransform: 代理方法即可。
兩個 CoverFlow 的差異相當細微,但 CoverFlow2 的邏輯複雜得多。快速撥動時兩者幾乎一樣,用手指慢慢拖曳時差別才顯現。CoverFlow2 是為了盡可能貼近 Apple 原生 CoverFlow 而設計,未來可能為了這個目標持續微調。
(Mac OS 平台請把 UIView 換成 NSView。)
dataSource:實作 iCarouselDataSource 協議、負責提供視圖的對象。delegate:實作 iCarouselDelegate 協議、回應事件與布局請求的對象。type:切換展示樣式。perspective:3D 透視縮短效果,必須是介於 -0.01 與 0 之間的負數,超出範圍會產生非常怪異的結果。預設 -0.005。contentOffset:調整項目視圖相對於 carousel 中心的偏移,預設 CGSizeZero。改動它時消失點會跟著項目一起移動,因此不會產生「俯視」的錯覺。viewpointOffset:調整使用者視點。效果與 contentOffset 相反,且會改變透視消失點——往上移視點,看起來就像在俯視 carousel。decelerationRate:撥動後的減速率,值越大減速越慢,預設 0.95。0.0 代表放手即停,1.0 代表永不減速(直到抵達端點)。bounces / bounceDistance:是否允許越過端點後彈回,以及彈跳的最大距離(以 itemWidth 的倍數計)。對環繞型 carousel 無效。centerItemWhenSelected:預設 YES,點擊非當前項目會平滑捲至中央;點擊當前項目則無反應。clipsToBounds:其實是 UIView 的屬性,但常被忽略。設為 YES 可避免項目視圖溢出邊界,在 Interface Builder 中勾選「Clip Subviews」即可。vertical:水平或垂直展示。切換會同時改變布局與滑動偵測方向。自訂變換矩陣不受影響,但手勢方向仍會改變。ignorePerpendicularSwipes:預設 YES,忽略與 carousel 方向垂直的滑動手勢,因此項目內嵌垂直捲動的 scrollView 仍能正常運作。useDisplayLink:預設在 iOS 使用 CADisplayLink、Mac 使用 CVDisplayLink,與螢幕刷新同步性更好。若發現拖動後動畫不再持續,可嘗試設為 NO。numberOfItems:項目總數,需透過 numberOfItemsInCarousel: 設定。注意並非所有項目同時載入,carousel 會隨捲動按需載入。numberOfPlaceholders:占位視圖數量。numberOfVisibleItems:同時顯示的最大項目數,由系統依樣式與 frame 自動計算,效能優化時可覆寫。wrapEnabled:是否啟用環繞。currentItemIndex:目前置中項目的索引,設定它等同以 animated:NO 呼叫 scrollToItemAtIndex:。currentItemView:目前置中的項目視圖。itemWidth:項目顯示寬度,預設取自第一個項目視圖,可用 carouselItemWidth: 覆寫。scrollOffset:目前捲動偏移量(以 itemWidth 為單位)。可讀可寫,適合在 carousel 運動時同步定位其他畫面元素。offsetMultiplier:手指拖曳時的偏移倍數,不影響程式化捲動。多數樣式為 1.0,CoverFlow 系列為 2.0(因其項目間距較緊)。需用代理方法覆寫。scrollSpeed:撥動時的速度倍數,預設 1.0。visibleItemViews:目前顯示的所有項目視圖陣列,順序與 indexesForVisibleItems 一致。contentView:承載項目視圖的容器。可加入子視圖與項目交錯排列;若只想放前景/背景裝飾,直接加到 iCarousel 本身更好。加進 contentView 的視圖建議把 userInteractionEnabled 設為 NO,以免與 carousel 的觸控處理衝突。stopAtItemBoundary:預設 YES,撥動後會停在精確的項目邊界。scrollToItemBoundary:預設 YES,停止移動後自動對齊最近的項目邊界。設為 NO 則會停在原地,但若禁用環繞且開啟 bounces,越過端點時仍會自動對齊首/末項。- (void)scrollToItemAtIndex:(NSInteger)index animated:(BOOL)animated; - (void)scrollToItemAtIndex:(NSInteger)index duration:(NSTimeInterval)scrollDuration; - (void)scrollByNumberOfItems:(NSInteger)itemCount duration:(NSTimeInterval)duration; - (void)scrollToOffset:(CGFloat)offset duration:(NSTimeInterval)duration; - (void)scrollByOffset:(CGFloat)offset duration:(NSTimeInterval)duration; - (void)reloadData; - (UIView *)itemViewAtIndex:(NSInteger)index; - (NSInteger)indexOfItemView:(UIView *)view; - (NSInteger)indexOfItemViewOrSubview:(UIView *)view; - (CGFloat)offsetForItemAtIndex:(NSInteger)index; - (void)removeItemAtIndex:(NSInteger)index animated:(BOOL)animated; - (void)insertItemAtIndex:(NSInteger)index animated:(BOOL)animated; - (void)reloadItemAtIndex:(NSInteger)index animated:(BOOL)animated;
幾點值得注意的用法:
兩個必實作方法:
- (NSUInteger)numberOfItemsInCarousel:(iCarousel *)carousel; - (UIView *)carousel:(iCarousel *)carousel viewForItemAtIndex:(NSUInteger)index reusingView:(UIView *)view;
reusingView 的行為類似 UIPickerView:先前用過、已離開螢幕的視圖會被傳回來給你重用。若它非 nil,直接改屬性後回傳即可,效能會略好一點。但要特別小心:每次都要把內容重設一遍,否則會看到某個項目出現在錯誤的位置——這是新手最常踩的坑。另外 iCarousel 沒有 reuseIdentifier 機制來區分不同型別的項目視圖,若你的 carousel 混有多種樣式,乾脆忽略這個參數、每次回傳全新實例。同一個視圖實例絕不可同時對應多個索引,否則顯示會出錯。
兩個選用的占位視圖方法:
- (NSUInteger)numberOfPlaceholdersInCarousel:(iCarousel *)carousel; - (UIView *)carousel:(iCarousel *)carousel placeholderViewAtIndex:(NSUInteger)index reusingView:(UIView *)view;
占位視圖用於「項目太少、填不滿寬度」的情況。它們隨 carousel 移動、行為與一般項目無異,但不計入 numberOfItems,也不能設為當前選中項,且在啟用環繞時會被隱藏。n 個占位視圖中,前 n/2 個在左、後 n/2 個在右;若 n 為奇數,畫面會左右不對稱。占位視圖的視圖池與一般項目分開,因此兩者型別不同也沒問題。
- (void)carouselWillBeginScrollingAnimation:(iCarousel *)carousel; - (void)carouselDidEndScrollingAnimation:(iCarousel *)carousel; - (void)carouselDidScroll:(iCarousel *)carousel; - (void)carouselCurrentItemIndexDidChange:(iCarousel *)carousel; - (void)carouselWillBeginDragging:(iCarousel *)carousel; - (void)carouselDidEndDragging:(iCarousel *)carousel willDecelerate:(BOOL)decelerate; - (void)carouselWillBeginDecelerating:(iCarousel *)carousel; - (void)carouselDidEndDecelerating:(iCarousel *)carousel; - (CGFloat)carouselItemWidth:(iCarousel *)carousel; - (CATransform3D)carousel:(iCarousel *)carousel itemTransformForOffset:(CGFloat)offset baseTransform:(CATransform3D)transform; - (CGFloat)carousel:(iCarousel *)carousel valueForOption:(iCarouselOption)option withDefault:(CGFloat)value; - (void)carousel:(iCarousel *)carousel didSelectItemAtIndex:(NSInteger)index; - (BOOL)carousel:(iCarousel *)carousel shouldSelectItemAtIndex:(NSInteger)index;
幾個容易混淆的時機點:
carouselDidEndDragging:willDecelerate: 中的 willDecelerate 表示是否還需要靠慣性滑行。即使為 NO,carousel 仍會自動對齊當前索引。想知道「完全靜止」的時刻,請用 carouselDidEndScrollingAnimation:。carouselDidEndDecelerating: 時的 currentItemIndex 就是最終停留值。為向後相容,此方法的實作在減速結束後仍會呼叫 scrollToItemAtIndex:animated:。carouselItemWidth: 只該用來「裁切或補白」——例如項目視圖尺寸不一、或背景圖自帶陰影/外光暈影響了實際尺寸。若只是想拉開間距,用 iCarouselOptionSpacing 才是正解。用 carousel:valueForOption:withDefault: 覆寫,不感興趣的選項直接回傳傳入的預設值即可。
iOS 上有兩種基本做法。最簡單的是用 carousel:didSelectItemAtIndex:,每次點擊都會觸發;若只關心置中項,比對 currentItemIndex 即可。
需要更多控制時,直接把 UIButton 或 UIControl 當成項目視圖,自行處理觸控;也可以在項目視圖內嵌 UIControl,它們會照常收到事件。若要偵測滑動、雙擊、長按等其他手勢,最省事的方式是在傳給 carousel 之前先掛上 UIGestureRecognizer。
注意:除非把 centerItemWhenSelected 設為 NO,否則非當前選中項目的點擊與手勢都會被忽略。另外在 Mac OS 上,由於項目視圖套用了一堆 transform,hit detection 無法正常運作,目前沒有簡單辦法在項目內嵌控制項。
Q:升級新版後專案壞了,怎麼取回舊版?
A:每個歷史版本在 GitHub 上都有獨立 tag,到 tags 分頁下載即可。
Q:一定要用 nib 嗎?可以用 Storyboard 嗎?
A:兩者都可以,分別參考 NoNibDemo 與 StoryboardDemo。
Q:項目視圖溢出邊界怎麼辦?
A:把 iCarousel 的 clipsToBounds 設為 YES,或在 Interface Builder 勾選「Clip Subviews」。
Q:有些視圖出現在 carousel 中不該出現的位置。
A:幾乎都是因為在 reusingView 流程中沒有重設內容。仔細檢查你的設定程式碼是否放對了位置。
Q:載入大量圖片後記憶體不足。
A:關鍵是隨捲動在背景執行緒逐步載入,而不是一次全部載入。參考 DynamicDownloads 的做法;本地圖片同樣適用,用 [NSURL fileURLWithPath:] 產生 URL 即可。
Q:圓柱樣式下看得到項目背面。
A:對 iCarouselOptionShowBackfaces 回傳 NO,或把項目視圖的 layer.doubleSided 設為 NO。
Q:reusingView 到底該不該用?各項目布局完全不同時呢?
A:它的目的是回收離開螢幕的視圖以省效能。若項目樣式差異很大、或數量不到上百個,忽略它、每次建立新視圖反而更簡單也更安全。
Q:讓線性樣式更接近分頁的 UIScrollView?
A:把 decelerationRate 設為 0 會接近許多。若還不夠像,可以考慮作者另一個基於 UIScrollView 的 SwipeView。
Q:想要真正的動態倒影,該怎麼做?
A:iCarousel 本身不內建倒影,可搭配 ReflectionView(含子視圖時)或 FXImageView(純圖片時)。
Q:項目視圖邊緣有鋸齒。
A:在圖片四周留至少 1px 的透明邊距,iOS 就會自動平滑——它會對圖片內部的像素做反鋸齒,但不處理視圖邊緣。即使項目是純色,也建議墊一張同色背景圖來換取平滑效果。