electron-capturo npm 使用手册

本文档用于指导你在 Electron 项目 中接入并使用 electron-capturo。

1. 适用范围

• Electron 主进程 + preload + 渲染进程（Vue/React/原生前端均可）
• Electron 版本建议 >=20
• Node.js 版本建议 >=18

说明：该库依赖 Electron 的 desktopCapturer 与 IPC，不适用于纯 Web 项目。

2. 安装

npm i electron-capturo

并确保你的宿主项目已经安装 Electron（>=20），例如：

npm i -D electron@^20

3. 接入步骤（简化版）

3.1 主进程一行注册（main）

在主进程初始化后注册：

import { app, BrowserWindow } from 'electron'
import { setupElectronCapturoMain } from 'electron-capturo/main'

let unregisterCapturo = null

app.whenReady().then(() => {
  unregisterCapturo = setupElectronCapturoMain()
  // 创建你的窗口
})

app.on('before-quit', () => {
  unregisterCapturo?.()
})

3.2 preload 一行暴露（preload）

import { contextBridge, ipcRenderer } from 'electron'
import { exposeElectronCapturoInMainWorld } from 'electron-capturo/preload'

exposeElectronCapturoInMainWorld(contextBridge, ipcRenderer)

默认仅暴露 window.electronCapturo，不会占用 window.api。
若你需要兼容旧代码，可显式开启别名：

exposeElectronCapturoInMainWorld(contextBridge, ipcRenderer, {
  legacyGlobalKey: 'api'
})

如果你使用 TypeScript，可为 window.electronCapturo 增加类型声明（示例）：

declare global {
  interface Window {
    electronCapturo: {
      captureScreenshot: (payload?: { targetPath?: string }) => Promise<any>
      chooseScreenshotPath: () => Promise<any>
      chooseRecordingPath: () => Promise<any>
      saveRecording: (payload: {
        targetPath: string
        data: ArrayBuffer
        mimeType?: string
      }) => Promise<any>
      getConfig: () => Promise<{
        defaultScreenshotPath: string
        defaultRecordingPath: string
      }>
      setConfig: (payload: {
        defaultScreenshotPath?: string
        defaultRecordingPath?: string
      }) => Promise<any>
    }
  }
}

3.3 渲染进程调用（renderer）

import { ElectronCapturo } from 'electron-capturo'

const capturo = new ElectronCapturo().init({
  screenshotPath: '',
  recordingPath: ''
})

await capturo.configure({
  screenshotPath: 'D:/captures/screen.png',
  recordingPath: 'D:/captures/record.mp4'
})
await capturo.captureScreenshot()
await capturo.startRecord()
await capturo.stopRecord()

4. API 说明

4.1 ElectronCapturo

• init(options)：初始化默认截图/录屏路径
• getState()：获取当前状态（status、recording、路径、最近输出文件）
• setScreenshotPath(path)：设置截图输出路径
• setRecordingPath(path)：设置录屏输出路径
• chooseScreenshotPath()：打开保存对话框选择截图路径
• chooseRecordingPath()：打开保存对话框选择录屏路径
• configure({ screenshotPath, recordingPath })：前端直接同步默认路径配置（同时下发到主进程）
• captureScreenshot()：执行截图并保存
• startRecord()：开始录屏
• stopRecord()：结束录屏并保存
• cleanup()：清理流与录屏资源

4.2 返回值约定（常见）

• 成功：{ ok: true, path: '文件路径', ... }
• 用户取消：{ ok: false, canceled: true }
• 失败：抛出异常（建议使用 try/catch）

5. 最小可用示例（推荐）

import { ElectronCapturo } from 'electron-capturo'

const capturo = new ElectronCapturo().init()

async function screenshotOnce() {
  try {
    const result = await capturo.captureScreenshot()
    console.log('截图结果:', result)
  } catch (error) {
    console.error('截图失败:', error)
  }
}

6. 录屏格式说明

• 库会优先尝试 video/mp4
• 若浏览器内核返回的是 WebM，主进程会尝试调用 ffmpeg 转成 mp4
• 若系统未安装 ffmpeg，可能会抛出“无法转为 mp4”的错误

建议：

• 生产环境预装并配置可执行的 ffmpeg
• 或在业务中捕获异常并给出用户提示

7. 常见问题（FAQ）

Q1：报错“未找到 capturo 通信桥”

原因：preload 没有正确暴露 electronCapturo（或项目没有可用的 window.electron.ipcRenderer.invoke）。
检查：

• BrowserWindow 的 webPreferences.preload 路径是否正确
• contextIsolation 是否与你的 preload 写法匹配

Q1.1：为什么默认不再使用 window.api

原因：很多项目会把业务能力挂在 window.api，容易命名冲突。
当前默认统一为 window.electronCapturo，避免和其他库相互覆盖。

Q2：调用 startRecord() 后没有保存文件

可能原因：

• 没有调用 stopRecord()
• 录屏路径未设置且用户在路径选择框中取消
• 转码依赖 ffmpeg 不可用

Q3：截图/录屏权限被拒绝

请检查系统层面的屏幕录制权限（Windows/macOS/Linux 各自权限策略不同）。

8. 发布后给使用方的建议

• 在集成文档中明确：主进程只需 setupElectronCapturoMain()，preload 只需 exposeElectronCapturoInMainWorld(...)
• 对 captureScreenshot/startRecord/stopRecord 全部做 try/catch
• 将输出路径、权限失败、转码失败做成明确的 UI 提示