vue-desktop/.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口表单事件管理器.md

# 窗口表单事件管理器

<cite>
**本文档引用的文件**  
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts)
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts)
</cite>

## 目录
1. [简介](#简介)
2. [窗口生命周期事件体系](#窗口生命周期事件体系)
3. [IWindowFormDataUpdateParams数据结构分析](#iwindowformdataupdateparams数据结构分析)
4. [wfem实例共享通信机制](#wfem实例共享通信机制)
5. [Vue组件中事件监听代码范例](#vue组件中事件监听代码范例)
6. [事件解耦带来的低耦合优势](#事件解耦带来的低耦合优势)

## 简介
本系统通过`WindowFormEventManager`模块提供了一套完整的窗口生命周期事件管理体系，用于统一管理桌面应用中各类窗口的状态变化与用户交互行为。该体系基于观察者模式实现，支持多个窗口组件之间高效、安全地进行状态同步和通信。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L1-L60)

## 窗口生命周期事件体系
系统定义了七种核心窗口事件，分别对应不同的用户操作或状态变更场景：

### windowFormMinimize（窗口最小化）
当用户点击窗口最小化按钮时触发，通知相关组件当前窗口已进入最小化状态。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L10-L13)

### windowFormMaximize（窗口最大化）
当用户点击窗口最大化按钮时触发，表示窗口已切换至全屏展示模式。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L15-L18)

### windowFormRestore（窗口还原）
在窗口处于最大化或最小化状态下，用户执行还原操作时触发，表明窗口恢复为正常尺寸。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L20-L23)

### windowFormClose（窗口关闭）
用户请求关闭窗口时触发，可用于执行清理逻辑或确认提示。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L25-L28)

### windowFormFocus（窗口聚焦）
当窗口获得焦点（即被激活）时触发，常用于高亮显示当前活动窗口。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L30-L33)

### windowFormDataUpdate（窗口数据更新）
每当窗口的位置、大小或状态发生变化时触发，携带完整的窗口元信息。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L35-L39)

### windowFormCreated（窗口创建完成）
新窗口初始化完毕后触发一次，标志窗口已准备就绪可交互。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L41-L43)

## IWindowFormDataUpdateParams数据结构分析
此接口定义了窗口状态更新时传递的数据结构，各字段含义如下：

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | string | 唯一标识一个窗口实例的ID |
| state | TWindowFormState | 当前窗口的视觉状态 |
| width | number | 窗口当前像素宽度 |
| height | number | 窗口当前像素高度 |
| x | number | 窗口左上角相对于屏幕的X坐标 |
| y | number | 窗口左上角相对于屏幕的Y坐标 |

其中，`TWindowFormState` 是一个联合类型，定义于 `WindowFormTypes.ts` 文件中，包含三种可能取值：
- `'default'`：默认状态（正常大小）
- `'minimized'`：最小化状态
- `'maximized'`：最大化状态

这些字段共同构成了窗口的完整状态快照，便于其他组件根据最新布局信息做出响应。

```mermaid
classDiagram
class IWindowFormDataUpdateParams {
+id : string
+state : TWindowFormState
+width : number
+height : number
+x : number
+y : number
}
class TWindowFormState {
<<type>>
'default'
'minimized'
'maximized'
}
```

**Diagram sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L44-L57)
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L9-L9)

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L44-L57)
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L9-L9)

## wfem实例共享通信机制
`wfem` 是一个全局唯一的 `EventBuilderImpl<IWindowFormEvent>` 实例，作为事件中心被所有窗口组件共享使用。其工作原理如下：

1. **事件注册**：任意组件可通过 `wfem.addEventListener(eventName, handler)` 订阅特定事件。
2. **事件分发**：当窗口状态改变时，调用 `wfem.notifyEvent(eventName, args)` 广播事件。
3. **跨组件通信**：不同组件间无需直接引用，仅通过事件总线即可实现松散耦合的状态同步。

这种设计使得各个窗口组件可以独立开发、测试和维护，同时又能实时感知彼此的状态变化。

```mermaid
sequenceDiagram
participant ComponentA as 组件A
participant ComponentB as 组件B
participant Wfem as wfem事件中心
ComponentA->>Wfem : addEventListener("focus", handler)
ComponentB->>Wfem : addEventListener("close", handler)
Note over Wfem : 多个组件注册监听
Window->>Wfem : notifyEvent("focus", "win123")
Wfem->>ComponentA : 执行handler("win123")
Window->>Wfem : notifyEvent("close", "win123")
Wfem->>ComponentB : 执行handler("win123")
```

**Diagram sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L1-L95)

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)

## Vue组件中事件监听代码范例
以下是在Vue 3组件中监听窗口聚焦与关闭事件的典型用法：

```typescript
import { onMounted, onBeforeUnmount } from 'vue';
import { wfem } from '@/events/WindowFormEventManager';

export default {
  setup() {
    const handleFocus = (id: string) => {
      console.log(`窗口 ${id} 获得焦点`);
      // 更新UI状态，如添加边框高亮
    };

    const handleClose = (id: string) => {
      console.log(`窗口 ${id} 已关闭`);
      // 清理资源，移除DOM节点等
    };

    onMounted(() => {
      wfem.addEventListener('windowFormFocus', handleFocus);
      wfem.addEventListener('windowFormClose', handleClose);
    });

    onBeforeUnmount(() => {
      wfem.removeEventListener('windowFormFocus', handleFocus);
      wfem.removeEventListener('windowFormClose', handleClose);
    });

    return {};
  }
}
```

上述代码展示了如何在组件挂载时注册事件监听，并在卸载前正确移除，避免内存泄漏。

**Section sources**
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L30-L39)

## 事件解耦带来的低耦合优势
采用事件驱动架构后，各组件之间的依赖关系显著降低，具体优势包括：

- **独立性增强**：组件无需知道谁会发送或接收事件，只需关注自身职责。
- **可维护性提升**：修改某一组件不会影响其他不相关的模块。
- **扩展性强**：新增功能只需监听已有事件，无需改动现有逻辑。
- **测试更简单**：可单独对每个组件进行单元测试，模拟事件输入即可验证行为。

通过 `wfem` 这一统一事件通道，系统实现了高度模块化的设计，有利于长期迭代和团队协作开发。

**Section sources**
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts#L1-L46)
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L1-L95)