simen-keyboard-listener

Native global keyboard listener for macOS and Windows. Captures keyboard events system-wide, including special keys like FN that cannot be detected via standard DOM events.

Installation

npm install simen-keyboard-listener

The package uses optionalDependencies to automatically install the correct native binary for your platform. Supported platforms:

| Package | Platform | |---------|----------| | @simen-keyboard-listener/darwin-arm64 | macOS Apple Silicon | | @simen-keyboard-listener/win32-x64 | Windows x64 |

For Electron/Bundler Projects

If you're using webpack, electron-builder, or other bundlers, you may need to configure them to include the native addon:

electron-builder (package.json):

{
  "build": {
    "files": [
      "node_modules/@simen-keyboard-listener/**/*"
    ]
  }
}

webpack (webpack.config.js):

module.exports = {
  externals: {
    '@simen-keyboard-listener/darwin-arm64': 'commonjs @simen-keyboard-listener/darwin-arm64',
    '@simen-keyboard-listener/win32-x64': 'commonjs @simen-keyboard-listener/win32-x64',
  }
};

Usage

import { getGlobalKeyboardListener } from 'simen-keyboard-listener';

const listener = getGlobalKeyboardListener();

listener.addListener((event, isDown) => {
  console.log(`Key: ${event.name}, State: ${event.state}`);
});

// Later, to stop listening:
listener.removeListener(myListener);

开发与构建

构建原生模块

本项目包含 C++ 和 Swift 原生代码，需要编译为平台特定的二进制文件。构建脚本会自动处理编译和文件复制。

一键构建（推荐）

自动检测当前平台并构建：

npm run prebuild

此命令会：

• 自动检测当前操作系统和架构
• macOS：编译 Swift 辅助文件 + 构建原生模块 + 复制到 packages/darwin-arm64/
• Windows：构建原生模块 + 复制到 packages/win32-x64/

手动指定平台构建

Windows 平台：

npm run prebuild:win

macOS 平台：

npm run prebuild:mac

仅复制已构建的文件

如果已经构建完成，只需要复制文件到 packages 目录：

npm run copy-native win32-x64    # Windows
npm run copy-native darwin-arm64 # macOS

完整构建流程

如果需要构建 TypeScript 代码和原生模块：

npm run build

这会执行：

1. 编译 Swift 文件（macOS）
2. 构建原生模块（node-gyp）
3. 编译 TypeScript 代码

发布流程

发布所有平台包到 npm：

npm run publish:all

发布脚本会：

1. 同步所有平台包的版本号
2. 检查 .node 文件是否存在
3. 依次发布各平台包
4. 最后发布主包

注意： 发布前需要确保所有平台的 .node 文件都已构建并复制到对应的 packages/ 目录。

API

getGlobalKeyboardListener(): IGlobalKeyboardListener

Returns the singleton keyboard listener instance.

IGlobalKeyboardListener

• addListener(listener: IGlobalKeyListener): void - Add a key event listener
• removeListener(listener: IGlobalKeyListener): void - Remove a listener
• kill(): void - Stop the listener (only when no listeners remain)

IGlobalKeyEvent

interface IGlobalKeyEvent {
  readonly name: string;   // e.g. "FN", "LEFT SHIFT", "A", "ESCAPE"
  readonly state: 'DOWN' | 'UP';
}

Context APIs (macOS & Windows)

这些 API 在 macOS 和 Windows 上都可用：

• getSelectedTextSmart(): string | null - 获取选中文本（必要时模拟 Cmd+C / Ctrl+C）
• getContextJSON(): string | null - 获取完整上下文（JSON）
• getFrontmostAppInfo(): IAppInfo | null - 获取前台应用信息
• getFocusedElementInfo(): IElementInfo | null - 获取焦点元素信息
• getFocusedTextInfo(): ITextInfo | null - 获取文本信息（选中/输入框等）
• getFocusedDOMInfo(): IDOMInfo | null - 获取浏览器 DOM 信息（仅浏览器应用）

平台差异：

• macOS: 使用 Accessibility API，需要辅助功能权限
• Windows: 使用 UI Automation API，无需特殊权限

Supported Keys

• Modifiers: FN (macOS), SHIFT, CTRL, ALT, META (Cmd/Win)
• Letters: A-Z
• Numbers: 0-9
• Function keys: F1-F12 (Windows)
• Special: ESCAPE, SPACE, RETURN, TAB, BACKSPACE, DELETE
• Arrows: UP, DOWN, LEFT, RIGHT

Platform Support

• macOS ARM64 (Apple Silicon)
• Windows x64

Requirements

• Node.js >= 18.0.0
• macOS: Accessibility permission required
• Windows: No special permissions needed

License

MIT