window_utils_mac 接口文档

window_utils_mac 是一个为 macOS 编写的 Node.js 插件（Node.js Addon），使用 C++ 开发。它提供了与应用窗口和屏幕交互的工具，能够检索窗口和屏幕的信息。该插件暴露了两个主要函数：

• getWindowScreenAndBounds
• getAllWindowIDs

目录

• 安装
• 函数
  • getWindowScreenAndBounds
  • getAllWindowIDs
• 使用示例
• 错误处理
• 附加说明

---

安装

要使用 window_utils_mac，需要使用 node-gyp 构建原生插件。确保你的 macOS 系统上已安装必要的构建工具。

1. 克隆仓库

   git clone https://github.com/your-repo/window_utils_mac.git
   cd window_utils_mac

2. 安装依赖

   确保全局安装了 node-gyp：

   npm install -g node-gyp

3. 构建插件

   node-gyp configure
   node-gyp build

4. 在项目中引入

   将编译好的插件（通常位于 build/Release 目录）复制到你的项目中，并在 JavaScript 代码中引用。

   const windowUtils = require("./build/Release/window_utils_mac");

---

函数

getWindowScreenAndBounds(windowID)

描述：

根据窗口 ID 获取该窗口所属的屏幕信息和边界。这包括屏幕 ID、显示 ID 以及窗口相对于屏幕的位置和大小。

参数：

• windowID (Number): 要查询信息的窗口的唯一标识符。

返回值：

• Object: 包含以下属性的对象：
  • screenId (Number): 窗口主要显示的屏幕的标识符。
  • displayId (Number): 与屏幕关联的 CGDirectDisplayID。
  • x (Number): 窗口相对于屏幕原点的 x 坐标。
  • y (Number): 窗口相对于屏幕原点的 y 坐标。
  • width (Number): 窗口的宽度（以点为单位）。
  • height (Number): 窗口的高度（以点为单位）。

错误：

• 如果无法获取窗口列表，则抛出错误。
• 如果指定的窗口在任何屏幕上不可见，则抛出错误。

示例：

const windowUtils = require("window_utils_mac");

const windowID = 12345; // 替换为有效的窗口 ID

try {
  const info = windowUtils.getWindowScreenAndBounds(windowID);
  console.log(`屏幕 ID: ${info.screenId}`);
  console.log(`显示 ID: ${info.displayId}`);
  console.log(`窗口位置: (${info.x}, ${info.y})`);
  console.log(`窗口尺寸: ${info.width}x${info.height}`);
} catch (error) {
  console.error(`错误: ${error.message}`);
}

---

getAllWindowIDs()

描述：

获取所有屏幕上可见的窗口列表。每个窗口对象包括其 ID、名称、层级（Z 顺序），以及窗口在屏幕上可见部分的位置和大小。窗口按层级从高到低排序，即高层级的窗口在前。

参数：

• 无

返回值：

• Array<Object>: 包含窗口对象的数组，每个窗口对象包含以下属性：
  • id (Number): 窗口的唯一标识符。
  • name (String): 窗口的名称/标题。
  • layer (Number): 窗口的层级（Z 顺序）；较高的数字表示在上层。
  • x (Number): 窗口在屏幕上可见部分的 x 坐标。
  • y (Number): 窗口在屏幕上可见部分的 y 坐标。
  • width (Number): 窗口在屏幕上可见部分的宽度（以点为单位）。
  • height (Number): 窗口在屏幕上可见部分的高度（以点为单位）。

错误：

• 如果无法获取窗口列表，则抛出错误。

示例：

const windowUtils = require("window_utils_mac");

try {
  const windows = windowUtils.getAllWindowIDs();
  windows.forEach((window) => {
    console.log(`窗口 ID: ${window.id}`);
    console.log(`名称: ${window.name}`);
    console.log(`层级: ${window.layer}`);
    console.log(`位置: (${window.x}, ${window.y})`);
    console.log(`尺寸: ${window.width}x${window.height}`);
    console.log("---");
  });
} catch (error) {
  console.error(`错误: ${error.message}`);
}

