李钟意讲前端

外观

咨询/接单/付费bug修复/学习交流群

Node Addon 屏幕捕获接口文档（支持 Windows 和 macOS） ​

本文档详细介绍了 Node.js 插件中用于屏幕捕获的各个方法。每个方法都包括其功能描述、参数说明、返回值以及相关备注。此插件支持 Windows 和 macOS 平台，具体实现根据不同平台有所差异。

方法概览 ​

方法名称描述参数返回值备注
captureScreen捕获指定显示器的屏幕内容。hMonitorId (number, 可选): 目标显示器的句柄 ID。默认为 0，表示主显示器。Object返回一个包含 bmpData (Buffer)、width (number) 和 height (number) 的对象。支持 Windows 和 macOS。
captureEntireDesktop捕获整个桌面的屏幕内容（包括所有显示器）。无Object返回一个包含 bmpData (Buffer)、width (number) 和 height (number) 的对象。当前仅支持 Windows，macOS 需进一步实现。

详细方法说明 ​

captureScreen(hMonitorId?: number) ​

捕获指定显示器的屏幕内容。

  • 参数:

    • hMonitorId (number, 可选): 目标显示器的句柄 ID。
      • Windows: hMonitorId 对应于 HMONITOR 类型的显示器句柄。传入 0 或省略参数时，默认为主显示器。
      • macOS: hMonitorId 对应于 CGDirectDisplayID。传入 0 或省略参数时，默认为主显示器。

  • 返回值:

    • Object: 一个 JavaScript 对象，包含以下属性：
      • bmpData (Buffer): RGBA 格式的图像数据。
      • width (number): 图像的宽度。
      • height (number): 图像的高度。

  • 使用示例:

    javascript
    const addon = require("./build/Release/addon");

// 捕获主显示器的屏幕
const screenData = addon.captureScreen();
console.log(`宽度: ${screenData.width}, 高度: ${screenData.height}`);

// 通过显示器句柄捕获特定显示器的屏幕（仅 Windows 示例）
const specificMonitorId = 1; // 示例显示器 ID
const specificScreenData = addon.captureScreen(specificMonitorId);
console.log(
  `特定显示器 - 宽度: ${specificScreenData.width}, 高度: ${specificScreenData.height}`
);

  • 平台特定说明:

    • Windows:
      • 使用 HMONITOR 类型的显示器句柄来指定目标显示器。
      • 如果未找到指定的显示器句柄，将默认使用主显示器。
    • macOS:
      • 使用 CGDirectDisplayID 来指定目标显示器。
      • 当前实现支持捕获单个显示器的屏幕内容。捕获多个显示器的内容需进一步实现。

captureEntireDesktop() ​

捕获整个桌面的屏幕内容（包括所有显示器）。

  • 参数:

    • 无

  • 返回值:

    • Object: 一个 JavaScript 对象，包含以下属性：
      • bmpData (Buffer): RGBA 格式的图像数据。
      • width (number): 图像的总宽度。
      • height (number): 图像的总高度。

  • 使用示例:

    javascript
    const addon = require("./build/Release/addon");

// 捕获整个桌面的屏幕
const desktopData = addon.captureEntireDesktop();
console.log(
  `桌面总宽度: ${desktopData.width}, 桌面总高度: ${desktopData.height}`
);

  • 平台特定说明:

    • Windows:
      • 当前实现支持捕获整个桌面的屏幕内容，包括所有连接的显示器。
      • 使用 DPI 感知以确保捕获的图像具有正确的尺寸和分辨率。
    • macOS:
      • 当前代码中 captureEntireDesktop 方法在 macOS 下尚未实现。
      • 需要根据 macOS 的屏幕捕获机制（如使用 CGWindowListCreateImage 等 Core Graphics API）进行进一步开发。

注意事项 ​

  • 日志记录:

    • 每次调用 captureScreen 或 captureEntireDesktop 方法时，都会检查并备份日志文件 debug.log。如果日志文件大小超过 1MB，将自动备份为 debug.old.log 并创建新的日志文件。
    • 日志文件记录了每次截图的时间戳、截图区域的尺寸及截图所耗费的时间等信息，便于调试和性能分析。

  • 性能:

    • 屏幕捕获操作可能会消耗一定的系统资源，尤其是在高分辨率显示器或多显示器配置下。
    • 建议在必要时调用这些方法，并避免频繁调用以减少系统负担。

  • 权限（macOS 相关）:

    • 在 macOS 上，应用程序需要获得屏幕录制的权限才能成功捕获屏幕内容。
    • 请确保在系统偏好设置中为运行 Node.js 的应用程序授予屏幕录制权限。

  • 错误处理:

    • 如果截图操作失败，相关方法可能会抛出异常或返回不完整的数据。建议在调用这些方法时使用 try-catch 块进行错误处理。

示例用法 ​

以下是一个完整的示例，展示如何在 Windows 和 macOS 上使用这些方法进行屏幕捕获。

