# 窗体功能增强设计文档

## 1. 概述

### 1.1 功能目标

1. 为项目中的窗体组件添加8个方向的拖拽调整尺寸功能，增强用户交互体验
2. 修复窗体最大化、最小化、还原功能存在的问题
3. 完善窗体状态管理和事件通知机制

### 1.2 当前系统分析

通过代码分析发现，当前系统已具备以下基础功能：

- 窗体创建、销毁、移动功能
- 窗体最大化、最小化、还原功能
- 基本的事件管理系统
- 窗体状态管理和配置

但现有功能存在以下问题：

1. 缺少用户通过鼠标拖拽调整窗体尺寸的功能
2. 窗体最大化、最小化、还原功能实现不完整，缺少与事件系统的完整集成
3. 窗体状态变更时未正确触发`windowFormDataUpdate`事件通知

## 2. 架构设计

### 2.1 整体架构

```mermaid
graph TD
    A[用户操作] --> B[窗体功能处理器]
    B --> C[窗体状态管理]
    C --> D[UI更新引擎]
    D --> E[界面重渲染]
    C --> F[事件通知系统]
    
    G[窗体服务] --> C
    H[事件管理器] --> F
```

### 2.2 核心组件

| 组件名称              | 职责               | 说明                                   |
| --------------------- | ------------------ | -------------------------------------- |
| WindowOperationHandler | 窗体操作处理核心   | 处理最大化、最小化、还原和拖拽调整尺寸操作 |
| WindowManager         | 窗体状态管理       | 管理窗体状态变更和配置更新             |
| WindowRenderer        | UI更新引擎         | 应用新状态到窗体界面                   |
| WindowEventManager    | 事件管理器         | 发布窗体状态变更事件                   |

## 3. 功能设计

### 3.1 窗体状态操作

窗体支持以下状态操作：

| 操作   | 状态变更                     | 事件触发                                   | 说明                                       |
| ------ | ---------------------------- | ------------------------------------------ | ------------------------------------------ |
| 最大化 | default/minimized → maximized | windowFormMaximize, windowFormDataUpdate   | 窗体占据除任务栏外的整个屏幕空间           |
| 最小化 | default/maximized → minimized | windowFormMinimize                         | 窗体隐藏，仅在任务栏保留图标               |
| 还原   | minimized/maximized → default | windowFormRestore, windowFormDataUpdate    | 窗体恢复到正常尺寸和位置                   |

### 3.2 拖拽调整尺寸方向定义

窗体支持8个方向的拖拽调整尺寸，具体如下：

```mermaid
graph TD
    subgraph 窗体
        direction LR
        A[↖] --- B[↑] --- C[↗]
        D[←] --- E[窗体内容] --- F[→]
        G[↙] --- H[↓] --- I[↘]
    end

    classDef corner fill:#f9f,stroke:#333;
    classDef edge fill:#bbf,stroke:#333;

    class A,C,G,I,corner
    class B,D,F,H,edge
```

| 方向   | 标识符      | 影响属性            | 说明               |
| ------ | ----------- | ------------------- | ------------------ |
| 左上角 | topLeft     | width, height, x, y | 同时调整宽高和位置 |
| 上边缘 | top         | height, y           | 调整高度和垂直位置 |
| 右上角 | topRight    | width, height, y    | 调整宽高和垂直位置 |
| 右边缘 | right       | width               | 仅调整宽度         |
| 右下角 | bottomRight | width, height       | 仅调整宽高         |
| 下边缘 | bottom      | height              | 仅调整高度         |
| 左下角 | bottomLeft  | width, height, x    | 调整宽高和水平位置 |
| 左边缘 | left        | width, x            | 调整宽度和水平位置 |

### 3.3 交互流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant WH as 窗体句柄
    participant WOH as 操作处理器
    participant WM as 窗体管理器
    participant WR as 窗体渲染器
    participant EM as 事件管理器

    U->>WH: 执行操作(最大化/最小化/还原/拖拽)
    WH->>WOH: 处理操作请求
    WOH->>WM: 更新窗体状态
    WM->>WR: 应用新状态
    WM->>EM: 发布状态变更事件
    EM->>EM: 发布windowFormDataUpdate事件
    WR->>U: 更新界面显示
```

## 4. 数据模型

### 4.1 窗体状态数据结构

```typescript
interface IWindowFormDataUpdateParams {
  /** 窗口id */
  id: string;
  /** 窗口状态 */
  state: TWindowFormState;
  /** 窗口宽度 */
  width: number;
  /** 窗口高度 */
  height: number;
  /** 窗口x坐标(左上角) */
  x: number;
  /** 窗口y坐标(左上角) */
  y: number;
}