---

使用示例

示例 1：获取特定窗口的屏幕和边界信息

const windowUtils = require("window_utils_mac");

const targetWindowID = 56789; // 替换为要查询的窗口 ID

try {
  const windowInfo = windowUtils.getWindowScreenAndBounds(targetWindowID);
  console.log("窗口所在屏幕:", windowInfo.screenId);
  console.log("显示 ID:", windowInfo.displayId);
  console.log(`位置: (${windowInfo.x}, ${windowInfo.y})`);
  console.log(`尺寸: ${windowInfo.width}x${windowInfo.height}`);
} catch (error) {
  console.error("无法获取窗口信息:", error.message);
}

示例 2：列出所有可见窗口

const windowUtils = require("window_utils_mac");

try {
  const allWindows = windowUtils.getAllWindowIDs();
  console.log(`总可见窗口数: ${allWindows.length}`);
  allWindows.forEach((win, index) => {
    console.log(`\n窗口 ${index + 1}:`);
    console.log(`ID: ${win.id}`);
    console.log(`名称: ${win.name}`);
    console.log(`层级: ${win.layer}`);
    console.log(`位置: (${win.x}, ${win.y})`);
    console.log(`尺寸: ${win.width}x${win.height}`);
  });
} catch (error) {
  console.error("无法获取窗口列表:", error.message);
}

---

错误处理

window_utils_mac 中的两个函数在某些情况下可能会抛出错误。合理处理这些错误对于确保应用程序的健壮性至关重要。

常见错误

1. 无法获取窗口列表

   • 原因： 插件无法访问窗口列表，可能是因为权限不足。
   • 处理方法：

     try {
       const windows = windowUtils.getAllWindowIDs();
       // 使用窗口数据
     } catch (error) {
       console.error("获取窗口列表时出错:", error.message);
       // 额外的错误处理逻辑
     }

2. 窗口在任何屏幕上不可见

   • 原因： 指定的窗口 ID 对应的窗口在任何屏幕上都不可见。
   • 处理方法：

     try {
       const info = windowUtils.getWindowScreenAndBounds(nonExistentWindowID);
     } catch (error) {
       console.error("窗口在任何屏幕上不可见:", error.message);
       // 通知用户或尝试恢复
     }

权限

macOS 可能要求你的应用程序具备特定权限才能访问窗口信息。确保你的应用程序具有必要的辅助功能权限：

1. 启用辅助功能权限

   • 前往 系统偏好设置 > 安全性与隐私 > 隐私 标签页。
   • 从侧栏选择 辅助功能。
   • 点击锁图标以进行更改并进行身份验证。
   • 将你的 Node.js 应用程序（例如 Terminal、VSCode）添加到允许控制计算机的应用程序列表中。

2. 处理权限拒绝

   如果你的应用程序缺少必要的权限，插件函数可能会失败。提示用户授予所需的权限或引导他们前往相应的设置。

---

附加说明

• 同步性质： getWindowScreenAndBounds 和 getAllWindowIDs 都是同步函数。它们会立即执行操作并返回结果，无需使用回调或 Promise。

• 性能考虑： 获取窗口和屏幕信息可能会消耗较多资源，尤其是在窗口或屏幕数量较多的情况下。建议谨慎使用这些函数，以避免性能瓶颈。

• 屏幕坐标系： 使用的是 macOS 基于点的坐标系统。如果你的应用需要支持多显示器设置，确保考虑不同屏幕分辨率和缩放因子。

• 层级排序： getAllWindowIDs 函数中的 layer 属性表示窗口的 Z 顺序。较高的层级表示窗口在上层。这对于确定窗口堆叠顺序或需要管理窗口焦点的应用程序非常有用。