空间化(Spatial UI)是HarmonyOS系统在视觉体验层面的一次重要升级。它通过沉浸光感材质与悬浮组件两大核心能力,让应用界面呈现出精致、通透、有层次的视觉效果,同时配合智感握姿等智能交互,提升UX的精致程度。
沉浸光感是空间化视觉的基石,为组件(标题栏、导航栏、工具栏等)提供三种视觉效果:内容相关的毛玻璃模糊、按压状态的弹性光效反馈、以及滑动过程的透明度渐变。悬浮组件则是空间化的交互载体,底部导航栏从传统的贴底色块变为悬浮圆角胶囊,配合MiniBar折叠展开、智感握姿左右跟随等能力,让交互更加自然流畅。空间化的效果如下所示:

本文将从沉浸光感的基础概念切入,重点围绕首眼沉浸光感、自适应悬浮导航与智感握姿智能交互三大应用场景,系统介绍如何在HarmonyOS应用中快速接入沉浸光感能力。
沉浸光感是一套高品质视觉与动效体系。通过模拟真实物理光照模型,在UI组件内部产生细腻的光晕、反射和折射效果,从而打造出通透玻璃质感,提升应用的视觉沉浸感和交互反馈的真实度。它赋予组件以下视觉特性:
特性 | 说明 |
|---|---|
通透材质 | 组件背景呈现毛玻璃效果,内容可透过组件隐约可见,营造层次感与通透感。 |
渐变模糊 | 标题栏随页面滑动产生渐变模糊效果,从透明到模糊平滑过渡。 |
按压弹性反馈 | 用户按压组件时产生弹性缩放动画,提供触觉层面的反馈。 |
按压点光源 | 按压时在触点位置产生光晕扩散效果,增强交互的视觉反馈。 |
材质流光 | 组件表面呈现微妙的流光效果,随视角和状态变化,提升精致感。 |
智能反色 | 当底层内容颜色与组件前景色接近时,自动调整前景色以保证可读性。 |
沉浸光感视觉示意图如下所示:

为应对不同设备的性能差异,沉浸光感提供了多个档位供开发者选择:
档位 | 说明 | |
|---|---|---|
强 | EXQUISITE | 完整的沉浸光感效果,包含所有视觉特性,适合高性能设备。 |
均衡(默认) | GENTLE | 适度的沉浸光感效果,在视觉效果与性能之间取得平衡。 |
弱 | SMOOTH | 轻量级沉浸光感效果,仅保留核心视觉特性,适合低性能设备。 |
系统自适应 | ADAPTIVE | 由系统根据设备性能自动选择合适的档位,推荐大多数场景使用。 |
沉浸光感效果由材质滤镜、折射、高光、阴影等多层效果叠加而成,渲染时需要消耗GPU资源,不合理使用会显著增加功耗。在实际应用中,总体原则是将沉浸光感效果作为一种"稀缺"视觉资源使用,具体参考沉浸光感功耗优化。
沉浸光感的适配要从框架层面整体规划,核心策略是:
为有效实现沉浸光感效果,应遵循“从整体到局部”的适配原则:首先通过整体框架适配确立应用的基础视觉规范,为后续工作奠定基础;在此基础上,针对标题栏、底部导航及内容区域组件进行针对性调整,以确保视觉风格统一与交互体验连贯。
应用需要将传统的Navigation、Tabs等组件替换为HDS系列组件:
已采用HDS系列组件的应用,即可通过systemMaterialEffect属性配置沉浸光感效果,且始终跟随最新规范,大大减少了适配工作量。
组件开启沉浸光感可以查看组件适配沉浸光感,系统介绍各组件如何通过应用级开关与组件级配置开启沉浸光感,涵盖沉浸光感的视觉效果、设置方法及适配要点,帮助开发者快速完成沉浸光感的组件适配。
本文通过组件级开启方式设置沉浸式系统材质,设置方式分三种方式开启:
通过设置组件的systemMaterial属性来开启新材质效果。该属性本身是一个开关:
当前支持设置的组件包括:Select下拉菜单的menuSystemMaterial、Navigation标题栏的systemMaterial。
弹窗类组件或方法包括:Popup、Tips、Menu、BindSheet、showActionMenu、AlertDialog、CustomDialog、ActionSheet、CalendarPickerDialog、DatePickerDialog、TextPickerDialog、TimePickerDialog、Toast、Select、AlphabetIndexer气泡弹窗、Text设置copyOption后长按或双击触发的文本菜单、SelectionMenu(结合bindSelectionMenu一起使用)。
标题栏是沉浸光感最直观的体现。沉浸光感标题栏示意图如下图所示:

