输入关键字搜索
开发者能力认证
鸿蒙高校创新赛
HarmonyOS 7
animation
HarmonyOS行业解决方案
layoutWeight
HarmonyOS模板&组件
bindPopup
bindsheet
CTRL+K
管理中心
全部文档版本说明工具设计指南与API参考开发与测试上架分发与运营问题处理与运维最佳实践行业解决方案
问题处理与运维
您当前正在浏览新版开发者文档中心，目录分类和层级有所调整。点击左侧当前文档分类名称前的“☰”图标，可切换文档分类。 了解新版目录
问题处理与运维开发与测试问题应用框架开发程序框架程序框架（Ability）应用启动时页面周边有白边

应用启动时页面周边有白边

更新时间: 2026-06-26 09:07
复制页面
本文导读

问题现象

应用启动时动效异常，启动图片未铺满屏幕，周边有空白。

背景知识

  • abilities标签：描述UIAbility组件的配置信息，标签值为数组类型，该标签下的配置只对当前UIAbility生效。
  • startWindowIcon标识当前UIAbility组件启动页面图标资源文件。目前startWindowIcon的大小是放多大画多大，没有能力根据设备屏幕或窗口大小自适应调整。

问题定位

  1. 根据entry\src\main\module.json5配置文件中startWindowIcon设置的图片资源，查看该图片资源的大小。
    收起
    自动换行
    深色代码主题
    复制
    1. {
    2.   "abilities": [{
    3.     "name": "EntryAbility",
    4.     "srcEntry": "./ets/entryability/EntryAbility.ets",
    5.     "launchType":"singleton",
    6.     "description": "$string:description_main_ability",
    7.     "icon": "$media:layered_image",
    8.     "label": "Login",
    9.     "startWindow": "$profile:start_window",
    10.     "startWindowIcon": "$media:startWindow",
    11.     "startWindowBackground": "$color:red",
    12.     "process": ":processTag"
    13.   }]
    14. }

  2. 在系统设置中查看屏幕的尺寸，启动页图片的大小与屏幕尺寸不一致。

分析结论

启动页图片的大小与设备分辨率不一致，导致应用启动动画周边有空白。

修改建议

  • 更换启动页图片为与屏幕宽高一致的图片。
  • 开发一个自定义的启动页的方式来实现自定义启动图，而不是只在module.json5配置文件中通过startWindowIcon字段设置启动图。
    收起
    自动换行
    深色代码主题
    复制
    1. @Entry
    2. @Component
    3. struct Index {
    4.   pageInfos: NavPathStack = new NavPathStack();
    5. 

    6.   aboutToAppear(): void {
    7.     this.pageInfos.pushPath({ name: 'Splash' }); // 跳转到启动页
    8.   }
    9. 

    10.   build() {
    11.     Navigation(this.pageInfos) {
    12.       Stack() {
    13.         Text('Hello World')
    14.           .fontSize(20)
    15.           .fontWeight(FontWeight.Bold);
    16.       }
    17.       .height('100%')
    18.       .width('100%');
    19.     }
    20.     .hideTitleBar(true)
    21.     .height('100%')
    22.     .width('100%')
    23.     .mode(NavigationMode.Stack);
    24.   }
    25. }

    src/main/ets/pages/Splash.ets：

    收起
    自动换行
    深色代码主题
    复制
    1. import { window } from '@kit.ArkUI';
    2. import { common } from '@kit.AbilityKit';
    3. 

    4. @Builder
    5. export function SplashBuilder() {
    6.   Splash();
    7. }
    8. 

    9. @Entry
    10. @Component
    11. export struct Splash {
    12.   pageInfos: NavPathStack = new NavPathStack();
    13. 

    14.   setFull(isFull: boolean) {
    15.     let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
    16.     window.getLastWindow(context).then((windowClass) => {
    17.       windowClass.setWindowLayoutFullScreen(isFull); // 启动页全屏显示
    18.       let systemBarPropertiesFull: window.SystemBarProperties = {
    19.         statusBarColor: '#00000000',
    20.         statusBarContentColor: '#ffffff'
    21.       };
    22.       let systemBarPropertiesOut: window.SystemBarProperties = {
    23.         statusBarColor: '#ffffff',
    24.         statusBarContentColor: '#000000'
    25.       };
    26.       windowClass.setWindowSystemBarProperties(isFull ? systemBarPropertiesFull : systemBarPropertiesOut);
    27.     });
    28.   }
    29. 

    30.   build() {
    31.     NavDestination() {
    32.       Stack() {
    33.         Image($r('app.media.startWindow')) // $r('app.media.startIcon')需要替换为开发者需要的图片资源文件
    34.           .width('100%')
    35.           .height('100%')
    36.           .syncLoad(true); // 设置图片为同步加载
    37. 

    38.         Column()
    39.           .width('100%')
    40.           .height('123px')
    41.           .linearGradient({
    42.             angle: 0,
    43.             colors: [[0x11000000, 0.0], [0x00000000, 1.0]]
    44.           })
    45.           .position({ y: 0 });
    46.       }
    47.       .height('100%')
    48.       .width('100%');
    49.     }
    50.     .onBackPressed(() => {
    51.       this.pageInfos.pop(); // 弹出路由栈栈顶元素
    52.       return true;
    53.     })
    54.     .onDisAppear(() => {
    55.       this.setFull(false);
    56.     })
    57.     .onReady((navContext: NavDestinationContext) => {
    58.       this.pageInfos = navContext.pathStack;
    59.       this.setFull(true);
    60.       setTimeout(() => {
    61.         this.pageInfos.pop();
    62.       }, 2000);
    63.     })
    64.     .hideTitleBar(true)
    65.     .systemTransition(NavigationSystemTransitionType.NONE)
    66.     .height('100%')
    67.     .width('100%')
    68.     .backgroundColor(Color.White);
    69.   }
    70. }

    src/main/resources/base/profile/router_map.json：

    收起
    自动换行
    深色代码主题
    复制
    1. {
    2.   "routerMap": [
    3.     {
    4.       "name": "Splash",
    5.       "pageSourceFile": "src/main/ets/pages/Splash.ets",
    6.       "buildFunction": "SplashBuilder"
    7.     }
    8.   ]
    9. }
    10.

    src/main/module.json5文件中需添加"routerMap": "$profile:router_map"。

    效果图如下：

UIContext与Ability的关系，列举常见UIContext、Ability、UIAbilityContext的关系
退出应用时的动画效果异常
简体中文
华为开发者联盟 版权所有 ©2026
问题反馈
使用条款
华为开发者联盟用户协议
关于华为开发者联盟与隐私的声明
Cookies
开源软件声明