uTools API

在插件初始化完成时,uTools 会自动在你的 window 对象上挂载 utools 对象,它将提供一些特有的 api,使你的插件能够更好的与uTools 主窗口沟通,并获得一些有意义的底层能力。

事件

你可以根据需要,事先定义好一些回调函数,uTools 会在事件产生时主动调用它们。

onPluginReady(callback)

  • callback Function

当插件装载成功,uTools 将会主动调用这个方法(生命周期内仅调用一次),所有的 api 都应该在 onPluginReady 之后进行调用。

示例

utools.onPluginReady(() => {
  console.log('插件装配完成,已准备好')
})
1
2
3

onPluginEnter(callback)

  • callback Function
    • Object
      • code String

        plugin.json 配置的 feature.code

      • type String

        plugin.json 配置的 feature.cmd.type,可以为 "text"、"img"、 "files"、 "regex"、 "over"、"window"

      • payload String | Object | Array

        feature.cmd.type 对应匹配的数据

每当插件从后台进入到前台时,uTools 将会主动调用这个方法。

示例

utools.onPluginEnter(({code, type, payload}) => {
  console.log('用户进入插件', code, type, payload)
})

/* 
type 为 "files" 时, payload 值示例
[
	{
		"isFile": true,
		"isDirectory": false,
		"name": "demo.js",
		"path": "C:\\demo.js"
	}
]

type 为 "window" 时, payload 值示例
{
	"id": 264584,
	"class": "Chrome_WidgetWin_1",
	"title": "demo",
	"x": -8,
	"y": -8,
	"width": 1936,
	"height": 1056,
	"appPath": "C:\\demo.exe",
	"pid": 232,
	"app": "demo.exe"
}

type 为 "img" 时, payload 值示例
data:image/png;base64,...

type 为 "text"、"regex"、 "over" 时, payload 值为进入插件时的主输入框文本
*/
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

onPluginOut(callback)

  • callback Function

每当插件从前台进入到后台时,uTools 将会主动调用这个方法。

示例

utools.onPluginOut(() => {
  console.log('用户退出插件')
})
1
2
3

onPluginDetach(callback)

  • callback Function

用户对插件进行分离操作时,uTools 将会主动调用这个方法。

示例

utools.onPluginDetach(() => {
  console.log('插件被分离')
})
1
2
3

onDbPull(callback)

  • callback Function

当此插件的数据在其他设备上被更改后同步到此设备时,uTools 将会主动调用这个方法

示例

utools.onDbPull(() => {
  console.log('onDbPull')
})
1
2
3

窗口交互

hideMainWindow(isRestorePreWindow)

  • isRestorePreWindow Boolean

    是否焦点回归到前面的活动窗口,默认 true

  • 返回 Boolean

执行该方法将会隐藏 uTools 主窗口,包括此时正在主窗口运行的插件,分离的插件不会被隐藏。

示例

utools.hideMainWindow()
1

showMainWindow()

  • 返回 Boolean

执行该方法将会显示 uTools 主窗口,包括此时正在主窗口运行的插件。

示例

utools.showMainWindow()
1

setExpendHeight(height)

  • height Integer
  • 返回 Boolean

执行该方法将会修改插件窗口的高度。

示例

utools.setExpendHeight(100)
1

setSubInput(onChange, placeholder, isFocus)

  • onChange Function

    • Object
      • text String

    子输入框文本修改时触发

  • placeholder String (可选)

    子输入框占位符

  • isFocus Boolean (可选)

    子输入框是否获得焦点,默认 true

  • 返回 Boolean

设置子输入框,进入插件后,原本 uTools 的搜索条主输入框将会变成子输入框,子输入框可以为插件所使用。

main.png

主输入框

main.png

子输入框

示例

utools.setSubInput(({ text }) => {
  console.log(text)
}, '搜索')
1
2
3

removeSubInput()

  • 返回 Boolean

移除已经设置的子输入框,在插件切换到其他页面时可以重新设置子输入框为其所用。

示例

utools.removeSubInput()
1

setSubInputValue(value)

  • value String
  • 返回 Boolean

直接对子输入框的值进行设置。

示例

utools.setSubInputValue('uTools')
1

subInputFocus()

  • 返回 Boolean

子输入框获得焦点

示例

utools.subInputFocus()
1

subInputSelect()

  • 返回 Boolean

子输入框获得焦点并选中

示例

utools.subInputSelect()
1

subInputBlur()

  • 返回 Boolean

子输入框失去焦点,插件获得焦点

示例

utools.subInputBlur()
1

outPlugin()

  • 返回 Boolean

