夜雨聆风学习资料网

ARTICLE · 1007214

iOS 27 终于把滚动隐藏导航栏做成 API 了,不用再手撸 contentOffset

发布时间：2026-09-16 01:50:43 最近访问：2026-09-16 01:50:42
iOS 27 终于把滚动隐藏导航栏做成 API 了,不用再手撸 contentOffset

这里每天分享一个 iOS 的新知识，快来关注我吧

前言

做内容流 App，基本都要那个交互：用户往下滑，导航栏收起来腾出屏幕；往上滑，导航栏回来。以前实现这套，得监听 scrollViewDidScroll，手动算 contentOffset 的进度，再驱动导航栏的 frame 和透明度，代码又长又脆。

iOS 27 终于把这个常见需求做成开箱即用的 API 了 —— UIBarMinimization。今天讲讲它怎么用。

UIBarMinimization 是个啥

UIBarMinimization 是一个配置对象，控制导航栏对滚动的反应。它挂在 UINavigationItem 上，设好之后系统接管整套最小化、恢复、内容回流的动画，你不用再碰 contentOffset。

三个核心属性：

  • minimizationBehavior：导航栏何时开始最小化
  • restorationBehavior：最小化后何时恢复
  • safeAreaAdjustment：最小化时 safe area 是否跟着变

这三个拆开很合理，因为"收起""展开""内容回流"本来就是三件不同的事，可以独立调。

最基础用法

先看最简单的挂法：

final class FeedViewController: UITableViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        title = "动态"
        let minimization = UIBarMinimization()
        minimization.minimizationBehavior = .onScrollDown
        minimization.restorationBehavior = .automatic
        minimization.safeAreaAdjustment = .automatic
        navigationItem.navigationBarMinimization = minimization
    }
}

用户向下滚动，导航栏最小化，动画和协调都由系统负责，不用你监听 contentOffset、算进度、自己动导航栏。

minimizationBehavior：何时收起

类型是 UIBarMinimizationBehavior，四个选项：

  • .automatic：系统按当前上下文决定，安全默认
  • .never：禁用最小化，导航控件得一直可见时用
  • .onScrollDown：向下滚动时收起，文章、feed、文档这类自上而下内容最自然
  • .onScrollUp：向上滚动时收起，适合底部对齐内容，比如某些聊天或时间线布局
minimization.minimizationBehavior = .onScrollDown

restorationBehavior：何时恢复

类型是 UIBarMinimizationRestorationBehavior，跟最小化分开设：

  • .automatic：系统选，标准交互下反向滚动就恢复
  • .atScrollEdge：一直最小化，直到滚到内容边缘才恢复
minimization.restorationBehavior = .atScrollEdge

.atScrollEdge 适合导航栏只是"界面装饰"的场景，长阅读/浏览时不会因为小幅度方向反复就反复展开收起，画面更安静。

safeAreaAdjustment：内容要不要回流

类型是 UIBarMinimizationSafeAreaAdjustment，三个选项：

  • .automatic：系统决定，大多数屏幕从这里起步
  • .enabled：safe area 随导航栏变化，内容回流到腾出的空间，适合列表、文章、文档
  • .disabled：safe area 不变，栏照样动画但布局不扩展，适合全屏媒体、自定义布局、自己管 insets 的页面
minimization.safeAreaAdjustment = .enabled

完整一点的例子

凑一个 feed 列表，把 UIBarMinimization 和 UIListContentConfiguration 配起来：

final class FeedViewController: UITableViewController {
    private struct Post {
        let title: String
        let summary: String
        let tag: String
    }
    private let posts: [Post] = [
        Post(title: "设计 Liquid Glass", summary: "现代 UIKit 的层次与材质", tag: "设计"),
        // ...
    ]
    override func viewDidLoad() {
        super.viewDidLoad()
        title = "动态"
        view.backgroundColor = .systemBackground
        tableView.register(UITableViewCell.self, forCellReuseIdentifier: "PostCell")
        tableView.rowHeight = UITableView.automaticDimension
        tableView.estimatedRowHeight = 96
        var minimization = UIBarMinimization()
        minimization.minimizationBehavior = .onScrollDown
        minimization.restorationBehavior = .automatic
        minimization.safeAreaAdjustment = .automatic
        navigationItem.navigationBarMinimization = minimization
    }
    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        posts.count
    }
    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let cell = tableView.dequeueReusableCell(withIdentifier: "PostCell", for: indexPath)
        let post = posts[indexPath.row]
        var content = UIListContentConfiguration.subtitleCell()
        content.text = post.title
        content.secondaryText = "\(post.tag) · \(post.summary)"
        content.textProperties.font = .preferredFont(forTextStyle: .headline)
        content.secondaryTextProperties.font = .preferredFont(forTextStyle: .subheadline)
        content.secondaryTextProperties.color = .secondaryLabel
        content.textToSecondaryTextVerticalPadding = 6
        cell.contentConfiguration = content
        cell.accessoryType = .disclosureIndicator
        return cell
    }
}

这套配置：向下滚动收起导航栏、小幅度方向反复时保持收起、滚到边缘恢复、safe area 跟着调，内容顺势回流。

提醒一句：iOS 27 还在 beta，这个 API 可能随版本调整，上线前盯紧 release notes。

最后

你之前手撸过滚动隐藏导航栏吗？评论区聊聊你被 contentOffset 折磨过的经历~

这里每天分享一个 iOS 的新知识，快来关注我吧

相关学习资料