ZTools 为插件提供了一套丰富的 API，通过全局对象 window.ztools 暴露。
获取应用名称。
- 返回:
string- 应用名称，固定返回'ZTools'。
获取拖放文件的真实路径。用于处理用户拖放文件到插件界面的场景（基于 Electron webUtils.getPathForFile）。
- file:
File- 拖放事件中的 File 对象。 - 返回:
string- 文件的本地路径。
检测当前是否为 macOS 系统。
- 返回:
boolean- 是否为 macOS。
检测当前是否为 Windows 系统。
- 返回:
boolean- 是否为 Windows。
检测当前是否为 Linux 系统。
- 返回:
boolean- 是否为 Linux。
获取设备唯一标识符（32位字符串）。
- 返回:
string- 设备唯一标识符。
获取应用版本号。
- 返回:
string- 应用版本号。
获取当前窗口类型。
- 返回:
string- 窗口类型。
检测当前是否为深色主题。
- 返回:
boolean- 是否为深色主题。
获取当前登录用户的公开资料。未登录时返回 null。
- 返回:
object | null- 用户资料，通常包含avatar、nickname、uid。
获取当前插件访问 ZTools 服务端的短期鉴权令牌。
- 返回:
Promise<object>-{ token: string, expiredAt: number }，expiredAt为毫秒级时间戳。
获取当前主题信息。
- 返回:
object- 包含isDark、primaryColor、customColor、windowMaterial等字段。
监听主题变化。再次注册会替换之前的回调。
- callback:
(themeInfo: object) => void- 主题变化时调用，参数结构与getThemeInfo()返回值一致。
检查当前插件是否处于开发模式。
- 返回:
boolean- 是否处于开发模式。
获取当前 WebContents ID。
- 返回:
number- WebContents ID。
设置插件视图的高度。
- height:
number- 期望的高度（像素）。
显示系统通知。
- body:
string- 通知内容。
在 ZTools 界面中显示 Toast 提示。
- message:
string- 提示内容。 - options:
object- (可选) Toast 配置，会与message合并后传给宿主。 - 返回:
Promise<object>- 宿主返回的 Toast 操作结果。
发送模拟输入事件。
- event:
MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent- 输入事件对象。
KeyboardInputEvent (键盘事件)
type:'keyDown'|'keyUp'|'char'keyCode:string- 键盘代码modifiers:string[]- 修饰键数组 (例如['shift', 'control'])
MouseInputEvent (鼠标事件)
type:'mouseDown'|'mouseUp'|'mouseEnter'|'mouseLeave'|'contextMenu'|'mouseMove'x:number- X 坐标y:number- Y 坐标button:'left'|'middle'|'right'- 按钮类型clickCount:number- 点击次数
MouseWheelInputEvent (滚轮事件)
type:'mouseWheel'deltaX:numberdeltaY:numberwheelTicksX:numberwheelTicksY:numberaccelerationRatioX:numberaccelerationRatioY:numberhasPreciseScrollingDeltas:booleancanScroll:boolean
模拟键盘按键。
- key:
string- 要按下的键。 - modifiers:
string[]- 修饰键数组（可选）。 - 返回:
boolean- 是否成功。
在当前插件页面中查找文本。
- text:
string- 要查找的文本。 - options:
object- (可选) 查找选项，可包含forward、findNext、matchCase、wordStart、medialCapitalAsWordStart。 - 返回:
Promise<{ success: boolean, requestId?: number, error?: string }>- 查找请求结果。
停止页面查找。
- action:
'clearSelection' | 'keepSelection' | 'activateSelection'- (可选) 停止行为，默认'clearSelection'。 - 返回:
Promise<{ success: boolean, error?: string }>- 停止查找结果。
监听或取消监听页面查找结果。
- callback:
(result: object) => void- 查找结果回调。结果对象来自 Electronfound-in-page事件，包含requestId、activeMatchOrdinal、matches、selectionArea、finalUpdate等字段。
模拟鼠标移动到屏幕坐标。
- x:
number- 屏幕 X 坐标。 - y:
number- 屏幕 Y 坐标。 - 返回:
boolean- 是否成功。
ztools.simulateMouseClick(x, y) / ztools.simulateMouseDoubleClick(x, y) / ztools.simulateMouseRightClick(x, y)
分别模拟鼠标左键单击、左键双击和右键单击。
- x:
number- 屏幕 X 坐标。 - y:
number- 屏幕 Y 坐标。 - 返回:
boolean- 是否成功。
显示主窗口。
- 返回:
Promise<boolean>- 是否成功。
隐藏主窗口，包括此时正在主窗口运行的插件应用。
- isRestorePreWindow:
boolean- (可选) 是否焦点回归到前面的活动窗口，默认true。 - 返回:
Promise<boolean>- 是否成功。
退出插件应用，默认将插件应用隐藏后台。
- isKill:
boolean- (可选) 为true时，将结束运行插件应用 (杀死进程)。 - 返回:
Promise<boolean>- 是否成功。
监听插件进入事件。当用户打开插件时触发。
- callback:
(param: LaunchParam) => void- 回调函数，接收启动参数。
payload:any- 传递的数据（例如搜索框内容）type:'text' | 'regex' | 'over'- 命令类型'text': 文本匹配'regex': 正则表达式匹配'over': 任意文本匹配
code:string- 插件 Feature Code (如果是由 Feature 触发)
监听插件退出事件。
- callback:
(isKill: boolean) => void- 回调函数，接收退出参数。isKill: 是否为强制退出（杀死进程）。
监听插件被分离为独立窗口的事件。当用户将插件从主窗口分离时触发。
- callback:
() => void- 回调函数。
注册主搜索推送功能。插件可以在主搜索框中提供搜索结果，用户无需进入插件即可看到结果。
- callback:
(queryData: any) => object[]- 查询回调函数，接收搜索数据，返回搜索结果数组。 - selectCallback:
(selectData: any) => boolean- (可选) 用户选择搜索结果时的回调函数。返回true表示需要进入插件。
兼容旧 API，功能与 onPluginEnter 相同。
- callback:
(param: LaunchParam) => void- 回调函数，接收启动参数。
设置主窗口搜索框的行为（当插件处于活动状态时）。
- onChange:
(details: { text: string }) => void- 当用户在搜索框输入时触发的回调函数。 - placeholder:
string- 搜索框的占位符文本。 - isFocus:
boolean- (可选) 是否自动聚焦搜索框，默认true。
设置子输入框的值。
- text:
string- 要设置的值。
聚焦子输入框。
- 返回:
boolean- 是否成功。
子输入框失去焦点，插件应用获得焦点。
- 返回:
boolean- 是否成功。
子输入框获得焦点并选中全部内容。
- 返回:
boolean- 是否成功。
移除（隐藏）子输入框。
- 返回:
Promise<boolean>- 是否成功。
插件拥有独立的数据库存储空间（Bucket），以插件名称隔离。
保存数据。
- doc:
object- 文档对象（必须包含_id字段）。 - 返回:
object- 保存后的文档对象（包含_id和_rev）。
获取数据。
- id:
string- 文档 ID。 - 返回:
object | null- 文档对象，不存在则返回null。
删除数据。
- docOrId:
object | string- 要删除的文档对象（通常包含_id和_rev）或文档 ID。 - 返回:
object- 删除结果。
批量操作文档。
- docs:
object[]- 文档数组。 - 返回:
object[]- 操作结果数组。
获取所有文档或按 key 前缀查询。
- key:
string- (可选) 文档 ID 前缀，用于过滤。 - 返回:
object[]- 文档数组。
为文档添加附件。
- id:
string- 文档 ID。 - attachment:
string | Buffer- 附件内容（base64 字符串或 Buffer）。 - type:
string- 附件 MIME 类型。 - 返回:
object- 操作结果。
获取文档附件。
- id:
string- 文档 ID。 - 返回:
Buffer- 附件内容。
获取文档附件的 MIME 类型。
- id:
string- 文档 ID。 - 返回:
string- MIME 类型。
数据库 API 还提供了 Promise 版本，位于 window.ztools.db.promises 下，所有方法签名与同步版本相同，但返回 Promise。
window.ztools.db.promises.put(doc)window.ztools.db.promises.get(id)window.ztools.db.promises.remove(docOrId)window.ztools.db.promises.bulkDocs(docs)window.ztools.db.promises.allDocs(key)window.ztools.db.promises.postAttachment(id, attachment, type)window.ztools.db.promises.getAttachment(id)window.ztools.db.promises.getAttachmentType(id)
类似 localStorage 的简化接口，用于简单的键值对存储。
保存数据。
- key:
string- 键名。 - value:
any- 要保存的数据（会自动序列化为 JSON）。
获取数据。
- key:
string- 键名。 - 返回:
any- 数据内容，不存在则返回null。
删除数据。
- key:
string- 键名。
获取动态添加的 features。
- codes:
string[]- (可选) 指定要获取的 feature codes，不传则返回所有。 - 返回:
object[]- Feature 数组。
设置动态 feature（如果已存在则更新）。
- feature:
object- Feature 对象。 - 返回:
boolean- 是否成功。
删除指定的动态 feature。
- code:
string- Feature code。 - 返回:
boolean- 是否成功。
获取剪贴板历史记录。
- page:
number- 页码，从 1 开始。 - pageSize:
number- 每页数量。 - filter:
string- (可选) 过滤条件。 - 返回:
Promise<object>- 历史记录数据。
搜索剪贴板历史。
- keyword:
string- 搜索关键词。 - 返回:
Promise<object[]>- 匹配的记录数组。
删除剪贴板记录。
- id:
string- 记录 ID。 - 返回:
Promise<{ success: boolean }>- 是否成功。
清空剪贴板历史。
- type:
string- (可选) 类型过滤。 - 返回:
Promise<{ success: boolean, count: number }>- 是否成功及清除数量。
获取剪贴板状态。
- 返回:
Promise<object>- 状态信息。
将指定记录写入剪贴板。
- id:
string- 记录 ID。 - shouldPaste:
boolean- (可选) 是否同时模拟粘贴操作，默认true。 - 返回:
Promise<{ success: boolean }>- 是否成功。
写入内容到剪贴板。
- data:
object- 数据对象。type:'text' | 'image' | 'file'- 内容类型。content:string | string[]- 文本、图片内容，或单个文件路径/文件路径数组。text和image类型要求为字符串。
- shouldPaste:
boolean- (可选) 是否同时模拟粘贴操作，默认true。 - 返回:
Promise<{ success: boolean }>- 是否成功。
更新剪贴板配置。
- config:
object- 配置对象。 - 返回:
Promise<{ success: boolean }>- 是否成功。
监听剪贴板变化事件。
- callback:
(item: object) => void- 回调函数，接收剪贴板变化项。
复制文本到剪贴板。
- text:
string- 要复制的文本。 - 返回:
boolean- 是否成功。
复制图片到剪贴板。
- image:
string | Buffer | Uint8Array- 图片 base64 Data URL、文件路径或图片二进制数据。 - 返回:
boolean- 是否成功。
复制文件到剪贴板。
- filePath:
string | string[]- 单个文件路径或文件路径数组。 - 返回:
boolean- 是否成功。
获取当前系统剪贴板中的文件或文件夹列表。方法名中的 Copyed 为兼容现有 API 的拼写。
- 返回:
object[]- 文件项数组，每项包含path、name、isFile、isDirectory。
获取系统路径。
- name:
string- 路径名称（如'home','desktop','documents'等）。 - 返回:
string- 路径。
弹出文件保存对话框。
- options:
SaveDialogOptions- 对话框配置，与 ElectronshowSaveDialogSync保持一致。 - 返回:
string | undefined- 选择的路径。用户取消则返回undefined。
弹出文件打开对话框。
- options:
OpenDialogOptions- 对话框配置，与 ElectronshowOpenDialogSync保持一致。 - 返回:
string[] | undefined- 选择的文件路径数组。用户取消则返回undefined。
屏幕截图，会进入截图模式，用户截图完执行回调函数。
- callback:
(image: string, bounds: object) => void- 截图完的回调函数。image: 截图的图像 base64 Data Url。bounds: 截图区域，包含x、y、width、height。
- 返回:
Promise<void>- 截图流程结束后完成。
进入屏幕取色模式，取色成功后调用回调。
- callback:
(color: { hex: string, rgb: string }) => void- 取色结果回调。 - 返回:
Promise<void>- 取色流程结束后完成。
开始将文件拖动到外部应用。
- filePath:
string | string[]- 要拖动的文件路径或路径数组。
隐藏主窗口，并将文本或图片粘贴到之前获得焦点的外部应用。
- text:
string- 要粘贴的文本。 - image:
string | Uint8Array- 图片 Data URL、路径或图片二进制数据。 - 返回:
boolean- 是否成功。
隐藏主窗口，并将文件粘贴到之前获得焦点的外部应用。
- filePath:
string | string[]- 文件路径或路径数组。 - 返回:
boolean- 是否成功。
隐藏主窗口，并向之前获得焦点的外部应用模拟键入字符串。
- text:
string- 要键入的文本。 - 返回:
boolean- 是否成功。
创建独立窗口。
- url:
string- 窗口加载的 URL。 - options:
object- 窗口选项，与 ElectronBrowserWindow构造函数选项保持一致。 - callback:
() => void- (可选) 窗口加载完成后的回调函数。 - 返回:
object- 返回带id、webContents和宿主白名单方法的窗口对象。主窗口方法和webContents方法分别可能是同步方法或返回 Promise 的异步方法，具体方法由当前版本宿主提供。
发送消息到父窗口。
- channel:
string- 通道名称。 - args:
any[]- 要传递的参数。
获取主显示器信息。
- 返回:
object- 显示器信息对象。
获取所有显示器。
- 返回:
object[]- 显示器信息数组。
获取鼠标光标的屏幕坐标。
- 返回:
object- 坐标对象{ x: number, y: number }。
获取最接近指定点的显示器。
- point:
object- 坐标对象{ x: number, y: number }。 - 返回:
object- 显示器信息对象。
获取桌面捕获源。
- options:
object- 捕获选项。 - 返回:
Promise<object[]>- 捕获源数组。
DIP 坐标转屏幕物理坐标。
- point:
object- DIP 坐标对象{ x: number, y: number }。 - 返回:
object- 屏幕物理坐标对象{ x: number, y: number }。
屏幕物理坐标转 DIP 坐标。
- point:
object- 屏幕物理坐标对象{ x: number, y: number }。 - 返回:
object- DIP 坐标对象{ x: number, y: number }。
DIP 区域转屏幕物理区域。
- rect:
object- DIP 区域对象{ x: number, y: number, width: number, height: number }。 - 返回:
object- 屏幕物理区域对象{ x: number, y: number, width: number, height: number }。
使用系统默认程序打开 URL。
- url:
string- 要打开的 URL。 - 返回:
object-{ success: boolean, error?: string }。
使用系统默认方式打开文件或文件夹。
- fullPath:
string- 文件或文件夹路径。 - 返回:
object-{ success: boolean, error?: string }。
在文件管理器中显示文件。
- fullPath:
string- 文件路径。 - 返回:
undefined- 请求已发送；具体打开结果由系统文件管理器处理。
播放系统提示音。
- 返回:
object-{ success: boolean, error?: string }。
将文件或文件夹移动到系统回收站。
- fullPath:
string- 文件或文件夹路径。 - 返回:
Promise<{ success: boolean }>- 是否成功；失败时可能抛出 Error。
读取当前活动文件管理器窗口的文件夹路径。macOS 支持 Finder，Windows 支持 Explorer。
- 返回:
Promise<string>- 当前文件夹路径。
读取当前活动浏览器窗口的 URL。前提是当前活动窗口属于受支持的浏览器。
- 返回:
Promise<string>- 当前 URL。
获取文件系统图标。
- filePath:
string- 文件路径。 - 返回:
string | null- 图标的 base64 Data URL；获取失败时为null。
插件跳转。
- label:
string | [string, string]- 指令名称，或[插件标题, 指令名称]。 - payload:
string- (可选) 传递给目标指令的文本。当前实现只按字符串处理非空 payload。 - 返回:
boolean- 是否成功。
跳转到快捷键设置，并定位到指定指令。
- cmdLabel:
string- 指令名称。 - 返回:
boolean- 是否成功。
跳转到 AI 模型设置页面。当前设置页已将 AI 模型入口并入 Provider 页面。
- 返回:
boolean- 是否成功。
设置 HTTP 请求头。
- headers:
object- 请求头对象。 - 返回:
boolean- 是否成功。
获取当前请求头配置。
- 返回:
object- 请求头对象。
清除请求头配置。
- 返回:
boolean- 是否成功。
注册一个供 ZTools MCP 服务调用的插件工具。工具必须先在 plugin.json.tools 中声明，详见 plugin.json 配置。
- name:
string- 工具名称，必须与plugin.json.tools中的 key 一致。 - handler:
(input: object) => any | Promise<any>- 工具处理器，接收调用输入并返回结果。 - 返回:
void- 注册成功后结束。 - 异常: 工具未声明、名称为空或 handler 不是函数时抛出 Error。
ztools.registerTool("list_files", async ({ path }) => {
return { path, entries: [] };
});Provider 支持两种角色：插件可以注册翻译/OCR Provider，也可以消费其他插件或内置 Provider。完整配置和契约见 Provider 开发指南。
注册一个翻译或 OCR Provider 的处理器。
- key:
string- 必须与plugin.json.providers中的 key 一致。 - handler:
(input: object) => Promise<object>- Provider 处理器，输入输出结构由声明的type决定。 - 返回:
void- 注册成功后结束。 - 异常: key 未声明、为空或 handler 不是函数时抛出 Error。
查询 Provider 列表。
- type:
'translation' | 'ocr'- (可选) 指定类型；省略时返回全部类型。 - 返回:
Promise<object[]>- Provider 列表，每项包含id、type、label、description、source、isDefault等字段。
查询指定类型的默认 Provider。
- type:
'translation' | 'ocr'- Provider 类型。 - 返回:
Promise<object | null>- 默认 Provider；没有可用 Provider 时返回null。
调用 Provider。省略 providerId 时使用该类型的默认 Provider。
- type:
'translation' | 'ocr'- Provider 类型。 - input:
object- Provider 输入。 - providerId:
string- (可选) 指定 Provider ID。 - 返回:
Promise<object>- Provider 输出。
调用翻译 Provider 的便捷封装。
- text:
string- 待翻译文本。 - options:
object- (可选){ from?: string, to?: string, providerId?: string }。 - 返回:
Promise<{ text: string, detectedFrom?: string }>- 翻译结果。
调用 OCR Provider 的便捷封装。
- image:
string- 图片路径、Data URI 或 URL，具体支持取决于 Provider。 - options:
object- (可选){ lang?: string, providerId?: string }。 - 返回:
Promise<{ text: string, blocks?: string[], confidence?: number }>- OCR 结果。
ztools.zbrowser 和 ztools.ubrowser 都返回一个新的 Builder 实例，方法支持链式调用。调用 run() 时才会创建或复用浏览器窗口并执行操作队列。
const result = await ztools.zbrowser
.goto("https://example.com")
.wait("h1")
.click("a")
.evaluate(() => document.title)
.run({ width: 900, height: 600 })| 方法 | 说明 |
|---|---|
goto(url, headers?, timeout?) |
打开 URL |
hide() / show() |
隐藏或显示浏览器窗口 |
useragent(userAgent) |
设置 User-Agent |
viewport(width, height) |
设置视口大小 |
css(css) |
注入 CSS |
press(key, ...modifiers) |
模拟键盘按键 |
paste(text?) |
执行粘贴，可选传入文本或图片 Base64 |
screenshot(arg?, savePath?) |
截图，可按选择器或区域截图 |
pdf(options?, savePath?) |
导出 PDF |
device(device) |
模拟设备尺寸和 User-Agent |
cookies(nameOrFilter?) |
获取 Cookie |
setCookies(name, value) / setCookies(cookies) |
设置 Cookie |
removeCookies(name) |
删除 Cookie |
clearCookies(url?) |
清空 Cookie |
devTools(mode?) |
打开开发者工具 |
evaluate(fn, ...args) |
在目标页面执行 JS，可执行异步函数 |
wait(msOrSelectorOrFn, options?, ...args) |
等待时间、元素或判断函数 |
when(selectorOrFn, ...args) / end() |
条件执行操作队列 |
mouse(eventName, selector) |
对元素分发鼠标事件 |
click(target, mouseButton?) |
点击元素或坐标 |
mousedown(target, mouseButton?) / mouseup(target, mouseButton?) |
鼠标按下或抬起 |
dblclick(target, mouseButton?) |
双击元素或坐标 |
hover(target) |
悬停元素或移动到坐标 |
drop(target, payload) |
拖放文件到元素或坐标 |
markdown(selector?) |
将页面或元素转换为 Markdown |
input(text) / input(selector, text) |
输入文本 |
file(selector, fileData) |
设置文件 input，支持路径、Base64、Uint8Array 或路径数组 |
download(urlOrFunction, savePath?, ...args) |
下载 URL 或函数返回的 URL |
value(selector, value) |
设置表单元素的值 |
check(selector, checked?) |
设置复选框状态 |
focus(selector) |
聚焦元素 |
scroll(...) |
滚动页面或滚动到元素 |
run(ubrowserIdOrOptions?, options?) |
执行队列并返回 Promise |
run() 支持以下形式：
await ztools.zbrowser.goto("https://example.com").run()
await ztools.zbrowser.goto("https://example.com").run({ show: true })
await ztools.zbrowser.goto("https://example.com").run(3, { show: true })当窗口保持显示时，后续 Builder 实例可以通过 getIdleUBrowsers() 返回的窗口 ID 复用它。
获取当前插件的空闲浏览器窗口。
- 返回:
object[]- 窗口信息数组，每项包含id、title、url。
设置当前插件浏览器 Session 的代理。ZTools 返回 Promise，与 uTools 的同步 API 不同。
- config:
object- Electron Session 代理配置，例如pacScript、proxyRules、proxyBypassRules。 - 返回:
Promise<boolean>- 是否成功。
清除当前插件浏览器 Session 的缓存。
- 返回:
Promise<boolean>- 是否成功。
兼容 uTools 的登录接口。
- 返回:
Promise<null>- ZTools 当前不支持此功能，固定返回null。
在插件进程中执行 FFmpeg 命令。FFmpeg 路径由 ZTools 管理，插件只需要传入命令行参数。
- args:
string[]- FFmpeg 命令行参数。 - options:
Function | object- (可选) 直接传入函数时视为onProgress；传入对象时可包含onProgress和onLog。 - 返回:
Promise<void> & { kill: () => void, quit: () => void }- 可等待、强制终止或优雅退出的任务。
onProgress 会收到解析后的 FFmpeg 进度对象，包含 FFmpeg 输出中的键值，可能额外包含 percent；onLog 会收到 stderr 文本。覆盖已有文件时，ZTools 会自动回答 N，拒绝覆盖。
const task = ztools.runFFmpeg(
["-i", inputPath, "-y", outputPath],
{
onProgress: (progress) => console.log(progress.percent),
onLog: (line) => console.log(line)
}
)
await task需要停止时可以调用 task.kill()，希望 FFmpeg 自己收尾时调用 task.quit()。