nativekit

English · Electron 集成指南 · API reference

nativekit 是一个只在 Electron 主进程运行的跨平台原生能力库。它由 TypeScript API 与 Node-API v8 插件组成，JavaScript 部分使用 Vite library mode 打包，原生部分继续使用 CMake/cmake-js。

• 可拖动、不会抢占应用焦点的原生图片 Overlay；
• 前台应用、系统窗口枚举、查找与坐标命中；
• 系统应用图标提取。

兼容性

| 运行时或平台 | 最低支持版本 | 架构与说明 | |---|---|---| | Electron | 28.0.0 | 仅主进程 | | macOS | 12 Monterey | arm64、x64 | | Windows | 10 版本 1809（build 17763） | x64 | | Linux | Ubuntu 22.04 或兼容的 glibc 发行版 | x64、arm64；窗口与 Overlay 能力要求 X11/XWayland |

原生 Wayland 仅支持应用图标提取，不支持窗口查询或 Overlay 绝对定位。本地工作区 构建要求 Node.js 20.19+；发布包声明的 Node.js 最低版本为 18。

安装

发布到 npm 后直接安装：

pnpm add @zerob13/nativekit

npm 包会携带以下 Node-API 预编译文件，正常安装不需要本机 C++ 编译环境：

prebuilds/darwin-arm64/node.napi.armv8.node
prebuilds/darwin-x64/node.napi.node
prebuilds/win32-x64/node.napi.node
prebuilds/linux-x64/node.napi.node
prebuilds/linux-arm64/node.napi.armv8.node

Linux 预编译文件会动态链接 GLib/GIO、GdkPixbuf、XCB 与 XCB RandR。常规 X11 桌面通常已经包含这些运行库；最小化系统需要自行安装对应的 runtime packages。

库只能在 Electron 主进程导入。Renderer 应通过启用 contextIsolation 的 preload 暴露最小业务接口，不能直接暴露整个模块。

最小示例

import { app, BrowserWindow, nativeImage } from 'electron'
import { overlay, windows } from '@zerob13/nativekit'

await app.whenReady()

const win = new BrowserWindow({ width: 800, height: 600 })
const toolbarIcon = (path: string) =>
  nativeImage.createFromPath(path).resize({ width: 32, height: 32 }).toDataURL()

overlay.start({
  toolbar: {
    style: 'dark',
    buttons: [
      {
        id: 'open-panel',
        imageData: toolbarIcon('/absolute/path/to/open-panel.png'),
        tooltip: 'Open panel',
      },
      {
        id: 'close',
        imageData: toolbarIcon('/absolute/path/to/close.png'),
        tooltip: 'Close',
      },
    ],
  },
})
overlay.attachHost({
  id: 'main',
  title: 'Assistant',
  bounds: win.getContentBounds(),
  windowHandle: win.getNativeWindowHandle(),
  anchor: { edge: 'trailing', offset: 16 },
})

overlay.pushImage({
  hostId: 'main',
  presentationId: 'capture-1',
  sessionId: 'task-42',
  imageData: 'data:image/png;base64,iVBORw0KGgo...',
})

overlay.on('activate', () => win.show())
overlay.on('control', (controlId) => {
  if (controlId === 'open-panel') win.show()
  if (controlId === 'close') overlay.setVisible(false)
})
console.log(await windows.frontmost())

app.on('will-quit', () => overlay.stop())

用户可以直接按住 Overlay 图片的可见区域拖动。手动位置会在 host 和图片更新时保留， 并被限制在当前显示器工作区内。顶部 toolbar 提供 system、light、dark 三种固定 样式；按钮图片由调用方传入透明 PNG，NativeKit 负责等比缩放、模板着色以及 hover/pressed 反馈。点击后通过 control 事件原样返回对应 id；双击图片会触发 activate。位置只保留到 presentation 被删除或 overlay.stop()，不会跨应用启动持久化。

Electron demo

pnpm install
pnpm demo
pnpm demo:smoke

交互 demo 覆盖主要桌面交互模块。点击 Choose images 可一次选择多张图片，Overlay 会立即显示第一张，并每 5 秒切换一张；也可直接拖动主窗口外侧的原生 Overlay。 Smoke 模式会集中验证窗口枚举、图标与 Overlay 渲染。

┌ nativekit demo ───────────────────────────────────────┐
│ Window awareness  │ Overlay: show / hide / drag      │
│                   │ multi-image rotation every 5s    │
│ Application icon                                     │
│ Ordered event log                                    │
└───────────────────────────────────────────────────────┘

本地开发

要求 Node.js 20.19+、pnpm 10、CMake 3.22+，以及 macOS 的 Xcode Command Line Tools、Windows 的 Visual Studio C++ Build Tools，或 Linux 的 GLib/GIO、GdkPixbuf、XCB、XCB RandR 与 pkg-config 开发包。 Debian/Ubuntu 可安装：

sudo apt-get install build-essential pkg-config libgdk-pixbuf-2.0-dev libglib2.0-dev libxcb1-dev libxcb-randr0-dev

pnpm build:js       # Vite ESM/CJS + TypeScript declarations
pnpm build:native   # CMake + cmake-js
pnpm check

Linux 的 Overlay 和窗口查询要求 Electron 运行在 X11/XWayland。原生 Wayland 不会向普通客户端暴露其他应用窗口、全局坐标或任意顶层窗口定位；需要这些能力时， 请使用 --ozone-platform=x11 启动 Electron。GNOME、KDE Plasma、Cinnamon、 Xfce 与 MATE 的 X11 会话属于支持范围。完整边界见 Linux support notes。

完整的主进程、preload、Renderer、打包和故障排查示例见 Electron 集成指南。全部方法与事件定义见 API reference。

发布

版本号与 vX.Y.Z tag 必须一致。推送匹配 v* 的 tag 会触发发布，普通分支 push（包括 main）不会；也可以在 GitHub Actions 手动运行 release workflow 并输入已有 tag。workflow 会分别构建并测试 macOS arm64/x64、Windows x64 和 Linux x64/arm64；Linux 会在 Xvfb/Openbox 下运行 X11 集成与 Electron smoke 测试。随后 workflow 组装唯一 npm tarball，再发布同一份归档到 npm 与 GitHub Release。发布身份由 npm Trusted Publishing 提供。

许可证：MIT。