当前位置：首页 > news >正文

如何集成TGLStackedViewController到现有iOS项目：完整指南

news 2026/7/11 16:17:41

如何集成TGLStackedViewController到现有iOS项目：完整指南

【免费下载链接】TGLStackedViewControllerA stacked view layout with gesture-based reordering using a UICollectionView -- inspired by Passbook and Reminders apps.项目地址: https://gitcode.com/gh_mirrors/tg/TGLStackedViewController

TGLStackedViewController是一个功能强大的iOS堆叠视图控制器库，专门用于创建类似Passbook和Reminders应用的卡片堆叠布局。通过本完整指南，您将学习如何快速将TGLStackedViewController集成到您的现有iOS项目中，实现优雅的堆叠卡片界面和流畅的手势交互体验。😊

📱 什么是TGLStackedViewController？

TGLStackedViewController是一个基于UICollectionView的堆叠视图布局组件，支持手势驱动的项目重新排序。它提供了两种布局模式：堆叠布局（所有卡片重叠显示）和展开布局（单个卡片完全展开）。这个库的灵感来源于苹果的Passbook和Reminders应用，能够为您的应用添加专业级的卡片交互体验。

核心功能特点：

手势驱动的卡片重新排序
流畅的展开/折叠动画
可自定义的堆叠和展开布局参数
支持iOS 9及以上版本
兼容CocoaPods和Carthage

🔧 准备工作与系统要求

在开始集成之前，请确保您的项目满足以下要求：

最低系统要求：

iOS 9.0或更高版本
Xcode 9.0或更高版本
启用ARC（自动引用计数）

项目配置检查：

打开您的Xcode项目
确认部署目标（Deployment Target）设置为iOS 9.0或更高
确保项目使用ARC（默认情况下新项目都使用ARC）

📦 三种安装方法详解

TGLStackedViewController提供了三种安装方式，您可以根据项目需求选择最适合的方法：

方法一：使用CocoaPods安装（推荐）

这是最简单快捷的安装方式，特别适合使用CocoaPods管理依赖的项目：

打开终端，导航到您的项目目录
如果项目还没有Podfile，运行：

pod init

编辑Podfile文件，添加TGLStackedViewController依赖：

pod 'TGLStackedViewController', '~> 2.2'

安装依赖：

pod install

完成后，使用新生成的.xcworkspace文件打开项目

方法二：使用Carthage安装

如果您使用Carthage管理依赖，请按照以下步骤操作：

在项目的Cartfile中添加：

github "gleue/TGLStackedViewController" ~> 2.2

运行Carthage更新命令：

carthage update --platform ios

将生成的framework添加到您的Xcode项目中

方法三：手动集成

对于不使用依赖管理工具的项目，可以手动集成：

克隆或下载TGLStackedViewController仓库：

git clone https://gitcode.com/gh_mirrors/tg/TGLStackedViewController

将TGLStackedViewController/目录下的所有文件添加到您的Xcode项目中
确保选中"Copy items if needed"选项
在需要的地方导入头文件

🚀 快速集成步骤

步骤1：创建TGLStackedViewController子类

首先创建一个继承自TGLStackedViewController的子类。在Xcode中：

选择File → New → File...
选择"Cocoa Touch Class"
类名输入"MyStackedViewController"
父类选择"TGLStackedViewController"
语言选择Objective-C

步骤2：配置数据源方法

在您的子类中实现UICollectionViewDataSource协议。关键要点：

// 必须返回1，目前只支持单个section - (NSInteger)numberOfSectionsInCollectionView:(UICollectionView *)collectionView { return 1; } - (NSInteger)collectionView:(UICollectionView *)collectionView numberOfItemsInSection:(NSInteger)section { return self.items.count; // 返回您的数据项数量 } - (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath { // 注册和配置您的自定义cell MyCustomCell *cell = [collectionView dequeueReusableCellWithReuseIdentifier:@"Cell" forIndexPath:indexPath]; cell.item = self.items[indexPath.item]; return cell; }

步骤3：实现项目重新排序支持

TGLStackedViewController使用iOS 9的集合视图重新排序API，需要实现以下方法：

