鸿蒙沉浸式

以下是将所有内容重新梳理整合后的完整技术指南，采用结构化框架和实战示例风格：

鸿蒙沉浸式UI开发终极指南

------双轨方案解析与避坑实践（2025版）

一、设计核心：理解系统边界

1. 界面分区模型

typescript 复制代码

// 系统UI区域划分示意图（图1）
interface ScreenAreas {
  avoidArea: {   // 系统独占区（禁止布局）
    top: number; // 状态栏高度 (StatusBar)
    bottom: number; // 导航条高度 (NavigationBar)
  };
  safeArea: Rect; // 应用安全布局区
}

2. 沉浸式设计目标

视觉融合：状态栏/导航条颜色与主界面一致
交互避让：可操作元素自动避开系统区域
动态响应：适应分屏、旋转、折叠屏等场景

二、方案一：窗口全屏布局（高自由度方案）

适用场景

✅ 游戏HUD控件 ✅ 视频播放器 ✅ 自定义状态栏

实现路径

javascript 复制代码

/*===== 模式1：保留系统UI =====*/
import window from '@ohos.window';

// STEP1: 激活全屏模式
window.getTopWindow().then(win => {
  win.setWindowLayoutFullScreen(true);
  
  // STEP2: 获取动态避让区
  const avoidArea = win.getWindowAvoidArea(window.AvoidAreaType.TYPE_SYSTEM);
  
  // STEP3: 设置安全边距
  Column() {
    CustomHeader() // 自定义顶部内容
    Scroll() { /* 主内容区 */ }
    CustomFooter() // 自定义底部控件
  }
  .padding({
    top: avoidArea.topRect.height, 
    bottom: avoidArea.bottomRect.height
  })
  
  // STEP4: 颜色透传（可选）
  win.setWindowSystemBarProperties({
    statusBarColor: '#00FFFFFF', // 透明背景
    isStatusBarLightIcon: true  // 浅色图标
  })
});

/*===== 模式2：隐藏系统UI =====*/
win.setWindowSystemBarEnable(['status', 'navigation'], false);
// 注：用户可通过手势上滑唤出导航条

避坑指南

scss 复制代码

// 错误案例：未做动态避让（图3）
Column() {
  Button('底部按钮').height(50)
} // 旋转屏后按钮被导航条遮挡

// 正解：监听区域变化
win.on('avoidAreaChange', (area) => {
  updateUI(area.topRect.height, area.bottomRect.height)
});

三、方案二：组件安全区方案（快速沉浸方案）

适用场景

✅ 电商首页 ✅ 社交Feed流 ✅ 普通页签应用

核心API

csharp 复制代码

/*===== 全局背景融合 =====*/
win.getMainWindowSync()
  .setWindowBackgroundColor('#F5F5F5'); // 状态栏/导航条同步颜色

/*===== 组件级延伸 =====*/
// 案例1：通栏Banner图
Image($r('app.media.header_bg'))
  .expandSafeArea(
    [window.SafeAreaType.SYSTEM], 
    [window.SafeAreaEdge.TOP]  // 顶部延伸
  )

// 案例2：底部悬浮按钮
Button('立即购买')
  .expandSafeArea(
    [window.SafeAreaType.SYSTEM],
    [window.SafeAreaEdge.BOTTOM] // 底部延伸
  )

特殊场景适配

scss 复制代码

// 滚动容器（图5/6）
Scroll()
  .clipContent(window.ContentClipMode.SAFE_AREA) // 安全区外裁剪
  .backgroundImage($r('app.media.bg'))

// 页签组件（默认延伸）
Tabs() { ... } // 自动延伸至导航条

// 顶部底部双色分离（图7）
Column() {
  TopBar()
    .expandSafeArea([window.SafeAreaType.SYSTEM], [window.SafeAreaEdge.TOP])
  ContentArea()
  BottomBar()
    .expandSafeArea([window.SafeAreaType.SYSTEM], [window.SafeAreaEdge.BOTTOM])
}

四、致命陷阱与破解之道

1. 尺寸0危机

arduino 复制代码

// 折叠屏展开时避让区高度可能为0
const topMargin = avoidArea.topRect.height > 0 ? 
                  avoidArea.topRect.height : 24; // 安全值

2. 组件尺寸禁忌

scss 复制代码

// ⛔ 绝对禁止（引发布局崩溃）
Image().expandSafeArea(...).width(200)

// ✅ 唯一正解
Image().expandSafeArea(...).width('100%')

3. 滚动容器铁律

scss 复制代码

// ❌ 子组件设置无效
Scroll() {
  Image().expandSafeArea(...) // 延伸失效
}

// ✅ 必须父容器设置
Scroll()
  .expandSafeArea(...) {
    Image() // 延伸生效
  }

五、方案决策树

flowchart TD A[需求分析] --> B{"需要自定义状态栏内容？"} B -->|是| C[窗口全屏布局] B -->|否| D{"仅需背景延伸？"} D -->|是| E[组件安全区方案] D -->|否| C C --> F{"是否隐藏系统UI？"} F -->|是| G[setWindowSystemBarEnable false] F -->|否| H[动态避让+颜色透传] E --> I{"背景类型？"} I -->|纯色| J[setWindowBackgroundColor] I -->|图片/视频| K[expandSafeArea分域延伸]

六、行业最佳实践

1. 电商首页模板

scss 复制代码

Column() {
  // 顶部通栏：安全区延伸
  SearchBar()
    .expandSafeArea([window.SafeAreaType.SYSTEM], [window.SafeAreaEdge.TOP])
  
  // 中部内容：自动避让
  BannerSwiper()
  GoodsGrid()
  
  // 底部页签：自动延伸
  Tabs().expandSafeArea([window.SafeAreaType.SYSTEM])
}

2. 视频播放器方案

csharp 复制代码

// 播放时隐藏系统UI
function enterFullscreen() {
  win.setWindowSystemBarEnable(['status','navigation'], false);
  VideoPlayer().fullscreen(true);
}

// 退出时恢复
function exitFullscreen() {
  win.setWindowSystemBarEnable(['status','navigation'], true);
}

3. 游戏场景优化

scss 复制代码

// 动态避让 + 手势响应
win.setWindowSystemBarEnable(['status'], false); // 保留导航条
GameHUD()
  .margin({ bottom: avoidArea.bottomRect.height })

// 三指下滑唤出菜单
Gesture({ fingers: 3, direction: GestureDirection.Down })
  .onAction(() => showGameMenu())

终极结论

方案	优势	代价	推荐场景
窗口全屏布局	完全控制权，可自定义系统区域	需动态监听避让区变化	游戏/播放器/AR应用
组件安全区方案	开发简单，属性配置即生效	无法定制系统区域内容	电商/社交/工具类应用

避雷红线：

⚠️ 禁止 绝对定位+ 固定尺寸+ 安全区延伸三者共存

⚠️ 折叠屏必须检测避让区高度0的边界情况

⚠️ 滚动容器延伸必须设置在父组件

完整示例工程：

GitHub@HarmonyOS-Immersive-Demo

图示详解：[避让区原理] | [滚动容器方案] | [页签组件延伸]