Skip to content

UINavigationController ​

UINavigationController 表示一个页面栈,称为导航控制器。它自己是一个页面(UIViewController),但不显示自己的内容,而是管理一组页面:栈顶的那个页面显示在屏幕上,其余的页面留在栈里不显示。

对栈有两种操作。推入(push)把一个新页面放到栈顶,屏幕切换到新页面。弹出(pop)拿走栈顶的页面,屏幕回到它下面的那一页。「列表 → 详情 → 再下一层」这种一层层进入、再一层层返回的界面,用的就是它。

导航控制器在屏幕顶部画一条导航条。导航条正中显示栈顶页面的标题;栈里不止一页时,导航条左侧有一个返回按钮,上面的字是上一页的标题。导航条、返回按钮和切换页面时的动画都由系统提供。导航条上显示什么由栈顶的页面决定:标题读页面的 title,按钮读页面的 navigationItem,见 UINavigationItem。

它是一个页面,所以 UIViewController 的成员它都有:可以做窗口的根页面,可以被模态呈现,也可以放进 UITabBarController 的一个标签里。

继承关系:EventTarget → NSObject → UIResponder → UIViewController → UINavigationController

怎么在页面之间跳转、按路径跳转、在页面离开栈时清理,见指南在页面之间跳转。

构造函数 ​

UINavigationController()

创建一个导航控制器。可以给一个页面做栈底,也可以是空栈。

实例属性 ​

还继承 UIViewController 的属性。

属性说明
viewControllers栈里的全部页面,栈底在前
topViewController 只读栈顶的页面
visibleViewController 只读此刻用户看到的页面
isNavigationBarHidden导航条藏不藏
isToolbarHidden底部的工具条藏不藏
toolbar 只读导航控制器自己管的底部工具条
interactivePopGestureRecognizer 只读左滑返回的手势。设它的 isEnabled 开关左滑返回
interactiveContentPopGestureRecognizer 只读在内容区任意位置右划返回的手势(iOS 26 起)
hidesBarsOnSwipe往上划页面时自动藏起导航条
hidesBarsOnTap点一下页面切换导航条的显示
hidesBarsWhenKeyboardAppears键盘出现时自动藏起导航条
hidesBarsWhenVerticallyCompact屏幕高度紧张时自动藏起导航条
barHideOnSwipeGestureRecognizer 只读hidesBarsOnSwipe 用的手势
barHideOnTapGestureRecognizer 只读hidesBarsOnTap 用的手势

实例方法 ​

还继承 UIViewController 的方法。

改栈的方法最后一个参数都是 { animated },不写时没有动画:

方法说明
pushViewController()把一个页面推入栈顶
popViewController()弹出栈顶的页面
popToViewController()弹出某一页上面的所有页面
popToRootViewController()弹出栈底以外的所有页面
setViewControllers()换掉整个栈
showViewController()显示一个页面,等同于带动画的 pushViewController()

导航条:

方法说明
setNavigationBarHidden()藏起或显示导航条,可以带动画
setToolbarHidden()藏起或显示底部的工具条,可以带动画

事件 ​

事件什么时候派发
beforeshow导航控制器即将显示某个页面
show导航控制器已经显示某个页面,转场动画结束
beforeappear、appear、beforedisappear、disappear继承自 UIViewController:导航控制器自己的视图出现和消失
traitchange继承自 UIViewController:外观特征变了

监听别的名字不会报错:它被当成自定义事件,只有自己用 dispatchEvent() 派发时才会触发。

注意:导航控制器被模态呈现时,在它上面监听 beforedismiss、dismiss、dismissattempt 不报错,但收不到。

用户自己也能返回 ​

栈不只由代码改变。用户有两种不经过代码的返回方式:

  • 点返回按钮。 导航条左侧的那个按钮。
  • 左滑返回。 手指从页面的左边缘往右滑,栈顶页面跟着手指滑走,露出上一页。见左滑返回。

这两种操作都由系统直接完成弹出,代码没有调用任何方法。弹出完成后,导航控制器派发 show 事件,事件对象的 viewController 是此刻显示的页面,nav.viewControllers 已经是弹出之后的栈。

所以任何时候都以 nav.viewControllers 为准。代码里如果另外记了一份「现在在第几层」「当前路径是什么」,要在 show 的回调里按 nav.viewControllers 重新对齐。

栈里的页面由谁保管 ​

推入之后不需要自己保存页面。 导航控制器保管栈里的每一个页面,窗口保管导航控制器。页面在栈里期间不会被回收,挂在页面上的数据、加在页面上的事件监听器都一直有效。验收用例验证过:推入之后丢掉对页面的引用,再从 nav.topViewController 读回来,得到的是同一个对象,上面的数据还在。

弹出之后,导航控制器不再保管这个页面。 这时:

  • 代码里没有别的地方保存它,它连同它的视图、视图上的按钮和监听器一起被回收。用户点返回按钮或左滑返回弹出的页面也一样(实测:点返回后,被弹出的页面在几秒内被回收)。
  • 代码里保存了它(比如 popViewController() 的返回值),它就一直留在内存里,可以再次推入。

页面被回收不需要代码做任何事,也没有事件通知。同一个页面对象不能在栈里出现两次。

左滑返回 ​

