用途:在应用与 TanStack Devtools 面板之间建立双向通信。前提是先理解 devtools-event-client 技能(事件映射类型、emit()/on()、pluginId 命名空间、连接生命周期与单例模式)。
主要能力:同一 EventClient 实例双向工作。应用侧 emit 观察事件(如 state-update),面板侧 on 监听并渲染;面板侧 emit 命令事件(如 set-state、reset、revert),应用侧 on 监听并修改状态。命令处理后可再 emit 观察事件以闭环。
时间旅行调试:应用在状态变更时 emit snapshot,载荷用 structuredClone(state) 深拷贝,附 timestamp 与 label;面板收集快照并用滑块 emit revert 命令,应用监听后恢复状态。
用法要点:在共享模块定义事件映射与客户端类,pluginId 区分插件,enabled 常设为 process.env.NODE_ENV !== 'production'。命名约定:观察事件描述已发生(state-update、action-dispatched、snapshot),命令事件描述要做什么(set-state、dispatch-action、reset、revert)。高频观察事件可在 emit 侧防抖(如 16ms),命令事件不应防抖。
限制与常见错误:快照必须用 structuredClone,否则面板保存的是活动状态引用,后续变更会污染历史快照;跨标签页经 WebSocket/SSE/BroadcastChannel 传输时载荷需可序列化,函数、DOM 节点、Map、Set、循环引用等会丢失;观察与命令事件命名需区分,避免方向混淆。
适用场景:为 TanStack Devtools 插件实现状态检查器、操作派发、重置与时间旅行等调试面板。