窗口控制与跨窗口状态同步.md 21 KB

窗口控制与跨窗口状态同步

本文引用的文件

  • windowCtl.ts
  • smartWindow.ts
  • appWindow.ts

目录

  1. 引言
  2. 项目结构定位
  3. 核心组件总览
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 新增窗口控制方法的示例
  8. 性能与健壮性特征
  9. 常见问题排查
  10. 结论

引言

本文面向 Electron 主进程与前端渲染进程之间的“窗口控制”和“跨窗口状态同步”。重点说明:

  • 主进程控制器 WindowCtl 如何暴露 IPC 方法,用于打开、关闭、查询智能工作台窗口,并聚焦主窗口。
  • 智能工作台窗口与普通主窗口的角色区分(main vs smart)。
  • 状态广播通道 SYNC_EVENT_CHANNEL='app:state' 如何通过 syncState 把语义事件发送给除发送者外的所有窗口。
  • 前端 appWindow.ts 中的 closeSmartWindow、focusMainWindow、initWindowRole、isSmartWindow 等函数如何调用后端控制器。
  • 如何扩展新的窗口控制方法,以及多窗口场景下的常见故障排查方式。

项目结构定位

与本次主题直接相关的代码分布在三层:

  • 主进程控制器层:ai-electron/electron/controller/windowCtl.ts
  • 主进程窗口服务层:ai-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.ts:1-123
  • smartWindow.ts:1-232
  • appWindow.ts:1-183

章节来源

  • windowCtl.ts:1-123
  • smartWindow.ts:1-232
  • appWindow.ts:1-183

核心组件总览

组件 运行环境 主要职责 关键接口/常量
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.ts:1-123
  • smartWindow.ts:1-232
  • appWindow.ts:1-183

架构概览

整体通信路径分为两类:

  1. 命令型 IPC:前端调用 WindowCtl 的窗口控制方法,例如打开智能窗口、关闭智能窗口、聚焦主窗口。
  2. 事件型广播:任意窗口通过 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)
    

图示来源

  • windowCtl.ts:22-123
  • smartWindow.ts:60-130
  • appWindow.ts:96-183

详细组件分析

主进程控制器 WindowCtl

WindowCtl 是 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 : "委托窗口操作"
    

图示来源

  • windowCtl.ts:1-123
  • smartWindow.ts:1-232

章节来源

  • windowCtl.ts:1-123

智能窗口服务 smartWindow

smartWindow 服务维护一个智能工作台窗口单例,负责:

  • 判断某个 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["返回新窗口"]
    

图示来源

  • smartWindow.ts:60-130

章节来源

  • smartWindow.ts:1-232

前端窗口逻辑 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(["返回角色"])

图示来源

  • appWindow.ts:34-75

章节来源

  • appWindow.ts:1-183

跨窗口状态同步机制

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.ts:78-123

章节来源

  • windowCtl.ts:66-123
  • appWindow.ts:157-183

依赖关系分析

  • 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.ts:1-123
  • smartWindow.ts:1-232
  • appWindow.ts:1-183

章节来源

  • windowCtl.ts:1-123
  • smartWindow.ts:1-232
  • appWindow.ts:1-183

新增窗口控制方法的示例

假设要新增一个“聚焦智能工作台窗口”的方法。可按以下模式扩展:

后端控制器方法

在 WindowCtl 中新增方法,委托 smartWindow 服务:

  • 方法名建议遵循现有命名风格,例如 focusSmartWindow。
  • 捕获异常并返回 { success, message }。
  • 如果涉及窗口实例,使用 isSmartWindow 或 getSmartWindow 做安全判断。

可参考的位置:

  • windowCtl.ts:22-65
  • windowCtl.ts:66-123

前端调用

在前端 appWindow.ts 中新增封装函数:

  • 仅在桌面环境调用 IPC。
  • 复用 invokeIpc 和 WINDOW_CTL。
  • 失败时记录警告,不中断前端流程。

可参考的位置:

  • appWindow.ts:126-156

跨窗口事件监听

如果需要该操作影响其他窗口,应通过 broadcastSync 广播语义事件:

  • 事件 type 要有明确语义,例如 FOCUS_WORKBENCH。
  • 接收端用 onSyncEvent 订阅,并根据 type 执行对应逻辑。

