harmonyOS开发基础之标题栏（HdsNavigation）

代码飞天2026-04-05 21:31

一、标题栏的作用

在移动应用和桌面应用的使用中，标题栏一直发挥着不可或缺的重要作用，从早期的显示简单信息，例如：软件logo、软件名称、软件介绍等，到现今包含菜单按钮，将大量复杂的入口以图标或菜单的形式显示在标题栏，方便用户进入，标题栏一直是应用的重要组成部分，而在鸿蒙应用开发中，华为已经为我们提供了多种多样的标题栏组件方便开发者使用，让开发更加简洁高效。

二、几种标题栏组件

1.HdsNavigation的titlebar

示例代码（参考官方文档）：

ts 复制代码 
import { HdsNavigation,  ScrollEffectType, HdsNavigationTitleMode } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';

const  TITLE_BAR_HEIGHT_FREE: number = 138;
@Entry
@Component
struct Index {
  @Provide('pageInfos') pageInfos: NavPathStack = new NavPathStack();
  scroller: Scroller = new Scroller();
  @State blankHeight: number = TITLE_BAR_HEIGHT_FREE;
  @State isHideBackButton: boolean = false;
  @State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
  @State subTitle: string = 'Sub'

  build() {
    HdsNavigation(this.pageInfos) {
      Column() {
        Stack() {
          Scroll(this.scroller) {
            Column() {
              Blank().height(this.blankHeight)
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
              Text('1')
              Image($r('app.media.scene')).width('100%')
            }
          }.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
        }
      }
    }
    .titleBar({
      padding: {
        start: LengthMetrics.vp(2),
        end: LengthMetrics.vp(2)
      },
      style: {
        scrollEffectOpts: {
          enableScrollEffect: true,
          scrollEffectType: ScrollEffectType.COMMON_BLUR,
          blurEffectiveStartOffset: LengthMetrics.vp(0),
          blurEffectiveEndOffset: LengthMetrics.vp(20)
        },
        originalStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        },
        scrollEffectStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background_transparent'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        }
      },
      content: {
        title: {
          mainTitle: '主标题',
          subTitle: '副标题'
        },
        menu: {
          value: [{
            content: {
              label: 'menu1',
              icon: $r('sys.symbol.ohos_wifi'),
              isEnabled: true,
              action: () => {
                console.info("HdsNavigation menu1");
              }
            }
          }, {
            content: {
              label: 'menu2',
              icon: $r('sys.symbol.plus'),
              isEnabled: true,
            }
          }, {
            content: {
              label: 'menu3',
              icon: $r('sys.symbol.lock'),
            }
          }, {
            content: {
              label: 'menu4',
              icon: $r('sys.symbol.trunk'),
            }
          }]
        },
        backIcon: {
          label: 'backButton',
          icon: $r('sys.symbol.trunk'),
          isEnabled: true,
        }
      }
    })
    .systemBarStyle({ statusBarContentColor: '#ffff0000' }, { statusBarContentColor: '#ff02025b' })
    .titleMode(this.titleMode)
    .hideBackButton(this.isHideBackButton)
    .hideTitleBar(false)
  }
}

界面演示：

  1. titlebar属性

代码部分：

ts 复制代码 
.titleBar({
      padding: {
        start: LengthMetrics.vp(2),
        end: LengthMetrics.vp(2)
      },
      style: {
        scrollEffectOpts: {
          enableScrollEffect: true,
          scrollEffectType: ScrollEffectType.COMMON_BLUR,
          blurEffectiveStartOffset: LengthMetrics.vp(0),
          blurEffectiveEndOffset: LengthMetrics.vp(20)
        },
        originalStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        },
        scrollEffectStyle: {
          backgroundStyle: {
            backgroundColor: $r('sys.color.ohos_id_color_background_transparent'),
          },
          contentStyle: {
            titleStyle: { mainTitleColor: $r('sys.color.font_primary'), subTitleColor: $r('sys.color.font_secondary') },
            menuStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') },
            backIconStyle: { backgroundColor: $r('sys.color.comp_background_tertiary'), iconColor: $r('sys.color.icon_primary') }
          }
        }
      },
      content: {
        title: {
          mainTitle: '主标题',
          subTitle: '副标题'
        },
        menu: {
          value: [{
            content: {
              label: 'menu1',
              icon: $r('sys.symbol.ohos_wifi'),
              isEnabled: true,
              action: () => {
                console.info("HdsNavigation menu1");
              }
            }
          }, {
            content: {
              label: 'menu2',
              icon: $r('sys.symbol.plus'),
              isEnabled: true,
            }
          }, {
            content: {
              label: 'menu3',
              icon: $r('sys.symbol.lock'),
            }
          }, {
            content: {
              label: 'menu4',
              icon: $r('sys.symbol.trunk'),
            }
          }]
        },
        backIcon: {
          label: 'backButton',
          icon: $r('sys.symbol.trunk'),
          isEnabled: true,
        }
      }
    })