通过HdsNavigation或HdsNavDestination的titleBar属性,可以配置标题栏的滚动效果与材质效果。
关键属性值说明:
属性 | 说明 |
|---|---|
渐变模糊效果,标题栏随滑动从透明渐变为模糊。 | |
自适应材质类型,系统根据场景自动选择材质风格。 | |
自适应材质强度,系统根据设备性能自动选择档位。 |
渐变模糊效果对比:
两种效果都需要配合systemMaterialEffect材质属性使用,才能呈现完整的沉浸光感效果.
在沉浸光感页面中,标题栏和状态栏支持滑动隐藏,具体可参考标题栏动态显隐。具体实现方案如下:
设置barOverlap(true)以启用悬浮模糊背景,通过barFloatingStyle配置悬浮样式,可将HdsTabs切换为悬浮胶囊形态,并通过barBottomMargin调整与内容区域的间距,增强视觉轻盈感。
悬浮导航示意图如下:

悬浮导航栏的沉浸光感效果可通过barFloatingStyle中的systemMaterialEffect属性进行配置,其中materialType用于定义材质风格,materialLevel则控制材质强度。
沉浸光感示意图如下:

针对悬浮导航的多功能场景,例如音乐播放等需同时展示底部导航和播放控制的场景,HdsTabs提供了MiniBar能力,即在底部导航栏中嵌入一个可折叠展开的迷你栏。
MiniBar示意图如下图所示:

对于内容区域中的普通组件,可通过设置其systemMaterial属性为ImmersiveMaterial实例来启用新材质效果。支持三个关键参数配置:
沉浸光感开启后,除了弹窗类组件或方法、Slider、Toggle,其他组件仅在以下区域中生效:Navigation/NavDestination标题栏,或横向Tabs中barPosition为BarPosition.End的底部TabBar中。
效果示意图如下图所示:

