前言

窗口方向控制和隐私模式是应用开发中的常见需求。方向锁定用于游戏、视频等场景，隐私模式则用于防止屏幕截图和录屏。@pura/harmony-utils 的 WindowUtil 封装了这些功能，开发者可以轻松实现方向控制和隐私保护。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、WindowUtil方向与隐私核心API

WindowUtil 提供了以下方向控制和隐私模式方法：

方法	说明	参数	使用场景
setOrientation(orientation)	设置窗口方向	Orientation枚举	游戏、视频方向锁定
getOrientation()	获取当前窗口方向	无	方向状态查询
setPrivacyMode(enabled)	设置隐私模式	boolean	防截屏、防录屏

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 即时生效：方向和隐私模式设置后立即生效

1.2 窗口方向类型

方向类型	说明	适用场景
PORTRAIT	竖屏	列表浏览、聊天
LANDSCAPE	横屏	视频播放、游戏
UNSPECIFIED	未指定	跟随系统旋转

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 设置窗口方向

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

Button('锁定竖屏')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setOrientation(window.Orientation.PORTRAIT);
      this.result = '已锁定竖屏 📱';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('锁定横屏')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setOrientation(window.Orientation.LANDSCAPE);
      this.result = '已锁定横屏 📺';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 设置隐私模式

Button('开启隐私模式')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setPrivacyMode(true);
      this.result = '隐私模式已开启 🔒\n截屏将显示黑屏';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

Button('关闭隐私模式')
  .width('100%')
  .onClick(() => {
    try {
      WindowUtil.setPrivacyMode(false);
      this.result = '隐私模式已关闭 🔓';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('锁定竖屏').width('100%').onClick(() => {
        WindowUtil.setOrientation(window.Orientation.PORTRAIT);
        this.result = '竖屏已锁定';
      });
      Button('锁定横屏').width('100%').onClick(() => {
        WindowUtil.setOrientation(window.Orientation.LANDSCAPE);
        this.result = '横屏已锁定';
      });
      Button('开启隐私模式').width('100%').onClick(() => {
        WindowUtil.setPrivacyMode(true);
        this.result = '隐私模式开启，截屏将显示黑屏';
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 视频播放方向自动切换

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

function onVideoFullScreen(isFull: boolean) {
  if (isFull) {
    WindowUtil.setOrientation(window.Orientation.LANDSCAPE);
  } else {
    WindowUtil.setOrientation(window.Orientation.PORTRAIT);
  }
}

4.2 敏感信息页面隐私保护

aboutToAppear() {
  WindowUtil.setPrivacyMode(true);
}

aboutToDisappear() {
  WindowUtil.setPrivacyMode(false);
}

五、注意事项

1. 方向锁定：设置方向后需手动恢复，否则整个应用都会锁定
2. 隐私模式：开启后截屏和录屏均显示黑屏，需在离开页面时关闭
3. 权限要求：部分方向设置可能需要系统权限
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 生命周期：建议在页面生命周期中管理隐私模式的开关

六、常见问题

Q1: 设置方向后没有生效怎么办？

检查是否在UIAbility的onCreate中完成了AppUtil.init()初始化，以及窗口是否已正确加载。

Q2: 隐私模式下录屏也是黑屏吗？

是的，开启隐私模式后截屏和录屏都会显示黑屏，这是系统级的安全保护。

Q3: 如何恢复自动旋转？

调用 WindowUtil.setOrientation(window.Orientation.UNSPECIFIED) 即可恢复自动旋转。

Q4: 隐私模式会影响性能吗？

隐私模式对性能影响极小，仅在截屏/录屏时生效，不影响正常渲染。

总结

WindowUtil 的方向控制和隐私模式方法为应用提供了窗口行为定制和安全保护能力。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。合理使用这些功能，可以提升应用的专业性和安全性。

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