uTools的插件开发教程

title: uTools的插件开发教程 id: d7ad21a1590d7623e98fc9b6c4032326 tags: [] date: 2024/01/05 18:02:41 updated: 2024/01/08 11:17:05 isPublic: true --#|[分隔]|#--

uTools的插件开发教程

uTools 是一款支持 windows、mac、linux 三大平台的软件。

官网：https://www.u.tools/

开发文档：https://www.u.tools/docs/developer/welcome.html

uTools是基于Electron开发的软件，它的主要功能，是可以下载海量的插件来运行，每一个插件可以视作一个软件。

可以把 uTools 当做微信的小程序模块，我们下载了微信，就可以使用很多微信小程序，同理，下载了 uTools，就可以使用 uTools 支持的那些插件。

uTools的插件市场，里面少部分是uTools官方开发的，大部分是网友开发的，开发的插件允许收费，但绝大部分是免费的。

一个优秀的插件，可以省去我们单独安装一个软件的磁盘空间，uTools上有很多优秀的插件，需要自己按需查找和使用。

本教程主要是如何开发uTools插件，哪怕这个插件只是自己使用，也可以发布到uTools中。

下面是uTools的主窗口和某一个插件的运行窗口的截图展示，插件可以独立窗口运行，类似一个独立的软件。

uTools插件的运行原理

因为uTools是基于Electron开发的软件，所以它内部自带完整的nodejs，uTools内的插件，也可以直接使用nodejs的Api。

所以uTools的插件，也是基于web和nodejs开发的，界面展示部分就是一个前端页面项目，其他的需要和系统交互的部分则是使用nodejs。

此外，uTools为了抹平不同系统之间的不同，封装了一些和系统操作的内置API。

所以按照不同的功能复杂程度，可以按需使用不同技术：

1. 最简单的插件。

最简单的插件，可以只使用前端技术开发一个页面，比如计算器、在线ps（凡是浏览器能展示的效果，都可以直接实现）。

2. 功能复杂一些的，需要读取剪贴板、存储文件、屏幕取色等功能。

此时仍然可以使用前端技术开发页面，然后在js中调用uTools封装的API来间接的和系统交互，就能实现系统工具级的功能，比如剪贴板历史记录、文件重命名工具。

3. 更复杂的和系统文件、网络交互。

想要实现更复杂的功能，当uTools封装的API无法满足需求，那就可以直接使用nodejs的原生API了。

**注：**本教程不讨论模板插件应用。

安装uTools开发者工具

现在开始开发，开发文档：https://www.u.tools/docs/developer/welcome.html。

uTools的插件是运行在uTools中的，需要和uToos联调，先下载uTools开发工具。

uTools开发者工具本身也是一个插件，可以在uTools的插件应用市场中搜索，然后安装。

安装成功后打开。

uTools开发者工具中创建新项目

打开后，此处应该是一个空列表，需要先点击左上角的新建项目。

在新窗口编辑新项目的名称、描述等信息，最后创建。

等待选择plugin.json文件的项目

下面这是创建完一个新项目后的界 面展示，这里的新项目，会要求选择一个 plugin.json 文件，才可以开始调试。

创建项目文件夹

在uTools中创建了项目，就差一个plugin.json文件就可以运行、发布了，**plugin.json **文件所在的文件夹，就是我们插件代码的项目文件夹。

plugin.json文件

plugin.json文件，这是最重要的一个文件，用来说明这个插件应用将如何与 uTools 集成。

首先创建一个文件夹，这个文件夹作为我们的项目代码文件夹，在里面创建三个文件：

• plugin.json：关键必要文件。

• index.html：插件的界面展示主文件，文件名和 plugin.json 中 icon 项的值保持一致即可。

• icon.png：插件的Logo文件，文件名和 plugin.json 中 icon 项的值保持一致即可，

比如下面是一个plugin.json文件的配置，也可以去uTools查看更多plugin.json配置项。