javascript
const addon = require("./build/Release/addon");

try {
  // 捕获主显示器的屏幕
  const screenData = addon.captureScreen();
  console.log(
    `主显示器 - 宽度: ${screenData.width}, 高度: ${screenData.height}`
  );
  // 处理 bmpData，例如保存为文件
  require("fs").writeFileSync("screenshot.png", screenData.bmpData);

  // 捕获整个桌面的屏幕（仅 Windows 支持）
  const desktopData = addon.captureEntireDesktop();
  console.log(
    `桌面总宽度: ${desktopData.width}, 桌面总高度: ${desktopData.height}`
  );
  // 处理 bmpData，例如保存为文件
  require("fs").writeFileSync("desktop_screenshot.png", desktopData.bmpData);
} catch (err) {
  console.error("屏幕捕获失败:", err);
}

方法对比 ​

通用方法名称Windows 特定实现macOS 特定实现描述
captureScreen支持支持捕获指定显示器的屏幕内容。
captureEntireDesktop支持尚未实现捕获整个桌面的屏幕内容，包括所有显示器。

确保在使用这些方法时，根据目标平台传递正确的参数，特别是在指定显示器句柄时。对于 macOS 用户，若需要实现 captureEntireDesktop 方法，可参考 macOS 的 Core Graphics API 进行开发。

方法详细描述 ​

captureScreen(hMonitorId?: number) ​

描述 ​

捕获指定显示器的屏幕内容，并返回图像数据及其尺寸。此方法支持 Windows 和 macOS 平台，根据传入的显示器句柄 ID 捕获相应显示器的内容。

参数 ​

  • hMonitorId (number, 可选): 目标显示器的句柄 ID。
    • Windows: hMonitorId 对应于 HMONITOR 类型的显示器句柄。传入 0 或省略参数时，默认为主显示器。
    • macOS: hMonitorId 对应于 CGDirectDisplayID。传入 0 或省略参数时，默认为主显示器。

返回值 ​

  • Object: 一个 JavaScript 对象，包含以下属性：
    • bmpData (Buffer): RGBA 格式的图像数据。
    • width (number): 图像的宽度。
    • height (number): 图像的高度。

使用示例 ​

javascript
const addon = require("./build/Release/addon");

// 捕获主显示器的屏幕
const screenData = addon.captureScreen();
console.log(`主显示器 - 宽度: ${screenData.width}, 高度: ${screenData.height}`);

// 保存截图为文件
const fs = require("fs");
fs.writeFileSync("screenshot.png", screenData.bmpData);

// 捕获特定显示器的屏幕（仅 Windows 示例）
const specificMonitorId = 1; // 示例显示器 ID
const specificScreenData = addon.captureScreen(specificMonitorId);
console.log(
  `特定显示器 - 宽度: ${specificScreenData.width}, 高度: ${specificScreenData.height}`
);
fs.writeFileSync("specific_screenshot.png", specificScreenData.bmpData);

captureEntireDesktop() ​

描述 ​

捕获整个桌面的屏幕内容，包括所有连接的显示器，并返回图像数据及其总尺寸。目前该方法在 Windows 平台上已实现，macOS 平台需要进一步开发。

参数 ​

  • 无

返回值 ​

  • Object: 一个 JavaScript 对象，包含以下属性：
    • bmpData (Buffer): RGBA 格式的图像数据。
    • width (number): 图像的总宽度。
    • height (number): 图像的总高度。

使用示例 ​

javascript
const addon = require("./build/Release/addon");

try {
  // 捕获整个桌面的屏幕（仅 Windows 支持）
  const desktopData = addon.captureEntireDesktop();
  console.log(
    `桌面总宽度: ${desktopData.width}, 桌面总高度: ${desktopData.height}`
  );

  // 保存截图为文件
  const fs = require("fs");
  fs.writeFileSync("desktop_screenshot.png", desktopData.bmpData);
} catch (err) {
  console.error("捕获整个桌面失败:", err);
}

平台特定说明 ​

  • Windows:
    • 当前实现支持捕获整个桌面的屏幕内容，包括所有连接的显示器。
    • 使用 DPI 感知以确保捕获的图像具有正确的尺寸和分辨率。
  • macOS:
    • 当前 captureEntireDesktop 方法尚未在 macOS 上实现。
    • 需要根据 macOS 的屏幕捕获机制（如使用 CGWindowListCreateImage 等 Core Graphics API）进行进一步开发。

总结 ​

本文档介绍了 Node.js 插件中用于屏幕捕获的 captureScreen 和 captureEntireDesktop 方法，支持 Windows 和 macOS 平台。通过这些方法，开发者可以在应用程序中集成屏幕捕获功能，实现截图、桌面监控等功能。请根据平台差异，传递正确的参数，并处理可能的权限和性能问题。

如有任何疑问或需要进一步的功能支持，请参考相关平台的开发文档或联系插件维护者。