1
This commit is contained in:
314
.qoder/quests/window-drag-resize-control.md
Normal file
314
.qoder/quests/window-drag-resize-control.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# 窗体功能增强设计文档
|
||||
|
||||
## 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 用户体验测试
|
||||
|
||||
- 拖拽流畅性测试
|
||||
- 视觉反馈效果测试
|
||||
- 不同设备兼容性测试
|
||||
Reference in New Issue
Block a user