@mukea/electron-overlay

为透明全屏 Electron Overlay 提供原生点击穿透、精确交互区域和 Vue 拖拽组件。

安装

pnpm add @mukea/electron-overlay

electron 与 vue 是 peer dependencies。Vue 入口是可选的，不使用 Vue 时只引入 main 和 preload 即可。

Main

import { createOverlayMain } from '@mukea/electron-overlay/main'

const overlay = createOverlayMain({
  window: mainWindow,
  onViewportMismatch: async (viewport, target) => {
    await repairViewport(viewport, target)
  }
})

overlay.init()

init() 会锁定原生窗口工作区、禁止移动和缩放、启动系统鼠标命中，并根据 renderer 上报的区域切换点击穿透。应用退出时调用 overlay.destroy()。

Preload

import { contextBridge, ipcRenderer } from 'electron'
import { createOverlayBridge } from '@mukea/electron-overlay/preload'

contextBridge.exposeInMainWorld('overlay', createOverlayBridge(ipcRenderer))

Vue

import { createApp } from 'vue'
import { createOverlayPlugin } from '@mukea/electron-overlay/vue'

app.use(createOverlayPlugin(window.overlay))

最小拖拽目标：

<OverlayDraggable>
  <Avatar />
</OverlayDraggable>

复合 Overlay：

<OverlayDraggable handle-only v-slot="{ isDragging, hasMoved }">
  <OverlayRegion>
    <InputBar />
  </OverlayRegion>

  <OverlayDragHandle>
    <Avatar :is-dragging="isDragging" :has-moved="hasMoved" />
  </OverlayDragHandle>
</OverlayDraggable>

OverlayRegion 只注册精确命中区域。OverlayDragHandle 同时注册命中区域并作为拖拽手柄。OverlayDraggable 默认约束在当前 viewport 内，可通过 :constrain-to-viewport="false" 关闭。

Window 类型

import type { OverlayBridge } from '@mukea/electron-overlay/types'

declare global {
  interface Window {
    overlay: OverlayBridge
  }
}