左滑返回是系统提供的手势:手指从页面的左边缘按下,往右滑,栈顶的页面跟着手指移动;滑过一定距离后松手,页面被弹出。不需要写任何代码。

它和点返回按钮的结果相同:页面被弹出,导航控制器派发 beforeshow 和 show。实测:栈里有 2 页时,从导航控制器视图的左边缘往右滑 144 pt,show 的 viewController 是上一页,栈变成 1 页。

手势起作用需要满足四个条件。这四条是 iOS 的规则,除第一条和第四条外未在模拟器验证:

条件说明
栈里不止一页栈底的页面没有上一页可以返回
栈顶的页面用的是系统的返回按钮页面设了 leftBarButtonItems,或者把 hidesBackButton 设成 true,手势就不起作用
手势没有被禁用interactivePopGestureRecognizer 的 isEnabled 是 true,这是默认值
从导航控制器自己的视图的左边缘开始滑导航控制器没有占满屏幕时,起点是它的视图的左边缘,不是屏幕的左边缘

手指滑到一半又滑回去松手时,页面不会被弹出。这时是否派发事件,未在模拟器验证。导航条藏起来之后左滑返回是否还能用,未在模拟器验证。

要暂时不让用户返回(比如提交订单的过程中),把这个手势的 isEnabled 设成 false,完成后再设回 true。iOS 26 起还有一个在内容区任意位置右划返回的手势 interactiveContentPopGestureRecognizer,要完全关掉左滑返回,两个都要关。导航条上的返回按钮不受影响。

示例 ​

首页和详情页 ​

从空白 App 开始:建一个导航控制器,首页上放一个按钮,点按钮进入详情页,并在每次页面切换完成时在控制台输出一行。

js
application.addEventListener('sceneconnect', (e) => {
  const win = new UIWindow(e.scene);
  const home = new UIViewController();
  home.title = '首页';
  home.view.backgroundColor = 'systemBackground';

  const nav = new UINavigationController(home);
  win.rootViewController = nav;
  win.makeKeyAndVisible();

  const button = UIButton.buttonWithType('system');
  button.setTitle('看详情', { forState: ['normal'] });
  button.translatesAutoresizingMaskIntoConstraints = false;
  home.view.addSubview(button);
  NSLayoutConstraint.activateConstraints([
    button.centerXAnchor.constraintEqualToAnchor(home.view.centerXAnchor),
    button.centerYAnchor.constraintEqualToAnchor(home.view.centerYAnchor),
  ]);

  button.addEventListener('click', () => {
    const detail = new UIViewController();
    detail.title = '详情';
    detail.view.backgroundColor = 'systemTeal';
    nav.pushViewController(detail, { animated: true });
  });

  nav.addEventListener('show', (ev) => {
    const event = /** @type {Event & { viewController: UIViewController }} */ (ev);
    console.log('现在显示', event.viewController.title, ',栈里有', nav.viewControllers.length, '页');
  });
});

效果

  • 屏幕顶部有一条导航条,正中是「首页」。页面正中是蓝色的「看详情」。
  • 点「看详情」,带着动画切换到青色的详情页。导航条的标题变成「详情」,左侧出现返回按钮,上面的字是「首页」。控制台输出 现在显示 详情 ,栈里有 2 页。
  • 点返回按钮,或者从页面左边缘往右滑,回到首页。控制台输出 现在显示 首页 ,栈里有 1 页。

推入、点返回、左滑返回时 show 的派发和栈的页数是实测的。App 启动后首页第一次显示时是否也输出一行,未在模拟器验证。这段代码没有作为一个整体在模拟器运行过,其中用到的每个 API 都在验收用例里运行过。

对应的 iOS API ​

ObjCJS
[[UINavigationController alloc] initWithRootViewController:home]new UINavigationController(home)
[nav pushViewController:vc animated:YES]nav.pushViewController(vc, { animated: true })
[nav popViewControllerAnimated:YES]nav.popViewController({ animated: true })
[nav popToViewController:vc animated:YES]nav.popToViewController(vc, { animated: true })
[nav popToRootViewControllerAnimated:YES]nav.popToRootViewController({ animated: true })
[nav setViewControllers:@[a, b] animated:YES]nav.setViewControllers([a, b], { animated: true })
nav.viewControllers = @[a, b]nav.viewControllers = [a, b]
nav.navigationBarHidden = YESnav.isNavigationBarHidden = true
[nav setNavigationBarHidden:YES animated:YES]nav.setNavigationBarHidden(true, { animated: true })
vc.navigationControllervc.navigationController
- navigationController:willShowViewController:animated:nav.addEventListener('beforeshow', …)
- navigationController:didShowViewController:animated:nav.addEventListener('show', …)
nav.toolbarHidden = NOnav.isToolbarHidden = false
[nav setToolbarHidden:NO animated:YES]nav.setToolbarHidden(false, { animated: true })
nav.interactivePopGestureRecognizer.enabled = NOnav.interactivePopGestureRecognizer.isEnabled = false
nav.hidesBarsOnSwipe = YESnav.hidesBarsOnSwipe = true
[nav showViewController:vc sender:button]nav.showViewController(vc, { sender: button })
nav.delegate不开放。事件用 addEventListener() 监听
nav.navigationBar导航条上的标题和按钮用页面的 navigationItem 设

参见 ​