目录

本文将聚焦于 UIDesignKit 的 HdsNavigation 导航壳组件与 ArkUI 布局、滚动联动、标题栏样式的搭配使用。

整体概览

UIDesignKit 的 HdsNavigation 作为“导航壳”，统一承载：

• 标题栏（Title Bar）内容与样式
• 系统状态栏样式（System Bar Style）
• 滚动联动效果（例如常见的模糊）
• 与内容区的布局层次（避免标题栏覆盖内容）

核心关键点：

• HdsNavigation：提供标题栏/系统栏/滚动联动的统一容器
• ScrollEffectType.COMMON_BLUR：常用的滚动模糊效果
• HdsNavigationTitleMode：标题栏模式（FREE/SMALL/LARGE）
• LengthMetrics.vp(...)：以 vp 作为长度单位，适配不同屏幕密度

代码结构解读

1. 引入与常量

import { HdsNavigation, HdsNavigationAttribute, ScrollEffectType, HdsNavigationTitleMode } from '@kit.UIDesignKit';
import { LengthMetrics } from '@kit.ArkUI';

const TITLE_BAR_HEIGHT_FREE: number = 138; // 与 FREE 模式标题栏高度保持一致，用于内容区预留空白（Blank）避免被覆盖

• 从 UIDesignKit 引入导航相关能力与枚举。
• 使用 ArkUI 的 LengthMetrics 以 vp 为单位传递长度。
• 通过 TITLE_BAR_HEIGHT_FREE 常量，在 FREE 模式下预留内容区头部空白，避免首屏内容被标题栏遮挡。

2. 组件与状态

@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 = '副标题';
  @State hideTitleBar: boolean = false;
  @State blurEndVp: number = 20;
  ...
}

• @Entry 标记页面入口，@Component 定义 UI 组件。
• @Provide('pageInfos') 向子树提供导航栈 NavPathStack，供 HdsNavigation 与后续页面跳转使用。
• scroller 用于控制 Scroll 组件（如回到顶部、定点）。
• blankHeight 预留顶部占位高度，避免内容被标题栏覆盖。
• isHideBackButton 控制返回键显隐（需结合导航栈或显式 backIcon 配置）。
• titleMode 选择标题栏模式（此处为 FREE，自由布局）。
• subTitle 作为可动态更新的副标题文案。
• hideTitleBar 控制整体隐藏标题栏（沉浸式场景适用）。
• blurEndVp 控制滚动模糊的生效终点（vp），值越小越早模糊。

3. build() 布局骨架

HdsNavigation(this.pageInfos) {
  Column() {
    Stack() {
      Scroll(this.scroller) {
        Column() {
          Blank().height(this.blankHeight)
          Image($r('app.media.scenery')).width('100%')
        }
      }.edgeEffect(EdgeEffect.Spring).scrollBar(BarState.Off)
    }
  }
}

• 最外层为 HdsNavigation，传入导航栈 pageInfos。
• 内容结构建议采用 Column -> Stack -> Scroll -> Column 的层次，清晰承载滚动内容。
• 通过 Blank().height(this.blankHeight) 在滚动内容的顶部预留与标题栏等高的空间，保证视觉上“内容从标题栏下方开始露出”。
• Image($r('app.media.scenery')).width('100%') 展示占位图（建议替换为本地品牌资源）。
• Scroll 设置：
  • edgeEffect(EdgeEffect.Spring)：弹性边缘效果，提升滚动体验。
  • scrollBar(BarState.Off)：隐藏滚动条，强化沉浸视觉。

标题栏（titleBar）详解

1. 基本结构

.titleBar({
  padding: {
    start: LengthMetrics.vp(2),
    end: LengthMetrics.vp(2)
  },
  style: { ... },
  content: { ... }
})

• 通过链式 .titleBar({...}) 配置标题栏。
• padding 使用 vp 为单位，保证在不同设备密度下的视觉一致性。

2. 滚动联动与样式分层

style: {
  scrollEffectOpts: {
    enableScrollEffect: true,
    scrollEffectType: ScrollEffectType.COMMON_BLUR,
    blurEffectiveStartOffset: LengthMetrics.vp(0),
    blurEffectiveEndOffset: LengthMetrics.vp(this.blurEndVp)
  },
  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') }
    }
  }
}

• scrollEffectOpts：
  • 开启滚动联动效果（enableScrollEffect: true）。
  • 使用 COMMON_BLUR 模糊类型，满足常见“下滑标题栏模糊”的需求。
  • 配置模糊的生效区间：起点 0vp，终点由状态 blurEndVp 控制（默认 20vp）。
• 样式分为两层：
  • originalStyle：未滚动或未达到模糊阈值时的背景与内容色彩。
  • scrollEffectStyle：达到模糊阈值后的背景与内容色彩（通常透明/半透明，需注意可读性）。
• 颜色引用统一使用系统资源 $r('sys.color...')，保证与系统主题一致并提升适配性。

3. 标题栏内容

content: {
  title: { mainTitle: '一级标题', subTitle: this.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 }
}

• title：主标题固定为 '一级标题'，副标题绑定状态 this.subTitle，便于动态更新（例如显示当前过滤条件、数据计数、网络状态等）。
• menu：右侧菜单区支持多个项，每项可配置 label / icon / isEnabled / action；menu1 演示了绑定日志输出的 action。
• backIcon：返回键外观定义（文案/图标/启用状态）。返回键显隐还需结合 .hideBackButton(this.isHideBackButton) 与实际导航栈行为。

系统状态栏与标题模式

.systemBarStyle({ statusBarContentColor: '#0A59F7' }, { statusBarContentColor: '#C7C7CD' })
.titleMode(this.titleMode)
.hideBackButton(this.isHideBackButton)
.hideTitleBar(this.hideTitleBar)

• .systemBarStyle(original, scrolled)：
  • 分别指定原始状态与滚动状态的系统状态栏前景色，形成与标题栏风格的联动统一。
• .titleMode(this.titleMode)：
  • 标题栏模式会影响布局与高度：
    • FREE：自由布局，适配自定义内容与高度（本例使用该模式）。
    • SMALL/LARGE：标准模式，具备固定高度与样式规范。
• .hideBackButton(this.isHideBackButton)：
  • 控制返回键是否显示（与导航栈或 backIcon 配合）。
• .hideTitleBar(this.hideTitleBar)：
  • 控制是否隐藏整个标题栏，适用于全屏媒体、沉浸式场景。

交互与体验要点

滚动体验：

弹性边缘 EdgeEffect.Spring 增强手感。
隐藏滚动条 BarState.Off 提升沉浸感。

视觉一致：

LengthMetrics.vp(...) 作为单位，保证不同密度设备下的尺寸一致性。
颜色统一使用系统资源 $r('sys.color...')，保障暗色/浅色主题适配与可访问性。

可读性与对比度：

originalStyle 与 scrollEffectStyle 需保证字体/图标与背景之间对比度足够，避免滚动后文字不可读。

内容不被覆盖：
通过 Blank().height(this.blankHeight) 与 TITLE_BAR_HEIGHT_FREE 的配合，确保首屏内容在标题栏下方露出。

结语

HdsNavigation 标题栏、系统栏与滚动联动整合为一个可配置的“导航壳”，结合 ArkUI 的布局与滚动容器，实现了精致且易维护的页面结构。掌握 FREE/SMALL/LARGE 模式、模糊阈值、系统色资源与占位策略等关键点，可在实际业务中快速搭建具有一致体验的页面。 同时UIDesignKit还提供了一系列的UI 组件更加友好的适配多端应用，好了下课~~~