# @cjser/get-windows 中文文档

规范地址：https://npmcn.com/package/%40cjser/get-windows/

版本：10\.0\.0-cjser\.2
npm 元数据更新时间：2026-10-31T18:23:29.070Z
中文译文更新时间：2026-10-31T19:53:09.639Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cjser/get-windows
原文对照：https://npmcn.com/package/%40cjser/get-windows/?lang=original
源码仓库：https://code.moenext.com/3rdeye/cjser

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：291 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：node-gyp ^13\.0\.2
- 首次发布：2026-05-07T12:51:24.527Z
- 最新版本发布：2026-10-31T18:23:28.888Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

获取有关活动窗口和打开窗口的元数据（标题、id、边界、所有者、URL等）

## 安装

```sh
npm install @cjser/get-windows
```

也可以使用：`pnpm add @cjser/get-windows`、`yarn add @cjser/get-windows`、`bun add @cjser/get-windows`

## README

# 让windows

> 获取有关 [活动窗口](https://en.wikipedia.org/wiki/Active_window) 并打开窗口（标题，id，边界，所有者，URL等）

适用于macOS 10.14+、Linux ([请注意](https://npmcn.com/package/%40cjser/get-windows/#readme-linux-support))，以及Windows 7+。

## 安装

```sh
npm install get-windows
```

**[这是一个ESM包，需要你使用ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c)**

## 使用

```js
import {activeWindow} from 'get-windows';

console.log(await activeWindow(options));
/*
{
    title: 'Unicorns - Google Search',
    id: 5762,
    bounds: {
        x: 0,
        y: 0,
        height: 900,
        width: 1440
    },
    owner: {
        name: 'Google Chrome',
        processId: 310,
        bundleId: 'com.google.Chrome',
        path: '/Applications/Google Chrome.app'
    },
    url: 'https://sindresorhus.com/unicorn',
    memoryUsage: 11015432
}
*/
```

## API

### activeWindow(选项?)

获取有关活动窗口的元数据。

#### 选项

类型: `object`

##### accessibilityPermission **(仅macOS)**

类型: `boolean`  
默认值: `true`

启用可访问性权限检查。将其设置为 `false` 将阻止macOS 10.15及更新版本上的访问权限提示。这个 `url` 属性将无法检索。

##### screenRecordingPermission **(仅macOS)**

类型: `boolean`  
默认值: `true`

开启录影权限检查。将其设置为 `false` 将阻止macOS 10.15及更新版本上的屏幕录制权限提示。这个 `title` 属性将始终设置为空字符串。

### activeWindowSync(选项?)

同步获取有关活动窗口的元数据。

## 结果

返回一个 `Promise<object>` 结果，或者 `Promise<undefined>` 如果没有活动窗口或信息不可用。

-   `platform` _(字符串)_ - `'macos'` | `'linux'` | `'windows'`
-   `title` _(字符串)_ -窗口标题
-   `id` _(数量)_ -窗口标识符
-   `bounds` _(对象)_ -窗口位置和大小
    -   `x` _(数量)_
    -   `y` _(数量)_
    -   `width` _(数量)_
    -   `height` _(数量)_
-   `contentBounds` _(对象)_ —窗口内容的位置和大小，不包括标题栏、菜单栏和框架 _(Windows)_
    -   `x` _(数量)_
    -   `y` _(数量)_
    -   `width` _(数量)_
    -   `height` _(数量)_
-   `owner` _(对象)_ -拥有窗口的应用程序
    -   `name` _(字符串)_ —应用名称
    -   `processId` _(数量)_ -进程标识符
    -   `bundleId` _(字符串)_ - Bundle标识符 _(仅macOS)_
    -   `path` _(字符串)_ -应用的路径
-   `url` _(字符串)_ —如果当前窗口是支持的浏览器，则显示当前窗口页签的URL _(仅macOS)_
    -   支持的浏览器：Safari（包括技术预览），Chrome（包括Beta， Dev和金丝雀），Edge（包括Beta， Dev和金丝雀），Brave（包括Beta和Nightly）， Mighty, Ghost Browser, Wavebox, Sidekick, Opera（包括Beta， Developer和GX），或Vivaldi
-   `memoryUsage` _(数量)_ —窗口所有者进程的内存使用情况

### openWindows ()

获取所有打开窗口的元数据。

窗户按照从前到后的顺序返回。

返回 `Promise<Result[]>`.

如果无法读取窗口列表，则数组为空。

### openWindowsSync ()

同步获取所有打开窗口的元数据。

窗户按照从前到后的顺序返回。

返回 `Result[]`.

如果无法读取窗口列表，则数组为空。

## 操作系统支持

它适用于macOS 10.14+， Linux和Windows 7+。

**注意**在Windows上，没有一个“窗口ID”的明确概念。方法中窗口“句柄”的内存地址 `id` 财产。该“句柄”在每个窗口中是唯一的，因此可以使用它来识别它们。 [阅读更多…](https://msdn.microsoft.com/en-us/library/windows/desktop/ms632597\(v=vs.85\).aspx#window_handle)

### Linux支持

韦兰不被支持。出于安全原因，Wayland没有提供识别活动窗口的方法。 [阅读更多…](https://stackoverflow.com/questions/45465016)

## 使用电子

如果您在电子应用程序中使用这个包是沙盒的，并且您希望获得 `.url` 属性，则需要添加 [适当的权利和用法描述](https://github.com/sindresorhus/get-windows/issues/99#issuecomment-870874546).

## 用户

-   [active-win-log](https://github.com/uglow/active-win-log) —窗口使用日志命令行。
-   [active-app-qmk-layer-updater](https://github.com/zigotica/active-app-qmk-layer-updater) -发送活动的应用程序信息到QMK设备自动改变键图层。

## 相关

-   [windows-cli](https://github.com/sindresorhus/windows-cli) -该包的CLI

## 开发

绕过 `gyp` 构建:

```sh
npm install --ignore-scripts
```

-   调试日志：设置 `DEBUG_GET_WINDOWS=1` 将Linux窗口枚举错误和汇总计数记录到控制台。

## cjser

这个包是由cjser为仍然需要的项目生成的commonjs兼容的构建 `require()` 支持。源版本与原始的npm包版本匹配，对这个生成的构建带有cjser预发布后缀。 原始存储库: [https://github.com/sindresorhus/get-windows](https://github.com/sindresorhus/get-windows)

## 常见问题

### @cjser/get-windows 是什么？

获取有关活动窗口和打开窗口的元数据（标题、id、边界、所有者、URL等）

### 如何安装 @cjser/get-windows？

在项目目录运行 npm install @cjser/get-windows，或使用 pnpm add / yarn add / bun add。

### @cjser/get-windows 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cjser/get-windows 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cjser/get-windows 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cjser/get-windows 可以商用吗？

@cjser/get-windows 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cjser/get-windows 还在维护吗？

最新版本 10\.0\.0-cjser\.2 发布于 2026/11/01（2 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/05/07。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。