文档开发者中心
我的
|

ArkUI (方舟UI框架)

HarmonyOS 5

FullScreenLaunchComponent 里面的元服务无法沉浸式

嵌入到FullScreenLaunchComponent里面的元服务本身是沉浸式的,但是嵌入进来后沉浸式失效了。只有全屏的弹窗可以沉浸式,但是普通页面无法沉浸式,FullScreenLaunchComponent有什么配置可以解决这个问题吗?
点赞
收藏
回复
6
分享
举报
浏览88 发布于2026-06-09 09:17湖南
全部评论
最多点赞
最新发布
最早发布
|
技术支持

尊敬的开发者,您好:

宿主应用和被拉起的沉浸式元服务在EntryAbility.ets中的onWindowStageCreate阶段中添加“mainWindow.setWindowLayoutFullScreen(true);”以开启沉浸式布局,您可以参考如下示例代码:

宿主应用:
收起
自动换行
深色代码主题
复制
// 宿主端 EntryAbility.ets
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  // 显式声明 storage,防止类型检查报错
  storage: LocalStorage = new LocalStorage();

  onWindowStageCreate(windowStage: window.WindowStage): void {
    // 1. 获取主窗口
    let mainWindow = windowStage.getMainWindowSync();

    // 2. 关键:强制开启全屏布局,允许内容覆盖状态栏和导航条
    mainWindow.setWindowLayoutFullScreen(true);

    // 3. 加载页面并传入 storage
    windowStage.loadContent('pages/Index', this.storage);
  }
}

Index.ets:

收起
自动换行
深色代码主题
复制
// 使用方入口界面Index.ets内容如下:
import { FullScreenLaunchComponent } from '@kit.ArkUI';

@Entry
@Component
struct Index {
  @State appId: string = ''; // 元服务appId

  build() {
    Row() {
      Column() {
        FullScreenLaunchComponent({
          content: ColumnChild,
          appId: this.appId,
          options: {},
          onTerminated: (info) => {
            console.info(`onTerminated code: ${info.code.toString()}`);
          },
          onError: (err) => {
            console.error(`onError code: ${err.code}, message: ${err.message}`);
          },
          onReceive: (data) => {
            console.info(`onReceive, data: ${JSON.stringify(data)}`);
          }
        }).width("80vp").height("80vp")
      }
      .width('100%')
    }
    .height('100%')
  }
}

@Builder
function ColumnChild() {
  Column() {
    Image($r('app.media.startIcon'))
    Text('test')
  }
}

被拉起的沉浸式元服务:
收起
自动换行
深色代码主题
复制
import { AbilityConstant, Want, EmbeddableUIAbility } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

const DOMAIN = 0x0000;

export default class EntryAbility extends EmbeddableUIAbility {
  storage = new LocalStorage();
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onCreate');
  }

  onDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onDestroy');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
    let mainWindow = windowStage.getMainWindowSync()
    this.storage.setOrCreate("window", mainWindow)
    this.storage.setOrCreate("windowStage", windowStage)
    mainWindow.setWindowLayoutFullScreen(true);

    windowStage.loadContent('pages/Index', this.storage);
  }

  onWindowStageDestroy(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    hilog.info(DOMAIN, 'testTag', '%{public}s', 'Ability onBackground');
  }
}
收起
自动换行
深色代码主题
复制
@Entry
@Component
struct ImmersiveMetaService {
  @State currentIndex: number = 0;

  build() {
    Stack({ alignContent: Alignment.Bottom }) {

      Tabs({ barPosition: BarPosition.End }) {
        TabContent() {
          Column() {
            Text("元服务内容展示区").fontSize(20).fontWeight(FontWeight.Bold)
          }
          .width('100%')
          .height('100%')
          .justifyContent(FlexAlign.Center)
        }.backgroundColor('#E6F0FF')

        TabContent() {
          Text("创作页面").fontSize(20)
        }.backgroundColor('#FFFFFF')

        TabContent() {
          Text("我的页面").fontSize(20)
        }.backgroundColor('#FFFFFF')
      }
      .width('100%')
      .height('100%')
      .barHeight(0)
      .scrollable(false)
      .expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.TOP, SafeAreaEdge.BOTTOM])

