调用约定与索引
插件页面里的 window.ling 由 lingtools 注入,页面加载前就已可用。所有方法都返回 Promise。
调用约定
ts
try {
const ok = await window.ling.copyText('hello')
} catch (error) {
console.error(error.code, error.message)
}- 全部异步:包括
isMacOS()这类在 uTools 里同步的方法。 - 失败以错误 reject:错误对象有
code(错误码)和message(中文原因),部分方法另带data。用@lingtools/plugin-sdk的isApiError(error)判断。错误码含义见 调试与常见问题。 - 返回
false不是错误:有些方法在「不适用」时返回false而不是 reject,比如插件不在主窗口时调用setExpandHeight。 - 权限:每页开头写了需要的权限,没有声明时以
forbidden失败。 - 事件回调:
on*方法返回取消函数,组件卸载时记得调用。 - 类型:完整的参数和返回类型在
@lingtools/plugin-types里,编辑器里悬停即可看到说明。
在哪里能调用
window.ling 在下面几个地方都可用,但能调用的方法不完全相同:
| 位置 | 说明 |
|---|---|
| 插件主页面 | 全部方法 |
| 自建窗口 | 不能调用作用于插件界面的方法:outPlugin、子输入框、setExpandHeight、plugin.detach、plugin.showMenu |
| Node 后端 | 与主页面相同(作用于插件界面的方法作用于主页面);没有页面专属的 findInPage、getPathForFile |
| 搜索卡片 | 不能调用作用于插件界面的方法、创建窗口、Node 后端;粘贴到前台、redirect、通知等只能在用户触发的动作里调用 |
| AI 工具(入口文件导出) | 和搜索卡片类似,没有 DOM 和 Node |
按需求找方法
| 我想… | 用 | 权限 |
|---|---|---|
| 知道用户从哪个入口、带着什么进来 | onPluginEnter | |
| 退出插件 / 退出时保存 | outPlugin、onPluginOut | |
| 调整插件高度 | setExpandHeight | |
| 在搜索框里接收输入 | setSubInput | |
| 给插件加一个下拉 / 参数输入 | plugin.setSubInputAccessory、setSubInputArguments | |
| 动态添加搜索入口(如每个书签一个) | setFeature | |
| 打开另一个插件 | redirect | |
| 弹系统通知 | showNotification | |
| 存设置 / 存一组记录 | dbStorage、db | |
| 复制到剪贴板 | copyText、copyImage、copyFile | clipboard.write |
| 读剪贴板 | clipboard.readText、getCopiedFiles | clipboard |
| 把结果直接粘贴到用户正在用的应用 | hideMainWindowPasteText | clipboard.write |
| 读写文件 | ling.fs | 插件目录外需 fs.read / fs |
| 让用户选文件 / 选保存位置 | showOpenDialog、showSaveDialog | |
| 打开文件、网址,在文件夹中显示 | shellOpenPath、shellOpenExternal、shellShowItemInFolder | shellOpenPath 需 shell |
| 读取用户正在看的文件夹 / 网页地址 | readCurrentFolderPath、readCurrentBrowserUrl | foreground |
| 取文件图标 | getFileIcon | 传路径需 fs.read |
| 中文拼音搜索 | pinyin.match | |
| 截图 / 录屏 | captureScreen | screen |
| 屏幕取色 | screenColorPick | screen |
| 压缩、转换、拼接图片 | ling.image | |
| 处理音视频 | runFFmpeg | ffmpeg |
| 调用 AI 模型 | ling.ai | ai |
| 打开一个额外的窗口 | createBrowserWindow | |
| 自动操作网页、抓取内容 | ling.browser | browser |
| 让手机通过局域网访问 | ling.server | server |
| 压缩 / 解压 ZIP | ling.zip | |
| 运行命令行程序 | ling.spawn | spawn |
| 模拟按键、鼠标 | simulateKeyboardTap 等 | input |
| 获取当前登录用户 | getUser |
全部方法
| 分类 | 方法 |
|---|---|
| 生命周期与窗口 | onPluginEnter onPluginOut onPluginDetach onNodeReady outPlugin isAllowRunInBackground getWindowType hideMainWindow showMainWindow setExpandHeight plugin.detach plugin.showMenu findInPage stopFindInPage getTheme isDarkColors onThemeChange isMacOS isWindows isLinux isDev getAppName getAppVersion getNativeId getUser |
| 子输入框 | setSubInput removeSubInput setSubInputValue subInputFocus subInputBlur subInputSelect plugin.setSubInputAccessory plugin.setSubInputAccessoryOptions plugin.removeSubInputAccessory plugin.showSubInputAccessory plugin.setSubInputArguments plugin.removeSubInputArguments plugin.focusSubInputArgument plugin.setSubInputPrefix plugin.removeSubInputPrefix |
| 指令与跳转 | getFeatures setFeature removeFeature redirect redirectSelf redirectHotKeySetting showNotification |
| 数据 | db.* dbStorage.* getPluginLocalDataPath getPluginTempPath |
| 剪贴板与输入 | copyText copyImage copyFile getCopiedFiles clipboard.readText clipboard.writeHtml hideMainWindowPasteText hideMainWindowPasteImage hideMainWindowPasteFile hideMainWindowPasteHtml hideMainWindowTypeString simulateKeyboardTap simulateMouseMove simulateMouseClick simulateMouseDoubleClick simulateMouseRightClick startDrag getPathForFile |
| 系统与 Shell | shellOpenPath shellShowItemInFolder shellTrashItem shellOpenExternal shellBeep showOpenDialog showSaveDialog getPath getFileIcon getFileIconAsync readCurrentFolderPath readCurrentBrowserUrl getForegroundApp getAllDisplays getPrimaryDisplay getCursorScreenPoint getDisplayNearestPoint getDisplayMatching screenToDipPoint dipToScreenPoint screenToDipRect dipToScreenRect screenColorPick pinyin.match |
| 文件 | fs.* |
| 截图 | captureScreen |
| 图片 | image() image.metadata image.merge image.gif image.pdf image.textToImage |
| 音视频 | runFFmpeg ffmpeg.probe ffmpeg.status |
| AI | ai allAiModels localAi.* registerTool unregisterTool |
| 自定义窗口 | createBrowserWindow browserWindow.* sendToParent ipc.* |
| 可编程浏览器 | browser getIdleBrowsers setBrowserProxy clearBrowserCache |
| 局域网服务与 ZIP | server.* zip.* |
| 运行本地程序 | spawn.* |