📋 plugin.json配置

基础字段

• "main": "index.html" - 入口HTML文件
• "logo": "logo.png" - 插件Logo（PNG/JPG）
• "preload": "preload.js" - 预加载JS文件

插件设置

• "single": true - 是否单例模式
• "height": 300 - 初始高度

功能定义

• "code": "unique_code" - 唯一功能编码
• "explain": "功能描述" - 功能说明
• "cmds": ["指令1", "指令2"] - 命令集合

{
  "main": "index.html",
  "logo": "logo.png",
  "preload": "preload.js",
  "features": [{
    "code": "hello",
    "explain": "hello world",
    "cmds": ["hello", "你好"]
  }]
}

🎯 事件监听

• utools.onPluginEnter(callback) - 进入插件时触发
• utools.onPluginOut(callback) - 退出插件时触发
• utools.onMainPush(callback, onSelect) - 推送内容到搜索框
• utools.onPluginDetach(callback) - 插件分离时触发
• utools.onDbPull(callback) - 数据同步时触发

参数类型

• action: {code, type, payload, from} - 插件进入信息
• type: "text"|"img"|"file"|"regex" - 匹配类型
• from: "main"|"panel"|"hotkey" - 触发来源

utools.onPluginEnter(({ code, type, payload, from }) => {
  console.log("用户进入插件", code, type, payload);
  console.log("触发方式：", from);
});

🖥️ 窗口操作

• utools.hideMainWindow([isRestore]) - 隐藏主窗口
• utools.showMainWindow() - 显示主窗口
• utools.setExpendHeight(height) - 设置窗口高度
• utools.outPlugin([isKill]) - 退出插件
• utools.getWindowType() - 获取窗口类型
• utools.isDarkColors() - 是否深色主题

子输入框

• utools.setSubInput(onChange, placeholder) - 设置子输入框
• utools.removeSubInput() - 移除子输入框
• utools.setSubInputValue(text) - 设置子输入框值
• utools.subInputFocus() - 聚焦子输入框

utools.setSubInput(({ text }) => {
  console.log("输入内容：", text);
}, "请输入搜索内容");

⚙️ 系统API

• utools.showNotification(body, code) - 系统通知
• utools.shellOpenPath(fullPath) - 用系统默认方式打开文件
• utools.shellShowItemInFolder(fullPath) - 在文件管理器中显示
• utools.shellTrashItem(fullPath) - 移至回收站
• utools.shellOpenExternal(url) - 打开外部URL
• utools.shellBeep() - 播放系统提示音

系统信息

• utools.getNativeId() - 获取设备ID
• utools.getAppName() - 获取应用名称
• utools.getAppVersion() - 获取应用版本
• utools.getPath(name) - 获取系统路径

utools.showNotification("任务完成", "result_feature");
utools.shellOpenExternal("https://www.u-tools.cn");

🗄️ 本地数据库

• utools.db.put(doc) - 创建/更新文档
• utools.db.get(id) - 获取文档
• utools.db.remove(doc) - 删除文档
• utools.db.allDocs(prefix) - 获取文档列表
• utools.db.bulkDocs(docs) - 批量操作

附件操作

• utools.db.postAttachment(id, data, type) - 存储附件
• utools.db.getAttachment(id) - 获取附件
• utools.db.getAttachmentType(id) - 获取附件类型

数据库同步

• utools.db.replicateStateFromCloud() - 云端同步状态

// 存储数据
const doc = {_id: "user/1", name: "张三"};
const result = utools.db.put(doc);
if (result.ok) doc._rev = result.rev;

💾 存储API

dbStorage（类localStorage）

• utools.dbStorage.setItem(key, value) - 存储数据
• utools.dbStorage.getItem(key) - 获取数据
• utools.dbStorage.removeItem(key) - 删除数据
• utools.dbStorage.clear() - 清空数据
• utools.dbStorage.key(index) - 获取键名

dbCryptoStorage（加密存储）

• utools.dbCryptoStorage.setItem(key, value) - 加密存储
• utools.dbCryptoStorage.getItem(key) - 获取加密数据

// 普通存储
utools.dbStorage.setItem("theme", "dark");
// 加密存储
utools.dbCryptoStorage.setItem("token", "secret_token");

📋 复制API

• utools.copyText(text) - 复制文本
• utools.copyFile(filePath) - 复制文件
• utools.copyImage(image) - 复制图像
• utools.getCopyedFiles() - 获取复制的文件列表

utools.copyText("Hello World!");
utools.copyFile("/path/to/file.txt");
utools.copyImage("data:image/png;base64,...");

⌨️ 输入API

