Skip to content

OpenTray v0.33~0.34：改进运行可靠性，扩展窗口定制

jixoai v0.34.1 opentray

0.33.0 到 0.34.1：SDK 调用全部有截止时限，broker 意外死亡零配置自动恢复；窗口拖拽与缩放改用 bindWindowRegion() 声明式绑定，macOS 补上原生缩放会话；修复 win32 通知不可见、对话框无法呈现与崩溃、文字托盘、布局重入崩溃、overlay 运行时加载。

$ npm view opentray version
0.34.1

OpenTray 0.33.0 到 0.34.1 的两条主线是连接可靠性与窗口定制。SDK 与 broker 之间的调用现在全部有截止时限，broker 意外死亡由零配置的进程内恢复接管；窗口的拖拽与缩放改用声明式绑定，macOS 补上原生缩放会话。区间内另有七个 Windows 实机修复、一个 darwin 连接修复和一次发布对齐。上一篇讲到 0.32.0，本篇按主题归组覆盖区间全部变更，每个版本的 release 永链在文末逐个列出。

broker 崩溃后自动恢复

0.33.0 起，托盘工具不用再写恢复代码。broker 进程被 kill -9 之后，SDK 在同一个进程里完成重连与状态重建，调用方只通过状态事件知情。

调用的挂死也一并消除。每次 SDK 调用都有截止时限（交互 5 s，收尾 2 s，引导 10 s，可按调用覆盖），超时以类型化的 TransportTimeoutError 落定。用户手上的延迟操作不受影响，等一次点击的对话框只经终帧落定。

自动恢复由 socket 关闭或心跳探到的半开连接触发。恢复预算默认每 10 分钟 3 次，耗尽后调用以 TransportAbandonedError 快速失败，运行时进入终态 abandoned，应用以无头模式继续运行。当前状态经 tray.onTransportStateChange 投影为 healthy/recovering/abandoned。

const tray = await createTray(
  { id: "com.example.tool", tooltip: { title: "tool" } },
  { appId: "com.example.tool", appName: "Tool" }
);

tray.onTransportStateChange?.((state) => {
  // "healthy" | "recovering" | "abandoned"
  setUiStatus(state);
});

恢复的边界是契约的一部分。WebView 页面在恢复后按 URL 整页重载，等同一次用户刷新，页面状态需要自行持久化；死亡到恢复之间的事件有界且丢失，重建后按可查询事件族重发全量快照。声明式状态会重放，一次性的命令式调用不会。需要进程级接管的应用改传 runtimeOptions.recovery.restartApp（替代进程内恢复），监督层做有界收尾后恰好回调一次并进入终态。

后续补丁逐个堵上实机暴露的恢复缺口。0.33.1 修复关闭与恢复的竞争、WebView 重建回调的路由，并给每次重连加上时限；0.33.2 起恢复保留每个窗口既定的可见性，隐藏的保留窗口不再被重新弹出；0.33.3 起监督层在死亡到重连的窗口内持有宿主事件循环，除 broker 连接外没有别的循环持有者的裸进程不再在恢复中途退出（实机证据 2026-09-22）。

机制：截止与恢复的两层结构

第一层是调用截止：interactive, teardown, bootstrap 三类预算可按调用覆盖，延迟操作走两阶段规则，不会被传输截止杀死。第二层是进程恢复：冷却退避后经同一条身份门控连接路径重生 broker，工件身份校验与锁回收全部重放，托盘与 WebView 状态声明式重放，最后全量快照重发。心跳每代单飞（0.33.1 起），每次重连受 recovery.connectTimeoutMs（默认 10 s）约束，迟到的连接在到达时关闭。测试套件带有永久的 kill -9 演习门和裸子进程腿，演习的 broker 解析也覆盖 Windows 的 opentray.exe cargo 产物。

窗口拖拽与缩放不用手写事件

0.34.0 起，页面驱动原生窗口行为有了声明式入口。navigator.opentrayWindow.bindWindowRegion(target, behavior) 接受元素、元素数组、选择器或 { root, selector }，把元素绑定到原生窗口行为，pointerdown 处理器不用再手写。

