ArkUI 自定义导航栏完全指南：从 Navigation 到沉浸式状态栏

几乎每个鸿蒙应用都需要自定义导航栏：改标题样式、加搜索框、做沉浸式首页。这篇用一个完整可跑的示例，把 Navigation 容器、状态栏沉浸和安全区处理串起来。

环境说明：Navigation 方案适用于 API 12 及以上（含 HarmonyOS 26），示例建议在 DevEco Studio 26.x 新建工程中对照练习。

方案选择：Navigation 还是自绘？

API 12 之后推荐用 Navigation 作为页面容器，它和路由、转场、返回手势天然集成。如果你的页面非常简单（单页无跳转），也可以用 Stack 自绘头部，但多页面应用请直接用 Navigation，否则转场动画和手势返回都要自己造轮子。

基础结构

@Entry
@Component
struct Index {
  @State title: string = '首页';

  build() {
    Navigation() {
      Column({ space: 16 }) {
        Text('页面内容').fontSize(16)
      }
      .padding(16)
      .width('100%')
    }
    .title(this.customTitle())
    .titleMode(NavigationTitleMode.Mini)
    .hideBackButton(false)
  }

  @Builder
  customTitle() {
    Row() {
      Text(this.title)
        .fontSize(18)
        .fontWeight(FontWeight.Bold)
    }
    .height(56)
    .padding({ left: 16 })
  }
}

.title() 接收一个自定义 Builder，想放搜索框、图标都在这里面加。NavigationTitleMode 三种模式（Free / Full / Mini）对应不同滚动行为，按需选择。

沉浸式状态栏

首页想要”图片顶到状态栏”的效果，需要在页面侧设置窗口属性：

import { window } from '@kit.ArkUI';

aboutToAppear() {
  window.getLastWindow(getContext(this)).then((win) => {
    win.setWindowLayoutFullScreen(true); // 内容延伸到状态栏下方
  });
}

关键点：setWindowLayoutFullScreen(true) 之后，你的内容会被状态栏遮挡，必须手动避让。

安全区避让（新手最大的坑）

沉浸式之后获取状态栏高度：

import { window } from '@kit.ArkUI';

@State statusBarHeight: number = 0;

aboutToAppear() {
  window.getLastWindow(getContext(this)).then((win) => {
    win.setWindowLayoutFullScreen(true);
    const avoidArea = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
    this.statusBarHeight = px2vp(avoidArea.topRect.height);
  });
}

拿到高度后给头部容器加 padding({ top: this.statusBarHeight })。不要硬编码 44 或 48，不同设备、不同系统版本的状态栏高度不一样，必须动态获取。

返回手势

Navigation 内页面通过 pageStack.pop() 返回，router 那套旧 API 在新工程中逐步淘汰，新项目直接用 Navigation + 路由栈管理。

小结

自定义导航栏 = Navigation 容器 + 自定义 title Builder + 沉浸式窗口设置 + 动态安全区避让。记住两个”不要”：不要自绘导航（多页场景），不要硬编码状态栏高度。

相关阅读：ArkTS 网络请求封装——页面做好了，接着接数据。

有收获的话，欢迎把本文分享给其他鸿蒙开发者。发现内容过时或有误？欢迎在评论区指出，我会持续更新。