Skip to content

从 uTools 迁移 ​

lingtools 的插件模型和 uTools 很接近:features、cmds、onPluginEnter、db 这些概念和名字基本照搬。迁移时主要改三件事:utools 换成 ling 并全部 await、声明权限、改写 preload。

三个必改项 ​

1. window.utools → window.ling,全部异步 ​

所有方法都返回 Promise,包括 uTools 里同步的方法。

ts
// 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、截图、getCursorScreenPointscreen
shellOpenPathshell
simulate*、hideMainWindowTypeStringinput
readCurrentFolderPath、readCurrentBrowserUrlforeground
ubrowserbrowser
runFFmpegffmpeg
preloadnode

完整列表见 权限。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 对照 ​

uToolslingtools说明
pluginNametitle显示名称
—name新增必填:插件唯一标识,小写字母、数字、-
version、description、author、main、logo、preload同名preload 需要 node 权限
development.main同名只能是本机地址,以 / 结尾
features[].code / explain / cmds / icon / mainHide / platform同名icon 只能是插件目录内的文件
features[].mainPush不支持
pluginSetting.singlepluginSetting.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.*)。

uToolslingtools差异
utools.ubrowserling.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 的 frommain / 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。

迁移检查清单 ​

  1. 新建 src-ling/ 目录,把插件文件放进去(或者直接把现有插件目录当作插件目录)。
  2. plugin.json:加 name,pluginName 改 title,删掉不支持的字段,加 permissions。
  3. 全局替换 utools. → window.ling.,给每个调用加 await。
  4. preload:能改用 ling.fs / ling.spawn / fetch 的改掉;剩下的保留,声明 node 权限,页面调用加 await。
  5. 用开发者工具装成开发版,逐个入口试一遍;看到 forbidden 就补权限。