const bridge = navigator.opentrayWindow;

bridge.bindWindowRegion(titlebar, "auto"); // 移动 + 双击最大化/还原
bridge.bindWindowRegion(dragStrip, "move");
const grip = bridge.bindWindowRegion(gripEl, "resize-bottom-right");
grip.setBehavior("none"); // 暂停，不解绑

默认行为 'auto' 走平台标题栏语义，按压移动加双击缩放；此外还有 'none', 'move', 'zoom' 与八向的 resize-<edge>（resize-top 到 resize-bottom-right）。resize 行为要求 frameless 窗口，在不支持的平台上绑定会抛 TypeError。macOS 为 resize 手柄补上原生 soft-resize 会话，复用 Windows 已有的同一条内部命令。

匹配语义是严格的。只有按压目标是被绑定元素本身才触发，后代保持普通页面交互；选择器匹配是绑定时的快照，重新绑定同一元素会替换旧绑定。命令式的 startAppRegionDrag() 仍是底层原语，原有用法不受影响。

细节：soft-resize 会话与探针测试

macOS 的 soft-resize 会话由本地事件监视器在拖拽全程驱动 setFrame，与 Windows 共用同一条内部 startSoftResize 命令；zoom 配对按句柄记录。九条 bootstrap 探针测试钉住行为归一化、目标匹配与投递校验的契约。

其余变更

  • 修复：win32 通知在当前 Windows 11 上完全不可见（暂存二进制早于通知桥、NIIF_NONE 被系统静默丢弃、气泡在托盘浮层打开后停摆而 API 仍返回成功，实机证据 2026-09-23），投递改走每应用 AUMID 下的 WinRT toast 与长驻工作线程（ce1bf51）。

  • 修复：win32 消息对话框以 0x80070057 失败，文件对话框在真实桌面必崩。v6 TaskDialog 在进程初始化公共控件前直接拒绝创建（实机证据 2026-09-22），文件对话框经 IModalWindow 指针调用 Show 则 15/15 崩溃（comdlg32+0x777c8，实机证据 2026-09-23）；现在 TaskDialog 先做进程级公共控件初始化，Show 改经 IFileDialog 指针派发（c025c8cf）。

  • 修复：win32 文字托盘图标此前渲染为透明槽位，现在经 GDI 栅格化为 RGBA 图标并跟随任务栏主题（c806ed2）。

  • 修复：win32 布局事务重入导致 broker 以 0xC0000409 中止（实机证据 2026-09-24），布局内借用全部改 try_borrow 并加每窗口重入台账（9dc1213）。

  • 修复：win32 overlay 标题带的输入回到页面。ExtendsContentIntoTitlebar 此前把整条标题带划为原生拖拽区，页面放进自定义标题栏的交互控件点不到；现在装入退化拖拽矩形，拖拽与双击缩放回归页面契约（e9823dc）。

  • 修复：win32 标题栏 overlay 在仅有 OS 预置运行时的机器上以 os error 126 失败，回退到 OS 公开的 Package Dependency API 直挂包图（实机证据 2026-09-28，2a08658）。

  • 修复：win32 像素托盘图标改为按物理槽位尺寸降采样注册，isTemplate 主题着色在 win32 生效（e1ff250）。

  • 修复：darwin 裸脚本消费者（入口脚本没有 package.json 祖先）在连接时崩溃，包身份解析改为穷尽后回落环境/cwd 兜底链（b90bef4，0.34.1）。

  • 发布：0.33.4 的发布流程漏发 @opentray/icon，0.33.5 重新版本化固定组补发对齐（3ddd839）。

  • 文档：消费者 skill 刷新了 toast 通道、恢复预算与 isTemplate 平台准则；示例新增 notify-repro、dialog-selftest、webview-recovery 与窗口区域冒烟。

本区间无破坏性变更。0.32.0 之后 54 个提交：5 feat / 14 fix / 16 docs / 4 test / 15 chore（口径为 conventional 提交前缀计数）。

升级

npm i opentray@0.34.1

链接

jixoai logo jixoai jixoai.com