一个基于 Swift/UIKit 的导航栏平滑转场组件,适用于 iOS 12 及以上系统。
本项目移植自 listenzz/HBDNavigationBar,并针对 Swift、现代 UIKit 和 iOS 18+ 的导航栏实现进行了适配。
UINavigationBar 的背景、阴影、标题和按钮样式通常由当前页面即时覆盖。当页面发生 push、pop 或交互式侧滑返回时,如果前后页面的配置不同,系统默认行为容易出现背景突然切换、阴影闪烁或标题颜色跳变。
MonsterNavigationBar 将导航栏的背景与内容拆开管理,在转场过程中分别计算并同步前后页面的状态,使导航栏能够连续地过渡到目标页面。它适合需要自定义导航栏样式,同时又希望保留系统导航控制器转场体验的应用。
本库主要处理以下场景:
前后页面可以分别控制导航栏底部阴影,交互式返回过程中阴影会跟随当前页面状态平滑切换。
monsterBarHidden 只隐藏导航栏内容和背景,不从视图层级移除导航栏,因此导航栏在有无之间也可以连续过渡。
滚动页面时动态修改 monsterBarAlpha,即可实现导航栏从透明到不透明的渐变效果,并同步处理页面布局和标题颜色。
每个页面都可以单独设置背景颜色或背景图片。push、pop 和侧滑返回时,颜色、图片、透明度、标题属性及按钮颜色会统一参与转场。
组件始终保持导航栏的系统转场能力,同时提供返回拦截、全屏返回、TabBar 联动、导航栈重定向和 iOS 26 Liquid Glass 按钮样式等扩展 API。
GIF 展示的是实际运行中的 Demo 录屏,主要过程如下:
- 首页提供导航栏颜色、透明度、阴影、背景图片、黑色样式、侧滑返回和 iOS 26 按钮样式开关。
- 切换颜色或样式后,导航栏背景与文字颜色立即同步更新。
- 点击“动态渐变”进入列表页,顶部图片随滚动移动,导航栏透明度和标题颜色随滚动进度渐变。
- 页面 push、pop 和模态展示都使用同一套导航栏转场协调逻辑。
完整 Demo 还包含图片背景、返回根页面、导航栈重定向和交互式侧滑返回等场景。
| 能力 | 说明 |
|---|---|
| 背景颜色 | 每个页面可设置独立的 UIColor,push/pop 时平滑插值 |
| 背景图片 | 支持每个页面使用独立图片,并参与转场 |
| 透明度 | 支持静态设置或在滚动过程中动态调整 |
| 毛玻璃背景 | 颜色背景通过 UIVisualEffectView 渲染,保持系统风格 |
| 阴影控制 | 支持显示、隐藏和自定义 shadowImage |
| 标题和按钮颜色 | 标题属性、导航栏 tintColor 在转场期间同步变化 |
| iOS 26 按钮样式 | 通过 monsterLiquidGlassBarButtonEnabled 统一切换左右按钮、标准返回按钮和单项按钮组的 Liquid Glass 背景(iOS 25 及以下无效果) |
| 导航栏显隐 | 只隐藏内容和背景,不移除导航栏视图,保证连续动画 |
| 返回控制 | 可分别控制返回按钮、侧滑返回和交互式返回 |
| 全屏返回 | 可复用 UIKit 系统侧滑 target 实现全屏返回手势 |
| TabBar 过渡 | 导航栏转场时同步处理 TabBar 的显隐和透明度 |
| 导航栈操作 | 提供 redirect,支持替换目标控制器之后的整个栈 |
| Delegate 转发 | 保留 UIKit delegate 能力,同时不破坏内部转场协调 |
在 Xcode 中选择 File > Add Package Dependencies...,填入:
https://github.com/monsterLinker/MonsterNavigationBar.git
或者在 Package.swift 中添加:
dependencies: [
.package(
url: "https://github.com/monsterLinker/MonsterNavigationBar.git",
from: "1.0.0"
)
]然后引入模块:
import MonsterNavigationBar组件不依赖第三方库,最低部署版本为 iOS 12。
将根导航控制器替换为 MonsterNavigationController:
import UIKit
import MonsterNavigationBar
let first = HomeViewController()
window?.rootViewController = MonsterNavigationController(rootViewController: first)在页面中只设置与全局样式不同的属性:
final class DetailViewController: UIViewController {
override func viewDidLoad() {
super.viewDidLoad()
monsterBarTintColor = UIColor(red: 0.08, green: 0.10, blue: 0.13, alpha: 0.86)
monsterTintColor = .white
monsterBlackBarStyle = true
monsterBarShadowHidden = true
}
}这些属性通过 UIViewController 扩展提供,设置在当前页面即可:
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
monsterBarStyle |
UIBarStyle |
.default |
导航栏明暗样式 |
monsterBlackBarStyle |
Bool |
false |
true 等同于 barStyle = .black |
monsterBarTintColor |
UIColor? |
nil |
当前页面的背景颜色 |
monsterBarImage |
UIImage? |
nil |
当前页面的背景图片 |
monsterTintColor |
UIColor? |
nil |
返回按钮和导航栏按钮颜色 |
monsterTitleTextAttributes |
[NSAttributedString.Key: Any] |
系统默认 | 导航栏标题属性 |
monsterBarAlpha |
CGFloat |
1 |
导航栏背景透明度,范围 0...1 |
monsterBarHidden |
Bool |
false |
隐藏导航栏内容和背景 |
monsterBarShadowHidden |
Bool |
false |
隐藏导航栏底部阴影 |
monsterBackInteractive |
Bool |
true |
是否允许交互式返回 |
monsterSwipeBackEnabled |
Bool |
true |
是否允许系统侧滑返回 |
monsterClickBackEnabled |
Bool |
true |
是否允许点击返回按钮 |
monsterSplitNavigationBarTransition |
Bool |
false |
强制拆分导航栏内容与背景进行转场 |
monsterLiquidGlassBarButtonEnabled |
Bool |
false |
iOS 26 及以上是否为页面自定义导航栏按钮显示 Liquid Glass 背景 |
滚动页面动态修改属性后,调用:
monsterBarAlpha = progress
monsterSetNeedsUpdateNavigationBar()在 iOS 26 及以上切换页面左右导航栏按钮的 Liquid Glass 样式:
monsterLiquidGlassBarButtonEnabled = true // 新版 Liquid Glass 胶囊背景
monsterLiquidGlassBarButtonEnabled = false // 旧版无胶囊背景样式属性设置后会立即更新已有的 leftBarButtonItems、rightBarButtonItems、backBarButtonItem 和单项按钮组;后续导航栏刷新时也会再次应用。页面没有自定义左侧按钮时,MonsterNavigationController 会在 iOS 26 上提供外观一致的标准返回按钮,使返回按钮也能跟随该属性切换;点击仍经过 monsterClickBackEnabled 和 shouldAllowBack(for:),侧滑返回不受影响。
UIKit 会忽略包含多个 item 的 UIBarButtonItemGroup 上的 hidesSharedBackground,因此多项按钮组仍使用系统统一背景。使用未包含 iOS 26 SDK 的旧版 Xcode 构建时,属性可以正常编译,但不会执行 Liquid Glass 样式切换。
打开 Example/NavigationBarDemo.xcodeproj 后运行 NavigationBarDemo scheme:首页各控件对应的功能如下:
| Demo 控件 | 验证内容 |
|---|---|
| 进入下一页 | push 不同导航栏配置,观察背景、标题和按钮颜色过渡 |
| 动态渐变 | 滚动顶部图片,观察透明度和标题颜色渐变 |
| 模态渐变 | 以全屏模态方式展示一个新的导航控制器 |
| 关闭页面 | dismiss 模态页面,或 pop 当前页面 |
| 导航栈操作 | 验证 popToRoot 和 redirect |
| 隐藏阴影 | 动态切换导航栏底部阴影 |
| 隐藏导航栏 | 隐藏内容和背景,同时保持转场连续 |
| 黑色导航栏样式 | 切换深色标题和按钮样式 |
| iOS 26 按钮样式 | 在 iOS 26 及以上切换 Liquid Glass 按钮;低版本不可用 |
| 图片背景 | 使用渐变图片替换颜色背景 |
| 开启侧滑返回 | 控制系统边缘返回手势 |
| 导航栏颜色 | 在白、黑、红、绿、蓝之间切换背景颜色 |
| 导航栏透明度 | 使用滑块动态调整背景透明度 |
需要在返回前执行确认逻辑时,继承 MonsterNavigationController 并覆盖 shouldAllowBack(for:)。返回 false 会同时拦截导航栏返回按钮和侧滑返回:
final class AppNavigationController: MonsterNavigationController {
override func shouldAllowBack(for viewController: UIViewController) -> Bool {
// 在这里显示确认 UI,并根据结果决定是否允许返回。
return viewController.monsterBackInteractive
}
}如果需要全屏返回,可以复用 UIKit 系统侧滑 target:
let target = interactivePopGestureRecognizer?.delegate
let pan = UIPanGestureRecognizer(
target: target,
action: #selector(handleNavigationTransition(_:))
)
pan.delegate = interactivePopGestureRecognizer?.delegate
view.addGestureRecognizer(pan)
interactivePopGestureRecognizer?.isEnabled = falseredirect 会删除目标控制器之后的页面,再把新控制器放入栈顶:
navigationController?.redirect(
to: LoginViewController(),
animated: true
)
navigationController?.redirect(
to: HomeViewController(),
target: oldHome,
animated: false
)- 打开
Example/NavigationBarDemo.xcodeproj。 - 选择
NavigationBarDemoscheme 和任意 iPhone Simulator。 - 按
Cmd + R运行 Demo。
下面的命令只做编译检查,不需要签名:
xcodebuild \
-project Example/NavigationBarDemo.xcodeproj \
-scheme NavigationBarDemo \
-destination 'generic/platform=iOS Simulator' \
-derivedDataPath /tmp/monster-demo-derived \
CODE_SIGNING_ALLOWED=NO \
build安装到已启动的模拟器:
xcrun simctl install booted \
/tmp/monster-demo-derived/Build/Products/Debug-iphonesimulator/NavigationBarDemo.app
xcrun simctl launch booted com.example.NavigationBarDemoMonsterNavigationBar始终保持isTranslucent == true,这是平滑过渡所必需的。- 背景计算优先级为:页面图片、页面颜色、全局图片、全局颜色、根据
barStyle推导的默认颜色。 monsterBarHidden只让导航栏内容和背景透明,不从视图层级移除导航栏。- 透明背景页面默认延伸到导航栏下方;在不透明背景上动态调低
monsterBarAlpha时,设置extendedLayoutIncludesOpaqueBars = true。 - 内部通过转场协调器处理 push、pop、交互式返回和 TabBar 过渡,并把 UIKit delegate 回调转发给
monsterDelegate。 - 为兼容旧代码,保留了下划线形式的命名别名,例如
monster_barAlpha和monster_setNeedsUpdateNavigationBar。
Sources/MonsterNavigationBar/
├── MonsterNavigationBar.swift
├── MonsterNavigationController.swift
├── UINavigationController+Monster.swift
└── UIViewController+Monster.swift
Example/NavigationBarDemo/
└── DemoViewController.swift
Tests/MonsterNavigationBarTests/
└── MonsterNavigationBarTests.swift
Assets/
└── demo.gif
本项目采用 MIT License。底层实现参考 listenzz/HBDNavigationBar。