参数：

名称 可选 说明
padding 是 标题栏内间距设置。
style 是 标题栏样式设置。
content 是 标题栏内容区设置。
enableHoverMode 是 是否响应悬停态。
avoidLayoutSafeArea 是 是否需要标题栏主动避让安全区。
enableComponentSafeArea 是 是否将标题栏设置为组件级安全区。

content设置：

名称 可选 说明
title 是 设置标题栏标题内容。
menu 是 设置标题栏菜单栏内容。
backIcon 是 设置标题栏的返回按钮内容。
stackBuilder 是 设置标题栏顶部自定义区域。
stackBuilderComponent 是 设置标题栏顶部自定义区域。
bottomBuilder 是 设置标题栏底部自定义区域。
divider 是 设置标题栏分割线内容。
subIcon 是 设置标题栏子图标内容。

title中使用mainTitle设置主标题的内容，使用subTitle设置副标题内容。

menu中使用value数组配置菜单相关信息,参考下面配置项:

名称 可选 说明
icon 是 图标型菜单项支持的图片资源类型。不配置时，显示空白。
label 是 图标型菜单项的文本。默认值：""。
isEnabled 是 是否使能。默认值：true。true：使能。false：未使能。
action 是 当前选项被选中的事件回调。
type 是 标题栏图标类型。

如果图标数量过多时，系统会使用更多的图标隐藏菜单图标，点击后以文字的label显示隐藏的菜单项，如下：

  1. systemBarStyle属性

代码部分：

ts 复制代码 
.systemBarStyle({ statusBarContentColor: '#fff70a84' }, { statusBarContentColor: '#ff0000ff' })

其中，statusBarContentColor用于设置不同状态下系统状态栏的主题色，例如这里初始化颜色设为红色，如下：

而改变后设置为蓝色，如下：

  1. titleMode属性

代码部分：

ts 复制代码 
@State titleMode: HdsNavigationTitleMode = HdsNavigationTitleMode.FREE;
......

.titleMode(this.titleMode)

该项有多种选择，对应关系如下：

名称 值 说明
FREE 0 标题随内容滚动而动态缩放。向上滚动时缩小，向下滚动回顶部时恢复。
FULL 1 固定为大标题模式。
MINI 2 固定为小标题模式。
MODAL 3 固定为半模态模式。
  1. hideBackButton属性

示例代码：

ts 复制代码 
.hideBackButton(false)

仅在MINI状态下生效，例如设置为false，即显示返回按钮：

点击按钮即返回上一页，这里因为是第一页，所以直接退出应用。

如果设置为true，即隐藏返回按钮：

  1. hideTitleBar属性

示例代码：

ts 复制代码 
.hideTitleBar(false)

设置是否显示标题栏，设置为false即显示标题栏，设置为true即隐藏标题栏。

相关推荐
2501_920627616 小时前
Flutter 框架跨平台鸿蒙开发 - 派对策划助手应用
flutter·华为·harmonyos
沙雕不是雕又菜又爱玩6 小时前
基于HarmonyOS的笔记管理应用
harmonyos
@不误正业7 小时前
AI Agent多轮对话管理：3大架构源码级实现与性能对比（附鸿蒙实战）
人工智能·架构·harmonyos
里欧跑得慢7 小时前
Flutter 组件 powersync_core 的适配 鸿蒙Harmony 实战 - 驾驭极致离线优先架构、实现鸿蒙端高性能 SQL 增量同步与数据安全治理方案
flutter·harmonyos·鸿蒙·openharmony·powersync_core
轻口味8 小时前
HarmonyOS 6 自定义人脸识别模型9：基于tflite的人脸识别模型转换
华为·harmonyos
芙莉莲教你写代码8 小时前
Flutter 框架跨平台鸿蒙开发 - 网络安全学习应用
学习·web安全·flutter·华为·harmonyos
互联网散修9 小时前
零基础鸿蒙应用开发第二十五节：接口的行为契约能力
华为·harmonyos
@不误正业9 小时前
AI Agent工具调用深度实战-从Function-Calling到鸿蒙设备控制全链路
人工智能·华为·harmonyos
云和数据.ChenGuang11 小时前
鸿蒙应用对接扣子智能体：从 0 到 1 落地 AI 智能体集成
人工智能·华为·harmonyos
热门推荐
01GitHub 镜像站点02Qwen3.5-Omni与Qwen3.6模型全面解析（含测评/案例/使用教程）03VMware Workstation Pro 17 虚拟机完整安装教程（2026最新）042026年3月AI领域大事件：DeepSeek引领开源风暴05OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程06【技术干货】Gemma 4 上手深度指南：本地多模态大模型的新基线07Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services08UV安装并设置国内源09AI 编程效率翻倍：Superpowers Skills 上手清单 + 完整指南10纯 HTML/CSS/JS 实现的高颜值登录页，还会眨眼睛！少女心爆棚！