// 检查项目是否可以移动 - (BOOL)collectionView:(UICollectionView *)collectionView canMoveItemAtIndexPath:(NSIndexPath *)indexPath { // 调用父类实现并检查您的业务逻辑 BOOL superCanMove = [super collectionView:collectionView canMoveItemAtIndexPath:indexPath]; return superCanMove && [self canMoveItemAtIndex:indexPath.item]; } // 处理项目移动后的数据更新 - (void)collectionView:(UICollectionView *)collectionView moveItemAtIndexPath:(NSIndexPath *)sourceIndexPath toIndexPath:(NSIndexPath *)destinationIndexPath { // 更新您的数据模型 id item = self.items[sourceIndexPath.item]; [self.items removeObjectAtIndex:sourceIndexPath.item]; [self.items insertObject:item atIndex:destinationIndexPath.item]; }

步骤4：配置Storyboard或代码布局

使用Storyboard配置：

在Storyboard中添加UICollectionViewController
将类设置为您的TGLStackedViewController子类
设置collection view的delegate和dataSource连接
将布局类设置为TGLStackedLayout

使用代码配置：

- (void)viewDidLoad { [super viewDidLoad]; // 创建并设置布局 TGLStackedLayout *layout = [[TGLStackedLayout alloc] init]; self.collectionView.collectionViewLayout = layout; // 注册cell [self.collectionView registerClass:[MyCustomCell class] forCellWithReuseIdentifier:@"Cell"]; }

⚙️ 高级配置选项

TGLStackedViewController提供了丰富的配置选项，让您可以自定义堆叠视图的行为和外观：

布局参数配置

// 设置展开布局的边距 self.exposedLayoutMargin = UIEdgeInsetsMake(40.0, 0.0, 0.0, 0.0); // 设置展开项目的尺寸 self.exposedItemSize = CGSizeMake(300, 200); // 配置堆叠布局参数 self.stackedLayoutMargin = UIEdgeInsetsMake(20.0, 0.0, 0.0, 0.0); self.stackedTopReveal = 120.0; // 每个卡片露出的部分

手势交互配置

// 启用/禁用展开项目的交互式折叠 self.exposedItemsAreCollapsible = YES; // 允许点击未展开的项目 self.unexposedItemsAreSelectable = NO; // 配置移动项目时的缩放因子 self.movingItemScaleFactor = 0.95; // 设置折叠手势的阈值 self.collapsePanMinimumThreshold = 120.0;

展开模式配置

TGLStackedViewController支持三种展开布局模式：

TGLExposedLayoutPinningModeNone- 项目被推送到展开项目的顶部和底部边缘
TGLExposedLayoutPinningModeBelow- 顶部项目推到展开项目顶部，底部项目固定到collection view底部
TGLExposedLayoutPinningModeAll- 所有非展开项目固定到collection view底部

self.exposedPinningMode = TGLExposedLayoutPinningModeAll;

🎨 自定义外观和交互

创建自定义Cell

要创建自定义的卡片cell，继承UICollectionViewCell并添加您的内容：

@interface MyCustomCell : UICollectionViewCell @property (nonatomic, strong) UIView *contentBackgroundView; @property (nonatomic, strong) UILabel *titleLabel; @property (nonatomic, strong) UIImageView *iconImageView; @end @implementation MyCustomCell - (instancetype)initWithFrame:(CGRect)frame { self = [super initWithFrame:frame]; if (self) { [self setupUI]; } return self; } - (void)setupUI { // 添加阴影和圆角 self.layer.shadowColor = [UIColor blackColor].CGColor; self.layer.shadowOffset = CGSizeMake(0, 2); self.layer.shadowOpacity = 0.3; self.layer.shadowRadius = 4; self.layer.cornerRadius = 8; // 创建内容视图 _contentBackgroundView = [[UIView alloc] init]; _contentBackgroundView.backgroundColor = [UIColor whiteColor]; _contentBackgroundView.layer.cornerRadius = 8; _contentBackgroundView.clipsToBounds = YES; [self.contentView addSubview:_contentBackgroundView]; // 添加其他UI元素... } - (void)layoutSubviews { [super layoutSubviews]; _contentBackgroundView.frame = self.contentView.bounds; } @end

处理项目选择事件

- (void)collectionView:(UICollectionView *)collectionView didSelectItemAtIndexPath:(NSIndexPath *)indexPath { // 调用父类实现 [super collectionView:collectionView didSelectItemAtIndexPath:indexPath]; // 处理您的业务逻辑 MyItem *item = self.items[indexPath.item]; [self handleItemSelection:item]; } - (void)collectionView:(UICollectionView *)collectionView didDeselectItemAtIndexPath:(NSIndexPath *)indexPath { [super collectionView:collectionView didDeselectItemAtIndexPath:indexPath]; // 处理项目取消选择 }