• utools.hideMainWindowPasteFile(filePath) - 粘贴文件
• utools.hideMainWindowPasteImage(image) - 粘贴图像
• utools.hideMainWindowPasteText(text) - 粘贴文本
• utools.hideMainWindowTypeString(text) - 模拟输入

utools.hideMainWindowPasteText("Hello World!");
utools.hideMainWindowTypeString("uTools 效率工具 🐼👏🦄");

🖼️ 屏幕API

• utools.screenColorPick(callback) - 屏幕取色
• utools.screenCapture(callback) - 屏幕截图
• utools.getPrimaryDisplay() - 获取主显示器
• utools.getAllDisplays() - 获取所有显示器
• utools.getCursorScreenPoint() - 获取鼠标位置
• utools.desktopCaptureSources(options) - 获取录屏源

坐标转换

• utools.screenToDipPoint(point) - 物理坐标转DIP
• utools.dipToScreenPoint(point) - DIP转物理坐标

utools.screenColorPick((colors) => {
  console.log("颜色：", colors.hex, colors.rgb);
});
utools.screenCapture((image) => {
  console.log("截图：", image);
});

👤 用户API

• utools.getUser() - 获取用户信息
• utools.fetchUserServerTemporaryToken() - 获取服务端临时令牌

用户信息字段

• avatar - 用户头像
• nickname - 用户昵称
• type - 用户类型（member/user）

const user = utools.getUser();
if (user) {
  console.log("用户：", user.nickname, user.type);
}

🔄 动态指令

• utools.getFeatures([codes]) - 获取动态功能
• utools.setFeature(feature) - 新增动态功能
• utools.removeFeature(code) - 删除动态功能

快捷键设置

• utools.redirectHotKeySetting(cmdLabel) - 跳转快捷键设置
• utools.redirectAiModelsSetting() - AI模型设置

utools.setFeature({
  code: "dynamic_" + Date.now(),
  explain: "测试动态功能",
  cmds: ["测试", "test"]
});

⌨️ 模拟按键

• utools.simulateKeyboardTap(key, ...modifiers) - 模拟键盘按键
• utools.simulateMouseMove(x, y) - 模拟鼠标移动
• utools.simulateMouseClick(x, y) - 模拟鼠标点击
• utools.simulateMouseDoubleClick(x, y) - 模拟鼠标双击
• utools.simulateMouseRightClick(x, y) - 模拟鼠标右击

// 模拟复制
utools.simulateKeyboardTap("a", "ctrl");
// 模拟点击
utools.simulateMouseClick(100, 100);

🤖 AI API

• utools.ai(option[, streamCallback]) - 调用AI
• utools.allAiModels() - 获取所有AI模型

Function Calling

• tools - 工具列表
• function must be on window - 函数必须挂载到window

// AI对话
const result = await utools.ai({
  messages: [
    {role: "system", content: "你是翻译专家"},
    {role: "user", content: "你好世界"}
  ]
});

// Function Calling
window.getSystemInfo = () => ({ cpu: "Intel i7" });
await utools.ai({ messages, tools });

🎬 FFmpeg API

• utools.runFFmpeg(args[, onProgress]) - 运行FFmpeg

PromiseLike扩展

• .kill() - 强制结束进程
• .quit() - 通知退出

// 视频压缩
const run = utools.runFFmpeg([
  "-i", "input.mp4",
  "-c:v", "libx264",
  "output.mp4"
], (progress) => {
  console.log("进度：" + progress.percent + "%");
});

// 可随时终止：run.kill()

🌐 可编程浏览器(ubrowser)

基础操作

• ubrowser.goto(url, headers, timeout) - 跳转网页
• ubrowser.viewport(width, height) - 设置视窗大小
• ubrowser.hide()/show() - 隐藏/显示窗口
• ubrowser.run([id], options) - 运行并获取结果

网页操作

• ubrowser.click(selector) - 点击元素
• ubrowser.value(selector, value) - 设置输入框值
• ubrowser.press(key, ...modifiers) - 按键
• ubrowser.evaluate(func, params) - 执行JS
• ubrowser.screenshot(target, savePath) - 截图
• ubrowser.pdf(options, savePath) - 导出PDF
• ubrowser.wait(ms|selector|func) - 等待条件

示例代码

// 百度地图定位
utools.ubrowser
  .goto("https://map.baidu.com")
  .wait("#sole-input")
  .focus("#sole-input")
  .value("#sole-input", "福州烟台山")
  .wait(300)
  .press("enter")
  .run({ width: 1200, height: 800 });

💰 用户付费

• utools.isPurchasedUser() - 是否付费用户
• utools.openPurchase(options, callback) - 软件付费
• utools.openPayment(options, callback) - 服务付费
• utools.fetchUserPayments() - 获取支付记录

