企业官网建设流程全解析

一句话场景:你想要标题栏带上"沉浸式光感模糊"的高级感,又不想再靠两个写死的高度值去给内容"让位"。鸿蒙 6.1 给了官方答案。

读完你将学会:

• 为什么过去我们要用Blank().height($r('sys.float.ohos_id_navigation_bar_height_emphasize'))这种"魔法值"来避让标题栏,以及它为什么是个临时方案。
• 鸿蒙 6.1 起怎么用HdsNavigation/HdsNavDestination的enableComponentSafeArea: true一键完成避让。
• 为什么开了这个属性后,List等滚动组件还要补一对clip(false)+cachedCount(_, true),否则光感模糊会"塌房"。

前置环境

• DevEco Studio:NEXT 版(支持 HarmonyOS 6.1 SDK 的版本)
• HarmonyOS:6.1 及以上(enableComponentSafeArea、scrollEffectOpts、systemMaterialEffect都依赖 6.1 的 HDS 组件能力)
• 依赖 Kit:@hms.hds.hdsBaseComponent、@kit.UIDesignKit、@kit.ArkUI
• 设备:真机或模拟器均可,沉浸光感效果建议在真机上观察更准确

一、先说清楚:我们过去是怎么"硬扛"避让的

鸿蒙的导航容器(HdsNavigation/HdsNavDestination)默认会把标题栏盖在内容之上。如果你又想让标题栏开启光感模糊(滚动时背景从透明到模糊渐变)——这是鸿蒙 6 那一套很好看的"沉浸式"风格——你就会遇到一个矛盾:

• 内容必须能滚到标题栏下方,模糊层才有东西可"糊"。
• 但内容默认从屏幕顶部开始,首屏会被标题栏整片挡住。

过去大家都是这么解决的——在内容最前面塞一个等高的占位:

// 老写法 1:给 HdsNavigation 的标题栏避让(带 emphasize 强调样式) Blank().height($r('sys.float.ohos_id_navigation_bar_height_emphasize')) // 老写法 2:给 HdsNavDestination 的标题栏避让(普通样式) Blank().height($r('sys.float.ohos_id_navigation_bar_height'))

能用,但本质是hack:

简而言之:避让本来该是容器的事,我们却让内容去自己挪。

二、鸿蒙 6.1 的正解:enableComponentSafeArea: true

6.1 起,HdsNavigation和HdsNavDestination的titleBar接受一个新字段enableComponentSafeArea。把它打开,容器会:

1. 自动告诉子内容"我占了多高",让子内容知道有一段"安全区域"在上面。
2. 配合子内容的expandSafeArea(),让内容绘制延伸到标题栏背后,但布局起点仍然落在标题栏下方。

也就是说:看起来"穿过"了标题栏,操作上又不会被压住。完全不需要再Blank()一个魔法值。

最小可用例(直接能跑):

