Skip to content

生命周期与窗口 ​

进入和退出插件、所在窗口、主题、环境信息。这一页的方法都不需要权限。

先读 插件运行模型 了解整体流程。

onPluginEnter ​

ts
onPluginEnter(callback: (action: PluginEnterAction) => void): () => void

每次进入插件时调用;注册时会立即收到本次进入。返回取消函数。

action 的字段:

字段说明
code入口标识(features[].code)
type'text' 功能指令;'regex' / 'over' / 'files' / 'img' / 'window' 对应的匹配指令
payloadtext:命中的指令文字;regex / over:搜索框的原样文字;files:{ path, name, isFile, isDirectory }[];img:PNG Data URL;window:窗口信息 { app, title, appPath, pid, x, y, width, height, id }
from'main' 搜索框;'tray' 托盘;'redirect' 其他插件或本插件跳转;'notification' 点击通知

从托盘、通知进入时 type 总是 'text',即使入口只有匹配指令,不要假定匹配指令入口只会收到对应的类型。

ts
window.ling.onPluginEnter(({ code, type, payload }) => {
  if (type === 'files') openFiles(payload.map((file) => file.path))
  else if (type === 'over' || type === 'regex') fillInput(payload)
})

退出 ​

outPlugin ​

ts
outPlugin(isKill?: boolean): Promise<void>

退出插件,相当于用户按 Esc。isKill 为 true 时直接销毁;否则允许后台运行就退到后台,不允许就销毁。在分离窗口里调用时总是关闭窗口并销毁。只能在插件主页面调用。

onPluginOut ​

ts
onPluginOut(callback: (isKill: boolean) => void): () => void

插件退到后台(isKill 为 false)或即将销毁(true)时调用。即将销毁时最多等回调同步执行 300 毫秒,不等它返回的 Promise。

isAllowRunInBackground ​

ts
isAllowRunInBackground(): Promise<boolean>

当前是否允许退到后台运行:用户在插件菜单里的选择优先,没选过时取 plugin.json 的 pluginSetting.runInBackground。用户修改时不会通知,需要时再读。

onPluginDetach ​

ts
onPluginDetach(callback: () => void): () => void

插件被分离到独立窗口时调用。

onNodeReady ​

ts
onNodeReady(callback: () => void): () => void

插件的 Node 后端 就绪时调用,此时 preload 挂出的函数都已可用;注册时已就绪则立即调用。页面加载时就要调用 preload 的,放进这个回调里。后端没能就绪时不会调用。没有 preload 的插件不会调用。

窗口 ​

方法说明
getWindowType(): Promise<'main' | 'detach' | 'custom'>所在窗口:主窗口、分离窗口、自建窗口
setExpandHeight(height: number): Promise<boolean>设置主窗口里插件区的高度(像素,不含顶栏)。每次进入都会恢复默认的 545,在 onPluginEnter 里设置。插件不在主窗口前台时返回 false
hideMainWindow(isFocusPrevWindow?: boolean): Promise<boolean>隐藏搜索框和其中的插件;分离窗口不受影响。搜索框隐藏一段时间后插件会被退出
showMainWindow(): Promise<boolean>显示搜索框和其中的插件
plugin.detach(): Promise<void>把插件分离到独立窗口,页面不重新加载
plugin.showMenu(): Promise<void>打开插件菜单

setExpandHeight、plugin.detach、plugin.showMenu 只能在插件主页面调用,自建窗口里调用以 forbidden 失败。

页内查找 ​

ts
findInPage(text: string, options?: { forward?: boolean; findNext?: boolean; matchCase?: boolean }): Promise<void>
stopFindInPage(action?: 'clearSelection' | 'keepSelection' | 'activateSelection'): Promise<void>

在插件页面里查找文字并高亮全部匹配,重复调用跳到下一项(forward: false 为上一项),到头后循环;文字为空时等于 stopFindInPage()。不改动页面 DOM。

主题 ​

方法说明
isDarkColors(): Promise<boolean>当前是否显示暗色(「跟随系统」时取系统的)
getTheme(): Promise<ThemeInfo>{ isDark, vibrancy, backgroundImage }:是否暗色、页面底下是否有窗口毛玻璃、是否有背景图片。只有声明了 view.appStyle: true 的主页面后两项才可能为 true
onThemeChange(callback: (info: ThemeInfo) => void): () => void主题变化时调用,包括「跟随系统」下系统切换亮暗

页面的 CSS prefers-color-scheme 也跟随 lingtools 的亮暗色。

用户与环境 ​

方法说明
isMacOS() / isWindows() / isLinux(): Promise<boolean>当前系统
isDev(): Promise<boolean>页面是否从开发服务加载(开发版为 true)
getAppName(): Promise<string>应用名称
getAppVersion(): Promise<string>lingtools 版本号,如 0.9.0
getNativeId(): Promise<string>本机标识(32 位十六进制):同一插件在同一台设备上不变,不同插件拿到的值不同。适合给「按设备区分」的设置做键名
getUser(): Promise<LingUser | null>当前登录的 lingtools 用户 { id, nickname, avatar };没登录、离线或登录失效时为 null,不会弹登录。id 在每个插件里不同,开发版与正式版相同;不提供邮箱

在页面里同步判断平台,可以用 @lingtools/plugin-sdk 的 currentPlatform。