从 uTools 迁移
lingtools 的插件模型和 uTools 很接近:features、cmds、onPluginEnter、db 这些概念和名字基本照搬。迁移时主要改三件事:utools 换成 ling 并全部 await、声明权限、改写 preload。
三个必改项
1. window.utools → window.ling,全部异步
所有方法都返回 Promise,包括 uTools 里同步的方法。
// uTools
const id = utools.getNativeId()
utools.dbStorage.setItem('theme', 'dark')
// lingtools
const id = await window.ling.getNativeId()
await window.ling.dbStorage.setItem('theme', 'dark')db 本身就是异步的,不再有 db.promises。
2. 敏感能力必须声明权限
uTools 里随手可用的能力,在 lingtools 里要先在 plugin.json 的 permissions 里声明,否则以 forbidden 失败;用户还可以在插件市场里逐项关闭。
| 用到 | 声明 |
|---|---|
copyText、copyImage、copyFile、hideMainWindowPaste* | clipboard.write |
getCopiedFiles、读剪贴板 | clipboard |
screenColorPick、截图、getCursorScreenPoint | screen |
shellOpenPath | shell |
simulate*、hideMainWindowTypeString | input |
readCurrentFolderPath、readCurrentBrowserUrl | foreground |
ubrowser | browser |
runFFmpeg | ffmpeg |
| preload | node |
完整列表见 权限。db、dbStorage、通知、文件对话框、redirect、shellOpenExternal 等不需要权限。
3. preload 在独立的 Node 进程里
uTools 的 preload 和页面跑在同一个渲染进程,页面能直接同步调用 preload 挂在 window 上的函数。lingtools 的 preload 跑在每个插件独立的 Node.js 进程里:
- 页面里仍然用同名全局调用,但要
await,参数和返回值必须能序列化(不能传 DOM 节点、类实例方法); - 回调函数可以作为参数传过去(会被代理),常用于进度通知;
- 首次打开时 Node 可能还没就绪,页面加载时就要调用的话,先等
ling.onNodeReady(); plugin.json里要声明"permissions": ["node"]。
另外,很多以前必须用 preload 做的事,现在页面里直接有 API:读写文件用 ling.fs(Node fs/promises 的形状)、运行程序用 ling.spawn、联网直接 fetch。能不用 preload 就不用,插件更轻、权限也更少。详见 Node 后端。
plugin.json 对照
| uTools | lingtools | 说明 |
|---|---|---|
pluginName | title | 显示名称 |
| — | name | 新增必填:插件唯一标识,小写字母、数字、- |
version、description、author、main、logo、preload | 同名 | preload 需要 node 权限 |
development.main | 同名 | 只能是本机地址,以 / 结尾 |
features[].code / explain / cmds / icon / mainHide / platform | 同名 | icon 只能是插件目录内的文件 |
features[].mainPush | 不支持 | |
pluginSetting.single | pluginSetting.multipleInstance | 取值相反 |
pluginSetting.height | 用 setExpandHeight() | 在 onPluginEnter 里设置 |
顶层 platform、homepage 等 | 不支持 | 平台写在每个入口的 platform 上 |
| — | permissions | 新增,见上文 |
| — | extends.searchCards、extends.ai | 新增:搜索卡片、AI 工具 |
plugin.json 严格校验,不认识的字段会导致插件不加载,迁移时把 uTools 专有字段删干净。
API 对照与差异
名字相同、行为相同的不再列出(如 onPluginEnter、outPlugin、setSubInput、setFeature、redirect、showNotification、shellOpenExternal、getPath、db.*、dbStorage.*)。
| uTools | lingtools | 差异 |
|---|---|---|
utools.ubrowser | ling.browser | 去掉 u;getIdleUBrowsers / setUBrowserProxy / clearUBrowserCache 同样改为 getIdleBrowsers / setBrowserProxy / clearBrowserCache |
screenCapture(callback) | captureScreen(options?) | 返回 { success, data, … },可配置工具栏、输出格式,支持长截图和录屏;用户取消也会返回结果 |
onMainPush | 无 | 改用 搜索卡片 在搜索结果上方直接显示内容 |
createBrowserWindow | 同名 | 异步,返回的句柄只有部分方法;自建窗口没有 preload,收消息用 ling.ipc.on |
sendToParent | 同名 | 参数必须能序列化为 JSON |
redirect | 同名 | 找不到时不会打开插件市场,返回 false |
getUser | 同名 | 不返回邮箱;id 在每个插件里不同 |
onPluginEnter 的 from | main / tray / redirect / notification | 没有 panel、hotkey |
shellOpenExternal | 同名 | 不接受 file: 链接,打开本地路径用 shellOpenPath |
getPath(name) | 同名 | 只支持 home、temp、desktop、documents、downloads、music、pictures、videos |
| 付费相关 API | 无 |
lingtools 额外提供的能力(uTools 没有):ling.fs、ling.image、ling.server / ling.zip、ling.spawn、ling.ai / ling.localAi、ling.pinyin、子输入框的下拉、参数框、前缀、搜索卡片、AI 工具、onThemeChange / getTheme。
迁移检查清单
- 新建
src-ling/目录,把插件文件放进去(或者直接把现有插件目录当作插件目录)。 plugin.json:加name,pluginName改title,删掉不支持的字段,加permissions。- 全局替换
utools.→window.ling.,给每个调用加await。 - preload:能改用
ling.fs/ling.spawn/fetch的改掉;剩下的保留,声明node权限,页面调用加await。 - 用开发者工具装成开发版,逐个入口试一遍;看到
forbidden就补权限。