前言

子窗口是HarmonyOS窗口系统的重要概念，用于实现悬浮窗、弹窗、画中画等高级UI效果。@pura/harmony-utils 的 WindowUtil 封装了子窗口的创建、显示和销毁方法，让开发者可以轻松管理子窗口的生命周期。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、WindowUtil子窗口核心API

WindowUtil 提供了以下子窗口管理方法：

方法	说明	参数	使用场景
createSubWindow(name)	创建子窗口	string	悬浮窗、弹窗
showSubWindow(name)	显示子窗口	string	子窗口显示
hideSubWindow(name)	隐藏子窗口	string	子窗口隐藏
destroySubWindow(name)	销毁子窗口	string	释放资源

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 生命周期管理：支持创建、显示、隐藏、销毁完整生命周期

1.2 子窗口生命周期

状态	方法	说明
创建	createSubWindow	创建子窗口实例
显示	showSubWindow	将子窗口显示到屏幕
隐藏	hideSubWindow	隐藏子窗口但不销毁
销毁	destroySubWindow	销毁子窗口释放资源

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 创建子窗口

import { WindowUtil } from '@pura/harmony-utils';

Button('创建子窗口')
  .width('100%')
  .onClick(async () => {
    try {
      let subWindow = await WindowUtil.createSubWindow('mySubWindow');
      this.result = '子窗口创建成功 ✅\n名称: mySubWindow';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 显示与隐藏子窗口

Button('显示子窗口')
  .width('100%')
  .onClick(async () => {
    try {
      await WindowUtil.showSubWindow('mySubWindow');
      this.result = '子窗口已显示 👁️';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('隐藏子窗口')
  .width('100%')
  .onClick(async () => {
    try {
      await WindowUtil.hideSubWindow('mySubWindow');
      this.result = '子窗口已隐藏 🙈';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 销毁子窗口

Button('销毁子窗口')
  .width('100%')
  .onClick(async () => {
    try {
      await WindowUtil.destroySubWindow('mySubWindow');
      this.result = '子窗口已销毁 🗑️';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { WindowUtil } from '@pura/harmony-utils';

@Entry
@Component
struct SubWindowDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('创建子窗口').width('100%').onClick(async () => {
        try {
          await WindowUtil.createSubWindow('demoSub');
          this.result = '子窗口创建成功';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('销毁子窗口').width('100%').onClick(async () => {
        try {
          await WindowUtil.destroySubWindow('demoSub');
          this.result = '子窗口已销毁';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 悬浮窗实现

import { WindowUtil } from '@pura/harmony-utils';

async function createFloatingWindow() {
  let subWindow = await WindowUtil.createSubWindow('floatWindow');
  await WindowUtil.showSubWindow('floatWindow');
}

async function destroyFloatingWindow() {
  await WindowUtil.hideSubWindow('floatWindow');
  await WindowUtil.destroySubWindow('floatWindow');
}

4.2 子窗口生命周期管理

aboutToDisappear() {
  try {
    WindowUtil.destroySubWindow('mySubWindow');
  } catch (e) {
    // 子窗口可能已销毁
  }
}

五、注意事项

1. 窗口名称：每个子窗口需要唯一的名称标识
2. 异步操作：子窗口操作均为异步，需使用async/await
3. 资源释放：不再使用的子窗口应及时销毁，避免内存泄漏
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 权限要求：悬浮窗可能需要系统权限

六、常见问题

Q1: 创建子窗口失败怎么办？

检查窗口名称是否重复，以及是否在UIAbility的onCreate中完成了初始化。

Q2: 子窗口可以设置大小和位置吗？

可以，创建子窗口后可以通过返回的Window对象设置大小、位置等属性。

Q3: 隐藏和销毁有什么区别？

隐藏只是不显示，子窗口仍然存在；销毁会释放所有资源，需要重新创建才能使用。

Q4: 子窗口数量有限制吗？

系统对子窗口数量有一定限制，建议按需创建并及时销毁不再使用的子窗口。

总结

WindowUtil 的子窗口管理方法为应用提供了灵活的多窗口能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用子窗口，可以实现悬浮窗、弹窗等高级UI效果。

本文基于 @pura/harmony-utils 工具库，更多功能请参考官方文档与后续系列文章。