您现在的位置: IOS教程網 >> IOS系統 >  >> iOS 程式開發 >> iOS 開發綜合

iCarousel 完整指南:屬性、方法、代理與常見問題一次搞懂

編輯:iOS 開發綜合

iCarousel 是 iOS 上最常被拿來做「3D 轉盤式」列表的開源元件之一。它把 UITableView 的「按需載入、視圖回收」思路搬到了 3D 空間,支援線性、圓柱、車輪、封面流、時光機等多種展示樣式,甚至允許你自訂變換矩陣。以下把官方文件重新整理成一份可查閱的參考。

支援版本與相容性

  • 支援的編譯目標:iOS 5.1 / Mac OS 10.7(Xcode 4.3.3、Apple LLVM 3.1)
  • 最早支援的部署目標:iOS 4.3 / Mac OS 10.7
  • 最早相容的部署目標:iOS 3.2 / Mac OS 10.6

文件特別區分了兩個詞: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:封面流 / 封面流 2
  • iCarouselTypeTimeMachine / 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;

幾點值得注意的用法:

  • scrollToItemAtIndex:animated: 對環繞型 carousel 會自動選擇最短路徑。若你要控制方向或捲動超過一圈,改用 scrollByNumberOfItems:。
  • scrollToOffset: / scrollByOffset: 接受小數偏移,適合追求精細動畫效果。但若 scrollToItemBoundary 為 YES,呼叫後仍會被自動對齊。
  • itemViewAtIndex: 傳入負數或大於等於 numberOfItems 的值可取得占位視圖。此方法的索引是 carousel 上的位置,與 visibleItemViews 陣列中的位置未必相同;未載入或超出範圍時回傳 nil。
  • indexOfItemViewOrSubview: 會沿著視圖階層往上找,直到找到屬於 carousel 的項目視圖並回傳其索引。這個方法在處理「項目內嵌控制項」的事件時極好用——把所有控制項綁到同一個 action,再用它判斷是哪個項目觸發的。
  • removeItemAtIndex: 不會自動同步資料來源,後續呼叫 reloadData 會把項目還回來。insertItemAtIndex: 則要求你先更新資料來源再呼叫,否則會出現重複或奇怪的顯示。

資料來源協議

兩個必實作方法:

- (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 才是正解。
  • 自訂變換時,offset 是該視圖距 carousel 中心的距離:置中項為 0.0,右邊一點為 1.0,左邊一點為 -1.0。要實作線性樣式,把 offset 乘以 itemWidth 當作 transform 的 x 值即可。此方法僅在 type 為 iCarouselTypeCustom 時才會被呼叫。

iCarouselOption 可調參數

用 carousel:valueForOption:withDefault: 覆寫,不感興趣的選項直接回傳傳入的預設值即可。

  • iCarouselOptionWrap:是否環繞。注意回傳型別是浮點數,任何非 0.0 的值都視為 YES。
  • iCarouselOptionShowBackfaces:是否顯示背面。圓柱等樣式會看到項目的反面,回傳 NO 可隱藏;InvertedCylinder 預設已隱藏,回傳 YES 可覆寫。
  • iCarouselOptionOffsetMultiplier:拖曳偏移倍數。
  • iCarouselOptionVisibleItems:同時可見的最大項目數(含占位視圖),一半顯示在當前項目的左側、一半在右側,超出範圍的不載入。這是 carousel 能承載海量資料的關鍵。
  • iCarouselOptionCount:Rotary、Cylinder、Wheel 中顯示的項目數,預設依視圖尺寸與項目數自動計算。
  • iCarouselOptionArc:上述三種樣式的弧度(radians),預設 2π(整圓),設為 π 可得半圓。
  • iCarouselOptionRadius:半徑(像素/點)。
  • iCarouselOptionAngle:每個項目之間的角度增量(radians)。單獨改它而不改半徑,會導致尾端出現缺口或項目重疊。
  • iCarouselOptionTilt:CoverFlow、CoverFlow2、TimeMachine 中非置中項目的傾斜量,範圍 0.0~1.0。
  • iCarouselOptionSpacing:項目間距,會乘以 itemWidth(垂直時為 height)。預設 1.0 代表無額外間距。
  • iCarouselOptionFadeMin / FadeMax / FadeRange:控制項目依偏移量淡出。FadeMin 是最小負向偏移,FadeMax 是最大正向偏移,FadeRange 則是從開始淡出到完全隱形之間的距離。

如何偵測點擊

iOS 上有兩種基本做法。最簡單的是用 carousel:didSelectItemAtIndex:,每次點擊都會觸發;若只關心置中項,比對 currentItemIndex 即可。

需要更多控制時,直接把 UIButton 或 UIControl 當成項目視圖,自行處理觸控;也可以在項目視圖內嵌 UIControl,它們會照常收到事件。若要偵測滑動、雙擊、長按等其他手勢,最省事的方式是在傳給 carousel 之前先掛上 UIGestureRecognizer。

注意:除非把 centerItemWhenSelected 設為 NO,否則非當前選中項目的點擊與手勢都會被忽略。另外在 Mac OS 上,由於項目視圖套用了一堆 transform,hit detection 無法正常運作,目前沒有簡單辦法在項目內嵌控制項。

官方範例專案

  • Basic iOS Example:最精簡的入門,示範 CoverFlow2。
  • iOS Demo / MacDemo:展示全部樣式與動態增刪項目,Mac 版功能對等。
  • ButtonsDemo / ControlsDemo:把按鈕或巢狀控制項作為項目視圖並正確處理事件;ControlsDemo 另示範從 nib 載入複雜項目視圖。
  • MultipleCarousels:單一視圖控制器中使用多個 carousel。
  • NoNibDemo / StoryboardDemo:不用 nib、以及用 Storyboard 建置的兩種寫法。
  • OffsetsDemo:contentOffset 與 viewpointOffset 的效果對照。
  • OptionsDemo:用 iCarouselOption API 微調各樣式外觀。
  • DynamicViewReflections / DynamicImageEffects:分別用 ReflectionView 與 FXImageView 動態產生倒影與陰影。
  • DynamicDownloads / Downloads&Effects:用 AsyncImageView 背景下載遠端圖片,避免阻塞主線程。

常見問題

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 就會自動平滑——它會對圖片內部的像素做反鋸齒,但不處理視圖邊緣。即使項目是純色,也建議墊一張同色背景圖來換取平滑效果。

  1. 上一篇文章:
  2. 下一篇文章:
蘋果刷機越獄教程| IOS教程問題解答| IOS技巧綜合| IOS7技巧| IOS8教程
Copyright © IOS教程網 All Rights Reserved