harmony 鸿蒙WindowExtensionAbility（仅对系统应用开放）

2025-06-16
浏览 (1)

WindowExtensionAbility（仅对系统应用开放）

WindowExtensionAbility是一种ExtensionAbility组件，用于提供界面组合扩展能力，仅允许系统应用进行跨应用的界面拉起和嵌入。

WindowExtensionAbility必须和UIExtensionComponent一起配合使用，并根据需求处理被拉起应用的业务。WindowExtensionAbility支持以连接形式运行，系统应用必须添加UIExtensionComponent组件启动WindowExtensionAbility服务。

每个ExtensionAbility都有自己的Context，WindowExtensionAbility通过 WindowExtensionContext提供相关能力。本文描述中称被启动的WindowExtensionAbility为提供方，称启动WindowExtensionAbility的UIExtensionComponent组件为使用方。

说明：

本文档涉及系统接口的使用，请使用full-SDK进行开发。具体使用可见full-SDK替换指南。

设置一个嵌入式UIAbility

WindowExtensionAbility提供了onConnect()、onDisconnect()和onWindowReady()生命周期回调，根据需要重写对应的回调方法。

onWindowReady：当该Ability的应用窗口创建成功时触发该回调。
onConnect：当窗口扩展组件UIExtensionComponent连接该Ability时回调。
onDisconnect：当窗口扩展组件UIExtensionComponent断开与该Ability的连接时回调。

开发步骤

开发者在实现一个嵌入式应用时，需要在DevEco Studio工程中手动新建一个WindowExtensionAbility，具体步骤如下。

在工程Module对应的ets目录下，右键选择“New > Directory”，新建一个目录并命名为WindowExtAbility。
在WindowExtAbility目录，右键选择“New > ts File”，新建一个.ts文件并命名为WindowExtAbility.ts。
打开WindowExtAbility.ts文件，导入WindowExtensionAbility的依赖包，自定义类继承WindowExtensionAbility并实现onWindowReady()、onConnect()和onDisconnect()生命周期回调。

    import { WindowExtensionAbility, window } from '@kit.ArkUI';
    import { Want } from '@kit.AbilityKit';
    import { BusinessError } from '@kit.BasicServicesKit';

    export default class WindowExtAbility extends WindowExtensionAbility {
        onWindowReady(window: window.Window) {
            window.setUIContent('WindowExtAbility/pages/index1',(err:BusinessError) => {
              let pro = window.getWindowProperties();
              console.log('WindowExtension pro: ${JSON.stringify(pro)}');
              window.showWindow();
            });
        }

        onConnect(want: Want) {
            console.info('JSWindowExtension onConnect ' + want.abilityName);
        }

        onDisconnect(want: Want) {
            console.info('JSWindowExtension onDisconnect ' + want.abilityName);
        }
    }

在工程Module对应的module.json5配置文件中注册WindowExtensionAbility，type标签需要设置为“window”，srcEntry标签表示当前ExtensionAbility组件所对应的代码路径。

   {
     "module": {
       "extensionAbilities": [
            {
                "name": "WindowExtAbility",
                "srcEntry": "./ets/WindowExtAbility/WindowExtAbility.ts",
                "icon": "$media:icon",
                "description": "WindowExtension",
                "type": "window",
                "exported": true,
            }
        ],
     }
   }

拉起一个嵌入式UIAbility

系统应用可以通过UIExtensionComponent容器加载创建好的WindowExtensionAbility。

开发步骤

开发者在连接一个嵌入式应用时，需要在DevEco Studio工程中相应的pages界面中加入UIExtensionComponent控件。
在UIExtensionComponent控件中写入正确的bundleName和abilityName。
设置好宽高。示例代码如下：

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        UIExtensionComponent({
          abilityName: "WindowExtAbility",
          bundleName: "com.example.WindowExtAbility"})
          .width(500)
          .height(500)
      }
      .width('100%')
    }
    .height('100%')
    .backgroundColor(0x64BB5c)
  }
}