list_windows

屏幕、窗口与界面 · macOS · Windows

效果: 读取. 状态: 受限可用.

“受限可用”表示工具可能取决于版本、平台、权限、账户或配置，并不表示它在所有安装中都已启用。

macOS

用途

列出任意应用在屏幕上的窗口，包括 window_id、所属应用的 bundle id 和名称、标题、边界（全局坐标空间、左上角原点、以点为单位）、display_id（即 CGDirectDisplayID，与 list_displays 一致，因此可以查出窗口位于哪个显示器）、layer（0 = 普通应用窗口；非零 = 面板/浮层/菜单）以及 is_focused。窗口标题需要屏幕录制权限；没有权限时会返回明确的 permission_required 错误，而不是没有标题的结果。可选 app_bundle_id 筛选器；注意，Electron 类应用的窗口往往由具有不同 bundle id 的 HELPER 进程拥有，因此即使应用明显显示在屏幕上，筛选结果也可能为空。on_screen_only 默认为 TRUE，会排除最小化、隐藏以及其他空间中的窗口；传入 false 可查看它们。include_overlays 默认为 FALSE，会排除非零 layer 的窗口（通知中心、小组件、菜单）；传入 true 可包含它们，并使用结果中的 layer 将其与普通窗口区分开。include_minimized_state 默认为 FALSE（每个应用需额外一次辅助功能查询，因此为可选项）；传入 true 可为每个窗口添加 `minimized`（true/false），并且当 on_screen_only 为 true（默认）时，还会带回该筛选原本会丢弃的最小化窗口；未授予辅助功能权限时，`minimized` 为 `null`（未知），也不会补回最小化窗口，绝不会给出猜测的 false，因此无需先将最小化窗口调到前台，就可以找到或截取它。结果为空时，此工具会返回 `note`，说明是哪个筛选器导致结果为空以及应改传什么；请阅读它，而不要断定该应用没有窗口。window_id 在会话内保持稳定，可供后续定位使用。

必填输入

此平台的架构未声明必填输入，但仍可能存在可选选择器或运行时要求。

权限与确认

架构未声明明确的确认参数。这并不代表可以未经许可操作；请检查效果并取得授权。

仅使用用户在此平台上授权的应用、账户和资源。请查阅此工具针对平台的说明，以了解其连接和权限要求；本目录不声称需要额外的 OAuth 范围或操作系统授权。

英文规范技术架构 — macOS

{
  "properties": {
    "app_bundle_id": {
      "description": "Only return windows owned by this app bundle id.",
      "type": "string"
    },
    "include_minimized_state": {
      "description": "Add `minimized` (true/false) to each window via an Accessibility lookup; null without Accessibility granted (default false).",
      "type": "boolean"
    },
    "include_overlays": {
      "description": "Include non-zero-layer windows — Notification Center, desktop widgets, menus (default false).",
      "type": "boolean"
    },
    "on_screen_only": {
      "description": "Only on-screen windows (default true).",
      "type": "boolean"
    }
  },
  "required": [],
  "type": "object"
}

文档示例

list_windows 的文档示例。请勿执行此示例。所示参数属于虚构数据集；在实际调用前，请解析真实标识符并获得授权。

{}

Windows

用途

列出本机上打开的窗口：窗口 id、所属应用（exe 名称）、pid、标题、边界 {x,y,w,h} 和显示器 id。仅限 Windows（使用 Win32 窗口 API）。可使用 app_bundle_id 按应用筛选（在 Windows 上为 exe 名称的子字符串匹配）。on_screen_only 默认为 TRUE，会排除最小化和无标题的窗口（与 mac-swift 的 list_windows 一致，#3634）；传入 false 可查看它们。include_minimized_state 默认为 FALSE；传入 true 可为每个窗口添加 `minimized`（true/false），并且当 on_screen_only 为 true（默认）时，还会保留该筛选原本会丢弃的最小化窗口（与 mac-swift 对齐，#3663）；与 Mac 上受辅助功能限制的查询不同，IsIconic 在 Windows 上无需权限，因此 `minimized` 始终能得到结果，此处绝不会是 null/未知。