TLYShyNavBar 开源项目安装与使用指南

TLYShyNavBar 开源项目安装与使用指南

还在为 iOS 应用中实现类似 Facebook、Instagram 那样流畅的导航栏自动滚动效果而烦恼吗？TLYShyNavBar 开源库让你只需一行代码就能轻松实现这个功能！本文将为你提供完整的安装配置指南和详细的使用教程。

🚀 项目概述

TLYShyNavBar 是一个轻量级的 iOS 导航栏组件，能够让你的 UINavigationBar 在用户滚动内容时自动展开和收缩。它不仅支持基本的导航栏滚动，还提供了扩展视图、粘性效果、淡入淡出动画等丰富功能。

核心特性一览表

功能特性	说明	适用场景
基础导航栏滚动	支持 UINavigationBar 自动展开/收缩	所有滚动视图场景
扩展视图支持	可在导航栏下方添加自定义视图	工具栏、搜索栏等
粘性效果	支持导航栏和扩展视图的粘性定位	需要固定显示重要控件
淡入淡出动画	多种淡入淡出行为选择	增强视觉体验
阻力控制	自定义展开/收缩的阻力值	精细控制滚动行为
多视图支持	兼容 UITableView/UICollectionView	列表和网格布局

📦 安装方式

方式一：CocoaPods（推荐）

CocoaPods 是最简单快捷的安装方式，只需在 Podfile 中添加：

pod 'TLYShyNavBar'

然后执行安装命令：

pod install

方式二：Carthage

如果你使用 Carthage 进行依赖管理，在 Cartfile 中添加：

github "telly/TLYShyNavBar"

然后运行：

carthage update

方式三：手动集成

1. 下载项目源码或使用 git submodule
2. 将 TLYShyNavBar 文件夹拖拽到你的 Xcode 项目中
3. 确保勾选 "Copy items if needed" 选项
4. 在需要使用的文件中导入头文件：

#import "TLYShyNavBarManager.h"

🛠️ 基础使用教程

Objective-C 版本

第一步：基本配置

在你的视图控制器中，只需一行代码即可启用导航栏滚动功能：

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // 核心代码：关联滚动视图
    self.shyNavBarManager.scrollView = self.scrollView;
}

第二步：添加扩展视图

你可以在导航栏下方添加自定义的扩展视图：

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // 创建扩展视图
    UIView *extensionView = [[UIView alloc] initWithFrame:CGRectMake(0, 0, CGRectGetWidth(self.view.bounds), 40)];
    extensionView.backgroundColor = [UIColor redColor];
    
    // 添加按钮到扩展视图
    UIButton *button = [UIButton buttonWithType:UIButtonTypeSystem];
    button.frame = extensionView.bounds;
    [button setTitle:@"点击我!" forState:UIControlStateNormal];
    [extensionView addSubview:button];
    
    // 配置 ShyNavBar
    self.shyNavBarManager.scrollView = self.scrollView;
    [self.shyNavBarManager setExtensionView:extensionView];
}

Swift 版本

桥接头文件配置

首先确保创建了 Bridging Header 文件，并添加导入语句：

// YourProject-Bridging-Header.h
#import "TLYShyNavBarManager.h"

Swift 代码实现

import UIKit

class ViewController: UIViewController {
    
    @IBOutlet weak var tableView: UITableView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // 创建扩展视图
        let extensionView = UIView(frame: CGRectMake(0, 0, CGRectGetWidth(self.view.bounds), 40))
        extensionView.backgroundColor = UIColor.redColor()
        
        // 配置 ShyNavBar
        self.shyNavBarManager.scrollView = self.tableView
        self.shyNavBarManager.extensionView = extensionView
    }
}

⚙️ 高级功能配置

1. 粘性效果设置

// 设置导航栏粘性（滚动时保持显示）
[self.shyNavBarManager setStickyNavigationBar:YES];

// 设置扩展视图粘性
[self.shyNavBarManager setStickyExtensionView:YES];

2. 阻力控制

控制导航栏展开和收缩的阻力值：

// 展开阻力（默认200）
self.shyNavBarManager.expansionResistance = 300.0f;

// 收缩阻力（默认0）
self.shyNavBarManager.contractionResistance = 50.0f;

3. 淡入淡出行为

// 选择淡入淡出行为
typedef NS_ENUM(NSInteger, TLYShyNavBarFade) {
    TLYShyNavBarFadeDisabled,     // 禁用淡入淡出
    TLYShyNavBarFadeSubviews,     // 淡出子视图（默认）
    TLYShyNavBarFadeNavigationBar // 淡出整个导航栏
};

// 设置淡入淡出行为
[self.shyNavBarManager setFadeBehavior:TLYShyNavBarFadeSubviews];

🔧 常见问题解决方案

