aboard-overlay 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +222 -2
- package/electron/index.cjs +104 -0
- package/package.json +37 -4
- package/src/index.js +963 -0
- package/src/styles.css +472 -0
- package/src/vue.js +124 -0
package/README.md
CHANGED
|
@@ -1,3 +1,223 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Aboard Overlay
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
透明标注白板:可覆盖在 PPT 等外部窗口之上,一边看幻灯片一边用画笔/橡皮擦批注。
|
|
4
|
+
|
|
5
|
+
- 背景层与绘图层分离:橡皮擦用 `destination-out` 擦除笔迹,擦掉后直接露出下层窗口(真正的透明,不是白色底)
|
|
6
|
+
- 两种背景:`transparent`(透明,看到 PPT)与 `blackboard`(黑板绿)
|
|
7
|
+
- 6 种画笔(普通 / 铅笔 / 圆珠笔 / 钢笔 / 毛笔 / 荧光笔)+ 8 个预设色 + 自定义颜色 + 粗细调节
|
|
8
|
+
- 框架无关内核(原生 ES Module,零构建)+ Vue 3 组件 + Electron 透明窗口辅助函数
|
|
9
|
+
- 窗口尺寸变化时按笔画数据重绘,不会因为拉伸而丢内容
|
|
10
|
+
|
|
11
|
+
## 安装
|
|
12
|
+
|
|
13
|
+
本地路径安装:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm install file:../board/aboard-overlay
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
或把 `aboard-overlay` 目录放进项目(例如 `packages/aboard-overlay`)后:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install file:./packages/aboard-overlay
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
包直接发布 ES Module 源码,不需要额外构建;Vite / webpack 可直接消费。`electron` 子路径是 CommonJS,主进程可直接 `require`。
|
|
26
|
+
|
|
27
|
+
## 目录结构
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
aboard-overlay/
|
|
31
|
+
├── src/
|
|
32
|
+
│ ├── index.js # Aboard 内核(绘制引擎 + 内置 UI + 设置持久化)
|
|
33
|
+
│ ├── vue.js # Vue 3 组件 <AboardBoard />
|
|
34
|
+
│ └── styles.css # 样式,全部限定在 .aboard-root 内
|
|
35
|
+
├── electron/
|
|
36
|
+
│ └── index.cjs # 主进程:透明置顶窗口 + 鼠标穿透切换
|
|
37
|
+
└── package.json
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## 快速开始
|
|
41
|
+
|
|
42
|
+
### 1. Electron 主进程:创建透明覆盖窗口
|
|
43
|
+
|
|
44
|
+
建议给画板单独一个路由页面(如 `/board`),窗口加载该页面。
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
const { app, globalShortcut } = require('electron')
|
|
48
|
+
const { createOverlayWindow, toggleOverlayInteractive } = require('aboard-overlay/electron')
|
|
49
|
+
|
|
50
|
+
let overlay = null
|
|
51
|
+
|
|
52
|
+
app.whenReady().then(() => {
|
|
53
|
+
overlay = createOverlayWindow({
|
|
54
|
+
url: 'http://localhost:5173/#/board'
|
|
55
|
+
})
|
|
56
|
+
|
|
57
|
+
// F9 切换「绘制 / 穿透」:绘制时窗口接管鼠标,穿透时鼠标回到 PPT
|
|
58
|
+
globalShortcut.register('F9', () => {
|
|
59
|
+
toggleOverlayInteractive(overlay)
|
|
60
|
+
})
|
|
61
|
+
})
|
|
62
|
+
|
|
63
|
+
app.on('will-quit', () => globalShortcut.unregisterAll())
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### 2. 渲染进程:Vue 3 组件
|
|
67
|
+
|
|
68
|
+
```vue
|
|
69
|
+
<template>
|
|
70
|
+
<AboardBoard transparent-window @ready="onReady" @change="onChange" />
|
|
71
|
+
</template>
|
|
72
|
+
|
|
73
|
+
<script setup>
|
|
74
|
+
import { AboardBoard } from 'aboard-overlay/vue'
|
|
75
|
+
import 'aboard-overlay/style.css'
|
|
76
|
+
|
|
77
|
+
function onReady(board) {
|
|
78
|
+
// board 即 Aboard 实例,可调用下面的 API
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function onChange(settings) {
|
|
82
|
+
// 用户在画板内置面板里改了工具/颜色/背景时触发
|
|
83
|
+
console.log(settings)
|
|
84
|
+
}
|
|
85
|
+
</script>
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### 3. 渲染进程:无框架用法
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import { Aboard } from 'aboard-overlay'
|
|
92
|
+
import 'aboard-overlay/style.css'
|
|
93
|
+
|
|
94
|
+
const board = new Aboard({
|
|
95
|
+
host: document.body,
|
|
96
|
+
background: 'transparent',
|
|
97
|
+
transparentWindow: true
|
|
98
|
+
})
|
|
99
|
+
|
|
100
|
+
// 收起画板
|
|
101
|
+
// board.destroy()
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## 实现「透明看到 PPT」的三个前提
|
|
105
|
+
|
|
106
|
+
1. 承载画板的 Electron 窗口必须是透明窗口:`createOverlayWindow` 已设置 `transparent: true`、`backgroundColor: '#00000000'`、`frame: false`、`hasShadow: false`,并以 `screen-saver` 层级置顶覆盖全屏 PPT。
|
|
107
|
+
2. 覆盖窗口页面的 `html`、`body`、`#app` 不要设置背景色。设置 `transparentWindow: true`(Vue 组件用 `transparent-window`)会给 `<html>` 加 `aboard-transparent-window` 类,把 `html/body` 变成透明。
|
|
108
|
+
3. 窗口需要能收到鼠标才能画:穿透状态下调用 `setOverlayInteractive(win, false)`,绘制状态下调用 `setOverlayInteractive(win, true)`。透明窗口本身不会自动把点击透传给 PPT。
|
|
109
|
+
|
|
110
|
+
黑板绿模式下整个窗口会铺满绿色(遮住 PPT),这是预期行为;切回「透明」即恢复。
|
|
111
|
+
|
|
112
|
+
## Aboard 内核
|
|
113
|
+
|
|
114
|
+
### 构造参数
|
|
115
|
+
|
|
116
|
+
```js
|
|
117
|
+
const board = new Aboard({
|
|
118
|
+
host: document.body, // HTMLElement 或选择器,默认 document.body
|
|
119
|
+
background: 'transparent', // 'transparent' | 'blackboard'
|
|
120
|
+
tool: 'pen', // 'pen' | 'eraser'
|
|
121
|
+
penType: 'normal', // normal | pencil | ballpoint | fountain | brush | marker
|
|
122
|
+
color: '#111111', // 必须为 #rrggbb,显式传入后不再随背景自动换色
|
|
123
|
+
penSize: 5, // 1 ~ 50
|
|
124
|
+
eraserSize: 40, // 10 ~ 150
|
|
125
|
+
showToolbar: true, // 是否显示底部工具栏
|
|
126
|
+
showBackgroundSwitcher: true, // 是否显示右上角背景切换
|
|
127
|
+
transparentWindow: false, // 是否把宿主 html/body 设为透明(覆盖窗口页面用)
|
|
128
|
+
persist: true, // 是否把设置写入 localStorage
|
|
129
|
+
storageKey: 'aboard-overlay-settings-v1',
|
|
130
|
+
onChange: (settings) => {} // 设置变化回调
|
|
131
|
+
})
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
未手动选过颜色时,切换透明 ↔ 黑板绿会自动在黑色/白色之间切换,避免笔迹看不见。
|
|
135
|
+
|
|
136
|
+
### 方法
|
|
137
|
+
|
|
138
|
+
| 方法 | 说明 |
|
|
139
|
+
| --- | --- |
|
|
140
|
+
| `setTool(tool)` | 切换 `pen` / `eraser` |
|
|
141
|
+
| `setPenType(type)` | 切换画笔类型 |
|
|
142
|
+
| `setColor(hex)` | 设置颜色并关闭自动换色 |
|
|
143
|
+
| `setPenSize(size)` | 设置画笔粗细(1~50) |
|
|
144
|
+
| `setEraserSize(size)` | 设置橡皮大小(10~150) |
|
|
145
|
+
| `setBackground('transparent' \| 'blackboard')` | 切换背景 |
|
|
146
|
+
| `setToolbarVisible(visible)` | 显示/隐藏工具栏 |
|
|
147
|
+
| `setBackgroundSwitcherVisible(visible)` | 显示/隐藏背景切换面板 |
|
|
148
|
+
| `resize()` | 手动触发画布重算(容器尺寸变化时) |
|
|
149
|
+
| `getSettings()` | 获取当前设置副本 |
|
|
150
|
+
| `getCanvas()` / `getElement()` | 获取 canvas / 根 DOM |
|
|
151
|
+
| `destroy()` | 解绑事件、移除 DOM、清理透明窗口类 |
|
|
152
|
+
|
|
153
|
+
> 当前版本只做批注,不包含撤销/重做、清空、导出图片。
|
|
154
|
+
|
|
155
|
+
## Vue 组件 `<AboardBoard />`
|
|
156
|
+
|
|
157
|
+
Props:`background`、`tool`、`penType`、`color`、`penSize`、`eraserSize`、`showToolbar`、`showBackgroundSwitcher`、`transparentWindow`、`persist`、`storageKey`。这些 prop 变化会同步到画板;不传则沿用内置默认值与本地存储。
|
|
158
|
+
|
|
159
|
+
Events:
|
|
160
|
+
|
|
161
|
+
- `ready(board)`:画板挂载完成,回传内核实例
|
|
162
|
+
- `change(settings)`:画板内设置发生变化
|
|
163
|
+
|
|
164
|
+
Expose:
|
|
165
|
+
|
|
166
|
+
- `getBoard()`:获取内核实例
|
|
167
|
+
|
|
168
|
+
组件模板只渲染一个用于挂载的 `div`,界面来自内核,因此视觉与无框架版本完全一致。
|
|
169
|
+
|
|
170
|
+
## Electron 辅助函数
|
|
171
|
+
|
|
172
|
+
```js
|
|
173
|
+
const {
|
|
174
|
+
createOverlayWindow,
|
|
175
|
+
setOverlayInteractive,
|
|
176
|
+
isOverlayInteractive,
|
|
177
|
+
toggleOverlayInteractive
|
|
178
|
+
} = require('aboard-overlay/electron')
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
### `createOverlayWindow(options)`
|
|
182
|
+
|
|
183
|
+
在 `app.whenReady()` 之后调用(内部使用 `screen`)。
|
|
184
|
+
|
|
185
|
+
| 参数 | 默认值 | 说明 |
|
|
186
|
+
| --- | --- | --- |
|
|
187
|
+
| `url` | 必填 | 覆盖窗口加载的地址 |
|
|
188
|
+
| `preload` | `undefined` | preload 脚本路径 |
|
|
189
|
+
| `bounds` | 主屏完整区域 | 窗口位置尺寸,传 `{ x, y, width, height }` |
|
|
190
|
+
| `displayId` | 主屏 | 指定显示器 id |
|
|
191
|
+
| `focusable` | `true` | 窗口是否可聚焦 |
|
|
192
|
+
| `interactive` | `false` | 初始是否接管鼠标 |
|
|
193
|
+
| `show` | `true` | 是否自动显示 |
|
|
194
|
+
| `alwaysOnTopLevel` | `'screen-saver'` | 置顶层级 |
|
|
195
|
+
| `webPreferences` | `{}` | 与默认值合并 |
|
|
196
|
+
|
|
197
|
+
返回 `BrowserWindow`。窗口默认先以穿透状态 `showInactive()` 显示,不抢 PPT 焦点。
|
|
198
|
+
|
|
199
|
+
### 鼠标穿透
|
|
200
|
+
|
|
201
|
+
| 函数 | 说明 |
|
|
202
|
+
| --- | --- |
|
|
203
|
+
| `setOverlayInteractive(win, boolean)` | `true` 接管鼠标可绘制;`false` 穿透给 PPT |
|
|
204
|
+
| `toggleOverlayInteractive(win)` | 切换并返回切换后的状态 |
|
|
205
|
+
| `isOverlayInteractive(win)` | 查询当前状态 |
|
|
206
|
+
|
|
207
|
+
## 常见问题
|
|
208
|
+
|
|
209
|
+
**画笔点不动 / 光标是箭头?**
|
|
210
|
+
覆盖窗口处于穿透状态。调用 `setOverlayInteractive(win, true)`(或绑个全局快捷键切换)。
|
|
211
|
+
|
|
212
|
+
**看到的是黑底或白底,不是 PPT?**
|
|
213
|
+
检查覆盖窗口页面的 `html/body/#app` 是否被应用 CSS 设了背景色;组件加 `transparent-window` / 选项加 `transparentWindow: true` 后,宿主页仍需要保持透明。
|
|
214
|
+
|
|
215
|
+
**画完切回 PPT,想保留笔迹?**
|
|
216
|
+
笔迹保存在画板实例内存中,`destroy()` 会丢弃;窗口隐藏 / 穿透不会清空。
|
|
217
|
+
|
|
218
|
+
**多显示器 / 分辨率变化?**
|
|
219
|
+
通过 `displayId` 或 `bounds` 指定窗口所在屏幕;画板监听 `ResizeObserver` 与 `window.resize`,会自动按笔画数据重绘。
|
|
220
|
+
|
|
221
|
+
## License
|
|
222
|
+
|
|
223
|
+
MIT
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Electron 主进程辅助:创建覆盖在 PPT 等外部窗口上方的透明窗口,并切换「绘制 / 鼠标穿透」。
|
|
5
|
+
*
|
|
6
|
+
* 用法(主进程):
|
|
7
|
+
* const { createOverlayWindow, setOverlayInteractive } = require('aboard-overlay/electron');
|
|
8
|
+
* const win = createOverlayWindow({ url: 'http://localhost:5173/#/board' });
|
|
9
|
+
* setOverlayInteractive(win, true); // 进入绘制,窗口接管鼠标
|
|
10
|
+
* setOverlayInteractive(win, false); // 退出绘制,鼠标穿透回 PPT
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const { BrowserWindow, screen } = require('electron');
|
|
14
|
+
|
|
15
|
+
const interactiveState = new WeakMap();
|
|
16
|
+
|
|
17
|
+
function resolveBounds(bounds, displayId) {
|
|
18
|
+
if (bounds) return bounds;
|
|
19
|
+
|
|
20
|
+
const displays = screen.getAllDisplays();
|
|
21
|
+
const display =
|
|
22
|
+
displayId === undefined || displayId === null
|
|
23
|
+
? screen.getPrimaryDisplay()
|
|
24
|
+
: displays.find(function (item) {
|
|
25
|
+
return item.id === displayId;
|
|
26
|
+
}) || screen.getPrimaryDisplay();
|
|
27
|
+
|
|
28
|
+
return display.bounds;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function createOverlayWindow(options) {
|
|
32
|
+
const opts = options || {};
|
|
33
|
+
if (!opts.url) throw new Error('[aboard-overlay] createOverlayWindow 需要传入 url');
|
|
34
|
+
|
|
35
|
+
const webPreferences = Object.assign(
|
|
36
|
+
{
|
|
37
|
+
contextIsolation: true,
|
|
38
|
+
nodeIntegration: false,
|
|
39
|
+
backgroundThrottling: false
|
|
40
|
+
},
|
|
41
|
+
opts.webPreferences || {}
|
|
42
|
+
);
|
|
43
|
+
if (opts.preload) webPreferences.preload = opts.preload;
|
|
44
|
+
|
|
45
|
+
const win = new BrowserWindow(
|
|
46
|
+
Object.assign({}, resolveBounds(opts.bounds, opts.displayId), {
|
|
47
|
+
show: false,
|
|
48
|
+
frame: false,
|
|
49
|
+
transparent: true,
|
|
50
|
+
backgroundColor: '#00000000',
|
|
51
|
+
hasShadow: false,
|
|
52
|
+
resizable: false,
|
|
53
|
+
movable: false,
|
|
54
|
+
minimizable: false,
|
|
55
|
+
maximizable: false,
|
|
56
|
+
fullscreenable: false,
|
|
57
|
+
skipTaskbar: true,
|
|
58
|
+
focusable: opts.focusable !== false,
|
|
59
|
+
alwaysOnTop: true,
|
|
60
|
+
webPreferences: webPreferences
|
|
61
|
+
})
|
|
62
|
+
);
|
|
63
|
+
|
|
64
|
+
// 'screen-saver' 层级可覆盖全屏播放中的 PPT
|
|
65
|
+
win.setAlwaysOnTop(true, opts.alwaysOnTopLevel || 'screen-saver');
|
|
66
|
+
win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true });
|
|
67
|
+
|
|
68
|
+
setOverlayInteractive(win, opts.interactive === true);
|
|
69
|
+
|
|
70
|
+
win.once('ready-to-show', function () {
|
|
71
|
+
if (opts.show === false) return;
|
|
72
|
+
if (interactiveState.get(win)) {
|
|
73
|
+
win.show();
|
|
74
|
+
} else {
|
|
75
|
+
// 穿透状态下不抢 PPT 的焦点
|
|
76
|
+
win.showInactive();
|
|
77
|
+
}
|
|
78
|
+
});
|
|
79
|
+
|
|
80
|
+
win.loadURL(opts.url);
|
|
81
|
+
return win;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
function setOverlayInteractive(win, interactive) {
|
|
85
|
+
const next = interactive === true;
|
|
86
|
+
interactiveState.set(win, next);
|
|
87
|
+
win.setIgnoreMouseEvents(!next, { forward: true });
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
function isOverlayInteractive(win) {
|
|
91
|
+
return interactiveState.get(win) === true;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
function toggleOverlayInteractive(win) {
|
|
95
|
+
setOverlayInteractive(win, !isOverlayInteractive(win));
|
|
96
|
+
return isOverlayInteractive(win);
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = {
|
|
100
|
+
createOverlayWindow: createOverlayWindow,
|
|
101
|
+
setOverlayInteractive: setOverlayInteractive,
|
|
102
|
+
isOverlayInteractive: isOverlayInteractive,
|
|
103
|
+
toggleOverlayInteractive: toggleOverlayInteractive
|
|
104
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,39 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "aboard-overlay",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "透明标注白板:可覆盖在 PPT 等外部窗口之上,支持画笔、橡皮擦与黑板绿/透明背景切换",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./src/index.js",
|
|
7
|
+
"module": "./src/index.js",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./src/index.js",
|
|
10
|
+
"./vue": "./src/vue.js",
|
|
11
|
+
"./style.css": "./src/styles.css",
|
|
12
|
+
"./electron": "./electron/index.cjs"
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"src",
|
|
16
|
+
"electron"
|
|
17
|
+
],
|
|
18
|
+
"sideEffects": [
|
|
19
|
+
"*.css"
|
|
20
|
+
],
|
|
21
|
+
"peerDependencies": {
|
|
22
|
+
"vue": "^3.3.0"
|
|
23
|
+
},
|
|
24
|
+
"peerDependenciesMeta": {
|
|
25
|
+
"vue": {
|
|
26
|
+
"optional": true
|
|
27
|
+
}
|
|
28
|
+
},
|
|
29
|
+
"keywords": [
|
|
30
|
+
"whiteboard",
|
|
31
|
+
"annotation",
|
|
32
|
+
"overlay",
|
|
33
|
+
"electron",
|
|
34
|
+
"vue",
|
|
35
|
+
"canvas",
|
|
36
|
+
"transparent"
|
|
37
|
+
],
|
|
38
|
+
"license": "MIT"
|
|
39
|
+
}
|