azure/vue-desktop

Fork 0

Files

Azure d18a3d5279 1

2025-09-25 13:36:38 +08:00

9.7 KiB

Raw Blame History

窗体功能增强设计文档

1. 概述

1.1 功能目标

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

1.2 当前系统分析

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

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

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

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

2. 架构设计

2.1 整体架构

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个方向的拖拽调整尺寸，具体如下：

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 交互流程

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 窗体状态数据结构

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 拖拽状态数据结构

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事件，需要修复以下问题：

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

5.2 新增事件定义

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

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

5.3 事件触发流程

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

6. 核心逻辑设计

6.1 窗体状态变更逻辑修复

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

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

6.2 边缘检测算法

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

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 尺寸计算规则

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

6.4 拖拽处理流程

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

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 用户体验测试

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

9.7 KiB Raw Blame History Unescape Escape