前言

窗口属性和焦点管理是应用窗口行为控制的基础。通过设置窗口是否可触摸、是否可移动等属性，可以实现弹窗遮罩、浮动窗口等高级UI效果。@pura/harmony-utils 的 WindowUtil 封装了这些窗口属性管理方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、WindowUtil窗口属性核心API

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

方法	说明	参数	使用场景
setWindowTouchable(enabled)	设置窗口是否可触摸	boolean	加载遮罩、弹窗
isWindowTouchable()	判断窗口是否可触摸	无	状态查询
setWindowFocusable(enabled)	设置窗口是否可聚焦	boolean	多窗口管理
isWindowFocusable()	判断窗口是否可聚焦	无	状态查询

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 灵活控制：支持触摸和焦点的独立控制

1.2 窗口属性组合方案

触摸	聚焦	效果	适用场景
可触摸	可聚焦	正常交互	普通页面
不可触摸	可聚焦	遮罩层	加载遮罩
可触摸	不可聚焦	背景窗口	悬浮窗背景
不可触摸	不可聚焦	完全屏蔽	安全锁屏

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 窗口触摸控制

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

Button('禁止触摸')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setWindowTouchable(false);
      this.result = '窗口触摸已禁止 🚫\n适用于加载遮罩场景';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('恢复触摸')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setWindowTouchable(true);
      this.result = '窗口触摸已恢复 ✅';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 窗口焦点控制

Button('查询窗口焦点')
  .width('100%')
  .onClick(() => {
    try {
      let focusable = WindowUtil.isWindowFocusable();
      this.result = `窗口焦点: ${focusable ? '可聚焦' : '不可聚焦'}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('查询窗口属性').width('100%').onClick(() => {
        try {
          let touchable = WindowUtil.isWindowTouchable();
          let focusable = WindowUtil.isWindowFocusable();
          this.result = `可触摸: ${touchable}\n可聚焦: ${focusable}`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 加载遮罩实现

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

async function loadData() {
  WindowUtil.setWindowTouchable(false);
  try {
    await fetchData();
    ToastUtil.showToast('加载完成');
  } finally {
    WindowUtil.setWindowTouchable(true);
  }
}

4.2 超时自动恢复

function disableTouchWithTimeout(timeout: number = 5000) {
  WindowUtil.setWindowTouchable(false);
  setTimeout(() => {
    WindowUtil.setWindowTouchable(true);
  }, timeout);
}

五、注意事项

1. 触摸禁止：禁止触摸后用户无法与窗口交互，需提供恢复机制
2. 焦点管理：多窗口场景下焦点管理尤为重要
3. 超时恢复：建议设置超时自动恢复触摸，避免窗口卡死
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 异常恢复：在try-finally中确保触摸状态恢复

六、常见问题

Q1: 禁止触摸后如何恢复？

调用 WindowUtil.setWindowTouchable(true) 即可恢复，建议在finally块中确保恢复。

Q2: 多窗口场景下焦点如何管理？

每个窗口独立管理焦点，子窗口获取焦点时主窗口可能失去焦点。

Q3: 禁止触摸后弹窗还能显示吗？

可以显示弹窗，但用户无法通过触摸关闭弹窗，建议使用定时自动关闭。

Q4: isWindowTouchable()返回false但还能点击？

可能是子窗口的触摸状态，需要确认操作的是正确的窗口。

总结

WindowUtil 的窗口属性管理方法为应用提供了精细的窗口行为控制能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用触摸和焦点控制，可以实现加载遮罩、弹窗等高级UI效果。

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