type TWindowFormState = 'default' | 'minimized' | 'maximized';
```

### 4.2 窗体尺寸配置扩展

在现有`WindowConfig`接口基础上增加最小/最大尺寸限制：

| 字段      | 类型    | 必填 | 说明                       |
| --------- | ------- | ---- | -------------------------- |
| minWidth  | number  | 可选 | 窗体最小宽度(像素)         |
| minHeight | number  | 可选 | 窗体最小高度(像素)         |
| maxWidth  | number  | 可选 | 窗体最大宽度(像素)         |
| maxHeight | number  | 可选 | 窗体最大高度(像素)         |
| resizable | boolean | 可选 | 是否可调整尺寸，默认为true |

### 4.3 拖拽状态数据结构

```typescript
interface ResizeState {
  /** 是否正在调整尺寸 */
  isResizing: boolean;
  /** 调整方向 */
  direction: ResizeDirection;
  /** 起始鼠标位置 */
  startX: number;
  /** 起始鼠标位置 */
  startY: number;
  /** 起始窗体宽度 */
  startWidth: number;
  /** 起始窗体高度 */
  startHeight: number;
  /** 起始窗体X坐标 */
  startXPosition: number;
  /** 起始窗体Y坐标 */
  startYPosition: number;
}

type ResizeDirection = 
  'topLeft' | 'top' | 'topRight' | 
  'right' | 'bottomRight' | 'bottom' | 
  'bottomLeft' | 'left' | 'none';
```

## 5. 事件系统设计

### 5.1 修复事件触发问题

当前窗体状态变更时未正确触发`windowFormDataUpdate`事件，需要修复以下问题：

1. 在最大化操作完成后，应触发`windowFormDataUpdate`事件，携带窗体新状态和尺寸信息
2. 在最小化操作完成后，应触发`windowFormDataUpdate`事件，携带窗体新状态信息
3. 在还原操作完成后，应触发`windowFormDataUpdate`事件，携带窗体新状态和尺寸信息

### 5.2 新增事件定义

在现有`IWindowFormEvent`接口中添加以下事件：

| 事件名称              | 参数类型                    | 触发时机         |
| --------------------- | --------------------------- | ---------------- |
| windowFormResizeStart | string                      | 开始调整窗体尺寸 |
| windowFormResizing    | IWindowFormDataUpdateParams | 调整尺寸过程中   |
| windowFormResizeEnd   | string                      | 完成窗体尺寸调整 |

### 5.3 事件触发流程

```mermaid
graph TD
    A[窗体状态变更] --> B{是否需要更新数据?}
    B -->|是| C[构造更新数据]
    C --> D[触发windowFormDataUpdate事件]
    B -->|否| E[直接触发状态事件]
    D --> F[通知监听组件]
    E --> F
```

## 6. 核心逻辑设计

### 6.1 窗体状态变更逻辑修复

当前窗体状态变更逻辑存在以下问题需要修复：

1. **最大化逻辑问题**：
   - 未正确保存原始窗体尺寸和位置信息
   - 未触发`windowFormDataUpdate`事件通知

2. **最小化逻辑问题**：
   - 未触发`windowFormDataUpdate`事件通知

3. **还原逻辑问题**：
   - 未正确恢复窗体尺寸和位置
   - 未触发`windowFormDataUpdate`事件通知

### 6.2 边缘检测算法

窗体边缘需要划分8个可拖拽区域，每个区域宽度为8px：

```mermaid
graph TD
    subgraph 边缘区域划分
        direction LR
        A[8px↖] --- B[8px↑] --- C[8px↗]
        D[8px←] --- E[窗体内容] --- F[8px→]
        G[8px↙] --- H[8px↓] --- I[8px↘]
    end
```

### 6.3 尺寸计算规则

1. **最小尺寸限制**：窗体宽度不能小于minWidth，高度不能小于minHeight
2. **最大尺寸限制**：窗体宽度不能大于maxWidth，高度不能大于maxHeight
3. **位置边界**：窗体不能被拖拽到屏幕外

### 6.4 拖拽处理流程

1. 鼠标按下时检测是否在边缘区域
2. 根据鼠标位置确定拖拽方向
3. 记录初始状态数据
4. 鼠标移动时实时计算新尺寸
5. 应用新尺寸并触发重渲染
6. 鼠标释放时结束拖拽状态

## 7. UI/UX设计

### 7.1 视觉反馈

- 鼠标悬停在可拖拽边缘时，光标应变为对应方向的调整光标
- 拖拽过程中窗体应有半透明遮罩效果
- 拖拽完成后应有平滑的过渡动画

### 7.2 响应式适配

- 在不同屏幕分辨率下保持边缘区域的可点击性
- 支持触屏设备的拖拽操作
- 在窗体尺寸接近最小/最大限制时提供视觉提示

## 8. 性能优化

### 8.1 事件处理优化

- 使用防抖机制减少高频事件触发
- 在拖拽过程中暂停不必要的重渲染
- 使用requestAnimationFrame优化动画性能

### 8.2 内存管理

- 及时清理事件监听器
- 复用计算对象避免频繁创建
- 在窗体销毁时清理所有相关资源

## 9. 安全考虑

### 9.1 边界检查

- 确保窗体不能被调整到超出屏幕边界
- 验证尺寸参数的有效性
- 防止负值或异常大值的输入

### 9.2 权限控制

- 只有具有调整权限的窗体才能被调整尺寸
- 外部应用的窗体尺寸调整需通过SDK接口

## 10. 测试策略

### 10.1 单元测试

- 边缘检测算法准确性测试
- 尺寸计算边界条件测试
- 事件发布/订阅机制测试

### 10.2 集成测试

- 不同方向拖拽功能测试
- 尺寸限制功能测试
- 与现有窗体功能集成测试

### 10.3 用户体验测试

- 拖拽流畅性测试
- 视觉反馈效果测试
- 不同设备兼容性测试