可参考的位置:

  • appWindow.ts:157-183
  • windowCtl.ts:78-123

性能与健壮性特征

  • 单例窗口:智能窗口采用单例模式,避免多个工作台窗口造成状态混乱。
  • 轻量 IPC 返回:控制器方法返回简单对象,不包含大对象,减少序列化成本。
  • 广播过滤:syncState 主动跳过已销毁窗口和发送者,降低无效事件开销。
  • 容错优先:IPC 失败不会抛到 Electron 层;前端对 IPC 失败也做降级处理。
  • 窗口位置持久化:智能窗口位置和尺寸保存到本地设置,并在分辨率变化时做合法性校验。

[本节为通用性能讨论,不直接分析特定代码行]

常见问题排查

多窗口状态不同步

可能原因

  • 某个窗口没有正确调用 broadcastSync。
  • 接收端没有注册 onSyncEvent。
  • syncState 收到的事件缺少 type,导致主进程直接返回失败。

排查步骤

  1. 确认调用方调用的是 broadcastSync,而不是普通 IPC。
  2. 确认接收端调用 onSyncEvent 订阅了 app:state。
  3. 检查 syncState 返回的 success 和日志,确认事件是否被主进程转发。

相关代码

  • windowCtl.ts:78-123
  • appWindow.ts:157-183

智能窗口未关闭

可能原因

  • 前端没有调用 closeSmartWindow。
  • 智能窗口已经被关闭,但前端仍认为其存在。
  • 渲染进程崩溃后窗口被销毁,但前端缓存的状态未及时更新。

排查步骤

  1. 调用 isSmartWindowOpen 查询真实状态。
  2. 检查 smartWindow 服务的 closed 和 render-process-gone 回调是否正确清理单例。
  3. 如果是主窗口换案后的状态不一致,考虑使用 reloadSmartWindowIfOpen 强制刷新。

相关代码

  • appWindow.ts:114-156
  • smartWindow.ts:60-130

主窗口未聚焦

可能原因

  • 智能窗口登录失效或授权失效时,前端没有调用 focusMainWindow。
  • 主窗口尚未创建或已被销毁。
  • focusMainWindow 内部捕获异常但没有向上抛出。

排查步骤

  1. 确认前端在登录失效场景中调用 focusMainWindow。
  2. 检查主进程 focusMainWindow 是否成功调用 smartWindow.focusMainWindow。
  3. 查看主进程日志,确认是否有 focusMainWindow failed 警告。

相关代码

  • windowCtl.ts:52-65
  • smartWindow.ts:131-146
  • appWindow.ts:146-156

getWindowRole 返回错误角色

可能原因

  • IPC 事件对象中没有 sender。
  • BrowserWindow.fromWebContents 无法找到对应窗口。
  • 智能窗口实例为空,导致 isSmartWindow 始终返回假。

排查步骤

  1. 确认前端调用 initWindowRole 时确实走桌面端分支。
  2. 检查 IPC 框架是否传递了 event.sender。
  3. 检查 smartWindow 服务中智能窗口是否已创建。
  4. 如果 IPC 失败,前端会回退为主窗口角色,这是预期行为。

相关代码

  • windowCtl.ts:66-77
  • smartWindow.ts:40-59
  • appWindow.ts:34-75

结论

WindowCtl 是 Electron 主进程中与窗口控制相关的统一 IPC 入口,它将具体窗口实现委托给 smartWindow 服务,并为前端提供稳定、统一的返回格式。智能窗口和普通主窗口通过 getWindowRole 明确区分,而 syncState 通过 app:state 通道实现了“除发送者外所有窗口”的语义事件广播。前端 appWindow.ts 在此基础上封装了更友好的 API,包括 initWindowRole、isSmartWindow、openSmartWindow、closeSmartWindow、focusMainWindow 和 broadcastSync。

在实际扩展中,新增窗口控制方法应遵循:

  • 后端:在 WindowCtl 中添加方法,委托 smartWindow 服务,统一返回格式。
  • 前端:在 appWindow.ts 中添加封装函数,仅在桌面环境调用 IPC。
  • 跨窗口:需要影响其他窗口时使用 broadcastSync 广播语义事件,接收端通过 onSyncEvent 订阅处理。