import { HdsNavigation } from '@hms.hds.hdsBaseComponent'; import { hdsMaterial, ScrollEffectType } from '@kit.UIDesignKit'; import { LengthMetrics } from '@kit.ArkUI'; @Entry @Component struct Index { private dataList: number[] = new Array(100).fill(0).map((_: number, i: number) => i + 1); build() { HdsNavigation() { List() { ForEach(this.dataList, (item: number) => { ListItem() { Text(`${item}. ${item * 10 + 1}`) } }, (item: number) => item.toString()) } .width('100%') .height('100%') .expandSafeArea() // 让 List 的绘制延伸到标题栏背后 } .mode(NavigationMode.Stack) .titleBar({ content: { title: { mainTitle: 'enableComponentSafeArea' }, }, style: { // 滚动时标题栏渐变模糊 scrollEffectOpts: { enableScrollEffect: true, scrollEffectType: ScrollEffectType.GRADIENT_BLUR, blurEffectiveStartOffset: LengthMetrics.vp(0), blurEffectiveEndOffset: LengthMetrics.vp(20), }, // 标题栏的系统材质(自适应明暗与层级) systemMaterialEffect: { materialType: hdsMaterial.MaterialType.ADAPTIVE, materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE, }, }, enableComponentSafeArea: true, // ← 关键开关 }) .height('100%') .width('100%') } }

跑一下,你会看到:

• 首屏第一行就在标题栏下方,而不是被压在它后面。
• 往上滑,数字1. 11的那一行会从标题栏底部钻进去,标题栏从透明渐变成模糊,数字隐约可见。

小结:容器自己声明安全区域 + 内容声明expandSafeArea(),避让和"穿过"两件事一次解决,完全不需要Blank()。

三、坑点:为什么你照抄完发现"List 不在标题栏下面"

这是这次最容易被忽悠的地方,踩过的人都点头。

enableComponentSafeArea打开后,如果你直接拿一个普通的List(或Scroll、Grid、WaterFlow)塞进去,可能会发现:

• 内容仍然从标题栏下方开始,没有穿过去。
• 标题栏的光感模糊看上去没东西可糊——因为 List 根本没把内容画到上面。

原因有两个:

1. clip默认会裁掉超出布局区域的绘制。List 的布局起点本来就在标题栏下方,默认clip(true)等于把"想画到上面去"的部分剪没了。需要clip(false),允许 List 画出自己的布局矩形。
2. 滚动组件默认只渲染可视范围 + 一两屏的缓存。标题栏背后那块"看似可见、布局上属于 list 之外"的区域,系统不会主动给它分配 item,自然没东西可糊。cachedCount(n, true)的第二个参数true表示显示缓存项,让缓存出来的 item 也参与渲染,标题栏背后才有真实内容透上来。

所以完整的、真正能用的版本是这样:

import { HdsNavigation } from '@hms.hds.hdsBaseComponent'; import { hdsMaterial, ScrollEffectType } from '@kit.UIDesignKit'; import { LengthMetrics } from '@kit.ArkUI'; @Entry @Component struct Index { private dataList: number[] = new Array(100).fill(0).map((_: number, i: number) => i + 1); build() { HdsNavigation() { List() { ForEach(this.dataList, (item: number) => { ListItem() { Text(`${item}. ${item * 10 + 1}`) } }, (item: number) => item.toString()) } .clip(false) // ① 允许内容绘制超出 List 布局区域 .cachedCount(2, true) // ② 渲染缓存项,标题栏背后才有真实内容可糊 .width('100%') .height('100%') .expandSafeArea() } .mode(NavigationMode.Stack) .titleBar({ content: { title: { mainTitle: 'enableComponentSafeArea' }, }, style: { scrollEffectOpts: { enableScrollEffect: true, scrollEffectType: ScrollEffectType.GRADIENT_BLUR, blurEffectiveStartOffset: LengthMetrics.vp(0), blurEffectiveEndOffset: LengthMetrics.vp(20), }, systemMaterialEffect: { materialType: hdsMaterial.MaterialType.ADAPTIVE, materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE, }, }, enableComponentSafeArea: true, }) .height('100%') .width('100%') } }

记住一句话就够了:

凡是用滚动组件 +enableComponentSafeArea+ 光感模糊,三件套必须配齐:expandSafeArea()+clip(false)+cachedCount(n, true)。

进阶:为什么cachedCount的第二个参数这么关键(老手可看)

cachedCount(count: number, show?: boolean):

• count控制预加载/缓存多少个 item;
• show控制这些缓存出来的 item是否也参与显示(默认false,缓存只在内存里准备好,不上屏)。

平时我们调cachedCount大多是为了滚动平顺,设个数就完事。但在"内容要穿过标题栏"这个场景下,缓存项就是要让它上屏——标题栏背后那一段相当于"视口之外但视觉之内",只有show = true时这部分内容才会真正被画出来,光感模糊才有真实的"底料"。

count给多少合适?一般给 2~3 就够,太多会增加渲染开销。如果标题栏很高,适当加大;如果内容 item 很轻,给 1 也行。

踩坑:clip(false)会不会导致内容溢出到别的地方?

理论上clip(false)会让 List 的所有子项都可以画到布局矩形之外,听起来有点"危险"。但在这个场景里是安全的:因为 List 本身被容器约束在屏幕内,标题栏背后的内容也是落在屏幕范围内,只是落在 List 的"布局矩形"之外——这正是我们想要的。

真正要注意的是:如果你的 List 里某个 item 自身有clip(true)的子元素(比如带圆角裁剪的卡片),那些子元素的裁剪行为不受影响,仍然是各自裁。List.clip(false)只影响 List 这个容器对自身的裁剪。

举一反三

• 换成HdsNavDestination?完全一样的写法。HdsNavDestination的titleBar也支持enableComponentSafeArea: true,把上面HdsNavigation换成HdsNavDestination即可。这也是为什么"两个魔法值"会被两个组件分别处理——现在统一用一个开关。
• 换成Grid/WaterFlow/Scroll?三件套照搬:expandSafeArea()+clip(false)+cachedCount(n, true)。套路不变,这是可复用的模式。
• 不想用光感模糊,只想要纯透明叠层?把style.scrollEffectOpts和style.systemMaterialEffect整段去掉即可。enableComponentSafeArea: true单独使用也成立,只是标题栏不会做渐变模糊,内容仍然会"穿过"它。
• 要兼容低版本(<6.1)?这时候才轮到老办法出场:在内容顶部用Blank().height($r('sys.float.ohos_id_navigation_bar_height'))占位。建议用版本判断包裹,6.1+ 走新方案,低版本走老办法。

可复用套路:沉浸式避让的核心是"容器声明安全区 + 内容扩展绘制区 + 滚动组件关闭裁剪并显示缓存"。只要把这三件事对齐,无论是哪个导航容器、哪种滚动组件、是否要模糊,都能套用。

小结

回顾本文要点:

1. 过去用Blank().height($r('sys.float.ohos_id_navigation_bar_height*'))做避让,是让内容自己挪位置。
2. 鸿蒙 6.1 起,在HdsNavigation/HdsNavDestination的titleBar上打开enableComponentSafeArea: true,容器会自己声明安全区域,配合内容的expandSafeArea()一次完成避让和"穿过"。
3. 用滚动组件时,务必补齐clip(false)和cachedCount(n, true),否则内容画不进标题栏背后,光感模糊无米下炊。