桌面 API

桌面 API

功能

bt_app 会向 static、server 和 remote 页面注入 window.bt。桌面 API 提供 BT 后端调用、窗口控制、系统对话框、托盘、剪贴板、屏幕吸管、框选截图、全局快捷键、通知、文件拖入、目录文件监听、应用信息，以及有界流式 HTTP、应用凭据、工作区、原生进程和应用自有数据能力。

页面只应使用 window.bt。运行器不会公开全局 window.__TAURI__，也不会把本地 fs、net、process 能力直接暴露给前端。

语法

所有异步方法返回 Promise。成功时直接返回数据；失败时 Promise 会 reject，错误值是字符串或可转为字符串的错误对象。

参数

bt.call

bt.window

set_background_color() 同时更新原生窗口和 WebView 的不透明底色，适合普通窗口切换亮暗主题。需要 HTML 圆角、PNG Alpha 或透明页面背景时，应在 app.json 创建期设置 window.transparent=true，不能用该运行期方法代替透明窗口配置。

set_position(x, y) 的 x、y 使用逻辑像素；多显示器位于主屏左侧或上方时可以传负数。placement() 返回字段：

content_area 与 work_area 都使用相同矩形字段；前者是桌面中的 WebView 内容区域，后者是当前显示器的可用工作区：

bt.dialog

options.title 为对话框标题，options.default_path 为默认路径，options.filters 为文件过滤器数组。消息框 options.kind 支持 info、warning、error。

bt.tray

菜单项格式为 {id:'show', text:'显示窗口', enabled:true}；分隔线格式为 {type:'separator'}。同一应用默认只保留一个托盘图标，重复调用 window.bt.tray.enable() 会更新图标、提示文本和菜单，不会新增多个托盘入口。

window.bt.window.set_close_mode('tray') 只设置窗口关闭按钮的行为：之后用户点击窗口关闭按钮或代码调用 window.bt.window.close() 时，窗口会隐藏到托盘，程序继续常驻运行。如果需要按钮点击后立刻关闭到托盘，应先设置 tray 模式，再调用 window.bt.window.close()。

on_close_requested() 用于必须在退出前等待异步落盘的应用。注册后，exit 模式的关闭请求会先被阻止并调用回调；回调完成保存后必须调用 close_now()。若保存失败，应用可保留窗口并提示用户，不能调用 close_now()。取消监听会恢复默认直接关闭行为。

bt.clipboard

bt.screen

pick_color(options) 的 options 字段：

capture_area(options) 的 options 字段：

ColorResult 字段：

CaptureResult 字段：

屏幕图像不经过 Base64 或 JSON 数组返回前端；原生层直接把 RGBA 写入系统图片剪贴板，因此可以在支持图片粘贴的聊天框、富文本编辑器和图像软件中粘贴。纯文本输入框或主动禁用图片粘贴的软件不能接收图片。

bt.shortcut

register() 参数：

回调负载字段：

同一应用最多注册 16 条全局快捷键。相同 shortcut_id 会原子替换原组合；相同组合不能同时绑定给两个 ID。快捷键由应用进程持有，主窗口隐藏或关闭到托盘后仍可触发；应用退出时会由操作系统释放，页面主动停用时应调用返回的注销函数或 unregister_all()。

bt.notify

options.title 为空时使用应用标题，options.body 为通知正文。

request_permission() 返回的是系统通知权限状态；show() 才是真正发送系统通知。Windows 便携 exe 会使用兼容的 toast 发送路径，不依赖安装器创建的应用通知注册。通知是否弹出桌面横幅仍由操作系统通知设置、勿扰模式和应用通知策略决定，未弹出时通常仍可在系统通知中心查看。

bt.drag

bt.app

info(path) 的 path 必须是存在的 .btr 文件绝对路径或可规范化路径。它会完成 BTR 格式、版本、资源路径和大小上限校验，只读取 btr.json、app.json 及可选图标，不执行 app.main、server.bt 或页面脚本，适合工具条安全展示软件信息。app.icon 当前只支持 ICO，因此 icon_data_url 使用 data:image/x-icon;base64,...；未配置或不存在时为 null。

BtrAppInfo 字段：

run(path, args=[]) 会在启动子进程前再次完整校验 BTR，并以参数数组直接创建进程，不经过 shell。args 最多 256 项，单项最长 32768 字节。Promise 完成仅表示操作系统已创建进程，不表示其 WebView 已完成页面加载。

BtrRunResult 字段：

每次 run() 都创建独立软件进程，使 VM、窗口、托盘、快捷键和退出生命周期彼此隔离；它解决的是多个软件重复携带 bt_app exe 的磁盘体积问题，不承诺多个正在运行的软件共用同一个 WebView 进程。像吸管、截图这类工具条内置能力可以继续留在工具条进程中，只有真正启动 BTR 软件时才创建其窗口。

documents_dir() 使用系统已知目录 API，不会硬编码 Documents 名称，可兼容本地化、OneDrive 和系统重定向。watch_path() 使用系统文件事件监听目录变化，不会按固定周期扫描目录；同一窗口最多同时保留 64 个监听器。options.recursive 默认为 true，表示递归监听子目录。回调参数为 {watch_id, root, kind, paths}，kind 可能是 create、modify、remove、rename 或 other。一般应保存 watch_path() 返回的取消函数，不需要直接使用内部 watch_id。

bt.credential