const purchased = utools.isPurchasedUser();
if (!purchased) {
  utools.openPurchase({
    goodsId: "xxxxxxxxxx"
  }, () => {
    console.log("付费成功");
  });
}

🖥️ 服务端API

用户接口

• GET /baseinfo - 获取用户基础信息
• GET /payments/record - 查询订单状态

支付回调

• POST /callback - 支付成功通知

签名算法

const str = new URLSearchParams(params).toString();
const sign = crypto.createHmac("sha256", secret).update(str).digest("hex");

👥 团队应用

• utools.team.info() - 获取团队信息
• utools.team.preset(key) - 获取团队配置
• utools.team.allPresets(filter) - 获取所有配置

团队信息字段

• teamId - 团队ID
• teamName - 团队名称
• userId - 成员ID
• userName - 成员名称

const { teamName } = utools.team.info();
const config = utools.team.preset("database");

🎯 匹配指令类型

文本匹配

• "type": "regex" - 正则表达式匹配
• "type": "over" - 匹配任意文本

文件匹配

• "type": "files" - 文件(夹)匹配
• "fileType": "file" - 文件类型
• "extensions": ["jpg", "png"] - 扩展名

其他匹配

• "type": "img" - 图像匹配
• "type": "window" - 窗口匹配

{
  "type": "regex",
  "label": "打开网址",
  "match": "/^https?:\\/\\/[^\\s/$.?#]\\S+$/i",
  "minLength": 10,
  "maxLength": 1000
}

🖥️ 平台检测

• utools.isDev() - 是否开发环境
• utools.isMacOS() - 是否macOS
• utools.isWindows() - 是否Windows
• utools.isLinux() - 是否Linux

路径获取

• getPath("home") - 用户主目录
• getPath("desktop") - 桌面目录
• getPath("documents") - 文档目录
• getPath("downloads") - 下载目录
• getPath("temp") - 临时目录

if (utools.isWindows()) {
  const path = utools.getPath("desktop");
  console.log("桌面路径：", path);
}

📁 文件对话框

• utools.showOpenDialog(options) - 文件选择对话框
• utools.showSaveDialog(options) - 文件保存对话框

OpenDialog选项

• filters: [{name: "Images", extensions: ["png","jpg"]}] - 文件过滤
• properties: ["openFile","multiSelections"] - 对话框属性

const files = utools.showOpenDialog({
  filters: [{name: "JSON", extensions: ["json"]}],
  properties: ["openFile", "multiSelections"]
});

🛠️ 实用工具

查找与导航

• utools.findInPage(text, options) - 页面内查找
• utools.stopFindInPage(action) - 停止查找
• utools.redirect(label, payload) - 跳转其他插件
• utools.startDrag(filePath) - 拖拽文件

图标获取

• utools.getFileIcon(filePath) - 获取文件图标
• utools.getFileIcon(".txt") - 获取类型图标
• utools.getFileIcon("folder") - 获取文件夹图标

当前窗口信息

• utools.readCurrentFolderPath() - 文件管理器路径
• utools.readCurrentBrowserUrl() - 浏览器URL

utools.findInPage("搜索内容");
utools.startDrag(["/path/to/file1.txt", "/path/to/file2.txt"])

📂 插件目录结构

基本结构

• plugin.json - 插件配置文件
• index.html - 入口HTML文件
• preload.js - 预加载脚本
• logo.png - 插件图标

其他资源

• css/ - 样式文件目录
• js/ - JavaScript文件目录
• assets/ - 静态资源
• node_modules/ - Node.js依赖

my-plugin/
├── plugin.json
├── index.html
├── preload.js
├── logo.png
└── assets/
    ├── favicon.ico
    └── images/

⚡ 预加载脚本

功能说明

• 调用Node.js API和Electron渲染进程API
• 遵循CommonJS规范
• 通过require引入Node.js模块

常用模块

• const fs = require('fs') - 文件系统
• const path = require('path') - 路径操作
• const { ipcRenderer } = require('electron') - IPC通信

// 读取配置文件
const fs = require('fs');
const config = JSON.parse(fs.readFileSync('config.json', 'utf8'));

// utools API可用性检查
if (typeof utools !== 'undefined') {
  utools.showNotification("预加载脚本已加载");
}

🔧 开发调试

开发模式

• 在uTools开发者工具中打开插件项目
• 支持HTTP开发地址（仅开发模式）
• 实时热重载功能

调试技巧

• 使用browser devtools调试前端代码
• 使用console.log调试preload脚本
• 检查plugin.json配置是否正确

常见问题排查

• 指令无法安装 - 检查是否有功能指令
• API调用失败 - 检查preload路径
• 样式错乱 - 检查CSS文件路径

// 开发环境检测
if (utools.isDev()) {
  console.log("开发模式已启用");
}