      Row() {
        this.TabItem(0, '探索')
        this.TabItem(1, '创作')
        this.TabItem(2, '我的')
      }
      .width('100%')
      .height(60)
      .backgroundColor('rgba(255, 255, 255, 0.95)')
      .backgroundBlurStyle(BlurStyle.COMPONENT_THICK)
      .padding({
        bottom: 16
      })
    }
    .width('100%')
    .height('100%')
  }

  @Builder
  TabItem(index: number, title: string) {
    Column() {
      Text(title)
        .fontSize(14)
        .fontColor(this.currentIndex === index ? '#0A59F7' : Color.Gray)
        .fontWeight(this.currentIndex === index ? FontWeight.Medium : FontWeight.Normal)
    }
    .layoutWeight(1)
    .justifyContent(FlexAlign.Center)
    .height('100%')
    .onClick(() => {
      this.currentIndex = index;
    })
  }
}
展开全部
5楼回复于2026-06-15 08:35 来自广东

开发者您好,元服务 UX 体验标准中详细介绍了沉浸式设计的标准。如开发者需使用头部以及底部导航栏,建议开发者直接调用元服务官方提供的导航栏(AtomicServiceNavigation以及AtomicServiceTabs)控件。实现沉浸式效果中的窗口设置沉浸式显示:调用窗口强制全屏布局接口setWindowLayoutFullScreen()设置窗口为沉浸式布局。页面布局范围从安全区域扩展为整个窗口(包括状态栏和导航条),所有页面均开启全屏模式,需要开发者在各页面进行避让处理,例如使用Window.getWindowAvoidArea()方法获取避让区域的高度,设置应用页面内容的上下padding实现避让状态栏和导航条。

示例代码及更多内容请参考文档:

元服务沉浸式布局与系统安全区避让的适配方案(点击查看)

2楼回复于2026-06-11 01:01 来自山东

嵌入式元服务的沉浸式效果通常不只由元服务自己决定,还受宿主窗口模式影响。FullScreenLaunchComponent 里展示时,如果宿主没有开启全屏布局,元服务普通页面很容易按宿主可用区域去避让。

建议这样拆开验证:

1. 宿主 EntryAbility 的主窗口先设置全屏布局。

2. 元服务自己的入口窗口也设置对应沉浸式布局。

3. 元服务普通页面 aboutToAppear 时再次确认安全区/全屏状态,不要只在启动页设置一次。

4. 区分“全屏弹窗可沉浸”和“普通页面可沉浸”,两者走的窗口层级不完全一样。

5. 如果 targetSdk/API 升级后行为变化,要按当前嵌入式元服务窗口规则重新验证。

核心原则是宿主和被嵌入页面要同时满足沉浸式条件,单独配置元服务页面往往不够。

6楼回复于2026-06-25 00:22 来自四川

在元服务页面生命周期中动态设置沉浸式

对于元服务内的每个页面(尤其是普通页面),可在其 aboutToAppear生命周期中重新启用沉浸式效果,并在 aboutToDisappear中恢复,确保页面显示时始终处于沉浸模式。

https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-arkui-370

4楼编辑于2026-06-12 03:18 来自广东
使用 FullScreenLaunchComponent组件拉起嵌入式元服务时,其沉浸式效果(即内容区避让系统安全区)的行为在 API Version 12及 targetSdkVersion >= 20(对应HarmonyOS 6.0.0+)发生了重要变更,旨在使嵌入式元服务与宿主应用的窗口模式保持一致。要关注宿主的沉浸设置。
参考:FullScreenLaunchComponent嵌入式运行元服务内容区避让系统安全区行为变更
3楼回复于2026-06-11 11:31 来自北京

目前看 FullScreenLaunchComponent 本身没有提供开启沉浸式的配置项。

它的定位更像是一个全屏容器,嵌入进去的元服务实际上运行在宿主提供的窗口环境里,所以很多窗口属性(状态栏、导航栏、沉浸式能力等)会受到宿主窗口限制,而不是完全继承元服务自身的配置。

你这个现象比较像是 FullScreenLaunchComponent 创建的窗口没有把页面扩展到系统栏区域,导致页面级沉浸式失效,而弹窗因为使用了独立 Window 能正常覆盖。 

建议确认几个点:

  • 元服务是否是通过独立启动时才设置沉浸式
  • 页面是否依赖 WindowStage 或 Window 的沉浸式配置
  • FullScreenLaunchComponent 场景下获取到的窗口对象是否发生变化
  • 在嵌入场景下打印窗口属性,看是否已经退出全屏状态

从目前公开能力来看,我没看到 FullScreenLaunchComponent 提供类似:

收起
自动换行
深色代码主题
复制
immersiveMode
layoutFullScreen
drawBehindSystemBar

这样的配置项。

所以如果确认是嵌入后失效,大概率不是配置问题,而是 FullScreenLaunchComponent 当前能力边界导致的。建议提一个最小 Demo 给华为工单确认是否组件用法是不是有问题。

希望能帮到你~~~

1楼回复于2026-06-10 07:38 来自辽宁
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。