执行该方法将会退出当前插件。(插件进入后台,进程并未结束)

示例

utools.outPlugin()
1

redirect(label, payload)

  • label String

    feature.cmd.label 名称

  • payload String | Object

    feature.cmd.type 对应的数据

  • 返回 Boolean

该方法可以携带数据,跳转到另一个插件进行处理,如果用户未安装对应的插件,uTools 会弹出提醒并引导进入插件市场下载。

示例

//content 为string类型
utools.redirect('翻译', 'hello world')

//content 为object类型
utools.redirect('翻译', {
	'type': 'text',
	'data': 'hello world'
})

//传递图片
utools.redirect('图片识别', {
	'type': 'img',
	// data 可以是本地图片路径、base64编码的图片、Buffer对象
	'data': '/path/to/img.jpg(支持jpeg|png|bmp)' //filePath、base64、Buffer
})

//传递文件、文件夹
utools.redirect('图片压缩', {
	'type': 'files',
	// data 可以是本地文件、文件夹路径
	'data': '/path/to/img.jpg' //filePath、array
	//'data': ['path1', 'path2'] //支持数组
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

showOpenDialog(options)

弹出文件选择框

示例

utools.showOpenDialog({ 
  filters: [{ 'name': 'plugin.json', extensions: ['json'] }], 
  properties: ['openFile'] 
})
1
2
3
4

showSaveDialog(options)

弹出文件保存框

示例

utools.showSaveDialog({ 
  title: '保存位置', 
  defaultPath: utools.getPath('downloads')
  buttonLabel: '保存'
})
1
2
3
4
5

findInPage(text, options)

插件页面中查找内容

示例

utools.findInPage('utools')
1

stopFindInPage(action)

停止插件页面中查找

示例

utools.stopFindInPage()
1

startDrag(file)

  • file String | Array

    文件路径 或 文件路径集合

原生拖拽文件到其他窗口

示例

utools.startDrag('/path/to/file')
1

createBrowserWindow(url, options, callback)

创建浏览器窗口

示例

const ubWindow = utools.createBrowserWindow('test.html', {
  show: false,
  title: '测试窗口',
  webPreferences: {
    preload: 'preload.js'
  }
}, () => {
  // 显示
  ubWindow.show()
  // 置顶
  ubWindow.setAlwaysOnTop(true)
  // 窗口全屏
  ubWindow.setFullScreen(true)
  // 向子窗口传递数据
  ubWindow.webContents.send('ping')
  require('electron').ipcRenderer.sendTo(ubWindow.webContents.id, 'ping')
  // 执行脚本
  ubWindow.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())')
    .then((result) => {
      console.log(result) // Will be the JSON object from the fetch call
    })
})
console.log(ubWindow)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// 在新建窗口 JavaScript 中接收父窗口传递过来的数据
const { ipcRenderer } = require('electron')
ipcRenderer.on('ping', (event, data) => {
    console.log(event);
    console.log(data);
})
1
2
3
4
5
6

isDarkColors()

是否深色模式

示例

utools.onPluginEnter(({code, type, payload}) => {
  document.body.className = utools.isDarkColors() ? 'dark-mode' : ''
})
1
2
3

动态增减功能

很多时候,插件中会提供一些功能供用户进行个性化设置(例如:网页快开插件),这部分配置无法在 plugin.json 事先定义好,所以我们提供了以下方法对插件功能进行动态增减。

getFeatures()

  • 返回 Array

返回本插件所有动态增加的功能。

const features = utools.getFeatures()
console.log(features)
1
2

setFeature(feature)

  • feature Object

    格式与 plugin.json 中配置的格式一致

    • code String
    • explain String
    • icon String (可选)
    • platform Array (可选)
    • cmds Array
  • 返回 Boolean

为本插件动态新增某个功能。

utools.setFeature({
  "code": "hosts",
  "explain": "hosts切换",
  // "icon": "res/xxx.png",
  // "icon": "data:image/png;base64,xxx...",
  // "platform": ["win32", "darwin", "linux"]
  "cmds": ["hosts"]
})
1
2
3
4
5
6
7
8

removeFeature(code)

  • code String
  • 返回 Boolean

动态删除本插件的某个功能。

utools.removeFeature('code')
1

用户

获取当前用户头像、昵称

getUser()

  • 返回 Object

    { avatar: String, nickname: String, type: 'member' | 'user' } | null

获取当前用户,未登录帐号返回 null

console.log(utools.getUser())
1

fetchUserServerTemporaryToken()

  • 返回 Promise

    Promise<{ token: string, expired_at: number }>

获取用户服务端临时令牌,用于获取用户基础信息接口

utools.fetchUserServerTemporaryToken().then((ret) => {
  console.log(ret)
})
1
2
3

支付

openPayment(options, callback)

  • options

    • goodsId String

      商品 ID,在 “ uTools 开发者工具” 插件中创建

    • outOrderId String (可选)

      第三方服务生成的订单号(6 - 64 字符)

    • attach String (可选)

      第三方服务附加数据,在查询API和支付通知中原样返回,可作为自定义参数使用(最多 256 字符)

  • callback

    支付成功后回调

打开支付

utools.openPayment({ goodsId: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' }, () => {
  // 用户完成支付,继续业务代码
})
1
2
3

fetchUserPayments()

  • 返回 Promise

    Promise<{ order_id: string, out_order_id: string, open_id:string, pay_fee: number, body: string, attach: string, goods_id: string, paid_at: string,created_at }[]>

获取用户支付记录

utools.fetchUserPayments().then((ret) => {
  // 判断如果存在支付记录则继续相关业务
  console.log(ret);
  /**
  	    {
        "order_id": "ZsVSwEDoR7PPs6vWdAGplEpEpNjn8xb4", // utools 订单号
        "out_order_id": "", // 外部订单号
        "open_id": "a331127d654761ac91d086b942aae7b6", uTools 用户 ID, 对于此插件不变且唯一
        "pay_fee": 1, // 支付金额(分)
        "body": "会员1年", // 支付内容
        "attach": "", // 附加数据
        "goods_id": "6n193s7P95p9gA13786YkwQ5oxHpVW4f", // 商品 ID
        "paid_at": "2021-06-18 16:55:26", // 支付时间
        "created_at": "2021-06-18 16:55:11" // 订单生成时间
    }
  */
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

工具

屏幕取色 & 屏幕截图

screenColorPick(callback)

  • callback Function

    取色结束回调

    • Object
      • hex String
      • rgb String

屏幕取色

示例

utools.screenColorPick(({hex, rgb})=>{
  console.log(hex) // #FFFFFF
  console.log(rgb) // RGB(0, 0, 0)
})
1
2
3
4

screenCapture(callback)

  • callback Function

    截图结束回调

    • String

      图片的 Base64 字符串

屏幕截图

示例

utools.screenCapture(base64Str => {
  utools.redirect('识别图片中文字', { type: 'img', data: base64Str })
})
1
2
3

模拟

模拟敲击键盘 和 鼠标点击

simulateKeyboardTap(key, ...modifier)

  • key String

    键值

  • modifier String (可选)

    功能键

模拟键盘按键

示例

// 模拟键盘敲击 Enter
utools.simulateKeyboardTap('enter')
// windows linux 模拟粘贴
utools.simulateKeyboardTap('v', 'ctrl')
// macos 模拟粘贴
utools.simulateKeyboardTap('v', 'command')
// 模拟 Ctrl + Alt + A
utools.simulateKeyboardTap('a', 'ctrl', 'alt')
1
2
3
4
5
6
7
8

simulateMouseMove(x, y)

  • x Integer
  • y Integer

模拟鼠标移动

示例

utools.simulateMouseMove(100100)
1

simulateMouseClick(x, y)

  • x Integer (可选)
  • y Integer (可选)

模拟鼠标左键单击

示例

utools.simulateMouseClick(100100)
1

simulateMouseRightClick(x, y)

  • x Integer (可选)
  • y Integer (可选)

模拟鼠标右键单击

示例

utools.simulateMouseRightClick(100100)
1

simulateMouseDoubleClick(x, y)

  • x Integer (可选)
  • y Integer (可选)

模拟鼠标双击

示例

utools.simulateMouseDoubleClick(100100)
1

屏幕

getCursorScreenPoint()

  • 返回 Object

    { x: Integer, y: Integer }

获取鼠标绝对位置

示例

const point = utools.getCursorScreenPoint()
console.log(point.x, point.y)
1
2

getPrimaryDisplay()

获取主显示器

示例

const display = utools.getPrimaryDisplay()
console.log(display)
1
2

getAllDisplays()

获取所有显示器

示例

const displays = utools.getAllDisplays()
console.log(displays)
1
2

getDisplayNearestPoint(point)

获取位置所在的显示器

示例

const display = utools.getDisplayNearestPoint({x: 100, y: 100 })
console.log(display)
1
2

getDisplayMatching(rect)

获取矩形所在的显示器

示例

const display = utools.getDisplayMatching({x: 100, y: 100, width: 200, height: 200 })
console.log(display)
1
2

复制

copyFile(file)

  • file String | Array
  • 返回 Boolean

复制文件到系统剪贴板

示例

// 复制单个文件
utools.copyFile('/path/to/file')
// 复制多个文件
utools.copyFile(['/path/to/file1', '/path/to/file2'])
1
2
3
4

copyImage(img)

  • img String | Buffer
  • 返回 Boolean

复制图片到系统剪贴板

示例

// 路径
utools.copyImage('/path/to/img.png')
// base64
utools.copyImage('data:image/png;base64,xxxxxxxxx')
1
2
3
4

copyText(text)

  • text String
  • 返回 Boolean

复制文本

示例

utools.copyText('Hi, uTools')
1

getCopyedFiles()

  • 返回 Array

获取复制的文件或文件夹

示例

utools.getCopyedFiles()
// 返回 [{ isFile: true, isDirectory: false, name: 'test.png', path: '/path/to/test.png' }]
1
2

系统

showNotification(body, clickFeatureCode)

  • body String

  • clickFeatureCode String (可选)

    plugin.json 配置的 feature.code,点击通知进入插件功能(该 feature.cmds 至少包含一个搜索字符串关键字)

显示系统通知

示例

utools.showNotification('Hi, uTools')
1

shellOpenPath(fullPath)

  • fullPath String

系统默认方式打开给定的文件

示例

utools.shellOpenPath('/path/to/file')
1

shellShowItemInFolder(fullPath)

  • fullPath String

系统文件管理器中显示给定的文件

示例

utools.shellShowItemInFolder('/path/to/file')
1

shellOpenExternal(url)

  • url String

系统默认的协议打开URL

示例

// 浏览器打开
utools.shellOpenExternal('https://u.tools')
1
2

shellBeep()

播放哔哔声

示例

utools.shellBeep()
1

getNativeId()

  • 返回 String

获取本地 ID

示例

// 存储只与当前设备相关的信息
const nativeId = utools.getNativeId()
utools.dbStorage.setItem(nativeId + '/key', 'native value')
1
2
3

getAppVersion()

  • 返回 String

获取软件版本

示例

console.log(utools.getAppVersion())
1

getPath(name)

  • name String

    你可以通过名称请求以下的路径:

    • home 用户的 home 文件夹(主目录)
    • appData 当前用户的应用数据文件夹,默认对应:
      • %APPDATA% Windows 中
      • ~/Library/Application Support macOS 中
    • userData 储存你应用程序设置文件的文件夹,默认是 appData 文件夹附加应用的名称
    • temp 临时文件夹
    • exe 当前的可执行文件
    • desktop 当前用户的桌面文件夹
    • documents 用户文档目录的路径
    • downloads 用户下载目录的路径
    • music 用户音乐目录的路径
    • pictures 用户图片目录的路径
    • videos 用户视频目录的路径
    • logs 应用程序的日志文件夹
  • 返回 String

获取路径

示例

// 获取下载路径
console.log(utools.getPath('downloads'))
1
2

getFileIcon(filePath)

  • filePath String

    文件路径、文件扩展名、"folder"

  • 返回 String

获取文件图标

示例

// 获取扩展名为 "txt" 的文件图标
utools.getFileIcon('.txt')
// 获取文件夹图标
utools.getFileIcon('folder')
// 获取文件图标
utools.getFileIcon('D:\\test.url')
1
2
3
4
5
6

readCurrentFolderPath()

  • 返回 Promise

读取当前文件管理器窗口路径 (linux 不支持)

示例

utools.readCurrentFolderPath().then((dir) => {
  console.log(dir)
})
1
2
3

readCurrentBrowserUrl()

  • 返回 Promise

读取当前浏览器窗口 URL (linux 不支持)

MacOS 支持浏览器 Safari、Chrome、Microsoft Edge、Opera、Vivaldi、Brave

Windows 支持浏览器 Chrome、Firefox、Edge、IE、Opera、Brave

示例

utools.readCurrentBrowserUrl().then((url) => {
  console.log(url)
})
1
2
3

isDev()

判断插件是否在开发环境

示例

if (utools.isDev()) {
  console.log('coding')
}
1
2
3

isMacOs()

是否 MacOS 操作系统

示例

if (utools.isMacOs()) {
  console.log('mac')
}
1
2
3

isWindows()

是否 Windows 操作系统

示例

if (utools.isWindows()) {
  console.log('windows')
}
1
2
3

isLinux()

是否 Linux 操作系统

示例

if (utools.isLinux()) {
  console.log('linux')
}
1
2
3