应用凭据以明文 JSON 保存到当前用户的隐藏应用目录。显式配置 app.id 时使用该稳定标识；未配置时为兼容旧版本继续使用 app.name，例如 %USERPROFILE%\.bt_ai\credentials\。这是便于迁移和人工维护的明文格式，不使用 Windows DPAPI。接口不会向页面提供读取明文的方法，但能访问该用户目录的本机程序可以读取文件，因此调用方必须在界面中明确提示并保护操作系统账户权限。

bt.http

stream() 发起真实异步 HTTP 请求，通过回调依次返回响应头、SSE 或普通分块以及最终完整正文。启动前会先安装事件监听；cancel() 会先关闭原生事件闸门，再通知网络任务终止，因此取消成功后不会再派发该请求的状态或正文事件。

stream() 返回控制对象：

原生层会在构造第一个 HTTP client 前幂等初始化 Rustls ring crypto provider。因此，即使应用冷启动后直接调用 window.bt.http.stream()，也不依赖 BT 标准库或 Web 服务提前执行网络初始化。

流式回调事件字段：

单个响应最多派发 16384 个分块事件；超过字节数或分块数上限会以 error 结束并释放请求登记。

bt.workspace

工作区 API 先登记一个真实目录，再用短期 workspace_id 操作相对路径。所有路径都经过规范化和真实路径边界检查，递归列表不跟随符号链接或 junction。

bt.process

原生进程使用程序名和参数数组直接启动，不经过 shell。进程必须属于一个调用方任务和已登记工作区；查询、停止时必须同时匹配 process_id、task_id 与不可伪造的 identity。停止会清理该句柄对应的进程树，不按名称批量结束外部进程。

on_event() 回调字段为 process_id:string、task_id:string、kind:string、data:string、pid:integer；kind 可为 start、stdout、stderr、exit、timeout 或 stopped。同时最多登记 32 个进程，结束记录会按启动时间淘汰。

bt.data

应用 JSON 状态默认保存在当前用户的隐藏应用目录下 sessions 子目录。显式配置 app.id 时使用稳定标识；未配置时为兼容旧版本继续使用 app.name。自动化验收可设置 BT_APP_DATA_HOME，把隐藏应用目录临时放到指定父目录；正常桌面运行应保持该变量未设置。清理采用“预览—用户二次确认—一次性票据执行”三步边界，只清理该应用数据根的固定子目录，不访问已登记工作区。

bt.events

on_backend(callback) 监听 bt.call() 完成事件，返回取消监听函数。回调字段如下；事件不包含 BT 函数返回正文。

返回值

bt.call() 直接返回 BT 函数的返回值。BT 函数返回对象时，前端收到普通 JSON 对象；返回字符串、数字、布尔或数组时，前端收到对应 JSON 值。

如果 BT 函数不存在、执行报错、VM 调用队列已满或桌面 API 参数无效，Promise 会 reject，不会返回 {error,message,data} 包装对象。

代码示例

main.bt：

页面调用：

屏幕吸管、截图和全局快捷键：

托盘菜单：

退出前完成异步快照：

读取用户文档目录：

监听目录变化：

流式请求与真实取消：

工作区原子更新：

注意事项

• bt.call() 是长期 VM 业务通道；窗口、托盘、剪贴板、通知等桌面能力走独立 command，不占用 BT VM。
• VM 调用队列有上限。前端高频调用时应节流，避免无控增长。
• remote 页面同样拥有完整 window.bt 能力，只应加载可信地址。
• 同一个窗口最多同时保留 64 个 watch_path() 监听；每个返回的取消函数只停止对应监听，unwatch_path() 不传参数时停止全部监听。
• on_close_requested() 只拦截窗口的 exit 关闭流程；回调应防止重复执行，并且只有异步收尾完成后才能调用 close_now()。
• 设置 BT_PERMISSION_DENY=desktop 后，窗口、对话框、托盘、剪贴板、全局快捷键、通知、拖入文件事件、文件监听事件和应用级桌面命令会被拒绝；屏幕吸管和截图还要求单独的 screen 权限。bt.call() 本身不受 desktop 限制，被调用 BT 函数内部使用的标准库能力仍按各自权限检查。
• Windows、macOS 和 Linux X11 使用同一套 Tauri 自绘吸管/框选遮罩；macOS 首次使用通常需要用户授予屏幕录制权限。原生 Wayland 不支持可靠的全局窗口坐标和普通全局快捷键，当前版本会返回错误，不承诺与 X11 相同的遮罩界面。
• 第一版截图选区限制在单个显示器内；多显示器各自有遮罩，但不能从一块显示器跨越到另一块显示器拖选。HDR、广色域、受保护视频和系统安全桌面可能与肉眼颜色不同或返回黑色内容。
• 通用生产 API 只提供受边界约束的客户端 HTTP、已登记工作区和句柄化子进程；不会暴露任意文件系统、网络监听、shell 字符串或按名称结束进程能力。
• 凭据是当前用户目录中的明文 JSON，不得再放入 URL、普通请求头、请求体、进程参数、日志或页面存储；应使用 credential_id 让原生层注入，并限制用户目录访问权限。
• 应用关闭、任务取消或清理数据前，应先取消仍在运行的流式请求并精确停止所属任务的子进程。
• 通用桌面 API 示例位于 examples/desktop-api；吸管、截图与全局快捷键示例位于 examples/desktop-screen-tools。