Skip to content

插件运行模型 ​

插件页面什么时候创建、什么时候销毁、显示在哪个窗口里。理解这些,才知道数据该什么时候保存、状态能不能留住。

一次完整的使用 ​

text
用户在搜索框命中入口
        │
        ▼
 创建插件页面(第一次)  ──或──  从后台恢复(页面还在)
        │
        ▼
 onPluginEnter({ code, type, payload, from })   ← 每次进入都会触发
        │
        ▼
 用户使用插件 …
        │
   用户按 Esc / 插件调用 outPlugin()
        │
        ├── 允许后台运行 ──▶ 退到后台:页面保留,onPluginOut(false)
        │
        └── 不允许 ─────────▶ 销毁:onPluginOut(true),页面关闭

进入:onPluginEnter ​

每次用户进入插件都会调用,包括插件已经在运行、用户又从另一个入口进来的情况。回调在注册时会立即收到本次进入,不会因为页面加载慢而错过。

ts
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:保存数据的时机 ​

ts
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 的亮暗色。需要更多信息(是否有毛玻璃、是否有背景图)时:

ts
const theme = await window.ling.getTheme() // { isDark, vibrancy, backgroundImage }
window.ling.onThemeChange((theme) => applyTheme(theme))

用 @lingtools/ui 的 useTheme() 会自动处理这些,见 与宿主一致的界面。

事件回调的清理 ​

onPluginEnter、onPluginOut、onPluginDetach、onThemeChange、onNodeReady 都返回一个取消函数。在会卸载的组件里注册时,卸载时要调用它,否则回调会越积越多:

ts
const off = window.ling.onThemeChange(applyTheme)
onUnmounted(off)