应用首眼是用户打开应用的第一印象,沉浸光感能让首眼效果焕然一新。基于HDS提供的HdsNavigation与HdsTabs组件,通过配置沉浸光感材质,即可打造精致的首眼视觉效果。
首眼沉浸效果-强 | 首眼沉浸效果-均衡 | 首眼沉浸效果-弱 |
|---|---|---|
|
|
|
沉浸光感标题栏的实现通过设置titleBar.style.systemMaterialEffect以启用材质效果,设置titleBar.style.scrollEffectOpts以配置标题栏的滚动效果。
import {
hdsMaterial,
HdsNavigation,
HdsNavigationMenuContentOptions,
HdsNavigationTitleMode,
HideMode,
ScrollEffectType,
TextStyleMode,
} from '@kit.UIDesignKit';
// ...
HdsNavigation() {
// ...
}
// ...
.titleBar({
// ...
style: {
scrollEffectOpts: {
enableScrollEffect: true,
scrollEffectType: ScrollEffectType.GRADIENT_BLUR,
// ...
},
systemMaterialEffect: {
materialType: hdsMaterial.MaterialType.ADAPTIVE,
materialLevel: this.customMaterialLevel.level,
},
},
// ...
})
// ... 实现方案如下:
.hideBackButton(false)
.titleMode(HdsNavigationTitleMode.MINI)
.dynamicHideTitleBar({
hideTitleArea: true,
hideStatusBar: true,
mode: HideMode.SCROLL_UP_TO,
})
// ...
.bindToScrollable([this.scroller]) 首页底部导航可通过HdsTabs悬浮模式实现,配置barFloatingStyle属性可自定义悬浮栏样式,包括圆角、背景色及位置偏移等参数,适配多设备布局需求。
HdsTabs({ controller: this.controller }) {
// ...
}
.scrollable(false)
.barOverlap(true)
.vertical(false)
.barPosition(BarPosition.End)
.onAttach(() => {
try {
this.controller.preloadItems([0, 1, 2, 3, 4]);
} catch (error) {
Logger.error(TAG, `OnAttach preloadItems failed`);
}
})
.barFloatingStyle({
barBottomMargin: this.globalInfoModel.naviIndicatorHeight > 0 ? this.globalInfoModel.naviIndicatorHeight :
$r('sys.float.padding_level8'),
adaptToHandedness: true,
systemMaterialEffect: {
materialType: hdsMaterial.MaterialType.ADAPTIVE,
materialLevel: this.customMaterialLevel.level,
}
}) 悬浮导航栏的材质效果通过统一配置systemMaterialEffect的参数SystemMaterialParams,让标题栏与悬浮导航栏呈现出协调一致的光感视觉风格。
HdsNavigation() {
// ...
}
// ...
.titleBar({
// ...
style: {
// ...
systemMaterialEffect: {
materialType: hdsMaterial.MaterialType.ADAPTIVE,
materialLevel: this.customMaterialLevel.level,
},
},
// ...
})
// ... import { uiMaterial } from '@kit.ArkUI';
import { deviceInfo } from '@kit.BasicServicesKit';
import { hdsMaterial } from '@kit.UIDesignKit';
export class MaterialUtil {
// ...
public static getMaterialOptions<T>(option: T): MaterialOptions<T> | T {
if (deviceInfo.apiAvailable('26.0.0') && hdsMaterial.getSystemMaterialTypes().length > 0) {
const materialOptions = option as MaterialOptions<T>;
materialOptions.systemMaterial = new uiMaterial.ImmersiveMaterial({
style: uiMaterial.ImmersiveStyle.THICK,
interactive: true,
lightEffect: { color: undefined }
});
return materialOptions;
}
return option;
}
}
interface MaterialOptions<T> extends ThisType<T> {
systemMaterial?: SystemUiMaterial;
} private menuId: string = 'MaterialLevelMenu' + this.currentIndex;
private menus: HdsNavigationMenuContentOptions = {
value: [
{
content: {
label: $r('app.string.level'),
icon: $r('sys.symbol.house_fill'),
type: TextStyleMode.NORMAL,
componentId: this.menuId,
action: () => {
try {
const uiContext = this.getUIContext();
const promptAction = this.getUIContext().getPromptAction();
const contentNode = new ComponentContent(uiContext, wrapBuilder(materialLevelMenu))
promptAction.openMenu(contentNode, { id: this.menuId }, MaterialUtil.getMaterialOptions<MenuOptions>(
{ mask: false, backgroundBlurStyle: BlurStyle.COMPONENT_THICK }) as MenuOptions)
.catch((error: BusinessError) => {
Logger.error(TAG, `Show menu failed. cause code: ${error.code}, msg: ${error.message}`);
});
} catch (error) {
Logger.error(TAG, `Show menu failed. cause msg: ${error.message}`);
}
}
}
}
],
}; 自适应悬浮-展开 | 自适应悬浮-折叠1 | 自适应悬浮-折叠2 |
|---|---|---|
|
|
|
在音乐播放场景中,采用主HdsTabs与可折叠MiniBar的组合方案。MiniBar作为嵌入HdsTabs的迷你控制栏,可灵活切换折叠/展开状态。示例效果折叠时呈现紧凑播放控制条,展开时展示完整播放信息与控制按钮,实现空间高效利用与操作便捷性的统一。
设置barFloatingStyle的materialType材质效果与materialLevel材质等级均为自适应(ADAPTIVE)模式。
通过barFloatingStyle方法的miniBar属性自定义迷你栏。
import {
HdsBarStyle,
hdsMaterial,
HdsNavDestination,
HdsTabs,
HdsTabsController,
ScrollEffectType,
} from '@kit.UIDesignKit';
// ...
private controller: HdsTabsController = new HdsTabsController();
@Local globalInfoModel: GlobalInfoModel =
AppStorageV2.connect(GlobalInfoModel, StorageKey.GLOBAL_INFO) ?? new GlobalInfoModel();
@Local isMiniBar: boolean = true;
@Builder
miniBarBuilder() {
Row() {
// ...
}
}
// ...
HdsTabs({ controller: this.controller }) {
// ...
}
.barOverlap(true)
.vertical(false)
.barPosition(BarPosition.End)
.barFloatingStyle({
barBottomMargin: this.globalInfoModel.naviIndicatorHeight > 0 ? this.globalInfoModel.naviIndicatorHeight :
$r('sys.float.padding_level8'),
systemMaterialEffect: {
materialType: hdsMaterial.MaterialType.IMMERSIVE,
materialLevel: hdsMaterial.MaterialLevel.ADAPTIVE
},
miniBar: {
miniBarBuilder: () => this.miniBarBuilder(),
onBarStyleChange: (miniBarStyle: HdsBarStyle) => {
this.isMiniBar = miniBarStyle === HdsBarStyle.COLLAPSE
}
}
})
// ... MiniBar可根据设备宽度自动适配展开/折叠状态:宽屏设备(如平板)默认展开,窄屏设备(如手机)默认折叠,无需开发者手动干预。