// 使用本json时，需要把注释删掉
{
	"pluginName": "我的Demo的插件名称",
	"description": "我的Demo的简短说明",
	"author": "作者",
	"homepage": "本插件的官网，或者作者个人页面",
	"version": "1.0.1",
	"main": "index.html", // 正常安装了本插件后，本插件的主页文件地址，可以是文件地址，也可以是个网址
	"logo": "icon.png", // 插件logo文件地址
  // "preload": "preload.js", // 如果是最简单的纯页面插件，用不着这个文件，当插件启动时，会自动载入此的预加载脚本
	// 开发环境配置项，也就是在uTools开发者工具中启动本插件
  "development": {
    // "main": "http://localhost:4002" // 仅开发环境生效，本插件的主页文件地址，可以是文件地址，也可以是个网址，非必填
  },
	// 支持的系统，不写本字段，默认会是下面三个值，分别对应 windows系统、mac系统、linux系统
	"platform": ["win32", "darwin", "linux"],
	// 电脑中已经安装了本插件，打开uTools的全局搜索条
	"features": [
		{
			"code": "start",
			"cmds": [
				"我的", // 电脑中已经安装了本插件，在uTools的全局搜索条中输入，能搜索到本插件
				"Demo", // 电脑中已经安装了本插件，在uTools的全局搜索条中输入，能搜索到本插件
        {
          "type": "files",
          "fileType": "file", // 文件类型
          "match": "/\\.(jpeg|jpg|png|webp)$/i", // 电脑中已经安装了本插件，再复制这几种格式的文件，打开了uTools后能自动检索到本插件
          "label": "我的Demo的插件名称 | 通过文件进入" // 检索列表中，本插件展示的label
        },
        {
          "type": "files",
          "fileType": "directory", // 脑中已经安装了本插件，再复制一个文件夹，打开了uTools后能自动检索到本插件
          "label": "我的Demo的插件名称 | 通过文件夹进入" // 检索列表中，本插件展示的label
        }
			]
		}
	]
}

添加完成 plugin.json 文件后，可以启动项目，也可以打包项目，且可以随时更换plugin.json文件：

运行项目

点击运行项目后，就会启动项目的开发环境，然后就可以【打开】，启动这个开发中的插件进行调试，开发时可以把这个插件当做运行在浏览器中的页面，都可以调出熟悉的控制台。

打包项目

这里简单说明一下打包项目，点击打包项目，会把本插件的项目文件夹进行打包，其实就是压缩生成一个 upx 格式的文件，这个文件就是可供uTools运行的插件包。

**安装方法：**很简单，直接复制这个文件，然后唤出uTools全局搜索框，就会自动提示安装，但这种使用upx文件安装的插件，因为不是走uTools发布插件正常的审核流程，所以安装完后会有个提示，说这个插件非官方之类的，但不影响使用。

正常情况，这个文件一般都用不着，哪怕在开发者工具里发布项目，对方也是直接打包项目文件夹，提交审核、上架到插件市场。

而自己手里打包出来upx插件文件，也就只能自己使用，或者发送给亲朋好友，对方再安装到自己的uTools中。

插件功能开发

后面就是插件实际功能开发了。

纯前端插件

【uTools插件的运行原理中】一节所说的【最简单的插件】，本质就是一个纯前端项目，上一步就能实现。

需要调用uTools内置API的插件

下面说一下如何调用uTools的内置API。

uTools内置API

在插件应用初始化完成时，uTools 会自动在你的 window 对象上挂载 utools 对象，utools 对象下就是uTools的内置API们。

内置API主要有下面四类，实现绝大多数功能时，只用前两个就能实现，少数需要后两个：

• uTools API：取用方式：utools['API方法']，这是uTools的主要API，提供了一系列的方法和属性供开发者使用，包括获取系统信息、操作系统剪贴板、发送系统通知、操作uTools主窗口、操作uTools托盘菜单等等。

• uTools DB API：**取用方式：utools.db['API方法']**这是uTools的数据库API，提供了一系列的方法供开发者操作uTools的内置数据库，包括创建、读取、更新和删除数据等操作。

