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 对应匹配的数据
option
undefined | Objectfeature.mainPush 设置为 ture ,且当用户选择 onMainPush 返回的选项进入时
进入插件应用时,uTools 将会主动调用这个方法。
示例
utools.onPluginEnter(({ code, type, payload, option }) => {
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 值为进入插件应用时的主输入框文本
*/
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
onMainPush(callback, selectCallback)
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 对应匹配的数据
返回
Array返回内容,协议如下 [{ icon: '图标.png', text: '文本内容', title: '鼠标移动到选项时显示的提示' }, ...]
selectCallback
FunctionObject
code
Stringplugin.json 配置的 feature.code
type
Stringplugin.json 配置的 feature.cmd.type,可以为 "text"、"img"、 "files"、 "regex"、 "over"、"window"
payload
String | Object | Arrayfeature.cmd.type 对应匹配的数据
option
Objectcallback 中返回的列表其中选项
返回
undefined | Boolean返回 true 表示进入插件应用
向搜索面板推送消息(需要 feature.mainPush 设置为 true)
示例
function callback({ code, type, payload }) {
return [
{
icon: "icon.png",
text: "选项1",
title: "help text",
},
{
text: "选项2",
anyField: "xxxx",
},
];
}
function selectCallback({ code, type, payload, option }) {
if (option.xxx) {
// 返回 true 表示需要进入插件应用处理
return true;
}
// 不进入插件应用 "执行粘贴文本"
utools.hideMainWindowPasteText(option.text);
}
utools.onMainPush(callback, selectCallback);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
onPluginOut(callback)
callback
FunctionprocessExit
Boolean是否完全退出插件应用
插件应用退出时,uTools 将会主动调用这个方法。
示例
utools.onPluginOut((processExit) => {
if (processExit) {
console.log("插件应用完全退出");
} else {
console.log("插件应用隐藏后台");
}
});
2
3
4
5
6
7
onPluginDetach(callback)
callback
Function
用户对插件应用进行分离操作时,uTools 将会主动调用这个方法。
示例
utools.onPluginDetach(() => {
console.log("插件应用已作为系统窗口使用");
});
2
3
onDbPull(callback)
callback
Function
当此插件应用的数据在其他设备上被更改后同步到此设备时,uTools 将会主动调用这个方法
示例
utools.onDbPull(() => {
console.log("onDbPull");
});
2
3
窗口交互
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);
}, "搜索");
2
3
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
Array | StringArray[0]: 插件应用名称,Array[1]: 功能关键字 | 功能关键字
payload
String | Object返回
Boolean
该方法可以携带数据,跳转到另一个插件应用进行处理,如果用户未安装对应的插件应用将引导进入插件应用市场下载。
示例
// 跳转到插件应用「聚合翻译」并翻译内容
utools.redirect(["聚合翻译", "翻译"], "hello world");
// 找到 “翻译” 关键字,并自动跳转到对应插件应用
utools.redirect("翻译", "hello world");
// 跳转到插件应用「OCR 文字识别」并识别图片中文字
utools.redirect(["OCR 文字识别", "OCR 文字识别"], {
type: "img",
data: "data:image/png;base64,", // base64
});
// 跳转到插件应用「JSON 编辑器」查看 Json 文件
utools.redirect(["JSON 编辑器", "Json"], {
type: "files",
data: "/path/test.json", // 支持数组
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
showOpenDialog(options)
options
Object与 Electron API dialog.showOpenDialogSyncopen in new window options 一致
返回
Array | undefined返回选择的文件数组,用户取消返回 undefined
弹出文件选择框
示例
utools.showOpenDialog({
filters: [{ name: "plugin.json", extensions: ["json"] }],
properties: ["openFile"],
});
2
3
4
showSaveDialog(options)
options
Object与 Electron API dialog.showSaveDialogSyncopen in new window options 一致
返回
String | undefined返回选择的路径,用户取消返回 undefined
弹出文件保存框
示例
utools.showSaveDialog({
title: "保存位置",
defaultPath: utools.getPath("downloads"),
buttonLabel: "保存",
});
2
3
4
5
findInPage(text, options)
text
String要搜索的内容(必填)
options
Object (可选)与 Electron API contentsfindinpagetext-optionsopen in new window options 一致
插件应用页面中查找内容
示例
utools.findInPage("utools");
stopFindInPage(action)
action
String"clearSelection" | "keepSelection" | "activateSelection", 默认 "clearSelection"
与 Electron API contentsstopfindinpageactionopen in new window 一致
停止插件应用页面中查找
示例
utools.stopFindInPage();
startDrag(file)
file
String | Array文件路径 或 文件路径集合
原生拖拽文件到其他窗口
示例
utools.startDrag("/path/to/file");
createBrowserWindow(url, options, callback)
url
String相对路径的 html 文件
options
Object与 Electron API new BrowserWindowopen in new window 参数一样,注意:preload 需配置相对位置
callback
Function (可选)url
加载完成时回调返回
Object返回 uTools API 构建的 BrowserWindowopen in new window 对象。 保留了大部分实例方法
创建浏览器窗口
示例
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);
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
// 在新建窗口 JavaScript 中接收父窗口传递过来的数据
const { ipcRenderer } = require("electron");
ipcRenderer.on("ping", (event, data) => {
console.log(event);
console.log(data);
});
2
3
4
5
6
isDarkColors()
是否深色模式
示例
utools.onPluginEnter(({ code, type, payload }) => {
document.body.className = utools.isDarkColors() ? "dark-mode" : "";
});
2
3
动态增减功能
很多时候,插件应用中会提供一些功能供用户进行个性化设置(例如:网页快开 插件应用),这部分配置无法在 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);
2
3
4
5
6
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"],
});
2
3
4
5
6
7
8
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);
});
2
3
付费
isPurchasedUser()
返回
ObjectBoolean | String
是否付费用户,返回
true
表示永久授权,返回"yyyy-mm-dd hh:mm:ss"
表示授权到期时间
if (utools.isPurchasedUser()) {
// 已付费的合法用户,可使用插件应用完整功能
}
2
3
openPurchase(options, callback)
options
goodsId
String商品 ID,在 “ uTools 开发者工具” 插件应用中创建
outOrderId
String (可选)第三方服务生成的订单号(6 - 64 字符)
attach
String (可选)第三方服务附加数据,在查询 API 和支付通知中原样返回,可作为自定义参数使用(最多 256 字符)
callback
购买成功后回调
打开付费 (软件付费模式)
utools.openPurchase({ goodsId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }, () => {
// 购买完成,解锁全部功能
});
2
3
openPayment(options, callback)
options
goodsId
String商品 ID,在 “uTools 开发者工具” 插件应用中创建
outOrderId
String (可选)第三方服务生成的订单号(6 - 64 字符)
attach
String (可选)第三方服务附加数据,在查询 API 和支付通知中原样返回,可作为自定义参数使用(最多 256 字符)
callback
支付成功后回调
打开支付(服务付费模式)
utools.openPayment({ goodsId: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }, () => {
// 用户完成支付
});
2
3
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" // 订单生成时间
}
*/
});
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
输入
hideMainWindowPasteFile(file)
file
String | Array文件路径或文件路径集合
返回
Boolean
粘贴文件
示例
utools.hideMainWindowPasteFile("/path/to/file");
hideMainWindowPasteImage(img)
img
String | Uint8Array图片路径 或 base64 或 Uint8Array
返回
Boolean
粘贴图像
示例
// 路径
utools.hideMainWindowPasteImage("/path/to/img.png");
// base64
utools.hideMainWindowPasteImage("data:image/png;base64,xxxxxxxxx");
2
3
4
hideMainWindowPasteText(text)
text
String字符串文本
返回
Boolean
粘贴文本
示例
utools.hideMainWindowPasteText("Hi, uTools");
hideMainWindowTypeString(text)
text
String任意文本包括 Emoji 符号字符
返回
Boolean
输入字符串(输入法原理)
示例
// 输入一句文本
utools.hideMainWindowTypeString("uTools 新一代效率工具平台 - 🐼👏🦄👨👩👧👦🚵🏻");
2
工具
屏幕取色 & 屏幕截图
screenColorPick(callback)
callback
Function取色结束回调
Object
hex
Stringrgb
String
屏幕取色
示例
utools.screenColorPick(({ hex, rgb }) => {
console.log(hex); // #FFFFFF
console.log(rgb); // RGB(0, 0, 0)
});
2
3
4
screenCapture(callback)
callback
Function截图结束回调
String
图片的 Base64 字符串
屏幕截图
示例
utools.screenCapture((base64Str) => {
utools.redirect("识别图片中文字", { type: "img", data: base64Str });
});
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");
2
3
4
5
6
7
8
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);
2
getPrimaryDisplay()
返回
Object
获取主显示器
示例
const display = utools.getPrimaryDisplay();
console.log(display);
2
getAllDisplays()
返回
Array
获取所有显示器
示例
const displays = utools.getAllDisplays();
console.log(displays);
2
getDisplayNearestPoint(point)
point
Object返回
Object
获取位置所在的显示器
示例
const display = utools.getDisplayNearestPoint({ x: 100, y: 100 });
console.log(display);
2
getDisplayMatching(rect)
rect
Object返回
Object
获取矩形所在的显示器
示例
const display = utools.getDisplayMatching({
x: 100,
y: 100,
width: 200,
height: 200,
});
console.log(display);
2
3
4
5
6
7
desktopCaptureSources(options)
options
Object返回
Promise
录屏源 参考 Electron API desktopCapturer getSourcesopen in new window
示例
(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();
})();
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
复制
copyFile(file)
file
String | Array返回
Boolean
复制文件到系统剪贴板
示例
// 复制单个文件
utools.copyFile("/path/to/file");
// 复制多个文件
utools.copyFile(["/path/to/file1", "/path/to/file2"]);
2
3
4
copyImage(img)
img
String | Buffer返回
Boolean
复制图片到系统剪贴板
示例
// 路径
utools.copyImage("/path/to/img.png");
// base64
utools.copyImage("data:image/png;base64,xxxxxxxxx");
2
3
4
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' }]
2
系统
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");
2
shellBeep()
播放哔哔声
示例
utools.shellBeep();
getNativeId()
返回
String
获取本地 ID
示例
// 存储只与当前设备相关的信息
const nativeId = utools.getNativeId();
utools.dbStorage.setItem(nativeId + "/key", "native value");
2
3
getAppName()
返回
String
获取软件名称
示例
console.log(utools.getAppName());
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"));
2
getFileIcon(filePath)
filePath
String文件路径、文件扩展名、"folder"
返回
String
获取文件图标
示例
// 获取扩展名为 "txt" 的文件图标
utools.getFileIcon(".txt");
// 获取文件夹图标
utools.getFileIcon("folder");
// 获取文件图标
utools.getFileIcon("D:\\test.url");
2
3
4
5
6
readCurrentFolderPath()
返回
Promise
读取当前文件管理器窗口路径 (linux 不支持)
示例
utools.readCurrentFolderPath().then((dir) => {
console.log(dir);
});
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);
});
2
3
isDev()
判断插件应用是否在开发环境
示例
if (utools.isDev()) {
console.log("coding");
}
2
3
isMacOS()
是否 MacOS 操作系统
示例
if (utools.isMacOS()) {
console.log("mac");
}
2
3
isWindows()
是否 Windows 操作系统
示例
if (utools.isWindows()) {
console.log("windows");
}
2
3
isLinux()
是否 Linux 操作系统
示例
if (utools.isLinux()) {
console.log("linux");
}
2
3