uTools API
在插件应用初始化完成时,uTools 会自动在你的 window 对象上挂载 utools 对象。
事件
你可以根据需要,事先定义好一些回调函数,uTools 会在事件产生时主动调用它们。
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 对应匹配的数据
进入插件应用时,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 值为进入插件应用时的主输入框文本
*/
onPluginOut(callback)
callback
FunctionprocessExit
Boolean是否完全退出插件应用
插件应用退出时,uTools 将会主动调用这个方法。
示例
utools.onPluginOut((processExit) => {
if (processExit) {
console.log('插件应用完全退出')
} else {
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 options 一致
返回
Array | undefined返回选择的文件数组,用户取消返回 undefined
弹出文件选择框
示例
utools.showOpenDialog({
filters: [{ 'name': 'plugin.json', extensions: ['json'] }],
properties: ['openFile']
})
showSaveDialog(options)
options
Object与 Electron API dialog.showSaveDialogSync options 一致
返回
String | undefined返回选择的路径,用户取消返回 undefined
弹出文件保存框
示例
utools.showSaveDialog({
title: '保存位置',
defaultPath: utools.getPath('downloads'),
buttonLabel: '保存'
})
findInPage(text, options)
text
String要搜索的内容(必填)
options
Object (可选)与 Electron API contentsfindinpagetext-options options 一致
插件应用页面中查找内容
示例
utools.findInPage('utools')
stopFindInPage(action)
action
String"clearSelection" | "keepSelection" | "activateSelection", 默认 "clearSelection"
停止插件应用页面中查找
示例
utools.stopFindInPage()
startDrag(file)
file
String | Array文件路径 或 文件路径集合
原生拖拽文件到其他窗口
示例
utools.startDrag('/path/to/file')
createBrowserWindow(url, options, callback)
url
String相对路径的 html 文件
options
Object与 Electron API new BrowserWindow 参数一样,注意:preload 需配置相对位置
callback
Function (可选)url
加载完成时回调返回
Object返回 uTools API 构建的 BrowserWindow 对象。 保留了大部分实例方法
创建浏览器窗口
示例
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)
// 在新建窗口 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(codes)
codes
Array (可选)为空,获取所有
返回
Array
获取插件应用动态创建的功能。
// 获取所有动态功能
const features = utools.getFeatures()
console.log(features)
// 获取特定 code
const features = utools.getFeatures(['code-1', 'code-2'])
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())
fetchUserServerTemporaryToken()
返回
PromisePromise<{ token: string, expired_at: number }>
获取用户服务端临时令牌,用于获取用户基础信息接口
utools.fetchUserServerTemporaryToken().then((ret) => {
console.log(ret)
})
支付
openPayment(options, callback)
options
goodsId
String商品 ID,在 “ uTools 开发者工具” 插件应用中创建
outOrderId
String (可选)第三方服务生成的订单号(6 - 64 字符)
attach
String (可选)第三方服务附加数据,在查询API和支付通知中原样返回,可作为自定义参数使用(最多 256 字符)
callback
支付成功后回调
打开支付
utools.openPayment({ goodsId: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' }, () => {
// 用户完成支付,继续业务代码
})
fetchUserPayments()
返回
PromisePromise<{ 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" // 订单生成时间
}
*/
})
工具
屏幕取色 & 屏幕截图
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 })
})
hideMainWindowTypeString(text)
text
String任意文本包括 Emoji 符号字符
隐藏主窗口键盘输入字符串(输入法原理),插件应用应用未分离下才能正常执行
示例
// 输入一句文本
utools.hideMainWindowTypeString('uTools 新一代效率工具平台 - 🐼👏🦄👨👩👧👦🚵🏻')
模拟
模拟敲击键盘 和 鼠标点击
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()
返回
ArrayDisplay对象 集合
获取所有显示器
示例
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)
desktopCaptureSources(options)
options
Object返回
Promise
示例
(async () => {
const ousrces = await utools.desktopCaptureSources({ types: ['window', 'screen'] })
const stream = await navigator.mediaDevices.getUserMedia({
audio: false,
video: {
mandatory: {
chromeMediaSource: 'desktop',
chromeMediaSourceId: ousrces[0].id,
minWidth: 1280,
maxWidth: 1280,
minHeight: 720,
maxHeight: 720
}
}
})
const video = document.querySelector('video')
video.srcObject = stream
video.onloadedmetadata = (e) => video.play()
})()
复制
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')
getCopyedFiles()
返回
Array
获取复制的文件或文件夹
示例
utools.getCopyedFiles()
// 返回 [{ isFile: true, isDirectory: false, name: 'test.png', path: '/path/to/test.png' }]
系统
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()
getNativeId()
返回
String
获取本地 ID
示例
// 存储只与当前设备相关的信息
const nativeId = utools.getNativeId()
utools.dbStorage.setItem(nativeId + '/key', 'native value')
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')
readCurrentFolderPath()
返回
Promise
读取当前文件管理器窗口路径 (linux 不支持)
示例
utools.readCurrentFolderPath().then((dir) => {
console.log(dir)
})
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)
})
isDev()
判断插件应用是否在开发环境
示例
if (utools.isDev()) {
console.log('coding')
}
isMacOS()
是否 MacOS 操作系统
示例
if (utools.isMacOS()) {
console.log('mac')
}
isWindows()
是否 Windows 操作系统
示例
if (utools.isWindows()) {
console.log('windows')
}
isLinux()
是否 Linux 操作系统
示例
if (utools.isLinux()) {
console.log('linux')
}