• ubrowser API：取用方式：utools.ubrowser['API方法']，是根据 uTools 的特性，量身打造的一个可编程浏览器。利用 ubrowser 可以轻而易举连接一切互联网服务，且与 uTools 完美结合。

• uTools Server API：取用方式：详见文档，多数为加密请求的方式，这是uTools的服务器API，可以将你的应用和 uTools 用户关联，实现帐号互通、接收支付通知、查询用户支付记录等，为保护密钥安全，请仅在服务端调用接口。

preload 文件和调用Nodejs API

上一步的uTools Server API，提示仅在服务端调用接口，这里说的【服务端】，指的就是preload文件。

在plugin.json中有一个非必填配置项是：preload，值是一个js文件的相对路径。

官方说明：

在传统的 web 开发中，所有的 javascript 脚本都在浏览器沙盒中运行，权限被严格限制，所能实现的功能非常有限。

通过 preload.js 能够帮你突破沙盒限制，进入一个崭新的 JavaScript 世界。

preload.js 是一个特殊且单独的文件，不需要与其他业务代码编译在一起，在此文件中可以访问 nodejs、electron、uTools 提供的 api，并挂载到 window 对象中，你其他的普通 javascript 代码就可以访问这些 api。

说白了，这个文件中可以使用nodejs的API，来和系统底层交互了。

简单项目示例

下面是一个简单项目的示例，分别是 plugin.json、index.html、preload.js，此外还需要一个logo的图片文件，随便截个图改好名字放在项目中即可。

效果展示

plugin.json 代码

{
	"pluginName": "我的Demo的插件名称",
	"description": "我的Demo的简短说明",
	"author": "作者",
	"homepage": "本插件的官网，或者作者个人页面",
	"version": "1.0.1",
	"main": "index.html",
	"logo": "icon.png",
  "preload": "preload.js",
  "development": {
  },
	"platform": ["win32", "darwin", "linux"],
	"features": [
		{
			"code": "start",
			"cmds": [
				"我的",
				"Demo",
        {
          "type": "files",
          "fileType": "file",
          "match": "/\\.(jpeg|jpg|png|webp)$/i",
          "label": "我的Demo的插件名称 | 通过文件进入"
        },
        {
          "type": "files",
          "fileType": "directory",
          "label": "我的Demo的插件名称 | 通过文件夹进入"
        }
			]
		}
	]
}

index.html代码

<!DOCTYPE html>
<html lang="zh-cn">
  <head>
    <meta charset="UTF-8" />
    <title>我的Demo</title>
  </head>
  <body>
    <div>
      <button id="toGetHomedir">点击获取用户主目录：</button>
      <span id="toGetHomedirResult"></span>
    </div>
  </body>
</html>
<script>
// 获取 proload 对象
const preload = window.preload

// 获取主目录
document.querySelector('#toGetHomedir').onclick = async () => {
  let value = await preload.getHomedir()
  document.querySelector('#toGetHomedirResult').innerHTML = value
}
</script>

preload.js 代码

const os = require('os')

// 可以通过这个对象，使用 uTools API
const utools = window.utools

// 获取系统用户的主目录文件夹 - 使用nodejs的API
function getHomedir() {
  return os.homedir()
}

// 把方法挂在到window上
window.preload = {
  getHomedir,
}

发布、更新插件

开发完成就可以上架插件了，也可以用同样的方式去更新；如果是更新，新更新的功能，最好也直接添加到插件介绍里，因为版本更新记录很少有人会看。

**强烈建议：**如果是新插件，在发布之前，最好先自己打包一下，打包出upx文件，自己安装一下使用一下，以免某些配置、环境、路径问题，导致正式环境下插件不可用。

上架和更新都需要审核，一般是三个工作日左右，上架的审核通过后，就可以直接在uTools的插件市场中搜索到了，安装后就可以使用了；如果是更新，那用户的【已安装应用】的列表中，此插件会显示小红点，提示有新版本。

下面是很简单的发布流程。