插件运行模型
插件页面什么时候创建、什么时候销毁、显示在哪个窗口里。理解这些,才知道数据该什么时候保存、状态能不能留住。
一次完整的使用
用户在搜索框命中入口
│
▼
创建插件页面(第一次) ──或── 从后台恢复(页面还在)
│
▼
onPluginEnter({ code, type, payload, from }) ← 每次进入都会触发
│
▼
用户使用插件 …
│
用户按 Esc / 插件调用 outPlugin()
│
├── 允许后台运行 ──▶ 退到后台:页面保留,onPluginOut(false)
│
└── 不允许 ─────────▶ 销毁:onPluginOut(true),页面关闭进入:onPluginEnter
每次用户进入插件都会调用,包括插件已经在运行、用户又从另一个入口进来的情况。回调在注册时会立即收到本次进入,不会因为页面加载慢而错过。
window.ling.onPluginEnter(({ code, type, payload, from }) => {
// code:入口标识(plugin.json 的 features[].code)
// type:'text' | 'regex' | 'over' | 'files' | 'img' | 'window'
// payload:随 type 不同,见 plugin.json 文档「匹配指令」一节
// from:'main' 搜索框 | 'tray' 托盘 | 'redirect' 其他插件跳转 | 'notification' 点击通知
})建议在 onPluginEnter 里决定显示哪一页、做哪些初始化,而不是在页面加载时:后台恢复时页面不会重新加载,但 onPluginEnter 一定会触发。
退出:后台还是销毁
用户按 Esc、插件调用 ling.outPlugin()、或用户打开了另一个插件时,插件「退出」:
| 情况 | 结果 |
|---|---|
| 允许后台运行 | 退到后台:页面、内存状态、定时器都保留;下次进入直接显示 |
| 不允许后台运行(默认) | 销毁:页面关闭,内存状态丢失 |
| 插件开着自建窗口 | 总是退到后台,直到窗口全部关闭 |
「允许后台运行」的默认值来自 plugin.json 的 pluginSetting.runInBackground,用户可以在插件菜单里改(「退出到后台立即结束运行」)。插件用 ling.isAllowRunInBackground() 读取当前生效的值。
以下情况插件一定会被销毁:
- 插件调用
ling.outPlugin(true); - 用户在插件菜单里选「结束运行」,或在搜索框里执行「停止所有插件」;
- 插件在分离窗口里,用户关掉了窗口;
- 用户在插件市场里改了插件的权限、卸载或更新了插件;
- lingtools 退出。
另外,搜索框隐藏一段时间后(用户在设置里配置,默认 3 分钟),主窗口里的插件会被自动退出。
onPluginOut:保存数据的时机
window.ling.onPluginOut((isKill) => {
// isKill 为 true:即将销毁
saveDraft()
})即将销毁时,lingtools 最多等回调同步执行 300 毫秒,不会等回调返回的 Promise;系统强制关闭时可能根本收不到。所以重要数据应该在修改时就保存(写 ling.db / dbStorage),不要攒到退出时再存。
窗口:主窗口、分离窗口、自建窗口
| 窗口 | 是什么 | getWindowType() |
|---|---|---|
| 主窗口 | 搜索框下方的插件区,默认高 545 像素 | 'main' |
| 分离窗口 | 用户按「分离为独立窗口」后,插件移到自己的窗口里,页面不重新加载 | 'detach' |
| 自建窗口 | 插件用 createBrowserWindow 创建的额外窗口 | 'custom' |
- 主窗口高度:用
ling.setExpandHeight(高度)调整,单位为像素。每次进入都会恢复默认高度,需要别的高度时在onPluginEnter里设置。 - 分离:用户可以通过插件菜单或快捷键分离;插件也可以调用
ling.plugin.detach()主动分离。分离后收到onPluginDetach。用户也可以在插件菜单里打开「自动分离」,以后每次打开都直接进分离窗口。 - 隐藏 / 显示搜索框:
ling.hideMainWindow()、ling.showMainWindow(),只对主窗口里的插件有效。
插件菜单
插件顶栏右侧有一个菜单按钮,在插件页面里按 ⌘ /(Windows 为 Ctrl /)也能打开,插件可以调用 ling.plugin.showMenu() 打开它。菜单项由 lingtools 提供,插件不能增删:

| 菜单项 | 作用 |
|---|---|
| 分离为独立窗口 | 移到分离窗口(只在主窗口里出现) |
| 自动分离 | 以后打开这个插件都直接进分离窗口 |
| 退出到后台立即结束运行 | 勾上 = 不允许后台运行 |
| 跟随主程序同时启动运行 | lingtools 启动时就在后台启动这个插件 |
| 退出插件 | 同 Esc |
| 结束运行 | 销毁插件 |
因此插件不要占用 ⌘ /,也不要把 Esc 用于别的用途:页面处理了 keydown 并调用 event.preventDefault() 时,lingtools 不会把 Esc 当作退出插件。
多实例
默认每个插件同时只有一个实例。plugin.json 声明 pluginSetting.multipleInstance: true 后:
- 主窗口里仍然最多一个实例,其余实例各在自己的分离窗口中,数量不限;
- 例如 JSON 编辑器:粘贴 JSON 打开 → 分离 → 再粘贴另一段 JSON 打开 → 再分离,得到两个窗口;
- 每个实例的页面、Node 后端、子输入框、自建窗口互相独立;数据(
ling.db、dbStorage)、权限和临时目录是共享的,多个实例写同一个键时后写的覆盖先写的。
主题
插件页面的 CSS prefers-color-scheme 跟随 lingtools 的亮暗色。需要更多信息(是否有毛玻璃、是否有背景图)时:
const theme = await window.ling.getTheme() // { isDark, vibrancy, backgroundImage }
window.ling.onThemeChange((theme) => applyTheme(theme))用 @lingtools/ui 的 useTheme() 会自动处理这些,见 与宿主一致的界面。
事件回调的清理
onPluginEnter、onPluginOut、onPluginDetach、onThemeChange、onNodeReady 都返回一个取消函数。在会卸载的组件里注册时,卸载时要调用它,否则回调会越积越多:
const off = window.ling.onThemeChange(applyTheme)
onUnmounted(off)