{"id":13743161,"url":"https://github.com/listenzz/HBDNavigationBar","last_synced_at":"2025-05-09T00:32:52.362Z","repository":{"id":38238560,"uuid":"126468623","full_name":"listenzz/HBDNavigationBar","owner":"listenzz","description":"A custom UINavigationBar for smooth switching between various states, including bar style, bar tint color,  background image, background alpha,   bar hidden, title text attributes, tint color, shadow hidden...","archived":false,"fork":false,"pushed_at":"2024-10-18T02:26:59.000Z","size":8701,"stargazers_count":1660,"open_issues_count":65,"forks_count":218,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-05-04T00:31:55.760Z","etag":null,"topics":["uinavigationbar","uinavigationcontroller"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/listenzz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-23T10:18:00.000Z","updated_at":"2025-04-29T09:02:00.000Z","dependencies_parsed_at":"2024-12-18T23:02:56.713Z","dependency_job_id":"700dcc03-94c7-4c71-9d99-16298a9c8e14","html_url":"https://github.com/listenzz/HBDNavigationBar","commit_stats":{"total_commits":162,"total_committers":8,"mean_commits":20.25,"dds":0.05555555555555558,"last_synced_commit":"586be2911fd74e4d296cd1a92ce947fc1705a13f"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/listenzz%2FHBDNavigationBar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/listenzz%2FHBDNavigationBar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/listenzz%2FHBDNavigationBar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/listenzz%2FHBDNavigationBar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/listenzz","download_url":"https://codeload.github.com/listenzz/HBDNavigationBar/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252690428,"owners_count":21789243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["uinavigationbar","uinavigationcontroller"],"created_at":"2024-08-03T05:00:41.622Z","updated_at":"2025-05-09T00:32:51.702Z","avatar_url":"https://github.com/listenzz.png","language":"Objective-C","funding_links":[],"categories":["Objective-C  Stars 1000以内排名整理"],"sub_categories":[],"readme":"# HBDNavigationBar\n\n[English Document](./README_EN.md)\n\nUINavigationBar 是每一个 iOS 工程师都会遇到的坎，它令人抓狂的地方在于是否能随着页面切换而平滑地过渡到目的状态。想要把这件事情做好，不需要高深的算法，不需要深刻的底层原理，只需要一颗执着的内心。\n\n## 介绍\n\n我们来看微信是如何平滑切换导航栏的状态的\n\n![weixin](./screenshot/weixin.gif)\n\n**我** 页面和 **收藏** 页面的导航栏具有不同的 barStyle 以及背景色\n\n当从 **收藏** 右滑返回 **我** 页面时，NavigationBar 的背景被分成黑白两段，并且 bar 上的元素平滑切换，就和只有一个背景色时一样。\n\n仔细观察，**我** 页面和 **收藏** 页面的导航栏背景颜色不一样，但是**都有毛玻璃效果**\n\n**收藏** 页面往上滑动到一定程度时，导航栏会出现 shadowImage，此时如果右滑返回，导航栏依然在 **收藏** 页保留 shadowImage，然而 **我** 页面却没有这根线\n\n不得不说，细节处理得真好\n\n下面，我们来看一个反例，这是掘金 app 收藏页面的效果，当右滑返回上一个页面时，导航栏那反应实在是突兀，尖锐。\n\n\u003e 特别说明，本人举掘金这个例子，纯粹是因为掘金是本人常用 app 之一\n\n![juejin](./screenshot/juejin.gif)\n\n导航栏的平滑过渡，可以划分为以下情况\n\n### 阴影显示与隐藏\n\n以下展示了平滑切换 shadowImage 的隐与现\n\n![shadow](./screenshot/shadow.gif)\n\n### 导航栏有与无\n\n以下展示导航栏有与无之间的平滑切换，和调用 `setNavigationBarHidden:animated:` 的效果不一样哦\n\n![hidden](./screenshot/hidden.gif)\n\n### 导航栏背景透明度随 UIScrollView 滚动变化\n\n这种效果是不是比掘金好多了\n\n![gradient](./screenshot/gradient.gif)\n\n### 控制器拥有不同的导航栏背景\n\n看下面效果，导航栏背景的表现是不是和微信一样\n\n![background](./screenshot/background.gif)\n\n## Usage\n\n上面这些效果是三个类共同协作的结果：\n\nHBDNavigationBar 继承 UINavigationBar\n\nHBDNavigationController 继承 UINavigationController， 内部使用了 HBDNavigationBar\n\nUIViewController(HBD) 是个分类，里面有一些可配置属性\n\n```objc\n@property (nonatomic, assign) UIBarStyle hbd_barStyle;   // 导航栏样式\n@property (nonatomic, strong) UIColor *hbd_barTintColor; // 导航栏背景颜色\n@property (nonatomic, strong) UIImage *hbd_barImage;     // 导航栏背景图片\n@property (nonatomic, strong) UIColor *hbd_tintColor;    // 导航栏按钮颜色\n@property (nonatomic, strong) NSDictionary *hbd_titleTextAttributes; // 导航栏标题属性\n@property (nonatomic, assign) float hbd_barAlpha;        // 导航栏背景透明度\n@property (nonatomic, assign) BOOL hbd_barHidden;        // 是否隐藏导航栏\n@property (nonatomic, assign) BOOL hbd_barShadowHidden;  // 是否隐藏导航栏下面的阴影\n@property (nonatomic, assign) BOOL hbd_backInteractive;  // 当前页面是否响应右滑返回，以及通过 `UINavigationBar` 的返回按钮返回，默认是 YES\n@property (nonatomic, assign) BOOL hbd_swipeBackEnabled; // 当前页面是否可以右滑返回，默认是 YES\n```\n\n实际使用起来很简单\n\n和使用普通的 `UINavigationBar` 一样，定义全局样式：\n\n```objc\n// AppDelegate.m\n- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {\n\n    [[UINavigationBar appearance] setTintColor:UIColor.blackColor];\n    // ...\n\n    return YES;\n}\n```\n\n使用 `HBDNavigationController` 代替 `UINavigationController`\n\n```objc\nDemoViewController *vc = [[DemoViewController alloc] init];\nself.window.rootViewController = [[HBDNavigationController alloc] initWithRootViewController:vc];\n```\n\n如果某个控制器的导航栏样式和全局样式有差异，可以使用 `UIViewController(HBD)` 中的属性，在 `viewDidLoad` 这个生命周期函数里进行微调。这是声明式 API，只需要设置有差异的样式即可，也不需要清理。\n\n```objc\n@implementation DemoViewController\n- (void)viewDidLoad {\n    [super viewDidLoad];\n    // 隐藏导航栏，就这样，不需要调用 setNavigationBarHidden:animated:\n    // 也不需要担心其它页面会受到影响\n    self.hbd_barHidden = YES;\n}\n@end\n```\n\n如果你使用 storyboard, 除了设置 `HBDNavigationController`， 也别忘了设置 `HBDNavigationBar`\n\n![storyboard](./screenshot/storyboard.jpg)\n\n### 注意事项以及限制\n\n#### hbd_barHidden\n\n`hbd_barHidden` 并不真正隐藏导航栏，只是把它变透明了，当然事件是可以穿透的，也正因为并不真正隐藏导航栏，才可以在导航栏有无之间平滑而优雅地切换\n\n#### Background algorithm\n\n一旦通过 `hbd_barImage` 设置背景图片，`hbd_barTintColor` 就会失效\n\n背景的计算规则如下：\n\n1. hbd_barImage 是否有值，如果有，将其设置为背景，否则下一步\n2. hbd_barTintColor 是否有值，如果有，将其设置为背景，否则下一步\n3. [[UINavigationBar appearance] backgroundImageForBarMetrics:UIBarMetricsDefault] 是否有返回值，如果有，将其设置为背景，否则下一步\n4. [UINavigationBar appearance].barTintColor 是否有值，如果有，将其设置为背景，否则下一步\n5. 根据 barStyle 计算出默认的背景颜色，并将其设置为背景\n\n如果使用图片来设置背景，并且希望带有透明度，使用带有透明度的图片即可。\n\n如果需要毛玻璃效果，那么设置给 `hbd_barTintColor` 的值应该带有透明度，具体数值根据色值的不同而不同。不要通过 `hbd_barAlpha` 来调整毛玻璃效果，它是用来动态控制导航栏背景的透与暗的，就像掘金收藏页面那个效果一样。\n\n图片是没有毛玻璃效果的\n\n#### Aways translucent\n\n本库重写了 UINavigationBar 的 `translucent` 属性，使得它的值总是 YES。\n\n本库根据导航栏的背景是否含有透明度，自动调整  `UIViewController#edgesForExtendedLayout`  这个属性。\n\n如果导航栏一开始是不透明的，由于后续操作而变透明，需要设置 `UIViewController#extendedLayoutIncludesOpaqueBars`  的值为 `YES`。\n\n```objc\n- (void)viewDidLoad {\n    [super viewDidLoad];\n    // 一开始导航栏为不透明\n    self.hbd_barTintColor = UIColor.whiteColor;\n    self.extendedLayoutIncludesOpaqueBars = YES;\n}\n\n- (void)handleScroll {\n    // 由于用户操作而变透明\n    self.hbd_barAlpha = 0.5;\n    [self hbd_setNeedsUpdateNavigationBar];\n}\n\n```\n\n基本原则就是如果我们设置的背景是含有透明度的，那么页面就应该位于 NavigationBar 底下(under)，否则位于 NavigationBar 下面(below).\n\n如果我们的 NavigationBar 一开始是不透明的，但有可能因为用户操作而变透明，那么设置 `extendedLayoutIncludesOpaqueBars` 的值为 `YES`。\n\n\n#### 拦截返回事件\n\n有时，我们需要在用户点击返回按钮或者侧滑返回时提醒用户，此时，可以重写以下方法，返回 NO\n\n```objc\n\n- (BOOL)hbd_backInteractive {\n    // show alert\n    return NO;\n}\n\n```\n\n#### 隐藏状态栏\n\n如果你需要隐藏状态栏，请配合 [HBDStatusBar](https://github.com/listenzz/HBDStatusBar) 一起使用\n\n#### 全屏返回\n\n创建一个继承于 `HBDNavigationController` 的子类，具体参考 FSPNavigationController\n\n```objc\n// FSPNavigationController.m\n@implementation FSPNavigationController\n\n- (void)viewDidLoad {\n    [super viewDidLoad];\n    \n    // 获取系统自带滑动手势的target对象\n    id target = self.interactivePopGestureRecognizer.delegate;\n    // 创建全屏滑动手势，调用系统自带滑动手势的 target 的 action 方法\n    UIPanGestureRecognizer *pan = [[UIPanGestureRecognizer alloc] initWithTarget:target action:@selector(handleNavigationTransition:)];\n    // 设置手势代理，拦截手势触发\n    pan.delegate = self.interactivePopGestureRecognizer.delegate;\n    // 给导航控制器的view添加全屏滑动手势\n    [self.view addGestureRecognizer:pan];\n    // 禁止使用系统自带的滑动手势\n    self.interactivePopGestureRecognizer.enabled = NO;\n}\n\n@end\n```\n\n\n## 感谢\n\n在完善导航栏相关功能时，查看了 GitHub 上十多个相关项目，其中给我帮助最大的是 [YPNavigationBarTransition](https://github.com/yiplee/YPNavigationBarTransition)，它为我解决不同背景之间如何平滑切换提供了非常有价值的参考。\n\n## Requirements\n\niOS 9+\n\n## Installation\n\nHBDNavigationBar is available through [CocoaPods](http://cocoapods.org). To install\nit, simply add the following line to your Podfile:\n\n```ruby\npod 'HBDNavigationBar', '~\u003e 1.9.8'\n```\n\n## License\n\nHBDNavigationBar is available under the MIT license. See the LICENSE file for more info.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flistenzz%2FHBDNavigationBar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flistenzz%2FHBDNavigationBar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flistenzz%2FHBDNavigationBar/lists"}