问题1：不透明的导航栏显示黑条

解决方案：在 View Controller 配置中勾选 "Extend Edges Under Opaque Bars" 选项。

问题2：视图控制器未添加到导航控制器时报错

解决方案：确保在视图控制器已经添加到导航控制器层次结构后再配置 ShyNavBar：

// 错误的方式（会报错）
- (void)viewDidLoad {
    [super viewDidLoad];
    // 此时可能还未添加到导航控制器
    self.shyNavBarManager.scrollView = self.scrollView;
}

// 正确的方式
- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    // 确保已添加到导航控制器
    self.shyNavBarManager.scrollView = self.scrollView;
}

问题3：与 UITableViewController 的兼容性

重要提示：不要与 UITableViewController 一起使用。建议使用 UIViewController 包含 UITableView 的方式：

// 推荐的方式
@interface MyViewController : UIViewController <UITableViewDelegate, UITableViewDataSource>
@property (nonatomic, strong) UITableView *tableView;
@end

// 在 viewDidLoad 中配置
self.shyNavBarManager.scrollView = self.tableView;

📋 功能对比表

功能	TLYShyNavBar	其他类似库	优势
易用性	⭐⭐⭐⭐⭐	⭐⭐⭐	一行代码即可使用
扩展视图	✅	❌	支持自定义扩展视图
粘性效果	✅	❌	导航栏和扩展视图都可粘性
动画效果	⭐⭐⭐⭐	⭐⭐⭐	多种淡入淡出选项
兼容性	⭐⭐⭐⭐⭐	⭐⭐⭐	支持 iOS 7+
文档完整性	⭐⭐⭐⭐	⭐⭐	详细的文档和示例

🎯 最佳实践建议

1. 性能优化

// 在不需要时及时释放资源
- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    self.shyNavBarManager.scrollView = nil;
    [self.shyNavBarManager setExtensionView:nil];
}

2. 内存管理

// 避免循环引用
__weak typeof(self) weakSelf = self;
self.shyNavBarManager.contractionResistance = ^CGFloat{
    return weakSelf.customResistanceValue;
};

3. 多场景适配

// 根据不同设备调整参数
if ([UIDevice currentDevice].userInterfaceIdiom == UIUserInterfaceIdiomPad) {
    self.shyNavBarManager.expansionResistance = 400.0f;
} else {
    self.shyNavBarManager.expansionResistance = 200.0f;
}

🔍 调试技巧

1. 启用调试日志

// 在开发阶段启用详细日志
#define TLY_SHY_NAV_BAR_DEBUG 1

2. 检查代理设置顺序

// 重要：先设置代理，再关联滚动视图
self.tableView.delegate = self; // 先设置代理
self.shyNavBarManager.scrollView = self.tableView; // 再关联

📊 版本兼容性

iOS 版本	支持状态	备注
iOS 7.0+	✅ 完全支持	最低支持版本
iOS 8.0+	✅ 优化支持	推荐使用版本
iOS 9.0+	✅ 最佳体验	所有功能可用
iOS 10+	✅ 完全兼容	无已知问题

🚨 注意事项

1. 代理设置顺序：务必在设置 shyNavBarManager.scrollView 之前设置滚动视图的代理
2. 导航控制器要求：视图控制器必须嵌入在 UINavigationController 中
3. 避免 UITableViewController：使用 UIViewController + UITableView 组合
4. 内存管理：在视图控制器销毁时适当清理资源

💡 进阶使用场景

场景1：动态修改扩展视图

// 动态更新扩展视图内容
- (void)updateExtensionView {
    UIView *newExtensionView = [self createNewExtensionView];
    [self.shyNavBarManager setExtensionView:newExtensionView];
}

场景2：与其他动画库配合使用

// 与 UIView 动画配合
[UIView animateWithDuration:0.3 animations:^{
    self.shyNavBarManager.expansionResistance = 500.0f;
}];

场景3：响应滚动事件

// 通过 KVO 监听导航栏状态
[self.shyNavBarManager addObserver:self 
                        forKeyPath:@"state" 
                           options:NSKeyValueObservingOptionNew 
                           context:nil];

🎉 结语

TLYShyNavBar 是一个功能强大且易于使用的导航栏滚动解决方案。通过本文的详细指南，你应该能够：

1. ✅ 快速安装和配置 TLYShyNavBar
2. ✅ 实现基本的导航栏滚动功能
3. ✅ 使用高级功能如扩展视图和粘性效果
4. ✅ 解决常见的兼容性问题
5. ✅ 优化性能并遵循最佳实践

无论你是要创建类似社交媒体的流畅体验，还是需要为你的应用添加专业的导航交互，TLYShyNavBar 都能为你提供完美的解决方案。开始使用吧，让你的导航栏也变得"害羞"起来！