生命周期与窗口
进入和退出插件、所在窗口、主题、环境信息。这一页的方法都不需要权限。
先读 插件运行模型 了解整体流程。
onPluginEnter
onPluginEnter(callback: (action: PluginEnterAction) => void): () => void每次进入插件时调用;注册时会立即收到本次进入。返回取消函数。
action 的字段:
| 字段 | 说明 |
|---|---|
code | 入口标识(features[].code) |
type | 'text' 功能指令;'regex' / 'over' / 'files' / 'img' / 'window' 对应的匹配指令 |
payload | text:命中的指令文字;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',即使入口只有匹配指令,不要假定匹配指令入口只会收到对应的类型。
window.ling.onPluginEnter(({ code, type, payload }) => {
if (type === 'files') openFiles(payload.map((file) => file.path))
else if (type === 'over' || type === 'regex') fillInput(payload)
})退出
outPlugin
outPlugin(isKill?: boolean): Promise<void>退出插件,相当于用户按 Esc。isKill 为 true 时直接销毁;否则允许后台运行就退到后台,不允许就销毁。在分离窗口里调用时总是关闭窗口并销毁。只能在插件主页面调用。
onPluginOut
onPluginOut(callback: (isKill: boolean) => void): () => void插件退到后台(isKill 为 false)或即将销毁(true)时调用。即将销毁时最多等回调同步执行 300 毫秒,不等它返回的 Promise。
isAllowRunInBackground
isAllowRunInBackground(): Promise<boolean>当前是否允许退到后台运行:用户在插件菜单里的选择优先,没选过时取 plugin.json 的 pluginSetting.runInBackground。用户修改时不会通知,需要时再读。
onPluginDetach
onPluginDetach(callback: () => void): () => void插件被分离到独立窗口时调用。
onNodeReady
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 失败。
页内查找
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。