# uTools API
在插件初始化完成时,uTools会自动在你的window对象上挂载utools对象,它将提供一些特有的api,使你的插件能够更好的与uTools主窗口沟通,并获得一些有意义的底层能力。
# 事件
你可以根据需要事先定义好一些回调函数,uTools会在事件产生时主动调用它们。
# onPluginReady(callback)
callback
Function
当插件装载成功,uTools将会主动调用这个方法(生命周期内仅调用一次)。
# 示例
utools.onPluginReady(() => {
console.log('插件装配完成,已准备好')
})
# onPluginEnter(callback)
callback
FunctionObject
code
Stringplugin.json 配置的 feature.code
type
Stringplugin.json 配置的 feature.cmd.type,可以为 "text"、"img"、 "files"、 "regex"、 "over"、"window"
payload
String | Object | Arrayfeature.cmd.type 对应匹配的数据
optional
Array | undefined存在多个匹配时的可选匹配类型和数据 [{ type, payload }]
每当插件从后台进入到前台时,uTools将会主动调用这个方法。
# 示例
utools.onPluginEnter(({code, type, payload, optional}) => {
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 值为进入插件时的主输入框文本
*/
# onPluginOut(callback)
callback
Function
每当插件从前台进入到后台时,uTools将会主动调用这个方法。
# 示例
utools.onPluginOut(() => {
console.log('用户退出插件')
})
# onPluginDetach(callback)
callback
Function
用户对插件进行分离操作时,uTools将会主动调用这个方法。
# 示例
utools.onPluginDetach(() => {
console.log('插件被分离')
})
# onDbPull(callback)
callback
Function
当此插件的数据在其他设备上被更改后同步到此设备时,uTools将会主动调用这个方法
# 示例
utools.onDbPull(() => {
console.log('onDbPull')
})
# 窗口交互
# hideMainWindow(isRestorePreWindow)
isRestorePreWindow
Boolean是否焦点回归到前面的活动窗口,默认 true
返回
Boolean
执行该方法将会隐藏uTools主窗口,包括此时正在主窗口运行的插件,分离的插件不会被隐藏。
# 示例
utools.hideMainWindow()
# showMainWindow()
返回
Boolean
执行该方法将会显示uTools主窗口,包括此时正在主窗口运行的插件。
# 示例
utools.showMainWindow()
# setExpendHeight(height)
height
Integer返回
Boolean
执行该方法将会修改插件窗口的高度。
# 示例
utools.setExpendHeight(100)
# setSubInput(onChange, placeholder, isFocus)
onChange
FunctionObject
text
String
子输入框文本修改时触发
placeholder
String (可选)子输入框占位符
isFocus
Boolean (可选)子输入框是否获得焦点,默认 true
返回
Boolean
设置子输入框,进入插件后,原本uTools的搜索条主输入框将会变成子输入框,子输入框可以为插件所使用。
主输入框

子输入框
# 示例
utools.setSubInput(({ text }) => {
console.log(text)
}, '搜索')
# removeSubInput()
返回
Boolean
移出先前设置的子输入框,在插件切换到其他页面时可以重新设置子输入框为其所用。
# 示例
utools.removeSubInput()
# setSubInputValue(value)
value
String返回
Boolean
直接对子输入框的值进行设置。
# 示例
utools.setSubInputValue('uTools')
# subInputFocus()
返回
Boolean
子输入框获得焦点
# 示例
utools.subInputFocus()
# subInputSelect()
返回
Boolean
子输入框获得焦点并选中
# 示例
utools.subInputSelect()
# subInputBlur()
返回
Boolean
子输入框失去焦点,插件获得焦点
# 示例
utools.subInputBlur()
# outPlugin()
返回
Boolean
执行该方法将会退出当前插件。
# 示例
utools.outPlugin()
# redirect(label, payload)
label
Stringfeature.cmd.label 名称
payload
String | Objectfeature.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'] //支持数组
})
# showOpenDialog(options)
options
Object与 Electron API dialog.showOpenDialogSync (opens new window) options 一致
返回
Array | undefined返回选择的文件数组,用户取消返回 undefined
弹出文件选择框
# 示例
utools.showOpenDialog({
filters: [{ 'name': 'plugin.json', extensions: ['json'] }],
properties: ['openFile']
})
# showSaveDialog(options)
options
Object与 Electron API dialog.showSaveDialogSync (opens new window) options 一致
返回
String | undefined返回选择的路径,用户取消返回 undefined
弹出文件保存框
# 示例
utools.showSaveDialog({
title: '保存位置',
defaultPath: utools.getPath('downloads')
buttonLabel: '保存'
})
# showMessageBox(options)
options
Object与 Electron API dialog.showMessageBoxSync (opens new window) options 一致
返回
Integer返回点击按钮的索引
弹出消息框
# 示例
utools.showMessageBox({
type: 'question',
buttons: ['取消', '关机'],
title: '关机确认',
message: '电脑确定要关机?',
defaultId: 1
})
# findInPage(text, options)
text
String要搜索的内容(必填)
options
Object (可选)与 Electron API contentsfindinpagetext-options (opens new window) options 一致
插件页面中查找内容
# 示例
utools.findInPage('utools')
# stopFindInPage(action)
action
String"clearSelection" | "keepSelection" | "activateSelection", 默认 "clearSelection"
与 Electron API contentsstopfindinpageaction (opens new window) 一致
停止插件页面中查找
# 示例
utools.stopFindInPage()
# startDrag(file)
file
String | Array文件路径 或 文件路径集合
原生拖拽文件到其他窗口
# 示例
utools.startDrag('/path/to/file')
# createBrowserWindow(url, options, callback)
url
String相对路径的html文件 例如: test.html?param=xxx
options
Object与 Electron API new BrowserWindow (opens new window) 参数一样, 注意: preload 需配置相对位置
callback
Function (可选)url
加载完成时回调返回
Integer返回 webContentsId
创建浏览器窗口
# 示例
const webContentsId = utools.createBrowserWindow('test.html?param=xxxxxx', {
title: '测试窗口',
fullscreen: true,
webPreferences: {
preload: 'test/preload.js'
}
}, () => {
// 向子窗口传递数据
require('electron').ipcRenderer.sendTo(webContentsId, 'ping', data)
})
// 在新建窗口 JavaScript 中接收父窗口传递过来的数据
const { ipcRenderer } = require('electron')
ipcRenderer.on('ping', (event, data) => {
console.log(event);
console.log(data);
})
# isDarkColors()
是否深色模式
# 示例
utools.onPluginEnter(({code, type, payload}) => {
document.body.className = utools.isDarkColors() ? 'dark-mode' : ''
})
# 动态增减功能
很多时候,插件中会提供一些功能供用户进行个性化设置(例如:网页快开
插件),这部分配置无法在plugin.json
事先定义好,所以我们提供了以下方法对插件功能进行动态增减。
# getFeatures()
返回
Array
返回本插件所有动态增加的功能。
const features = utools.getFeatures()
console.log(features)
# setFeature(feature)
feature
Object格式与
plugin.json
中配置的格式一致code
Stringexplain
Stringicon
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"]
})
# removeFeature(code)
code
String返回
Boolean
动态删除本插件的某个功能。
utools.removeFeature('code')
# 用户
获取当前用户头像、昵称
# getUser()
返回
Object{ avatar: String, nickname: String, type: 'member' | 'user' } | null
获取当前用户,未登录帐号返回
null
console.log(utools.getUser())
# 工具
屏幕取色 & 屏幕截图
# screenColorPick(callback)
callback
Function取色结束回调
Object
hex
Stringrgb
String
屏幕取色
# 示例
utools.screenColorPick(({hex, rgb})=>{
console.log(hex) // #FFFFFF
console.log(rgb) // RGB(0, 0, 0)
})
# screenCapture(callback)
callback
Function截图结束回调
String
图片的Base64字符串
屏幕截图
# 示例
utools.screenCapture(base64Str => {
utools.redirect('识别图片中文字', { type: 'img', data: base64Str })
})
# 模拟
模拟敲击键盘 和 鼠标点击
# 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')
# simulateMouseMove(x, y)
x
Integery
Integer
模拟鼠标移动
# 示例
utools.simulateMouseMove(100,100)
# simulateMouseClick(x, y)
x
Integer (可选)y
Integer (可选)
模拟鼠标左键单击
# 示例
utools.simulateMouseClick(100,100)
# simulateMouseRightClick(x, y)
x
Integer (可选)y
Integer (可选)
模拟鼠标右键单击
# 示例
utools.simulateMouseRightClick(100,100)
# simulateMouseDoubleClick(x, y)
x
Integer (可选)y
Integer (可选)
模拟鼠标双击
# 示例
utools.simulateMouseDoubleClick(100,100)
# 屏幕
# getCursorScreenPoint()
返回
Object{ x: Integer, y: Integer }
获取鼠标绝对位置
# 示例
const point = utools.getCursorScreenPoint()
console.log(point.x, point.y)
# getPrimaryDisplay()
返回
Object
获取主显示器
# 示例
const display = utools.getPrimaryDisplay()
console.log(display)
# getAllDisplays()
返回
Array
获取所有显示器
# 示例
const displays = utools.getAllDisplays()
console.log(displays)
# getDisplayNearestPoint(point)
point
Object返回
Object
获取位置所在的显示器
# 示例
const display = utools.getDisplayNearestPoint({x: 100, y: 100 })
console.log(display)
# getDisplayMatching(rect)
rect
Object返回
Object
获取矩形所在的显示器
# 示例
const display = utools.getDisplayMatching({x: 100, y: 100, width: 200, height: 200 })
console.log(display)
# 复制
# copyFile(file)
file
String | Array返回
Boolean
复制文件到系统剪贴板
# 示例
// 复制单个文件
utools.copyFile('/path/to/file')
// 复制多个文件
utools.copyFile(['/path/to/file1', '/path/to/file2'])
# copyImage(img)
img
String | Buffer返回
Boolean
复制图片到系统剪贴板
# 示例
// 路径
utools.copyImage('/path/to/img.png')
// base64
utools.copyImage('data:image/png;base64,xxxxxxxxx')
# copyText(text)
text
String返回
Boolean
复制文本
# 示例
utools.copyText('Hi, uTools')
# 系统
# showNotification(body, clickFeatureCode)
body
StringclickFeatureCode
String (可选)plugin.json 配置的 feature.code, 点击通知进入插件功能(该 feature.cmds 至少包含一个搜索字符串关键字)
显示系统通知
# 示例
utools.showNotification('Hi, uTools')
# shellOpenPath(fullPath)
fullPath
String
系统默认方式打开给定的文件
# 示例
utools.shellOpenPath('/path/to/file')
# shellShowItemInFolder(fullPath)
fullPath
String
系统文件管理器中显示给定的文件
# 示例
utools.shellShowItemInFolder('/path/to/file')
# shellOpenExternal(url)
url
String
系统默认的协议打开URL
# 示例
// 浏览器打开
utools.shellOpenExternal('https://u.tools')
# shellBeep()
播放哔哔声
# 示例
utools.shellBeep()
# getLocalId()
返回
String
获取本地ID
# 示例
console.log(utools.getLocalId())
# getAppVersion()
返回
String
获取软件版本
# 示例
console.log(utools.getAppVersion())
# 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'))
# getFileIcon(filePath)
filePath
String文件路径、文件扩展名、"folder"
返回
String
获取文件图标
# 示例
// 获取扩展名为 "txt" 的文件图标
utools.getFileIcon('.txt')
// 获取文件夹图标
utools.getFileIcon('folder')
// 获取文件图标
utools.getFileIcon('D:\\test.url')
# getCurrentFolderPath()
返回
String
获取当前文件管理器路径(linux 不支持),呼出uTools前的活动窗口为资源管理器才能获取
# 示例
console.log(utools.getCurrentFolderPath())
# getCurrentBrowserUrl()
返回
String
获取当前浏览器URL(linux 不支持), 呼出uTools前的活动窗口为浏览器才能获取
MacOs 支持浏览器 Safari、Chrome、Microsoft Edge、Opera、Vivaldi、Brave
Windows 支持浏览器 Chrome、Firefox、Edge、IE、Opera、Brave
# 示例
console.log(utools.getCurrentBrowserUrl())
# isMacOs()
是否 MacOs 操作系统
# 示例
if (utools.isMacOs()) {
console.log('mac')
}
# isWindows()
是否 Windows 操作系统
# 示例
if (utools.isWindows()) {
console.log('windows')
}
# isLinux()
是否 Linux 操作系统
# 示例
if (utools.isLinux()) {
console.log('linux')
}
# 本地数据库
传统的B/S结构的程序中,除了前端的开发之外,可能还需要有一台服务器、一门后端语言和一个数据库来处理和存储用户数据,这会带来很大的维护成本和可用性的问题。
uTools的很多插件就像是一个微型的应用程序,总是会碰到一些数据需要持久化存储的场景,为了解决这个问题,我们整合并提供了一个nosql数据库系统,它可以很方便的使用,如果开启同步的话可在多个设备之间实现秒级同步。
# utools.db.put(doc)
doc
Object返回
Object
执行该方法将会创建或更新数据库文档
// 创建请求
utools.db.put({
_id: "demo",
data: "demo"
})
// 返回 {id: "demo", ok: true, rev: "1-05c9b92e6f24287dc1f4ec79d9a34fa8"}
// 更新请求
utools.db.put({
_id: "demo",
data: "demo",
_rev: "1-05c9b92e6f24287dc1f4ec79d9a34fa8"
})
_id
代表这个文档在数据库中唯一值,如果值不存在,则会创建一个新的文档,如果值已经存在,则会进行更新。你可能已经注意到,返回对象中包含一个rev
属性,这是代表此文档的版本,每次对文档进行更新时,都要带上最新的版本号,否则更新将失败,版本化的意义在于解决同步时数据冲突。
另外需要注意,每次更新时都要传入完整的文档数据,无法对单个字段进行更新。
注意
在 uTools 的生命周期里,数据库在onPluginReady
钩子函数执行完成后才被初始化完成,即onPluginReady
函数执行前无法执行所有和数据库相关的操作,如果在onPluginReady
执行完成前调用了数据库相关的 API,代码将会抛出一个异常
Uncaught Error: called after onPluginReady event
at Object.get (/Applications/uTools.app/Contents/Resources/app.asar/dist/apisdk.js:273)
at window.get (/Users/lanyuanxiaoyao/Project/squirrel-old/utools-server/dist/preload.js:160)
at Xi.fetch (app.82c75e58.js:8)
at lo.Ze (app.82c75e58.js:8)
at new lo (app.82c75e58.js:8)
at app.82c75e58.js:8
at Object.<anonymous> (app.82c75e58.js:8)
at n (app.82c75e58.js:1)
at Object.<anonymous> (app.82c75e58.js:8)
at n (app.82c75e58.js:1)
建议将数据库初始化的操作放在onPluginReady
函数内。
# utools.db.get(id)
id
String返回
Object
执行该方法将会根据文档ID获取数据
utools.db.get("demo")
// 返回 {_id: "demo", _rev: "3-9836c5c68af5aef618e17d615882942a", data: "demo"}
# utools.db.remove(doc)
doc
String | Object返回
Object
执行该方法将会删除数据库文档,可以传入文档对象或文档id进行操作。
utools.db.remove("demo")
// 返回 {id: "demo", ok: true, rev: "2-effe5dbc23dffc180d8411b23f3108fb"}
# utools.db.bulkDocs(docs)
docs
Array返回
Array
执行该方法将会批量更新数据库文档,传入需要更改的文档对象合并成数组进行批量更新。
utools.db.bulkDocs([{
_id: "demo1",
data: "demo",
_rev: "1-c8817a74e292eda4cba1a45924853af6"
}, {
_id: "demo2",
data: "demo",
_rev: "1-f0399b42cc6123a9cc8503632ba7b3a7"
}])
/* 返回
[{
id: "demo1", ok: true, rev: "2-7857b2801bc0303d2cc0bb82e8afd796"
}, {
id: "demo2", ok: true, rev: "2-7857b2801bc0303d2cc0bb82e8afd796"
}]
*/
# utools.db.allDocs(key)
key
String | Array返回
Array
执行该方法将会获取所有数据库文档,如果传入字符串,则会返回以字符串开头的文档,也可以传入指定ID的数组,不传入则为获取所有文档。
// 获取所有文档
utools.db.allDocs()
// 传入字符串,则返回id以 demo 开头的文档
utools.db.allDocs("demo")
/* 返回
[{
_id: "demo/123", _rev: "2-7857b2801bc0303d2cc0bb82e8afd796", data: "demo"
}, {
_id: "demo/124", _rev: "1-f0399b42cc6123a9cc8503632ba7b3a7", data: "demo"
}, {
_id: "demo/125", _rev: "1-f0399b42cc6123a9cc8503632ba7b3a7", data: "demo"
}]
*/
// 根据id数组请求
utools.db.allDocs([
"demo1",
"demo2"
])
/* 返回
[{
_id: "demo1", _rev: "2-7857b2801bc0303d2cc0bb82e8afd796", data: "demo"
}, {
_id: "demo2", _rev: "1-f0399b42cc6123a9cc8503632ba7b3a7", data: "demo"
}]
*/
# utools.db.putAttachment(docId, attachmentId, rev, attachment, type)
docId
String文档 ID
attachmentId
String附件 ID
rev
String文档版本
attachment
Buffer | Uint8Array附件,最大 20M
type
String附件类型,比如:image/png, text/plain
返回
Object
存储附件到文档
const testTxtBuffer = require('fs').readFileSync('/path/to/test.txt')
// 存储附件到新文档
utools.db.putAttachment('demo', 'test.txt', null, testTxtBuffer, 'text/plain')
// 返回 {id: "demo", ok: true, rev: "1-44055137915c41c080fc920a8470e14b"}
// 存储附件到已存在的文档
utools.db.putAttachment('demo', 'test.txt', '1-44055137915c41c080fc920a8470e14b', testTxtBuffer, 'text/plain')
// 返回 {id: "demo", ok: true, rev: "2-abdbbc4227884d2fa90e12666f5bdfd0"}
# utools.db.getAttachment(docId, attachmentId)
docId
String文档 ID
attachmentId
String附件 ID
返回
Unit8Array
获取附件
const data = utools.db.getAttachment('demo', 'text.txt')
if (data) {
const buffer = Buffer.from(data)
}
# utools.db.removeAttachment(docId, attachmentId, rev)
docId
String文档 ID
attachmentId
String附件 ID
rev
String文档版本号
返回
Object
删除附件
const result = utools.db.removeAttachment('demo', 'text.txt', '1-20c9b99681a2454a9fa9566a255823cb')
console.log(result)
# ubrowser
可编程浏览器
# getIdleUBrowsers()
返回
Array
获取闲置的 ubrowser
# 示例
console.log(utools.getIdleUBrowsers())
// [{ id: number, title: string, url: string }]
# setUBrowserProxy(config)
config
Object返回
Boolean
设置 ubrowser 代理
# 示例
utools.setUBrowserProxy({
proxyRules: 'http=foopy:80;ftp=foopy2'
})
# clearUBrowserCache()
返回
Boolean
清空 ubrowser 缓存
# 示例
utools.clearUBrowserCache()