本文引用的文件
本文面向 Electron 主进程与前端渲染进程之间的“窗口控制”和“跨窗口状态同步”。重点说明:
WindowCtl 如何暴露 IPC 方法,用于打开、关闭、查询智能工作台窗口,并聚焦主窗口。main vs smart)。SYNC_EVENT_CHANNEL='app:state' 如何通过 syncState 把语义事件发送给除发送者外的所有窗口。appWindow.ts 中的 closeSmartWindow、focusMainWindow、initWindowRole、isSmartWindow 等函数如何调用后端控制器。与本次主题直接相关的代码分布在三层:
ai-electron/electron/controller/windowCtl.tsai-electron/electron/service/window/smartWindow.ts前端窗口逻辑层:ai-electron/frontend/src/core/logics/appWindow.ts
graph TB
subgraph "前端渲染进程"
FE_AppWindow["前端 appWindow.ts<br/>openSmartWindow / closeSmartWindow / focusMainWindow<br/>initWindowRole / isSmartWindow / broadcastSync"]
end
subgraph "Electron 主进程"
CTL_WindowCtl["主进程控制器 windowCtl.ts<br/>WindowCtl<br/>IPC 入口:openSmartWindow / closeSmartWindow / isSmartWindowOpen / focusMainWindow / getWindowRole / syncState"]
SVC_SmartWindow["窗口服务 smartWindow.ts<br/>智能窗口单例 / 位置恢复 / 状态通知"]
end
FE_AppWindow -->|invokeIpc| CTL_WindowCtl
CTL_WindowCtl --> SVC_SmartWindow
SVC_SmartWindow -->|"向主窗口广播 SMART_WINDOW_STATE_CHANNEL"| FE_AppWindow
CTL_WindowCtl -->|"通过 SYNC_EVENT_CHANNEL 广播语义事件"| FE_AppWindow
图示来源
章节来源
| 组件 | 运行环境 | 主要职责 | 关键接口/常量 |
|---|---|---|---|
WindowCtl |
主进程 | 作为 IPC 控制器,封装窗口操作;统一返回 `{ success, data | message }`;提供跨窗口状态广播 |
smartWindow 服务 |
主进程 | 管理智能工作台窗口的生命周期、位置持久化、导航策略、状态通知 | openSmartWindow、closeSmartWindow、focusSmartWindow、focusMainWindow、isSmartWindowOpen、isSmartWindow、SMART_WINDOW_STATE_CHANNEL |
appWindow 前端逻辑 |
渲染进程 | 判断是否桌面端、解析窗口角色、调用后端 IPC、订阅跨窗口状态事件 | initWindowRole、isSmartWindow、openSmartWindow、closeSmartWindow、focusMainWindow、broadcastSync、onSyncEvent |
章节来源
整体通信路径分为两类:
WindowCtl 的窗口控制方法,例如打开智能窗口、关闭智能窗口、聚焦主窗口。事件型广播:任意窗口通过 broadcastSync 触发 syncState,主进程将语义事件转发给除发送者外的所有窗口。
sequenceDiagram
participant FE as "前端 appWindow.ts"
participant CTL as "主进程 WindowCtl"
participant SVC as "主进程 smartWindow 服务"
participant OtherFE as "其他前端窗口"
Note over FE,CTL: 命令型 IPC
FE->>CTL: invokeIpc("openSmartWindow", params, "windowCtl")
CTL->>SVC: openSmartWindow(params)
SVC-->>CTL: 完成
CTL-->>FE: { success: true }
Note over FE,OtherFE: 跨窗口状态广播
FE->>CTL: invokeIpc("syncState", { event }, "windowCtl")
CTL->>CTL: 遍历所有窗口并排除发送者
CTL-->>OtherFE: send("app:state", payload)
图示来源
WindowCtlWindowCtl 是 Electron 主进程中对外暴露的窗口控制类。它不负责实现具体窗口创建细节,而是委托给 smartWindow 服务,并把结果包装成统一的 IPC 响应格式。
| 方法 | 参数 | 返回值 | 行为说明 |
|---|---|---|---|
openSmartWindow |
{ fullPath?, reloadIfOpen?, navigateIfOpen? } |
{ success, data: { open } } |
打开或聚焦智能工作台窗口;失败时记录日志并返回错误信息 |
closeSmartWindow |
无 | { success } |
关闭智能窗口;未打开时视为空操作 |
isSmartWindowOpen |
无 | { success, data: { open } } |
查询智能窗口是否已存在 |
focusMainWindow |
无 | { success } |
将主窗口置于前台,常用于智能窗口登录失效时的提示场景 |
getWindowRole |
第一个参数为调用方传入的参数,第二个参数为 IPC 事件对象 | { success, data: { role } } |
根据发起调用的 webContents 判断当前窗口是 main 还是 smart |
syncState |
{ event?: { type?, payload? } } |
{ success } |
校验事件类型后,向除发送者外的所有存活窗口广播 app:state 语义事件 |
{ success, data|message },避免异常向上抛出到 Electron 层。syncState 使用 event.sender.id 排除自身,防止事件自循环。webContents。角色判定依据:getWindowRole 通过 BrowserWindow.fromWebContents(event.sender) 拿到实际窗口,再用 isSmartWindow 比较智能窗口实例。
classDiagram
class WindowCtl {
+openSmartWindow(params)
+closeSmartWindow()
+isSmartWindowOpen()
+focusMainWindow()
+getWindowRole(params, event)
+syncState(params, event)
-toMessage(error) string
}
class SmartWindowService {
+openSmartWindow(options)
+closeSmartWindow()
+focusSmartWindow() boolean
+focusMainWindow() void
+isSmartWindowOpen() boolean
+isSmartWindow(win) boolean
}
WindowCtl --> SmartWindowService : "委托窗口操作"
图示来源
章节来源
smartWindowsmartWindow 服务维护一个智能工作台窗口单例,负责:
BrowserWindow 是否为智能窗口。SMART_WINDOW_STATE_CHANNEL 状态事件。reloadIfOpen=true:对已加载完成的窗口整窗重载,用于主窗口换案后重建工作区上下文。navigateIfOpen=true 且目标地址带 query:显式导航到新视图,例如新建对话。/workbench 开头的完整路径,防止业务页被塞入智能窗口。状态通知:窗口关闭、渲染进程崩溃等时机,向主窗口广播智能窗口开关状态。
flowchart TD
Start(["调用 openSmartWindow"]) --> CheckExisting["检查是否已有智能窗口"]
CheckExisting --> Exists{"已存在?"}
Exists -->|是| FocusExisting["聚焦已有窗口"]
FocusExisting --> ReloadCheck{"需要重载?"}
ReloadCheck -->|是| LoadReload["检查是否加载中<br/>未加载则整窗重载"]
ReloadCheck -->|否| NavigateCheck{"需要导航?"}
NavigateCheck -->|是| LoadNavigate["按 fullPath 导航"]
NavigateCheck -->|否| ReturnExisting["返回已有窗口"]
Exists -->|否| CreateWin["创建 BrowserWindow"]
CreateWin --> SetupEvents["绑定 ready-to-show / close / closed / render-process-gone"]
SetupEvents --> LoadRenderer["加载渲染页面"]
LoadRenderer --> NotifyOpen["通知主窗口:智能窗口已打开"]
NotifyOpen --> ReturnNew["返回新窗口"]
图示来源
章节来源
appWindow.ts前端 appWindow.ts 是渲染进程侧的统一窗口能力抽象。它屏蔽了桌面客户端与浏览器环境的差异,并提供:
| 函数 | 作用 | 与后端交互 |
|---|---|---|
initWindowRole |
启动阶段解析当前窗口角色;非桌面端默认主窗口;成功设置 setPersistOnUnload(!isSmartWindow()) |
调用 getWindowRole |
isSmartWindow |
判断当前前端实例是否在智能窗口中 | 读取本地 role |
openSmartWindow |
无案件时返回 no-case;浏览器环境降级为路由跳转;桌面环境调用 IPC |
调用 openSmartWindow |
closeSmartWindow |
仅桌面环境调用 IPC | 调用 closeSmartWindow |
focusMainWindow |
仅桌面环境调用 IPC | 调用 focusMainWindow |
isSmartWindowOpen |
仅桌面环境查询智能窗口状态 | 调用 isSmartWindowOpen |
broadcastSync |
广播共享状态事件 | 调用 syncState |
onSyncEvent |
订阅 app:state 语义事件 |
监听 SYNC_EVENT_CHANNEL |
flowchart TD
Start(["调用 initWindowRole"]) --> DesktopCheck{"是否桌面端?"}
DesktopCheck -->|否| SetMain["角色设为 main"]
DesktopCheck -->|是| CallIPC["调用 getWindowRole"]
CallIPC --> IPCSuccess{"IPC 成功?"}
IPCSuccess -->|是| RoleResult{"返回 role === 'smart'?"}
RoleResult -->|是| SetSmart["角色设为 smart"]
RoleResult -->|否| SetMain
IPCSuccess -->|否| WarnFallback["记录警告并按主窗口处理"]
WarnFallback --> SetMain
SetMain --> PersistCheck["设置卸载时缓存写入权限"]
SetSmart --> PersistCheck
PersistCheck --> Done(["返回角色"])
图示来源
章节来源
syncState 的职责不是解释业务,而是做可靠的语义事件转发。接收端应根据自己的 type 决定行为:
前端定义了 SyncEvent 类型,包含 APP_RESET 和 AUTH_INVALID 两种语义事件。
sequenceDiagram
participant Sender as "发送方窗口"
participant CTL as "WindowCtl.syncState"
participant WinA as "其他窗口 A"
participant WinB as "其他窗口 B"
Sender->>CTL: syncState({ event: { type, payload } })
CTL->>CTL: 校验 event.type 是否存在
CTL->>CTL: 记录 senderId
loop 遍历所有窗口
CTL->>CTL: 跳过已销毁窗口
CTL->>CTL: 跳过 senderId 相同的窗口
CTL-->>WinA: send("app:state", payload)
CTL-->>WinB: send("app:state", payload)
end
CTL-->>Sender: { success: true }
图示来源
章节来源
WindowCtl 依赖 smartWindow 服务完成实际的窗口操作。WindowCtl 依赖 Electron 的 BrowserWindow 获取所有窗口、判断窗口是否销毁。WindowCtl 通过 ipcRenderer.invoke 风格的前端调用链被 appWindow.ts 调用。appWindow.ts 同时定义了两个重要常量:IPC 控制器名 WINDOW_CTL = 'windowCtl' 和状态通道 SYNC_EVENT_CHANNEL = 'app:state'。smartWindow 服务还维护另一个状态通道 SMART_WINDOW_STATE_CHANNEL = 'smart-window:state',用于通知主窗口智能窗口的开闭状态,这与 app:state 不同:前者是窗口状态信号,后者是业务语义事件。
graph LR
AppWindow["frontend appWindow.ts"] --> WindowCtl["electron controller/windowCtl.ts"]
WindowCtl --> SmartWindow["electron service/window/smartWindow.ts"]
SmartWindow --> Electron["Electron BrowserWindow"]
WindowCtl --> Electron
图示来源
章节来源
假设要新增一个“聚焦智能工作台窗口”的方法。可按以下模式扩展:
在 WindowCtl 中新增方法,委托 smartWindow 服务:
focusSmartWindow。{ success, message }。isSmartWindow 或 getSmartWindow 做安全判断。可参考的位置:
在前端 appWindow.ts 中新增封装函数:
invokeIpc 和 WINDOW_CTL。可参考的位置:
如果需要该操作影响其他窗口,应通过 broadcastSync 广播语义事件:
type 要有明确语义,例如 FOCUS_WORKBENCH。onSyncEvent 订阅,并根据 type 执行对应逻辑。可参考的位置:
syncState 主动跳过已销毁窗口和发送者,降低无效事件开销。[本节为通用性能讨论,不直接分析特定代码行]
可能原因
broadcastSync。onSyncEvent。syncState 收到的事件缺少 type,导致主进程直接返回失败。排查步骤
broadcastSync,而不是普通 IPC。onSyncEvent 订阅了 app:state。syncState 返回的 success 和日志,确认事件是否被主进程转发。相关代码
可能原因
closeSmartWindow。排查步骤
isSmartWindowOpen 查询真实状态。smartWindow 服务的 closed 和 render-process-gone 回调是否正确清理单例。reloadSmartWindowIfOpen 强制刷新。相关代码
可能原因
focusMainWindow。focusMainWindow 内部捕获异常但没有向上抛出。排查步骤
focusMainWindow。focusMainWindow 是否成功调用 smartWindow.focusMainWindow。focusMainWindow failed 警告。相关代码
getWindowRole 返回错误角色可能原因
sender。BrowserWindow.fromWebContents 无法找到对应窗口。isSmartWindow 始终返回假。排查步骤
initWindowRole 时确实走桌面端分支。event.sender。smartWindow 服务中智能窗口是否已创建。相关代码
WindowCtl 是 Electron 主进程中与窗口控制相关的统一 IPC 入口,它将具体窗口实现委托给 smartWindow 服务,并为前端提供稳定、统一的返回格式。智能窗口和普通主窗口通过 getWindowRole 明确区分,而 syncState 通过 app:state 通道实现了“除发送者外所有窗口”的语义事件广播。前端 appWindow.ts 在此基础上封装了更友好的 API,包括 initWindowRole、isSmartWindow、openSmartWindow、closeSmartWindow、focusMainWindow 和 broadcastSync。
在实际扩展中,新增窗口控制方法应遵循:
WindowCtl 中添加方法,委托 smartWindow 服务,统一返回格式。appWindow.ts 中添加封装函数,仅在桌面环境调用 IPC。broadcastSync 广播语义事件,接收端通过 onSyncEvent 订阅处理。