前言

窗口截图可以将整个窗口内容渲染为图片，适用于全屏分享、问题反馈等场景。@pura/harmony-utils 的 SnapshotUtil 封装了窗口截图方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

一、SnapshotUtil窗口核心API

SnapshotUtil 提供了以下窗口截图方法：

方法	说明	返回类型	使用场景
snapshotWindow()	截取当前窗口	PixelMap	全屏截图
snapshotWindowToFile(path)	截取窗口到文件	void	保存全屏截图

1.1 核心特性

• 简洁易用：封装复杂API为一行调用，降低使用门槛
• 类型安全：完整的TypeScript类型定义，编译期即可发现错误
• 异常处理：内置异常捕获机制，避免运行时崩溃
• 全屏截取：一键截取整个窗口内容

1.2 组件截图与窗口截图对比

特性	组件截图	窗口截图
范围	指定组件	整个窗口
精确度	高	全屏
适用场景	局部分享	全屏分享

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 截取当前窗口

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

Button('截取当前窗口')
  .width('100%')
  .onClick(async () => {
    try {
      let pixelMap = await SnapshotUtil.snapshotWindow();
      this.result = `窗口截图成功 ✅\n尺寸: ${pixelMap.getImageInfo().size.width}x${pixelMap.getImageInfo().size.height}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 窗口截图保存

Button('窗口截图保存')
  .width('100%')
  .onClick(async () => {
    try {
      let path = FileUtil.getFilesDir() + '/window_shot.png';
      await SnapshotUtil.snapshotWindowToFile(path);
      this.result = `窗口截图已保存 ✅\n路径: ${path}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

三、完整页面示例

import { SnapshotUtil, ImageUtil } from '@pura/harmony-utils';

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

  build() {
    Column({ space: 12 }) {
      Button('全屏截图').width('100%').onClick(async () => {
        try {
          let pixelMap = await SnapshotUtil.snapshotWindow();
          let uri = await ImageUtil.savePixelMap(pixelMap);
          this.result = '已保存到相册';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 问题反馈全屏截图

import { SnapshotUtil, ImageUtil } from '@pura/harmony-utils';

async function captureFeedbackScreenshot(): Promise<string> {
  let pixelMap = await SnapshotUtil.snapshotWindow();
  let base64 = await ImageUtil.pixelMapToBase64(pixelMap);
  return base64;
}

4.2 自动截图保存

async function autoSaveScreenshot(): Promise<void> {
  let timestamp = DateUtil.formatDate(Date.now(), 'yyyyMMdd_HHmmss');
  let path = FileUtil.getCacheDir() + `/screenshot_${timestamp}.png`;
  await SnapshotUtil.snapshotWindowToFile(path);
}

五、注意事项

1. 隐私保护：窗口截图可能包含敏感信息，注意保护
2. 权限要求：保存到相册需要相应权限
3. 异步操作：截图方法为异步，需使用await
4. 初始化依赖：使用前需确保 AppUtil.init() 已调用
5. 性能影响：频繁截图可能影响性能

六、常见问题

Q1: 窗口截图包含状态栏吗？

取决于系统实现，通常包含状态栏和导航栏。

Q2: 窗口截图模糊？

检查窗口的实际分辨率，高分辨率屏幕可能需要特殊处理。

Q3: 可以截取其他应用的窗口吗？

不可以，只能截取自己应用的窗口。

Q4: 截图时弹窗会被截取吗？

是的，当前窗口上的所有可见内容都会被截取。

总结

SnapshotUtil 的窗口截图方法为全屏分享和反馈提供了便捷支持。本文详细介绍了核心API、使用步骤、完整示例、进阶用法以及常见问题的解决方案。开发者可以利用窗口截图实现全屏分享、问题反馈等功能。

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