Ramotion Expanding-Collection 框架深度解析与使用指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00659/article/details/148491020

Ramotion Expanding-Collection 框架深度解析与使用指南

expanding-collection Ramotion/expanding-collection: Expanding Collection 是由Ramotion开发的一款iOS组件，它提供了一种独特的展开折叠式的集合视图效果，广泛应用于移动应用中的卡片式布局展示，提升用户体验。项目地址: https://gitcode.com/gh_mirrors/ex/expanding-collection

框架概述

Ramotion Expanding-Collection 是一个优雅的 iOS 卡片式交互框架，它实现了类似 Apple Wallet 的卡片展开动画效果。这个框架特别适合需要展示卡片式内容并支持展开详情的应用场景，如电商商品展示、旅游景点介绍等。

核心特性

流畅的卡片展开动画：支持卡片点击后平滑展开到详情页面的过渡效果
双面卡片设计：每个卡片都有正面(frontView)和背面(backView)两个视图
自定义灵活：支持完全自定义卡片大小、内容和动画细节
无缝集成：与 UITableView 和 UICollectionView 原生组件无缝结合

环境要求

iOS 8.0+
Xcode 7.3 或更高版本
Swift 项目

安装方式

手动安装

直接将 Source 文件夹添加到您的项目中

CocoaPods

在 Podfile 中添加：

pod 'expanding-collection'

Carthage

在 Cartfile 中添加：

github "Ramotion/expanding-collection"

核心组件详解

BasePageCollectionCell

这是所有自定义卡片单元格的基类，提供了卡片展开/收起的基本功能。开发者需要继承这个类来实现自己的卡片样式。

关键属性：

frontContainerView: 卡片正面容器视图
backContainerView: 卡片背面容器视图
frontConstraintY: 正面视图的垂直居中约束
backConstraintY: 背面视图的垂直居中约束

ExpandingViewController

卡片集合视图控制器基类，管理卡片集合的布局和基本交互。

关键方法：

pushToViewController(_:): 执行向详情页的过渡动画
popTransitionAnimation(): 执行返回卡片列表的过渡动画

ExpandingTableViewController

详情页表格视图控制器基类，管理详情页的展示和返回动画。

实现步骤详解

第一步：创建自定义卡片单元格

创建继承自 BasePageCollectionCell 的类（建议使用 xib 文件）
设计正面视图：
- 在 xib 中添加一个视图作为 frontContainerView
- 设置宽度、高度、水平居中和垂直居中约束
- 将垂直居中约束连接到 frontConstraintY IBOutlet
设计背面视图：
- 重复正面视图的步骤，使用 backContainerView 和 backConstraintY
特殊标记：任何标记为 101 的子视图将在过渡动画期间隐藏

class DemoCell: BasePageCollectionCell {
    @IBOutlet weak var frontImageView: UIImageView!
    @IBOutlet weak var backTextView: UITextView!
    
    // 其他自定义代码...
}

第二步：创建卡片集合视图控制器

创建继承自 ExpandingViewController 的类
设置卡片大小并注册自定义单元格：

override func viewDidLoad() {
    itemSize = CGSize(width: 214, height: 264)
    super.viewDidLoad()
    
    let nib = UINib(nibName: "DemoCell", bundle: nil)
    collectionView?.register(nib, forCellWithReuseIdentifier: "DemoCell")
}

实现 UICollectionViewDataSource：

extension YourViewController {
    override func collectionView(_ collectionView: UICollectionView, 
                               numberOfItemsInSection section: Int) -> Int {
        return items.count
    }
    
    override func collectionView(_ collectionView: UICollectionView, 
                               cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
        let cell = collectionView.dequeueReusableCell(withReuseIdentifier: "DemoCell", 
                                                     for: indexPath) as! DemoCell
        // 配置单元格
        return cell
    }
}

处理卡片点击事件：

func collectionView(_ collectionView: UICollectionView, 
                   didSelectItemAt indexPath: IndexPath) {
    guard let cell = collectionView.cellForItem(at: indexPath) as? DemoCell else { return }
    cell.cellIsOpen(!cell.isOpened)
    
    if cell.isOpened {
        let detailVC = DetailViewController()
        pushToViewController(detailVC)
    }
}

第三步：创建详情页视图控制器

创建继承自 ExpandingTableViewController 的类
设置头部高度：

override func viewDidLoad() {
    super.viewDidLoad()
    headerHeight = 300 // 根据设计需求调整
}

处理返回动画：

@objc func handleBackButton() {
    popTransitionAnimation()
}

高级技巧与注意事项

自定义动画曲线：可以通过重写 transitionAnimation 相关方法来自定义动画的时间曲线和效果
性能优化：对于复杂的卡片内容，建议在 willDisplayCell 中延迟加载非关键资源
特殊处理：如果重写了以下方法，必须调用 super 的实现：
- collectionView(_:willDisplay:forItemAt:)
- scrollViewDidEndDecelerating(_:)
适配不同屏幕尺寸：建议根据屏幕宽度动态计算卡片大小，确保最佳显示效果