保存
This commit is contained in:
204
.qoder/repowiki/zh/content/UI组件体系/AppIcon组件.md
Normal file
204
.qoder/repowiki/zh/content/UI组件体系/AppIcon组件.md
Normal file
@@ -0,0 +1,204 @@
|
||||
# AppIcon组件
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心数据结构](#核心数据结构)
|
||||
3. [拖拽交互机制](#拖拽交互机制)
|
||||
4. [网格定位原理](#网格定位原理)
|
||||
5. [事件过滤逻辑](#事件过滤逻辑)
|
||||
6. [容器响应式布局](#容器响应式布局)
|
||||
7. [图标重排策略](#图标重排策略)
|
||||
8. [持久化存储](#持久化存储)
|
||||
9. [扩展与最佳实践](#扩展与最佳实践)
|
||||
|
||||
## 简介
|
||||
`AppIcon` 组件是桌面应用系统中的可交互图标单元，实现了基于HTML5 Drag API的拖拽功能。该组件通过精确的坐标计算和网格系统集成，允许用户将图标重新定位到桌面容器的任意有效网格位置。本文档深入解析其技术实现细节，涵盖从拖拽事件处理、坐标换算、网格定位到状态持久化的完整流程。
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
|
||||
## 核心数据结构
|
||||
|
||||
### IDesktopAppIcon 接口
|
||||
定义了桌面图标的元数据结构，包含名称、图标资源、启动路径及在网格布局中的位置坐标。
|
||||
|
||||
```typescript
|
||||
export interface IDesktopAppIcon {
|
||||
name: string; // 图标显示名称
|
||||
icon: string; // 图标资源路径或标识符
|
||||
path: string; // 关联的应用程序启动路径
|
||||
x: number; // 在grid布局中的列索引（从1开始）
|
||||
y: number; // 在grid布局中的行索引（从1开始）
|
||||
}
|
||||
```
|
||||
|
||||
该设计意图明确：`x` 和 `y` 字段直接映射到CSS Grid的`grid-column`和`grid-row`属性，实现了数据驱动的UI布局。
|
||||
|
||||
**Section sources**
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L3-L14)
|
||||
|
||||
## 拖拽交互机制
|
||||
|
||||
`AppIcon` 组件利用原生HTML5 Drag API实现拖拽功能：
|
||||
|
||||
1. **启用拖拽**：通过设置 `draggable="true"` 属性激活元素的拖拽能力。
|
||||
2. **事件监听**：
|
||||
- `@dragstart`：拖拽开始时触发，当前实现为空函数，保留未来扩展空间。
|
||||
- `@dragend`：拖拽结束时触发，执行核心的坐标计算与位置更新逻辑。
|
||||
|
||||
此机制无需依赖第三方库，轻量且兼容性好。
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L2-L8)
|
||||
|
||||
## 网格定位原理
|
||||
|
||||
### 动态样式绑定
|
||||
组件通过内联样式动态设置其在CSS Grid中的位置：
|
||||
```vue
|
||||
:style="`grid-column: ${iconInfo.x}/${iconInfo.x + 1}; grid-row: ${iconInfo.y}/${iconInfo.y + 1};`"
|
||||
```
|
||||
此表达式将 `iconInfo.x` 和 `iconInfo.y` 的值转换为Grid的列/行跨度声明，确保图标精准占据一个网格单元。
|
||||
|
||||
### 坐标换算过程
|
||||
`onDragEnd` 事件处理器的核心任务是将鼠标绝对坐标转换为相对网格坐标：
|
||||
|
||||
1. **获取容器边界**：使用 `getBoundingClientRect()` 获取父容器的绝对位置和尺寸。
|
||||
2. **计算相对坐标**：通过 `e.clientX - rect.left` 和 `e.clientY - rect.top` 得到鼠标相对于容器左上角的偏移量。
|
||||
3. **确定目标网格**：利用 `cellRealWidth` 和 `cellRealHeight` 进行除法运算并向上取整（`Math.ceil`），得到目标网格的行列索引。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[拖拽结束] --> B{获取鼠标<br/>clientX/clientY}
|
||||
B --> C{获取容器<br/>getBoundingClientRect}
|
||||
C --> D[计算鼠标相对<br/>容器坐标]
|
||||
D --> E[用cellRealWidth/Height<br/>计算网格索引]
|
||||
E --> F[更新iconInfo.x/y]
|
||||
F --> G[触发UI重渲染]
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L10-L38)
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L10-L38)
|
||||
|
||||
## 事件过滤逻辑
|
||||
|
||||
为了防止图标被错误地放置在其他图标之上，`onDragEnd` 方法实现了关键的事件过滤：
|
||||
|
||||
1. 使用 `document.elementFromPoint(e.clientX, e.clientY)` 检测鼠标终点位置的DOM元素。
|
||||
2. 如果该元素是另一个 `.icon-container`，则立即返回，不执行任何位置更新。
|
||||
|
||||
此逻辑确保了“空位投放”原则，提升了用户体验，避免了图标的视觉重叠。
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L13-L17)
|
||||
|
||||
## 容器响应式布局
|
||||
|
||||
### IGridTemplateParams 接口
|
||||
该接口定义了网格系统的动态参数，是实现响应式布局的关键。
|
||||
|
||||
```typescript
|
||||
export interface IGridTemplateParams {
|
||||
cellExpectWidth: number; // 单元格预设宽度
|
||||
cellExpectHeight: number; // 单元格预设高度
|
||||
cellRealWidth: number; // 单元格实际宽度
|
||||
cellRealHeight: number; // 单元格实际高度
|
||||
gapX: number; // 列间距
|
||||
gapY: number; // 行间距
|
||||
colCount: number; // 总列数
|
||||
rowCount: number; // 总行数
|
||||
}
|
||||
```
|
||||
|
||||
### 实际尺寸计算
|
||||
`useDesktopContainerInit` 函数通过 `ResizeObserver` 监听容器尺寸变化，并动态计算 `cellRealWidth` 和 `cellRealHeight`：
|
||||
|
||||
```javascript
|
||||
const w = containerRect.width - (gridTemplate.gapX * (gridTemplate.colCount - 1));
|
||||
gridTemplate.cellRealWidth = Number((w / gridTemplate.colCount).toFixed(2));
|
||||
```
|
||||
|
||||
此计算考虑了所有列间距的总和，确保了网格单元的实际尺寸能完美填充容器，无边距误差。
|
||||
|
||||
**Section sources**
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L3-L20)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L30-L38)
|
||||
|
||||
## 图标重排策略
|
||||
|
||||
当网格的行列数发生变化时，`rearrangeIcons` 函数负责智能地重新分配图标位置：
|
||||
|
||||
1. **优先保留原位**：遍历所有图标，若其原位置在新网格范围内且未被占用，则保留在原位。
|
||||
2. **寻找空位**：对于超出范围或位置冲突的图标，从 `(1,1)` 开始扫描，为其寻找第一个可用的空网格。
|
||||
3. **隐藏溢出图标**：如果所有网格均被占用，则将无法安置的图标放入 `hideAppIcons` 数组。
|
||||
|
||||
此策略保证了用户自定义布局的最大程度保留，同时优雅地处理了空间不足的情况。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant DC as DesktopContainer
|
||||
participant UDCI as useDesktopContainerInit
|
||||
participant RI as rearrangeIcons
|
||||
DC->>UDCI : 监听gridTemplate变化
|
||||
UDCI->>RI : 调用rearrangeIcons()
|
||||
loop 遍历每个图标
|
||||
RI->>RI : 检查是否在新网格内且位置空闲
|
||||
alt 是
|
||||
RI->>RI : 保留在原位
|
||||
else 否
|
||||
RI->>RI : 加入临时队列
|
||||
end
|
||||
end
|
||||
loop 处理临时队列
|
||||
RI->>RI : 扫描网格寻找空位
|
||||
alt 找到空位
|
||||
RI->>RI : 分配新位置
|
||||
else 无空位
|
||||
RI->>RI : 加入hideAppIcons
|
||||
end
|
||||
end
|
||||
RI-->>UDCI : 返回appIcons和hideAppIcons
|
||||
UDCI->>DC : 更新appIconsRef
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L77-L80)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L77-L80)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
## 持久化存储
|
||||
|
||||
用户的图标布局偏好通过 `localStorage` 实现持久化：
|
||||
|
||||
1. **写入**：使用 `watch` 监听 `appIconsRef.value` 的变化，一旦有更新，立即将整个数组序列化为JSON字符串并存入 `localStorage` 键名为 `'desktopAppIconInfo'` 的条目中。
|
||||
2. **读取**：在初始化时，尝试从 `localStorage` 中读取 `'desktopAppIconInfo'`，若存在则使用存储的位置信息覆盖默认布局。
|
||||
|
||||
这确保了用户关闭页面后再次打开时，仍能看到上次调整好的桌面布局。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L88-L90)
|
||||
|
||||
## 扩展与最佳实践
|
||||
|
||||
### 自定义图标样式
|
||||
可通过修改 `<style scoped>` 中的 `.icon-container` 类来定制图标外观，例如添加背景图片、阴影或动画效果。
|
||||
|
||||
### 扩展拖拽行为
|
||||
可在 `onDragStart` 回调中添加逻辑，如设置拖拽图像 (`e.dataTransfer.setDragImage`) 或传输自定义数据。
|
||||
|
||||
### 避免跨容器拖拽冲突
|
||||
**最佳方案**：为每个可拖拽区域（容器）维护独立的 `gridTemplate` 状态和图标集合。在 `onDragEnd` 事件中，首先确认 `pointTarget` 是否属于当前容器的 `.desktop-icons-container`，如果不是，则忽略此次拖拽操作，防止图标被错误地投放到其他容器中。
|
||||
309
.qoder/repowiki/zh/content/UI组件体系/DesktopContainer组件.md
Normal file
309
.qoder/repowiki/zh/content/UI组件体系/DesktopContainer组件.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# DesktopContainer组件
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [App.vue](file://src/ui/App.vue)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心功能分析](#核心功能分析)
|
||||
3. [响应式网格布局初始化](#响应式网格布局初始化)
|
||||
4. [ResizeObserver尺寸监听机制](#resizeobserver尺寸监听机制)
|
||||
5. [应用图标状态管理与持久化](#应用图标状态管理与持久化)
|
||||
6. [模板渲染与事件处理](#模板渲染与事件处理)
|
||||
7. [与父组件的数据流关系](#与父组件的数据流关系)
|
||||
8. [自定义容器集成示例](#自定义容器集成示例)
|
||||
|
||||
## 简介
|
||||
|
||||
`DesktopContainer` 是 Vue 桌面应用的核心容器组件，负责管理桌面图标的布局、状态和交互。该组件通过组合式函数 `useDesktopContainerInit` 实现了动态响应式网格系统，并结合 `localStorage` 提供图标位置的持久化存储能力。作为桌面环境的主视图容器，它与 `App.vue` 父组件构成清晰的数据流结构，为上层应用提供稳定可靠的桌面管理服务。
|
||||
|
||||
## 核心功能分析
|
||||
|
||||
`DesktopContainer` 组件承担着桌面环境的核心职责，主要包括：
|
||||
- 初始化并维护一个基于 CSS Grid 的响应式布局系统
|
||||
- 动态计算网格行列数及单元格实际尺寸以适应容器变化
|
||||
- 管理所有桌面应用图标的元数据及其在网格中的坐标位置
|
||||
- 通过本地存储实现用户自定义图标准置的持久化
|
||||
- 提供标准化的应用启动接口（双击事件）
|
||||
- 支持拖拽重排功能并与子组件 `AppIcon` 协同工作
|
||||
|
||||
该组件的设计体现了关注点分离原则，将复杂的布局逻辑封装在独立的组合式函数中，保持了模板的简洁性和可维护性。
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## 响应式网格布局初始化
|
||||
|
||||
### useDesktopContainerInit组合式函数
|
||||
|
||||
`useDesktopContainerInit` 函数是整个桌面布局系统的核心引擎，接收一个 CSS 选择器字符串 `containerStr` 作为参数，用于定位需要监控尺寸变化的 DOM 容器元素。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IGridTemplateParams {
|
||||
+cellExpectWidth : number
|
||||
+cellExpectHeight : number
|
||||
+cellRealWidth : number
|
||||
+cellRealHeight : number
|
||||
+gapX : number
|
||||
+gapY : number
|
||||
+colCount : number
|
||||
+rowCount : number
|
||||
}
|
||||
class useDesktopContainerInit {
|
||||
-container : HTMLElement
|
||||
-gridTemplate : IGridTemplateParams
|
||||
-ro : ResizeObserver
|
||||
-appIconsRef : Ref~Array~
|
||||
-exceedApp : Ref~Array~
|
||||
+return gridStyle : ComputedRef
|
||||
}
|
||||
useDesktopContainerInit --> IGridTemplateParams : "uses"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L1-L20)
|
||||
|
||||
### gridTemplate参数计算逻辑
|
||||
|
||||
`gridTemplate` 对象采用 `reactive` 声明为响应式数据，包含以下关键属性：
|
||||
- `cellExpectWidth` 和 `cellExpectHeight`：单元格期望尺寸（默认90x110px）
|
||||
- `gapX` 和 `gapY`：行列间距（默认4px）
|
||||
- `colCount` 和 `rowCount`：动态计算的总行列数
|
||||
|
||||
初始状态下，行列数设为1，随后由 `ResizeObserver` 根据容器实际尺寸重新计算。
|
||||
|
||||
### gridStyle动态生成机制
|
||||
|
||||
通过 `computed` 属性 `gridStyle` 动态生成应用于容器的内联样式：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始计算]) --> CalcColumns["构建 gridTemplateColumns<br/>repeat(colCount, minmax(cellExpectWidth + 'px', 1fr))"]
|
||||
CalcColumns --> CalcRows["构建 gridTemplateRows<br/>repeat(rowCount, minmax(cellExpectHeight + 'px', 1fr))"]
|
||||
CalcRows --> SetGap["设置 gap: gapY + 'px' gapX + 'px'"]
|
||||
SetGap --> ReturnStyle["返回样式对象"]
|
||||
ReturnStyle --> End([完成])
|
||||
```
|
||||
|
||||
此计算属性确保了每当 `gridTemplate` 中的任何字段发生变化时，都能立即生成正确的 CSS Grid 样式规则。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## ResizeObserver尺寸监听机制
|
||||
|
||||
### 尺寸监听流程
|
||||
|
||||
`ResizeObserver` 被用来监听传入选择器所匹配容器的尺寸变化，其回调函数执行以下步骤：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant RO as ResizeObserver
|
||||
participant CT as Container
|
||||
participant GT as gridTemplate
|
||||
RO->>CT : getBoundingClientRect()
|
||||
CT-->>RO : 返回容器矩形信息
|
||||
RO->>GT : 计算 colCount
|
||||
RO->>GT : 计算 rowCount
|
||||
RO->>GT : 计算 cellRealWidth
|
||||
RO->>GT : 计算 cellRealHeight
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L38-L52)
|
||||
|
||||
### 行列数计算公式
|
||||
|
||||
根据容器当前宽度和高度，使用如下数学公式计算最优行列分布：
|
||||
|
||||
```
|
||||
colCount = floor((width + gapX) / (cellExpectWidth + gapX))
|
||||
rowCount = floor((height + gapY) / (cellExpectHeight + gapY))
|
||||
```
|
||||
|
||||
这种算法确保即使在存在间隙的情况下也能最大化利用可用空间。
|
||||
|
||||
### 实际单元格尺寸调整
|
||||
|
||||
考虑到间隙对总可用空间的影响，实际单元格尺寸通过以下方式精确计算：
|
||||
|
||||
```typescript
|
||||
const w = containerRect.width - (gapX * (colCount - 1))
|
||||
const h = containerRect.height - (gapY * (rowCount - 1))
|
||||
cellRealWidth = w / colCount
|
||||
cellRealHeight = h / rowCount
|
||||
```
|
||||
|
||||
最终结果保留两位小数，保证视觉上的平滑过渡。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L38-L52)
|
||||
|
||||
## 应用图标状态管理与持久化
|
||||
|
||||
### appIconsRef状态管理
|
||||
|
||||
`appIconsRef` 是一个 `ref` 类型的响应式数组，存储所有桌面应用图标的配置信息。每个图标对象遵循 `IDesktopAppIcon` 接口规范：
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
IDesktopAppIcon {
|
||||
string name PK
|
||||
string icon
|
||||
string path
|
||||
int x
|
||||
int y
|
||||
}
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L1-L15)
|
||||
|
||||
初始图标数据来源于两个渠道：
|
||||
1. 当前运行的应用进程列表（模拟为空数组）
|
||||
2. `localStorage` 中保存的历史图标位置信息
|
||||
|
||||
系统优先使用历史记录中的坐标，若无则按顺序自动分配。
|
||||
|
||||
### localStorage持久化机制
|
||||
|
||||
通过 `watch` 监听器实现自动持久化：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[appIconsRef变化] --> B{触发watch}
|
||||
B --> C[序列化为JSON字符串]
|
||||
C --> D[存入localStorage]
|
||||
D --> E[键名为'desktopAppIconInfo']
|
||||
```
|
||||
|
||||
同时，在初始化时从 `localStorage` 读取已有数据，实现跨会话的状态恢复。
|
||||
|
||||
### 图标重排逻辑
|
||||
|
||||
当窗口大小导致网格行列数变化时，`rearrangeIcons` 函数会被调用，执行智能重排算法：
|
||||
|
||||
1. 优先保留原有有效位置的图标
|
||||
2. 为移出可视区域的图标寻找新的空闲位置
|
||||
3. 若无足够空间，则将其加入 `exceedApp` 隐藏列表
|
||||
|
||||
该机制确保用户体验的一致性，避免图标因窗口缩放而丢失。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L60-L94)
|
||||
|
||||
## 模板渲染与事件处理
|
||||
|
||||
### v-for循环渲染机制
|
||||
|
||||
组件模板使用 `v-for` 指令遍历 `appIconsRef` 数组，为每个图标实例化一个 `AppIcon` 子组件：
|
||||
|
||||
```vue
|
||||
<AppIcon
|
||||
v-for="(appIcon, i) in appIconsRef"
|
||||
:key="i"
|
||||
:iconInfo="appIcon"
|
||||
:gridTemplate="gridTemplate"
|
||||
@dblclick="runApp(appIcon)"
|
||||
/>
|
||||
```
|
||||
|
||||
`:key` 使用索引值确保渲染性能，`iconInfo` 和 `gridTemplate` 作为 props 向下传递必要数据。
|
||||
|
||||
### runApp双击事件扩展点
|
||||
|
||||
`@dblclick` 事件绑定到 `runApp` 方法，目前为空实现，作为未来功能扩展的预留接口：
|
||||
|
||||
```typescript
|
||||
const runApp = (appIcon: IDesktopAppIcon) => {}
|
||||
```
|
||||
|
||||
此处可集成应用启动逻辑，如进程管理器调用、窗口创建等。
|
||||
|
||||
### AppIcon组件协同
|
||||
|
||||
`AppIcon` 组件接收父级传递的 `gridTemplate` 参数，结合自身 `x/y` 坐标计算绝对位置：
|
||||
|
||||
```css
|
||||
grid-column: ${x}/${x + 1};
|
||||
grid-row: ${y}/${y + 1};
|
||||
```
|
||||
|
||||
并实现拖拽功能，在释放时根据鼠标位置更新坐标，形成闭环控制。
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
|
||||
## 与父组件的数据流关系
|
||||
|
||||
### 挂载关系分析
|
||||
|
||||
`DesktopContainer` 被直接嵌入 `App.vue` 的模板结构中，位于 `.desktop-bg` 容器内部：
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[App.vue] --> B[desktop-root]
|
||||
B --> C[desktop-bg]
|
||||
C --> D[DesktopContainer]
|
||||
B --> E[task-bar]
|
||||
```
|
||||
|
||||
这种层级结构明确了其作为主内容区核心组件的地位。
|
||||
|
||||
### 数据流路径
|
||||
|
||||
数据流动遵循典型的 Vue 单向数据流模式：
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[onMounted Hook] --> B[查询DOM容器]
|
||||
B --> C[启动ResizeObserver]
|
||||
C --> D[触发尺寸计算]
|
||||
D --> E[更新gridTemplate]
|
||||
E --> F[computed生成gridStyle]
|
||||
F --> G[模板应用样式]
|
||||
H[localStorage读取] --> I[初始化appIconsRef]
|
||||
I --> J[渲染AppIcon列表]
|
||||
J --> K[用户交互]
|
||||
K --> L[更新appIconsRef]
|
||||
L --> M[watch触发持久化]
|
||||
```
|
||||
|
||||
整个过程无需向上通信，完全由组合式函数内部闭环处理。
|
||||
|
||||
**Section sources**
|
||||
- [App.vue](file://src/ui/App.vue#L1-L52)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
|
||||
## 自定义容器集成示例
|
||||
|
||||
要在其他环境中复用 `DesktopContainer`，可通过修改 `containerStr` 参数指定不同的监听目标：
|
||||
|
||||
```typescript
|
||||
// 在自定义组件中使用
|
||||
const { appIconsRef, gridStyle, gridTemplate } = useDesktopContainerInit('#custom-desktop-container')
|
||||
```
|
||||
|
||||
对应的 HTML 结构需包含匹配的选择器：
|
||||
|
||||
```html
|
||||
<div id="custom-desktop-container" :style="gridStyle">
|
||||
<!-- AppIcon will be rendered here -->
|
||||
</div>
|
||||
```
|
||||
|
||||
注意确保目标元素具有明确的尺寸（宽高），否则 `ResizeObserver` 无法正确计算布局参数。此外，建议保持原有的 CSS 类名以继承样式定义。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
254
.qoder/repowiki/zh/content/UI组件体系/UI组件体系.md
Normal file
254
.qoder/repowiki/zh/content/UI组件体系/UI组件体系.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# UI组件体系
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
- [App.vue](file://src/ui/App.vue)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心数据模型](#核心数据模型)
|
||||
3. [主容器布局机制](#主容器布局机制)
|
||||
4. [可拖拽图标实现](#可拖拽图标实现)
|
||||
5. [组件层级与数据流](#组件层级与数据流)
|
||||
6. [模板使用示例](#模板使用示例)
|
||||
7. [自定义扩展建议](#自定义扩展建议)
|
||||
|
||||
## 简介
|
||||
本文档深入解析Vue桌面应用的UI组件结构与交互逻辑。重点阐述`DesktopContainer.vue`作为主容器的动态网格布局机制，以及`AppIcon.vue`如何实现可拖拽的应用图标功能。通过分析`IDesktopAppIcon`和`IGridTemplateParams`接口定义，说明图标数据模型和网格参数的设计原理。同时解释从根组件`App.vue`到子组件`DesktopContainer`再到`AppIcon`的父子关系及数据传递方式，并提供实际使用示例与扩展建议。
|
||||
|
||||
## 核心数据模型
|
||||
|
||||
### 桌面应用图标接口 (IDesktopAppIcon)
|
||||
该接口定义了桌面图标的元数据结构，包含名称、图标资源路径、启动路径及其在网格中的位置坐标。
|
||||
|
||||
```typescript
|
||||
export interface IDesktopAppIcon {
|
||||
name: string;
|
||||
icon: string;
|
||||
path: string;
|
||||
x: number;
|
||||
y: number;
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `name`: 图标显示名称
|
||||
- `icon`: 图标资源路径
|
||||
- `path`: 应用启动路径
|
||||
- `x`: 在网格布局中的列索引（从1开始）
|
||||
- `y`: 在网格布局中的行索引（从1开始）
|
||||
|
||||
此接口用于统一管理所有桌面图标的配置信息，并支持持久化存储至`localStorage`。
|
||||
|
||||
### 网格模板参数接口 (IGridTemplateParams)
|
||||
该接口定义了网格布局的核心计算参数，支持响应式调整。
|
||||
|
||||
```typescript
|
||||
export interface IGridTemplateParams {
|
||||
readonly cellExpectWidth: number
|
||||
readonly cellExpectHeight: number
|
||||
cellRealWidth: number
|
||||
cellRealHeight: number
|
||||
gapX: number
|
||||
gapY: number
|
||||
colCount: number
|
||||
rowCount: number
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
- `cellExpectWidth/Height`: 单元格预设宽高
|
||||
- `cellRealWidth/Height`: 实际渲染时的单元格宽高
|
||||
- `gapX/Y`: 列/行间距
|
||||
- `colCount/rowCount`: 当前容器可容纳的总行列数
|
||||
|
||||
这些参数由`ResizeObserver`监听容器尺寸变化后动态计算得出，确保布局自适应。
|
||||
|
||||
**Section sources**
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L3-L14)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L3-L20)
|
||||
|
||||
## 主容器布局机制
|
||||
|
||||
`DesktopContainer.vue`组件负责构建整个桌面的网格布局系统。其核心是通过组合式API `useDesktopContainerInit` 初始化并维护网格状态。
|
||||
|
||||
### 响应式网格生成
|
||||
组件利用CSS Grid布局特性，通过计算属性`gridStyle`动态生成`grid-template-columns`和`grid-template-rows`样式规则：
|
||||
|
||||
```css
|
||||
gridTemplateColumns: `repeat(${gridTemplate.colCount}, minmax(${gridTemplate.cellExpectWidth}px, 1fr))`
|
||||
```
|
||||
|
||||
### 容器尺寸监听
|
||||
使用`ResizeObserver` API实时监听`.desktop-icons-container`容器的尺寸变化，重新计算：
|
||||
- 可容纳的行列数量 (`colCount`, `rowCount`)
|
||||
- 单元格实际尺寸 (`cellRealWidth`, `cellRealHeight`)
|
||||
|
||||
### 图标初始化与持久化
|
||||
首次加载时从`localStorage`读取历史图标位置信息，结合应用列表进行映射初始化。当图标位置变更时自动同步回本地存储。
|
||||
|
||||
### 超出边界处理
|
||||
当窗口缩放导致图标超出可视区域时，`rearrangeIcons`函数会智能重排图标：
|
||||
- 优先放置于原始位置
|
||||
- 若冲突则寻找最近空位
|
||||
- 实在无法容纳则暂存于`exceedApp`数组
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([组件挂载]) --> Observe["创建ResizeObserver"]
|
||||
Observe --> InitGrid["初始化网格参数"]
|
||||
InitGrid --> LoadStorage["从localStorage加载图标位置"]
|
||||
LoadStorage --> MapIcons["映射应用信息与图标"]
|
||||
MapIcons --> Render["渲染AppIcon组件"]
|
||||
Resize["容器尺寸变化"] --> Recalculate["重新计算行列数"]
|
||||
Recalculate --> Rearrange["调用rearrangeIcons重排"]
|
||||
Rearrange --> UpdateState["更新appIconsRef状态"]
|
||||
UpdateState --> SyncStorage["同步至localStorage"]
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## 可拖拽图标实现
|
||||
|
||||
`AppIcon.vue`组件实现了完整的拖拽交互逻辑，允许用户自由调整图标位置。
|
||||
|
||||
### 拖拽事件绑定
|
||||
在模板中为图标容器启用原生HTML5拖拽API：
|
||||
```html
|
||||
<div draggable="true" @dragstart="onDragStart" @dragend="onDragEnd">
|
||||
```
|
||||
|
||||
### 位置计算逻辑
|
||||
在`dragend`事件中执行以下步骤：
|
||||
1. 获取鼠标相对于容器的坐标
|
||||
2. 根据单元格实际尺寸换算为网格坐标（向上取整）
|
||||
3. 更新`iconInfo.x`和`iconInfo.y`属性
|
||||
|
||||
### 防止重复放置
|
||||
通过检查目标元素是否已是其他图标容器来避免无效操作：
|
||||
```javascript
|
||||
if (pointTarget.classList.contains('icon-container')) return
|
||||
```
|
||||
|
||||
### 样式定位
|
||||
使用CSS Grid的`grid-column`和`grid-row`属性将图标精确定位于指定网格单元：
|
||||
```css
|
||||
grid-column: ${x}/${x + 1}; grid-row: ${y}/${y + 1}
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
|
||||
## 组件层级与数据流
|
||||
|
||||
整个UI体系遵循清晰的父子组件层级结构，数据沿树状结构单向流动。
|
||||
|
||||
### 组件层级关系
|
||||
```mermaid
|
||||
graph TD
|
||||
A[App.vue] --> B[DesktopContainer.vue]
|
||||
B --> C[AppIcon.vue]
|
||||
```
|
||||
|
||||
### 数据传递路径
|
||||
1. **App.vue** → **DesktopContainer.vue**: 通过直接嵌入`<DesktopContainer/>`标签建立父子关系
|
||||
2. **DesktopContainer.vue** → **AppIcon.vue**:
|
||||
- 使用`v-for`遍历`appIconsRef`数组创建多个实例
|
||||
- 通过`defineProps`接收`iconInfo`和`gridTemplate`两个关键参数
|
||||
- 绑定双击事件`@dblclick="runApp"`实现应用启动
|
||||
|
||||
### 状态管理特点
|
||||
- **集中式初始化**：所有状态在`useDesktopContainerInit`中统一创建
|
||||
- **响应式驱动**：基于Vue的`ref`和`reactive`实现自动更新
|
||||
- **本地持久化**：重要状态如图标位置通过`localStorage`保存
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant App as App.vue
|
||||
participant DC as DesktopContainer.vue
|
||||
participant AI as AppIcon.vue
|
||||
App->>DC : 渲染组件
|
||||
DC->>DC : 执行useDesktopContainerInit()
|
||||
DC->>DC : 初始化gridTemplate/appIconsRef
|
||||
DC->>AI : v-for循环渲染多个实例
|
||||
DC->>AI : 传递iconInfo和gridTemplate props
|
||||
AI->>AI : 用户拖拽图标
|
||||
AI->>AI : 计算新坐标并更新iconInfo
|
||||
AI->>DC : 触发watch监听
|
||||
DC->>DC : 同步至localStorage
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [App.vue](file://src/ui/App.vue#L1-L52)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
|
||||
**Section sources**
|
||||
- [App.vue](file://src/ui/App.vue#L1-L52)
|
||||
|
||||
## 模板使用示例
|
||||
|
||||
以下是如何在项目中正确使用这些组件的标准范例：
|
||||
|
||||
```vue
|
||||
<!-- 在任意父组件中引入DesktopContainer -->
|
||||
<template>
|
||||
<div class="desktop-wrapper">
|
||||
<DesktopContainer />
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script setup lang="ts">
|
||||
import DesktopContainer from '@/ui/desktop-container/DesktopContainer.vue'
|
||||
</script>
|
||||
```
|
||||
|
||||
每个`AppIcon`实例由`DesktopContainer`内部自动创建，无需手动实例化。只需确保：
|
||||
1. 应用列表数据已正确注入`useDesktopContainerInit`
|
||||
2. 图标资源配置路径准确无误
|
||||
3. localStorage中保留历史位置记录以实现记忆功能
|
||||
|
||||
## 自定义扩展建议
|
||||
|
||||
### 样式定制
|
||||
可通过覆盖SCSS变量或添加自定义类名修改图标外观：
|
||||
```scss
|
||||
.icon-container {
|
||||
@apply bg-transparent hover:bg-blue-100;
|
||||
border-radius: 8px;
|
||||
}
|
||||
```
|
||||
|
||||
### 功能增强
|
||||
- 添加右键菜单支持
|
||||
- 实现图标排序功能（按名称、时间等）
|
||||
- 增加动画过渡效果（拖拽、进入/离开）
|
||||
|
||||
### 性能优化
|
||||
- 对大量图标实施虚拟滚动
|
||||
- 使用Web Worker处理复杂重排算法
|
||||
- 添加防抖机制优化频繁resize场景
|
||||
|
||||
### 接口拓展
|
||||
可继承`IDesktopAppIcon`接口增加新字段：
|
||||
```typescript
|
||||
interface ExtendedIcon extends IDesktopAppIcon {
|
||||
tooltip?: string;
|
||||
category?: 'productivity' | 'entertainment' | 'development';
|
||||
lastLaunched?: Date;
|
||||
}
|
||||
```
|
||||
|
||||
以上扩展应在保持原有接口兼容性的前提下进行，确保不影响现有功能。
|
||||
262
.qoder/repowiki/zh/content/事件系统/事件系统.md
Normal file
262
.qoder/repowiki/zh/content/事件系统/事件系统.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# 事件系统
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心组件分析](#核心组件分析)
|
||||
3. [接口契约规范](#接口契约规范)
|
||||
4. [事件管理器扩展实现](#事件管理器扩展实现)
|
||||
5. [跨组件通信实例](#跨组件通信实例)
|
||||
6. [错误处理与内存泄漏防范](#错误处理与内存泄漏防范)
|
||||
|
||||
## 简介
|
||||
本文档全面记录了自定义事件总线系统的实现原理与使用方法。基于 `EventBuilderImpl` 类，详细解释 `addEventListener`、`removeEventListener` 和 `notifyEvent` 三个核心方法的工作机制，包括 `once`、`immediate` 等选项的行为特征。文档描述了 `IEventBuilder` 接口的契约规范，并分析了 `DesktopEventManager` 和 `WindowFormEventManager` 如何继承和扩展基础事件功能。同时提供跨组件通信的实际用例，并说明错误处理和内存泄漏防范措施。
|
||||
|
||||
## 核心组件分析
|
||||
|
||||
### EventBuilderImpl 实现机制
|
||||
|
||||
`EventBuilderImpl` 是事件总线系统的核心实现类，采用泛型设计支持类型安全的事件管理。其内部通过 `Map<keyof Events, Set<HandlerWrapper<Events[keyof Events]>>>` 结构存储事件处理器，确保高效的事件查找与去重。
|
||||
|
||||
#### addEventListener 方法工作机制
|
||||
该方法用于注册事件监听器，具有以下特性：
|
||||
- **去重机制**：在添加前检查是否已存在相同处理器函数，避免重复绑定
|
||||
- **即时执行**：当 `options.immediate` 为 `true` 时，立即同步执行一次处理器
|
||||
- **单次监听**：通过 `options.once` 标记，使监听器在触发后自动移除
|
||||
- **类型安全**：利用 TypeScript 泛型约束确保事件名与处理器参数类型匹配
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> ValidateHandler["验证处理器非空"]
|
||||
ValidateHandler --> HasEvent{"是否存在事件队列?"}
|
||||
HasEvent --> |否| CreateSet["创建新的处理器集合"]
|
||||
CreateSet --> AddToSet
|
||||
HasEvent --> |是| GetSet["获取现有集合"]
|
||||
GetSet --> AddToSet
|
||||
AddToSet --> CheckDuplicate{"是否已存在?"}
|
||||
CheckDuplicate --> |否| AddWrapper["添加包装器(once标记)"]
|
||||
AddWrapper --> CheckImmediate{"是否立即执行?"}
|
||||
CheckImmediate --> |是| ExecuteNow["立即执行处理器"]
|
||||
CheckImmediate --> |否| End([结束])
|
||||
ExecuteNow --> End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L20-L46)
|
||||
|
||||
#### removeEventListener 方法工作机制
|
||||
该方法通过遍历对应事件的处理器集合，精确匹配并删除指定的处理器函数引用，实现精准解绑。
|
||||
|
||||
#### notifyEvent 方法工作机制
|
||||
通知方法按顺序调用所有注册的处理器，并处理以下特殊情况：
|
||||
- 自动清理标记为 `once` 的监听器
|
||||
- 捕获并记录处理器执行中的异常，防止中断其他监听器
|
||||
- 支持任意数量的参数传递
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Publisher as "发布者"
|
||||
participant EventBus as "EventBus"
|
||||
participant Handler1 as "处理器1"
|
||||
participant Handler2 as "处理器2"
|
||||
Publisher->>EventBus : notifyEvent('event', args)
|
||||
EventBus->>EventBus : 获取处理器集合
|
||||
loop 每个处理器
|
||||
EventBus->>Handler1 : 执行处理器
|
||||
Handler1-->>EventBus : 完成
|
||||
EventBus->>EventBus : 检查once标记
|
||||
alt 是单次监听
|
||||
EventBus->>EventBus : 从集合中移除
|
||||
end
|
||||
EventBus->>Handler2 : 执行处理器
|
||||
Handler2-->>EventBus : 完成
|
||||
end
|
||||
EventBus-->>Publisher : 通知完成
|
||||
Note over Handler1,Handler2 : 异常被捕获，不影响其他处理器执行
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L75-L90)
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
## 接口契约规范
|
||||
|
||||
### IEventBuilder 接口定义
|
||||
`IEventBuilder` 接口定义了事件管理器的标准行为契约，继承自 `IDestroyable` 接口以支持资源清理。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IEventBuilder {
|
||||
<<interface>>
|
||||
+addEventListener(eventName, handler, options) : void
|
||||
+removeEventListener(eventName, handler) : void
|
||||
+notifyEvent(eventName, ...args) : void
|
||||
}
|
||||
class IDestroyable {
|
||||
<<interface>>
|
||||
+destroy() : void
|
||||
}
|
||||
IEventBuilder --|> IDestroyable : 继承
|
||||
class EventBuilderImpl {
|
||||
-_eventHandlers : Map<string, Set<HandlerWrapper>>
|
||||
+addEventListener()
|
||||
+removeEventListener()
|
||||
+notifyEvent()
|
||||
+destroy()
|
||||
}
|
||||
EventBuilderImpl ..|> IEventBuilder : 实现
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts#L13-L46)
|
||||
|
||||
接口方法参数说明：
|
||||
|
||||
| 方法 | 参数 | 类型 | 描述 |
|
||||
|------|------|------|------|
|
||||
| addEventListener | eventName | keyof Events | 事件名称 |
|
||||
| | handler | F extends Events[E] | 事件处理器函数 |
|
||||
| | options | {immediate?: boolean, immediateArgs?: Parameters<F>, once?: boolean} | 配置选项 |
|
||||
| removeEventListener | eventName | keyof Events | 事件名称 |
|
||||
| | handler | F extends Events[E] | 要移除的处理器函数 |
|
||||
| notifyEvent | eventName | keyof Events | 事件名称 |
|
||||
| | ...args | Parameters<F> | 传递给处理器的参数 |
|
||||
|
||||
**Section sources**
|
||||
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts#L1-L46)
|
||||
|
||||
## 事件管理器扩展实现
|
||||
|
||||
### DesktopEventManager 桌面事件管理
|
||||
`DesktopEventManager` 通过实例化 `EventBuilderImpl<IDesktopEvent>` 创建专用的桌面事件总线，定义了桌面应用相关的特定事件类型。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IDesktopEvent {
|
||||
<<interface>>
|
||||
+desktopAppPosChange(info : IDesktopAppIcon) : void
|
||||
}
|
||||
class desktopEM {
|
||||
+instance of EventBuilderImpl<IDesktopEvent>
|
||||
}
|
||||
desktopEM ..> IDesktopEvent : 类型约束
|
||||
desktopEM ..> EventBuilderImpl : 实例化
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L1-L16)
|
||||
|
||||
### WindowFormEventManager 窗口表单事件管理
|
||||
`WindowFormEventManager` 提供了窗口生命周期管理的完整事件体系，涵盖最小化、最大化、关闭、聚焦等状态变化。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IWindowFormEvent {
|
||||
<<interface>>
|
||||
+windowFormMinimize(id : string) : void
|
||||
+windowFormMaximize(id : string) : void
|
||||
+windowFormRestore(id : string) : void
|
||||
+windowFormClose(id : string) : void
|
||||
+windowFormFocus(id : string) : void
|
||||
+windowFormDataUpdate(data : IWindowFormDataUpdateParams) : void
|
||||
+windowFormCreated() : void
|
||||
}
|
||||
class wfem {
|
||||
+instance of EventBuilderImpl<IWindowFormEvent>
|
||||
}
|
||||
class IWindowFormDataUpdateParams {
|
||||
+id : string
|
||||
+state : TWindowFormState
|
||||
+width : number
|
||||
+height : number
|
||||
+x : number
|
||||
+y : number
|
||||
}
|
||||
wfem ..> IWindowFormEvent : 类型约束
|
||||
IWindowFormEvent ..> IWindowFormDataUpdateParams : 引用
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L1-L61)
|
||||
|
||||
**Section sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L1-L16)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L1-L61)
|
||||
|
||||
## 跨组件通信实例
|
||||
|
||||
### 桌面应用位置更新场景
|
||||
```typescript
|
||||
// 发布者组件
|
||||
const updatePosition = (iconInfo) => {
|
||||
desktopEM.notifyEvent('desktopAppPosChange', iconInfo)
|
||||
}
|
||||
|
||||
// 订阅者组件
|
||||
desktopEM.addEventListener('desktopAppPosChange', (info) => {
|
||||
console.log('应用位置更新:', info.name, info.x, info.y)
|
||||
}, {
|
||||
immediate: true,
|
||||
immediateArgs: [currentIconInfo]
|
||||
})
|
||||
```
|
||||
|
||||
### 窗口状态变更场景
|
||||
```typescript
|
||||
// 窗口最小化
|
||||
wfem.notifyEvent('windowFormMinimize', 'win123')
|
||||
|
||||
// 监听窗口最小化（仅一次）
|
||||
wfem.addEventListener('windowFormMinimize', (id) => {
|
||||
addToTaskbar(id)
|
||||
}, {
|
||||
once: true
|
||||
})
|
||||
|
||||
// 监听所有窗口数据更新
|
||||
wfem.addEventListener('windowFormDataUpdate', (data) => {
|
||||
saveWindowState(data)
|
||||
})
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L1-L16)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L1-L61)
|
||||
|
||||
## 错误处理与内存泄漏防范
|
||||
|
||||
### 错误处理机制
|
||||
系统在关键执行路径上均包含异常捕获：
|
||||
- 处理器执行时捕获异常，防止中断其他监听器
|
||||
- 控制台输出错误信息便于调试
|
||||
- 不抛出异常保证事件总线稳定性
|
||||
|
||||
### 内存泄漏防范措施
|
||||
1. **及时解绑**：使用 `removeEventListener` 移除不再需要的监听器
|
||||
2. **单次监听**：对只需执行一次的逻辑使用 `once: true` 选项
|
||||
3. **资源清理**：实现 `destroy()` 方法清空所有事件处理器
|
||||
4. **实例管理**：通过单例模式管理事件总线实例生命周期
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[组件挂载] --> B[添加事件监听]
|
||||
B --> C[设置once或immediate]
|
||||
C --> D[组件运行]
|
||||
D --> E{组件卸载?}
|
||||
E --> |是| F[调用removeEventListener]
|
||||
F --> G[或调用destroy清理所有]
|
||||
G --> H[防止内存泄漏]
|
||||
E --> |否| D
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L92-L94)
|
||||
207
.qoder/repowiki/zh/content/事件系统/核心事件总线.md
Normal file
207
.qoder/repowiki/zh/content/事件系统/核心事件总线.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# 核心事件总线
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts)
|
||||
- [IDestroyable.ts](file://src/common/types/IDestroyable.ts)
|
||||
- [EventManager.ts](file://src/events/EventManager.ts)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心数据结构设计](#核心数据结构设计)
|
||||
3. [泛型类型安全机制](#泛型类型安全机制)
|
||||
4. [事件监听器管理](#事件监听器管理)
|
||||
- [addEventListener 方法详解](#addeventlistener-方法详解)
|
||||
- [removeEventListener 方法详解](#removeeventlistener-方法详解)
|
||||
5. [事件通知与分发](#事件通知与分发)
|
||||
6. [资源清理与内存泄漏防范](#资源清理与内存泄漏防范)
|
||||
7. [实际应用示例](#实际应用示例)
|
||||
8. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
|
||||
`EventBuilderImpl` 类是本系统事件机制的核心实现，提供了一个类型安全、功能完整的事件总线系统。该类实现了 `IEventBuilder` 接口，遵循发布-订阅模式，支持事件的注册、移除和触发，并具备立即执行、一次性监听等高级特性。通过继承 `IDestroyable` 接口，它还提供了资源清理能力，有效防止内存泄漏。
|
||||
|
||||
该事件系统被多个模块广泛使用，包括全局事件管理器（`eventManager`）、桌面事件管理器（`desktopEM`）和窗口表单事件管理器（`wfem`），构成了整个应用的通信骨架。
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts#L13-L46)
|
||||
- [IDestroyable.ts](file://src/common/types/IDestroyable.ts#L4-L7)
|
||||
|
||||
## 核心数据结构设计
|
||||
|
||||
`EventBuilderImpl` 采用 `Map` 和 `Set` 的组合来高效管理事件监听器，这种设计在性能和内存使用上达到了良好的平衡。
|
||||
|
||||
其核心是一个私有成员 `_eventHandlers`，其类型为 `Map<keyof Events, Set<HandlerWrapper<Events[keyof Events]>>>`。这个数据结构的含义是：
|
||||
- **外层 Map**：以事件名称（`keyof Events`）作为键，确保每个事件名对应一个独立的监听器集合。
|
||||
- **内层 Set**：存储特定事件的所有监听器包装对象（`HandlerWrapper`）。使用 `Set` 而非数组可以天然避免重复添加同一个监听函数，并且插入和删除操作的时间复杂度为 O(1)。
|
||||
|
||||
`HandlerWrapper` 是一个简单的接口，包含两个属性：`fn`（原始的监听函数）和 `once`（布尔值，标记是否为一次性监听器）。这种包装方式将业务逻辑（函数本身）与元数据（如 `once` 标志）分离，使得事件管理更加灵活。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class EventBuilderImpl~Events~ {
|
||||
-_eventHandlers : Map~keyof Events, Set~HandlerWrapper~Events[keyof Events]~~~
|
||||
+addEventListener()
|
||||
+removeEventListener()
|
||||
+notifyEvent()
|
||||
+destroy()
|
||||
}
|
||||
class HandlerWrapper~T~ {
|
||||
+fn : T
|
||||
+once : boolean
|
||||
}
|
||||
EventBuilderImpl --> "0..*" HandlerWrapper : 包含
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L15)
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L15)
|
||||
|
||||
## 泛型类型安全机制
|
||||
|
||||
`EventBuilderImpl` 类通过 TypeScript 的泛型系统实现了严格的类型安全。其定义为 `class EventBuilderImpl<Events extends IEventMap>`，其中 `Events` 是一个必须符合 `IEventMap` 接口约束的泛型类型。
|
||||
|
||||
`IEventMap` 接口定义了事件映射的基本结构：一个索引签名 `[key: string]: (...args: any[]) => void`，表示键是字符串类型的事件名，值是任意参数的无返回值函数。
|
||||
|
||||
当实例化 `EventBuilderImpl` 时，需要传入一个具体的事件接口。例如，在 `WindowFormEventManager.ts` 中定义了 `IWindowFormEvent` 接口，并将其作为泛型参数：
|
||||
|
||||
```typescript
|
||||
export const wfem = new EventBuilderImpl<IWindowFormEvent>()
|
||||
```
|
||||
|
||||
这种设计带来了以下优势：
|
||||
1. **编译时检查**：在调用 `addEventListener` 或 `notifyEvent` 时，TypeScript 编译器会根据 `IWindowFormEvent` 的定义检查事件名和参数类型是否正确。
|
||||
2. **智能提示**：开发者在编写代码时能获得准确的事件名和参数类型提示。
|
||||
3. **防止错误**：无法订阅未在接口中定义的事件，也无法传递错误类型的参数。
|
||||
|
||||
**Section sources**
|
||||
- [IEventBuilder.ts](file://src/events/IEventBuilder.ts#L4-L7)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L5-L59)
|
||||
|
||||
## 事件监听器管理
|
||||
|
||||
### addEventListener 方法详解
|
||||
|
||||
`addEventListener` 方法用于向事件总线注册新的监听器。它接收三个参数：事件名、处理函数和可选的配置项。
|
||||
|
||||
#### 配置项行为逻辑
|
||||
- **immediate (立即执行)**：如果设置为 `true`，则在添加监听器后立即同步执行一次该函数。
|
||||
- **immediateArgs (立即执行参数)**：为 `immediate` 执行阶段提供参数。若未指定，则使用空数组。
|
||||
- **once (一次性监听)**：如果设置为 `true`，则该监听器在第一次被触发后自动从事件队列中移除。
|
||||
|
||||
#### 实现细节
|
||||
1. **空值检查**：首先检查 `handler` 是否存在，避免无效监听器。
|
||||
2. **惰性初始化**：如果这是该事件的第一个监听器，则创建一个新的 `Set` 来存放后续的 `HandlerWrapper`。
|
||||
3. **去重机制**：在添加前，通过遍历 `Set` 并比较 `wrapper.fn === handler` 来确保不会重复添加相同的函数引用。
|
||||
4. **异常捕获**：在执行 `immediate` 回调时，使用 `try-catch` 捕获任何可能抛出的异常，并将其输出到控制台，防止因单个监听器的错误而中断主流程。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始]) --> CheckHandler["检查 handler 是否为空"]
|
||||
CheckHandler --> |否| InitSet["检查事件对应的 Set 是否存在"]
|
||||
InitSet --> |否| CreateSet["创建新的 Set"]
|
||||
CreateSet --> GetSet["获取事件对应的 Set"]
|
||||
InitSet --> |是| GetSet
|
||||
GetSet --> CheckDuplicate["检查是否已存在相同 handler"]
|
||||
CheckDuplicate --> |否| AddWrapper["添加 HandlerWrapper 到 Set"]
|
||||
AddWrapper --> CheckImmediate["检查 immediate 选项"]
|
||||
CheckImmediate --> |是| ExecuteNow["立即执行 handler"]
|
||||
ExecuteNow --> End([结束])
|
||||
CheckImmediate --> |否| End
|
||||
CheckHandler --> |是| End
|
||||
CheckDuplicate --> |是| End
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L20-L46)
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L20-L46)
|
||||
|
||||
### removeEventListener 方法详解
|
||||
|
||||
`removeEventListener` 方法负责从事件队列中移除指定的监听器。
|
||||
|
||||
其实现的关键在于**引用比对去重机制**。由于监听器是以 `HandlerWrapper` 对象的形式存储在 `Set` 中的，直接比较 `Set` 中的对象与传入的 `handler` 函数是不相等的。因此，该方法会遍历 `Set` 中的每一个 `wrapper`，并使用 `wrapper.fn === handler` 来精确匹配原始的函数引用。
|
||||
|
||||
一旦找到匹配项，就调用 `set.delete(wrapper)` 将其从 `Set` 中移除。这种基于引用的比对确保了只有完全相同的函数实例才会被移除，保证了操作的准确性。
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L55-L64)
|
||||
|
||||
## 事件通知与分发
|
||||
|
||||
`notifyEvent` 方法是事件系统的触发点，负责通知所有订阅了特定事件的监听器。
|
||||
|
||||
其工作流程如下：
|
||||
1. **存在性检查**：首先检查是否存在该事件名对应的监听器集合，若不存在则直接返回。
|
||||
2. **批量通知**：遍历该事件名对应 `Set` 中的所有 `HandlerWrapper`。
|
||||
3. **异常捕获**：在调用每个监听器的 `fn(...args)` 时，使用 `try-catch` 块包裹，确保单个监听器的错误不会影响其他监听器的执行。
|
||||
4. **once 监听器清理**：在成功调用一个监听器后，检查其 `once` 标志。如果为 `true`，则立即将其从 `Set` 中删除，实现一次性监听的功能。
|
||||
|
||||
这种“先通知，后清理”的策略保证了即使在 `once` 监听器执行过程中有其他代码尝试移除它，也不会产生竞态条件。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Publisher as 事件发布者
|
||||
participant EventBus as EventBuilderImpl
|
||||
participant ListenerA as 监听器 A (once : true)
|
||||
participant ListenerB as 监听器 B (once : false)
|
||||
Publisher->>EventBus : notifyEvent('click', x, y)
|
||||
EventBus->>ListenerA : 执行 fn(x, y)
|
||||
ListenerA-->>EventBus : 完成
|
||||
EventBus->>EventBus : 检查 wrapper.once == true
|
||||
EventBus->>EventBus : 从 Set 中删除 ListenerA
|
||||
EventBus->>ListenerB : 执行 fn(x, y)
|
||||
ListenerB-->>EventBus : 完成
|
||||
EventBus-->>Publisher : 通知完成
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L75-L90)
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L75-L90)
|
||||
|
||||
## 资源清理与内存泄漏防范
|
||||
|
||||
`EventBuilderImpl` 通过多种策略有效防范内存泄漏：
|
||||
|
||||
1. **显式销毁接口**：通过实现 `IDestroyable` 接口，提供了 `destroy()` 方法。调用此方法会清空 `_eventHandlers` Map，释放所有对监听器函数的引用，使它们可以被垃圾回收器回收。这对于长生命周期的应用或动态创建/销毁的组件至关重要。
|
||||
|
||||
2. **监听器去重**：`addEventListener` 方法中的去重逻辑防止了同一函数被多次添加，避免了不必要的内存占用和重复执行。
|
||||
|
||||
3. **once 监听器自动清理**：`once` 选项确保了一次性监听器在执行后立即被移除，无需手动清理。
|
||||
|
||||
4. **异常隔离**：`try-catch` 机制保证了事件分发过程的健壮性，防止因监听器内部错误导致整个事件系统崩溃。
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L92-L94)
|
||||
- [IDestroyable.ts](file://src/common/types/IDestroyable.ts#L4-L7)
|
||||
|
||||
## 实际应用示例
|
||||
|
||||
以下是 `EventBuilderImpl` 在项目中的具体应用实例：
|
||||
|
||||
- **全局事件管理器**：在 `EventManager.ts` 中，`eventManager` 实例被用来管理认证状态改变 (`onAuthChange`) 和主题切换 (`onThemeChange`) 等全局事件。
|
||||
- **桌面事件管理器**：在 `DesktopEventManager.ts` 中，`desktopEM` 实例用于响应桌面应用图标位置的变化 (`desktopAppPosChange`)。
|
||||
- **窗口表单事件管理器**：在 `WindowFormEventManager.ts` 中，`wfem` 实例监控窗口的最小化、最大化、关闭等生命周期事件。
|
||||
|
||||
这些预定义的事件管理器实例化了 `EventBuilderImpl`，并通过具体的事件接口（如 `IWindowFormEvent`）锁定了可用的事件集，为不同模块提供了清晰、类型安全的通信契约。
|
||||
|
||||
**Section sources**
|
||||
- [EventManager.ts](file://src/events/EventManager.ts#L3-L34)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L3-L15)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L3-L60)
|
||||
|
||||
## 总结
|
||||
|
||||
`EventBuilderImpl` 作为一个轻量级但功能完备的事件总线实现，通过精心设计的数据结构（`Map`+`Set`）和 TypeScript 泛型，实现了高性能、类型安全的事件管理。其 `addEventListener`、`removeEventListener` 和 `notifyEvent` 方法构成了一个健壮的发布-订阅循环，而 `immediate`、`once` 等选项以及异常捕获机制则增强了其实用性和可靠性。最后，通过 `IDestroyable` 接口提供的 `destroy` 方法，确保了资源的可管理性，有效防止了内存泄漏，是构建可维护前端应用的理想选择。
|
||||
187
.qoder/repowiki/zh/content/事件系统/桌面事件管理器.md
Normal file
187
.qoder/repowiki/zh/content/事件系统/桌面事件管理器.md
Normal file
@@ -0,0 +1,187 @@
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [核心事件总线架构](#核心事件总线架构)
|
||||
3. [桌面事件接口定义](#桌面事件接口定义)
|
||||
4. [事件管理器实例化与类型注入](#事件管理器实例化与类型注入)
|
||||
5. [应用图标位置变化事件语义解析](#应用图标位置变化事件语义解析)
|
||||
6. [桌面容器中的事件监听实践](#桌面容器中的事件监听实践)
|
||||
7. [拖拽结束时的事件发布机制](#拖拽结束时的事件发布机制)
|
||||
8. [总结](#总结)
|
||||
|
||||
## 引言
|
||||
|
||||
本文档详细阐述了`DesktopEventManager`如何基于核心事件总线构建特定领域的事件系统。通过分析`IDesktopEvent`接口、`desktopEM`实例化过程以及在`useDesktopContainerInit`中的实际用例，全面揭示该事件管理器的设计原理与运行机制。
|
||||
|
||||
## 核心事件总线架构
|
||||
|
||||
`DesktopEventManager`并非独立实现事件机制，而是基于一个通用的核心事件总线——`EventBuilderImpl`类进行领域特化。这种设计模式实现了关注点分离：底层提供统一的事件订阅与通知能力，上层定义具体业务语义。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IEventBuilder~Events~ {
|
||||
<<interface>>
|
||||
+addEventListener(eventName, handler, options)
|
||||
+removeEventListener(eventName, handler)
|
||||
+notifyEvent(eventName, ...args)
|
||||
}
|
||||
class EventBuilderImpl~Events~ {
|
||||
-_eventHandlers : Map<keyof Events, Set<HandlerWrapper>>
|
||||
+addEventListener()
|
||||
+removeEventListener()
|
||||
+notifyEvent()
|
||||
+destroy()
|
||||
}
|
||||
class IDesktopEvent {
|
||||
<<interface>>
|
||||
+desktopAppPosChange(info : IDesktopAppIcon)
|
||||
}
|
||||
class DesktopEventManager {
|
||||
+desktopEM : EventBuilderImpl<IDesktopEvent>
|
||||
}
|
||||
EventBuilderImpl --> IEventBuilder : "implements"
|
||||
DesktopEventManager ..> IDesktopEvent : "defines"
|
||||
DesktopEventManager ..> EventBuilderImpl : "instantiates"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L7-L15)
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L7-L15)
|
||||
|
||||
## 桌面事件接口定义
|
||||
|
||||
`IDesktopEvent`接口继承自泛型事件映射接口`IEventMap`，专门用于声明桌面环境下的各类事件。其核心成员是`desktopAppPosChange`事件，明确表达了“桌面应用位置改变”的业务语义。
|
||||
|
||||
该接口采用TypeScript的索引签名与函数类型组合方式，为每个事件名称绑定对应的回调函数签名，确保类型安全。
|
||||
|
||||
**Section sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L7-L12)
|
||||
|
||||
## 事件管理器实例化与类型注入
|
||||
|
||||
`desktopEM`是一个全局单例实例，通过`new EventBuilderImpl<IDesktopEvent>()`创建。此处的关键在于泛型参数`IDesktopEvent`的注入，它将通用的`EventBuilderImpl`约束为仅支持处理`IDesktopEvent`所定义的事件类型。
|
||||
|
||||
这种类型注入机制保证了：
|
||||
- 订阅时只能监听`desktopAppPosChange`等预定义事件
|
||||
- 发布时必须提供符合`IDesktopAppIcon`结构的数据
|
||||
- 编译期即可捕获类型错误，提升代码健壮性
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Code as "源码"
|
||||
participant Compiler as "TypeScript编译器"
|
||||
participant Runtime as "运行时"
|
||||
Code->>Compiler : const desktopEM = new EventBuilderImpl<IDesktopEvent>()
|
||||
Compiler->>Compiler : 类型检查：验证IDesktopEvent结构
|
||||
Compiler-->>Code : 返回类型安全的事件管理器实例
|
||||
Code->>Runtime : desktopEM.addEventListener('desktopAppPosChange', handler)
|
||||
Runtime->>Runtime : 存储事件处理器
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L15-L15)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
**Section sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L15-L15)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
## 应用图标位置变化事件语义解析
|
||||
|
||||
`desktopAppPosChange`事件承载着桌面应用图标位置变更的核心语义。其参数类型`IDesktopAppIcon`精确描述了图标的元数据：
|
||||
|
||||
| 属性 | 类型 | 描述 |
|
||||
|------|------|------|
|
||||
| `name` | string | 图标名称，唯一标识 |
|
||||
| `icon` | string | 图标资源路径或标识符 |
|
||||
| `path` | string | 点击后启动的应用路径 |
|
||||
| `x` | number | 在网格布局中的列索引（从1开始） |
|
||||
| `y` | number | 在网格布局中的行索引（从1开始） |
|
||||
|
||||
当用户拖动图标并释放时，系统会构造包含新坐标(x,y)的`IDesktopAppIcon`对象，并通过`desktopEM.notifyEvent`触发此事件，通知所有监听者更新UI状态。
|
||||
|
||||
**Section sources**
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L11-L11)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L3-L14)
|
||||
|
||||
## 桌面容器中的事件监听实践
|
||||
|
||||
在`useDesktopContainerInit`这一组合式函数中，展示了如何在桌面容器初始化过程中订阅`desktopAppPosChange`事件以实现UI同步更新。
|
||||
|
||||
虽然当前代码未直接展示订阅逻辑，但根据上下文可推断出典型使用模式如下：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["组件挂载 onMounted"] --> B["订阅 desktopAppPosChange 事件"]
|
||||
B --> C["接收 IDesktopAppIcon 数据"]
|
||||
C --> D["更新 appIconsRef 状态"]
|
||||
D --> E["触发 Vue 响应式更新"]
|
||||
E --> F["UI 自动重渲染"]
|
||||
G["图标拖拽结束"] --> H["发布 desktopAppPosChange 事件"]
|
||||
H --> B
|
||||
```
|
||||
|
||||
理想情况下，在`onMounted`钩子内应调用：
|
||||
```ts
|
||||
desktopEM.addEventListener('desktopAppPosChange', (info) => {
|
||||
const index = appIconsRef.value.findIndex(icon => icon.name === info.name);
|
||||
if (index !== -1) {
|
||||
appIconsRef.value[index] = { ...info };
|
||||
}
|
||||
});
|
||||
```
|
||||
从而建立从事件到视图的完整响应链路。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L0-L164)
|
||||
|
||||
## 拖拽结束时的事件发布机制
|
||||
|
||||
`desktopEM`的事件发布时机严格遵循用户交互生命周期。在应用图标的拖拽组件中，应在拖拽结束（dragend）事件处理器中调用：
|
||||
|
||||
```ts
|
||||
desktopEM.notifyEvent('desktopAppPosChange', currentIconInfo);
|
||||
```
|
||||
|
||||
此时传递的`currentIconInfo`必须是完整的`IDesktopAppIcon`对象，包含更新后的`x`和`y`坐标。该调用会遍历所有注册的监听器，并按顺序执行其回调函数，实现多播通知。
|
||||
|
||||
发布流程的关键特性包括：
|
||||
- **同步执行**：所有监听器在同一线程内依次调用
|
||||
- **异常隔离**：单个监听器错误不会中断其他监听器执行
|
||||
- **一次性监听支持**：可通过`once: true`选项注册只触发一次的监听器
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant DragComponent as "拖拽组件"
|
||||
participant DesktopEM as "desktopEM"
|
||||
participant ListenerA as "监听器A"
|
||||
participant ListenerB as "监听器B"
|
||||
DragComponent->>DesktopEM : notifyEvent('desktopAppPosChange', info)
|
||||
DesktopEM->>ListenerA : 执行回调函数
|
||||
ListenerA-->>DesktopEM : 完成
|
||||
DesktopEM->>ListenerB : 执行回调函数
|
||||
ListenerB-->>DesktopEM : 完成
|
||||
DesktopEM-->>DragComponent : 通知完成
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L75-L90)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts#L15-L15)
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L75-L90)
|
||||
|
||||
## 总结
|
||||
|
||||
`DesktopEventManager`通过泛型化继承核心事件总线`EventBuilderImpl`，成功构建了一个类型安全、语义清晰的领域事件系统。`IDesktopEvent`接口明确定义了`desktopAppPosChange`事件及其`IDesktopAppIcon`参数结构，`desktopEM`实例作为全局事件枢纽，在拖拽结束时精准发布坐标变更事件。尽管当前`useDesktopContainerInit`中尚未体现订阅逻辑，但整个架构已为实现响应式桌面UI奠定了坚实基础。
|
||||
186
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口关闭事件.md
Normal file
186
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口关闭事件.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# 窗口关闭事件
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
- [DesktopEventManager.ts](file://src/events/DesktopEventManager.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心职责与生命周期管理](#核心职责与生命周期管理)
|
||||
3. [事件定义与接口规范](#事件定义与接口规范)
|
||||
4. [事件注册与监听机制](#事件注册与监听机制)
|
||||
5. [事件广播与跨组件通信](#事件广播与跨组件通信)
|
||||
6. [资源清理与内存泄漏防护](#资源清理与内存泄漏防护)
|
||||
7. [完整示例：带确认对话框的关闭流程](#完整示例：带确认对话框的关闭流程)
|
||||
8. [总结](#总结)
|
||||
|
||||
## 简介
|
||||
|
||||
`windowFormClose` 事件是 Vue 桌面应用中用于管理窗口实例销毁的核心机制。当用户点击窗口右上角的关闭按钮时，系统会触发该事件，并携带目标窗口的唯一标识符（ID），以精确地定位并销毁对应的窗口实例。此事件不仅负责 UI 层面的 DOM 移除，还承担着状态存储更新、资源释放以及防止内存泄漏的重要职责。
|
||||
|
||||
本文档将深入解析 `windowFormClose` 事件的整个生命周期，涵盖其定义、注册、广播及处理过程，并说明如何通过 `wfem`（Window Form Event Manager）进行监听器注册，集成用户确认逻辑，并确保系统的安全性和一致性。
|
||||
|
||||
## 核心职责与生命周期管理
|
||||
|
||||
`windowFormClose` 事件在窗口关闭流程中扮演着中枢角色，其生命周期贯穿从用户交互到最终资源回收的全过程：
|
||||
|
||||
1. **触发阶段**：由用户点击关闭按钮发起，事件携带窗口 ID 作为参数。
|
||||
2. **广播阶段**：通过 `wfem.notifyEvent('windowFormClose', id)` 将事件分发至所有注册的监听器。
|
||||
3. **处理阶段**：各组件根据自身业务逻辑响应事件，执行如显示确认对话框、保存未提交数据等操作。
|
||||
4. **清理阶段**：完成必要检查后，执行 DOM 节点移除、状态 store 更新和相关资源释放。
|
||||
5. **终止阶段**：确保所有引用被清除，避免因闭包或事件监听器残留导致的内存泄漏。
|
||||
|
||||
该事件的设计遵循单一职责原则，专注于“关闭”这一核心动作，同时通过松耦合的发布-订阅模式实现跨组件协作。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L27-L27)
|
||||
|
||||
## 事件定义与接口规范
|
||||
|
||||
`windowFormClose` 事件在 `IWindowFormEvent` 接口中明确定义，位于 `src/events/WindowFormEventManager.ts` 文件中。该接口继承自通用事件映射类型 `IEventMap`，并声明了多个与窗口操作相关的事件处理器签名。
|
||||
|
||||
```typescript
|
||||
interface IWindowFormEvent extends IEventMap {
|
||||
/**
|
||||
* 窗口关闭
|
||||
* @param id 窗口id
|
||||
*/
|
||||
windowFormClose: (id: string) => void;
|
||||
// 其他事件...
|
||||
}
|
||||
```
|
||||
|
||||
此定义明确了以下关键信息：
|
||||
- **事件名称**：`windowFormClose`
|
||||
- **参数类型**：单个字符串类型的 `id`，用于唯一标识待关闭的窗口实例。
|
||||
- **返回类型**：`void`，表示该事件不期望返回值，主要用于触发副作用。
|
||||
|
||||
这种强类型的接口设计保证了事件使用的安全性，编译器能够在开发阶段捕获类型错误。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IWindowFormEvent {
|
||||
+windowFormMinimize(id : string) void
|
||||
+windowFormMaximize(id : string) void
|
||||
+windowFormRestore(id : string) void
|
||||
+windowFormClose(id : string) void
|
||||
+windowFormFocus(id : string) void
|
||||
+windowFormDataUpdate(data : IWindowFormDataUpdateParams) void
|
||||
+windowFormCreated() void
|
||||
}
|
||||
class IEventMap {
|
||||
<<interface>>
|
||||
}
|
||||
IWindowFormEvent --|> IEventMap : 继承
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L7-L42)
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L7-L42)
|
||||
|
||||
## 事件注册与监听机制
|
||||
|
||||
系统使用 `wfem`（`WindowFormEventManager` 的实例）作为 `windowFormClose` 事件的管理中心。开发者可通过 `addEventListener` 方法注册监听器，语法如下：
|
||||
|
||||
```typescript
|
||||
wfem.addEventListener('windowFormClose', (id) => {
|
||||
// 处理关闭逻辑
|
||||
});
|
||||
```
|
||||
|
||||
`wfem` 是基于 `EventBuilderImpl` 类构建的事件总线实例，它提供了类型安全的事件注册、移除和通知功能。`addEventListener` 方法支持可选参数，例如 `immediate` 可用于在注册时立即执行一次回调，`once` 则确保监听器仅响应一次事件。
|
||||
|
||||
这种机制允许任意组件在需要时订阅关闭事件，而无需直接依赖具体的窗口管理逻辑，实现了高度的解耦。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant UI as UI组件
|
||||
participant Wfem as wfem(事件管理器)
|
||||
participant Listener as 关闭监听器
|
||||
User->>UI : 点击关闭按钮
|
||||
UI->>Wfem : notifyEvent("windowFormClose", windowId)
|
||||
Wfem->>Listener : 执行所有注册的监听器
|
||||
Listener-->>Wfem : 返回
|
||||
Wfem-->>UI : 事件处理完毕
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
|
||||
## 事件广播与跨组件通信
|
||||
|
||||
`windowFormClose` 事件的广播能力由 `EventBuilderImpl` 类的 `notifyEvent` 方法实现。该方法遍历内部存储的所有监听器，并按顺序调用它们。这种发布-订阅模式是实现跨组件通信的关键。
|
||||
|
||||
其优势在于：
|
||||
- **低耦合**：发送者（如窗口控件）无需知道接收者的存在，只需关注事件的发出。
|
||||
- **高内聚**：每个监听器只需关注与自己相关的业务逻辑，例如一个监听器负责弹出确认框，另一个负责清理定时器。
|
||||
- **可扩展性**：可以轻松添加新的监听器来增强关闭流程的功能，而无需修改现有代码。
|
||||
|
||||
事件广播确保了所有相关方都能及时收到关闭通知，从而协同完成复杂的清理任务，维护了系统状态的一致性。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[窗口A] --> |notifyEvent| B(wfem)
|
||||
C[窗口B] --> |notifyEvent| B
|
||||
D[其他组件] --> |notifyEvent| B
|
||||
B --> E[监听器1]
|
||||
B --> F[监听器2]
|
||||
B --> G[监听器N]
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
## 资源清理与内存泄漏防护
|
||||
|
||||
正确处理 `windowFormClose` 事件是防止内存泄漏的核心环节。一个完整的清理流程应包括：
|
||||
|
||||
1. **DOM 移除**：从虚拟 DOM 和真实 DOM 中卸载窗口及其子组件。
|
||||
2. **状态更新**：在全局状态 store（如 Pinia 或 Vuex）中移除对应窗口的状态条目。
|
||||
3. **事件解绑**：移除该窗口实例上注册的所有自定义事件监听器。
|
||||
4. **资源释放**：清除与该窗口关联的定时器（`setInterval`, `setTimeout`）、WebSocket 连接或其他长生命周期对象。
|
||||
|
||||
`EventBuilderImpl` 内部通过 `Set` 数据结构管理监听器，并在每次事件通知后检查 `once` 标志，自动清理一次性监听器。此外，`destroy` 方法可用于彻底清空所有事件处理器，为整个事件管理器的销毁提供支持。
|
||||
|
||||
**Section sources**
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
## 完整示例：带确认对话框的关闭流程
|
||||
|
||||
以下是一个典型的 `windowFormClose` 事件监听器实现，集成了用户确认对话框和资源释放逻辑：
|
||||
|
||||
```typescript
|
||||
wfem.addEventListener('windowFormClose', async (id) => {
|
||||
const shouldClose = await showConfirmDialog(`确定要关闭窗口 ${id} 吗？`);
|
||||
if (!shouldClose) return; // 用户取消，中断关闭流程
|
||||
|
||||
// 1. 清理特定于该窗口的资源
|
||||
cleanupWindowResources(id);
|
||||
|
||||
// 2. 从状态store中移除窗口记录
|
||||
windowStore.removeWindow(id);
|
||||
|
||||
// 3. 触发DOM移除（通常由组件自身在状态变更后自动处理）
|
||||
console.log(`窗口 ${id} 已成功关闭并清理`);
|
||||
}, { once: false }); // 保持监听器长期有效
|
||||
```
|
||||
|
||||
在此示例中：
|
||||
- 使用异步函数等待用户确认。
|
||||
- 若用户取消，则直接返回，阻止后续清理操作。
|
||||
- 按照逻辑顺序执行资源清理、状态更新等步骤。
|
||||
- 监听器设置为持久性（`once: false`），以便能响应未来可能发生的同类型事件。
|
||||
|
||||
## 总结
|
||||
|
||||
`windowFormClose` 事件是 Vue 桌面应用中窗口管理模块的基石。它通过清晰的接口定义、高效的事件广播机制和严谨的资源清理策略，确保了窗口实例能够被安全、可靠地销毁。借助 `wfem` 事件总线，系统实现了组件间的松耦合通信，使得复杂的关闭流程可以被分解为多个独立、可维护的监听器。遵循本文档所述的最佳实践，可以有效避免内存泄漏，保障应用的长期稳定运行。
|
||||
76
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口创建完成事件.md
Normal file
76
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口创建完成事件.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# 窗口创建完成事件
|
||||
|
||||
<cite>
|
||||
**本文档引用文件**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [事件语义与调用时机](#事件语义与调用时机)
|
||||
2. [应用场景分析](#应用场景分析)
|
||||
3. [事件监听代码范例](#事件监听代码范例)
|
||||
4. [生命周期时序关系](#生命周期时序关系)
|
||||
|
||||
## 事件语义与调用时机
|
||||
|
||||
`windowFormCreated` 事件在新窗口实例成功挂载并完成首次渲染后触发，标志着窗口已完全初始化并可交互。该事件不携带任何参数，作为全局窗口创建完成的信号。
|
||||
|
||||
根据 `WindowFormEventManager.ts` 中的定义，此事件是 `IWindowFormEvent` 接口的一部分，由 `wfem` 事件管理器负责分发。虽然当前实现中未直接显示触发逻辑，但结合 `WindowService.ts` 的窗口创建流程可知，该事件应在 `createWindow` 方法执行完毕、DOM 元素已添加至页面且应用内容加载完成后被通知。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L41-L41)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L83-L118)
|
||||
|
||||
## 应用场景分析
|
||||
|
||||
### 启动引导
|
||||
在系统启动或模块初始化过程中，通过监听 `windowFormCreated` 事件可以确保所有核心窗口均已准备就绪，从而安全地执行后续引导逻辑，如自动聚焦主窗口或初始化关联组件。
|
||||
|
||||
### 任务栏更新
|
||||
当新窗口创建完成后，任务栏组件可通过监听该事件实时更新其窗口列表，确保用户界面状态与实际运行情况保持同步。
|
||||
|
||||
### 快捷方式激活
|
||||
从桌面快捷方式启动应用时，该事件可用于确认目标窗口已成功打开，进而执行焦点切换或动画展示等增强用户体验的操作。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L41-L41)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L83-L118)
|
||||
|
||||
## 事件监听代码范例
|
||||
|
||||
以下为监听 `windowFormCreated` 事件并执行后续操作的典型代码模式：
|
||||
|
||||
```typescript
|
||||
import { wfem } from '@/events/WindowFormEventManager'
|
||||
|
||||
// 监听窗口创建完成事件
|
||||
wfem.addEventListener('windowFormCreated', () => {
|
||||
// 执行日志记录
|
||||
console.log('新窗口创建完成')
|
||||
|
||||
// 执行自动聚焦或其他初始化操作
|
||||
// focusMainWindow()
|
||||
})
|
||||
```
|
||||
|
||||
此类监听器常用于执行一次性初始化任务，例如设置默认焦点、注册快捷键、加载用户偏好设置或发送性能监控指标。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L83-L118)
|
||||
|
||||
## 生命周期时序关系
|
||||
|
||||
`windowFormCreated` 事件作为窗口生命周期的起点，在以下关键阶段之后发生：
|
||||
1. **CREATING**：窗口对象创建
|
||||
2. **LOADING**：DOM 元素构建与插入
|
||||
3. **ACTIVE**：窗口激活并获得焦点
|
||||
|
||||
它早于任何用户交互事件（如 `windowFormFocus`）和状态变更事件（如 `windowFormMinimize`），是首个表示窗口已进入稳定可用状态的全局事件。
|
||||
|
||||
与其他事件相比，`windowFormCreated` 是唯一无参数的创建完成信号，而其他事件如 `windowFormDataUpdate` 则携带具体的状态数据。这种设计使其成为理想的初始化钩子点。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L41-L41)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L83-L118)
|
||||
149
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口数据更新事件.md
Normal file
149
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口数据更新事件.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 窗口数据更新事件
|
||||
|
||||
<cite>
|
||||
**本文档引用文件**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [IWindowFormDataUpdateParams接口字段语义解析](#iwindowformdataupdateparams接口字段语义解析)
|
||||
3. [TWindowFormState类型关联说明](#twindowformstatetype类型关联说明)
|
||||
4. [窗口拖拽、缩放与状态切换中的统一元数据发送机制](#窗口拖拽缩放与状态切换中的统一元数据发送机制)
|
||||
5. [接收端批量更新UI的TypeScript示例](#接收端批量更新ui的typescript示例)
|
||||
6. [高频更新性能优化建议：防抖策略](#高频更新性能优化建议防抖策略)
|
||||
7. [窗口状态实时同步与持久化存储支持机制](#窗口状态实时同步与持久化存储支持机制)
|
||||
|
||||
## 简介
|
||||
`windowFormDataUpdate` 事件是桌面应用中用于传递窗口最新元数据的核心通信机制。该事件在窗口发生位置移动、尺寸调整或状态变更（如最小化、最大化）时触发，通过 `IWindowFormDataUpdateParams` 接口统一封装窗口的ID、状态、尺寸和坐标信息，并广播至所有监听者。此设计实现了窗口状态变化的集中通知与响应，为UI同步、布局管理及状态持久化提供了基础支撑。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L37-L37)
|
||||
|
||||
## IWindowFormDataUpdateParams接口字段语义解析
|
||||
`IWindowFormDataUpdateParams` 接口定义了窗口更新事件所携带的数据结构，包含以下关键字段：
|
||||
|
||||
- **id**: 字符串类型，表示窗口的唯一标识符。该ID由系统生成并贯穿窗口生命周期，用于精确识别和定位特定窗口实例。
|
||||
- **state**: 枚举类型 `TWindowFormState`，表示当前窗口的状态，包括 `'default'`（默认）、`'minimized'`（最小化）、`'maximized'`（最大化）三种可能值。
|
||||
- **width**: 数字类型，表示窗口当前的宽度（单位：像素），反映窗口水平方向的实际尺寸。
|
||||
- **height**: 数字类型，表示窗口当前的高度（单位：像素），反映窗口垂直方向的实际尺寸。
|
||||
- **x**: 数字类型，表示窗口左上角相对于屏幕原点的X轴坐标（单位：像素），用于确定窗口的水平位置。
|
||||
- **y**: 数字类型，表示窗口左上角相对于屏幕原点的Y轴坐标（单位：像素），用于确定窗口的垂直位置。
|
||||
|
||||
这些字段共同构成了窗口的完整元数据快照，确保接收方能够准确还原窗口的视觉表现和行为状态。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L44-L57)
|
||||
|
||||
## TWindowFormState类型关联说明
|
||||
`TWindowFormState` 是一个字符串联合类型，明确定义了窗口可处于的三种核心状态：
|
||||
- `'default'`: 窗口处于正常显示状态，既非最大化也非最小化。
|
||||
- `'minimized'`: 窗口被最小化，通常从主视图隐藏，仅在任务栏或启动器中保留图标。
|
||||
- `'maximized'`: 窗口被最大化，占据除任务栏外的整个屏幕空间。
|
||||
|
||||
该类型与 `IWindowFormDataUpdateParams.state` 字段直接关联，作为事件数据的一部分，在窗口状态发生变化时（例如用户点击最大化按钮），新的状态值将被封装进事件参数中并广播出去。这种强类型的约束保证了状态传递的准确性与一致性。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L9-L9)
|
||||
|
||||
## 窗口拖拽、缩放与状态切换中的统一元数据发送机制
|
||||
无论窗口因何种操作而改变其外观或状态，系统均通过 `windowFormDataUpdate` 事件统一发送最新的元数据。具体流程如下：
|
||||
|
||||
1. **拖拽操作**：当用户拖动窗口标题栏时，鼠标移动事件会持续更新窗口的 `x` 和 `y` 坐标。在每次坐标更新后，系统调用 `setActiveWindow` 激活该窗口，并最终通过事件总线触发 `windowFormDataUpdate`，附带更新后的坐标、尺寸及当前状态。
|
||||
2. **缩放操作**：当用户调整窗口大小时，`setWindowSize` 方法被调用以更新 `width` 和 `height`。此方法不仅修改DOM样式，还会通知事件总线，从而触发包含新尺寸的 `windowFormDataUpdate` 事件。
|
||||
3. **状态切换**：无论是最小化、最大化还是还原操作，都会先调用 `updateWindowState` 修改内部状态机，随后根据新状态调整DOM表现（如隐藏元素或全屏展示）。最后，系统发出 `windowFormDataUpdate` 事件，其中 `state` 字段反映最新状态，同时附带相应的坐标和尺寸信息。
|
||||
|
||||
这一机制确保了所有窗口变更都通过单一入口进行通知，简化了状态管理逻辑，避免了多事件源导致的不一致问题。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[用户操作] --> B{操作类型}
|
||||
B --> |拖拽| C[更新 x, y]
|
||||
B --> |缩放| D[更新 width, height]
|
||||
B --> |状态切换| E[更新 state]
|
||||
C --> F[调用 setActiveWindow]
|
||||
D --> G[调用 setWindowSize]
|
||||
E --> H[调用 updateWindowState]
|
||||
F --> I[触发 windowFormDataUpdate]
|
||||
G --> I
|
||||
H --> I
|
||||
I --> J[接收端更新UI]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L512-L552)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L248-L304)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L179-L213)
|
||||
|
||||
**Section sources**
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L512-L552)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L248-L304)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L179-L213)
|
||||
|
||||
## 接收端批量更新UI的TypeScript示例
|
||||
接收 `windowFormDataUpdate` 事件后，应使用接收到的完整数据对象一次性批量更新UI，避免逐个属性设置带来的性能开销和视觉闪烁。以下为推荐的处理方式：
|
||||
|
||||
```typescript
|
||||
wfem.addEventListener('windowFormDataUpdate', (data) => {
|
||||
const { id, state, width, height, x, y } = data;
|
||||
const windowElement = document.getElementById(`window-${id}`);
|
||||
|
||||
if (!windowElement) return;
|
||||
|
||||
// 批量更新样式属性
|
||||
Object.assign(windowElement.style, {
|
||||
width: `${width}px`,
|
||||
height: `${height}px`,
|
||||
left: `${x}px`,
|
||||
top: `${y}px`,
|
||||
display: state === 'minimized' ? 'none' : 'block'
|
||||
});
|
||||
|
||||
// 根据状态添加CSS类以支持主题化样式
|
||||
windowElement.classList.toggle('maximized', state === 'maximized');
|
||||
windowElement.classList.toggle('minimized', state === 'minimized');
|
||||
windowElement.classList.toggle('default', state === 'default');
|
||||
});
|
||||
```
|
||||
|
||||
上述代码利用 `Object.assign` 对目标DOM元素的样式进行原子性更新，确保浏览器只进行一次重排（reflow）和重绘（repaint），从而提升渲染效率。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L37-L37)
|
||||
|
||||
## 高频更新性能优化建议：防抖策略
|
||||
由于拖拽和缩放操作会产生大量连续的 `windowFormDataUpdate` 事件，若不对处理函数加以节流，可能导致UI线程阻塞或频繁重绘，影响用户体验。为此，建议对接收端的事件处理器应用防抖（debounce）技术：
|
||||
|
||||
```typescript
|
||||
function debounce<T extends (...args: any[]) => void>(func: T, delay: number): T {
|
||||
let timeoutId: ReturnType<typeof setTimeout>;
|
||||
return function (this: any, ...args: any[]) {
|
||||
clearTimeout(timeoutId);
|
||||
timeoutId = setTimeout(() => func.apply(this, args), delay);
|
||||
} as T;
|
||||
}
|
||||
|
||||
const debouncedHandler = debounce((data: IWindowFormDataUpdateParams) => {
|
||||
// 执行UI更新逻辑
|
||||
}, 16); // 约60fps的间隔
|
||||
|
||||
wfem.addEventListener('windowFormDataUpdate', debouncedHandler);
|
||||
```
|
||||
|
||||
通过设置约16毫秒的延迟（对应60Hz刷新率），可以有效过滤掉中间过渡状态，仅处理最终稳定的位置或尺寸，显著降低计算负担并提升流畅度。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L44-L57)
|
||||
|
||||
## 窗口状态实时同步与持久化存储支持机制
|
||||
`windowFormDataUpdate` 事件不仅是UI更新的驱动源，也为跨组件通信和状态持久化提供了可靠的数据通道。任何需要感知窗口状态的模块（如任务栏、窗口管理器、布局保存服务）均可订阅此事件，实现状态的实时同步。
|
||||
|
||||
此外，通过监听该事件，可将窗口的 `id`、`state`、`width`、`height`、`x`、`y` 等元数据记录到本地存储（如localStorage）或远程服务器，实现用户偏好的记忆功能。例如，在用户下次启动应用时，系统可根据存储的历史数据恢复窗口的原始位置和大小，提供一致的使用体验。
|
||||
|
||||
该事件的设计使得状态采集与业务逻辑解耦，任何持久化逻辑只需作为事件观察者存在，无需侵入窗口控制核心代码，符合关注点分离原则。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L37-L37)
|
||||
- [WindowService.ts](file://src/services/WindowService.ts#L67-L118)
|
||||
114
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口最大化事件.md
Normal file
114
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口最大化事件.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 窗口最大化事件
|
||||
|
||||
<cite>
|
||||
**本文档引用文件**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
- [basic.css](file://src/css/basic.css)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [事件触发机制](#事件触发机制)
|
||||
3. [状态映射与UI响应](#状态映射与ui响应)
|
||||
4. [CSS视觉变换实现](#css视觉变换实现)
|
||||
5. [TypeScript代码范例](#typescript代码范例)
|
||||
6. [多窗口协调机制](#多窗口协调机制)
|
||||
7. [总结](#总结)
|
||||
|
||||
## 引言
|
||||
本节全面阐述`windowFormMaximize`事件的触发条件与交互逻辑。当用户点击窗口最大化按钮时，系统将广播该事件并携带窗口ID至所有订阅者，驱动UI进入全屏布局模式。此机制是桌面级应用中实现窗口管理的核心部分。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L1-L60)
|
||||
|
||||
## 事件触发机制
|
||||
`windowFormMaximize`事件定义于`IWindowFormEvent`接口中，其函数签名接受一个字符串类型的窗口ID参数：
|
||||
|
||||
```ts
|
||||
windowFormMaximize: (id: string) => void;
|
||||
```
|
||||
|
||||
该事件由全局事件管理器`wfem`（即`EventBuilderImpl<IWindowFormEvent>`实例）负责分发。当用户交互触发最大化行为时，调用`notifyEvent('windowFormMaximize', windowId)`方法，向所有监听此事件的组件广播通知。
|
||||
|
||||
事件系统基于观察者模式实现，支持动态注册和注销监听器，并可通过配置项实现立即执行、单次监听等功能。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L17-L17)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
## 状态映射与UI响应
|
||||
`windowFormMaximize`事件与`TWindowFormState`类型中的`maximized`状态存在直接映射关系。`TWindowFormState`定义如下：
|
||||
|
||||
```ts
|
||||
export type TWindowFormState = 'default' | 'minimized' | 'maximized';
|
||||
```
|
||||
|
||||
当事件被触发后，相关组件会更新对应窗口的状态为`maximized`，并通过响应式机制驱动视图重绘。通常结合`windowFormDataUpdate`事件同步窗口尺寸与位置信息，确保状态一致性。
|
||||
|
||||
状态变更不仅影响当前窗口的显示模式，还可能触发任务栏图标高亮、Z轴层级调整等副作用，以保证用户体验的一致性。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L9-L9)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L50-L55)
|
||||
|
||||
## CSS视觉变换实现
|
||||
窗口最大化过程中的视觉效果主要通过CSS变换实现。虽然具体样式未在核心逻辑文件中体现，但可推断其依赖以下机制：
|
||||
|
||||
- 使用`transform: scale()`或`width/height: 100%`实现尺寸扩展
|
||||
- 配合过渡动画（transition）实现平滑缩放
|
||||
- 利用`z-index`控制多窗口堆叠顺序
|
||||
- 可能结合`position: fixed`或`absolute`脱离文档流进行定位
|
||||
|
||||
基础样式文件`basic.css`提供了通用的盒模型重置、字体设置及响应式支持，为窗口动画提供稳定的样式环境。
|
||||
|
||||
**Section sources**
|
||||
- [basic.css](file://src/css/basic.css#L1-L134)
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
|
||||
## TypeScript代码范例
|
||||
使用`wfem`监听并处理最大化行为的标准TypeScript代码范例如下：
|
||||
|
||||
```ts
|
||||
// 订阅窗口最大化事件
|
||||
wfem.addEventListener('windowFormMaximize', (id: string) => {
|
||||
// 更新窗口状态
|
||||
const window = getWindowById(id);
|
||||
if (window) {
|
||||
window.state = 'maximized';
|
||||
// 触发DOM重绘
|
||||
redrawWindow(window);
|
||||
// 持久化状态（可选）
|
||||
saveWindowState(id, 'maximized');
|
||||
}
|
||||
});
|
||||
|
||||
// 发送最大化事件
|
||||
function maximizeWindow(id: string) {
|
||||
wfem.notifyEvent('windowFormMaximize', id);
|
||||
}
|
||||
```
|
||||
|
||||
建议在状态变更后调用重绘函数，并考虑将用户偏好（如是否最大化）持久化至`localStorage`，以便页面刷新后恢复。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L70-L75)
|
||||
|
||||
## 多窗口协调机制
|
||||
在多窗口堆叠场景下，`windowFormMaximize`事件起到关键协调作用。当某一窗口最大化时：
|
||||
|
||||
- 其他非最小化窗口应自动退至后台
|
||||
- 最大化窗口获得最高`z-index`层级
|
||||
- 任务栏对应图标处于激活状态
|
||||
- 若存在模态窗口，则需特殊处理避免遮挡
|
||||
|
||||
事件广播机制确保所有关注窗口状态的模块（如任务栏、窗口管理器、快捷键服务）能同步响应，维持系统整体状态一致。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L17-L17)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
|
||||
## 总结
|
||||
`windowFormMaximize`事件作为窗口控制系统的重要组成部分，实现了从用户操作到UI响应的完整闭环。它通过标准化的事件总线机制解耦组件间通信，结合类型安全的状态定义与CSS视觉变换，构建出流畅且可维护的桌面级交互体验。在复杂多窗口环境中，该事件有效协调各组件行为，保障系统稳定性与一致性。
|
||||
96
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口最小化事件.md
Normal file
96
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口最小化事件.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# 窗口最小化事件
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [事件机制概述](#事件机制概述)
|
||||
2. [事件触发与参数传递](#事件触发与参数传递)
|
||||
3. [状态同步与枚举值应用](#状态同步与枚举值应用)
|
||||
4. [监听器注册与Pinia状态更新](#监听器注册与pinia状态更新)
|
||||
5. [事件解耦设计分析](#事件解耦设计分析)
|
||||
|
||||
## 事件机制概述
|
||||
|
||||
`windowFormMinimize` 事件是窗口管理系统中的核心交互事件之一，用于响应用户点击窗口最小化按钮的操作。该事件通过全局事件管理器 `wfem` 进行广播，采用发布-订阅模式实现组件间的松耦合通信。事件定义在 `IWindowFormEvent` 接口中，并由 `EventBuilderImpl` 类提供具体的事件注册与通知能力。
|
||||
|
||||
此事件机制的设计使得任意组件均可独立监听窗口最小化行为，而无需直接依赖窗口实例本身，从而提升了系统的可维护性与扩展性。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L12-L12)
|
||||
|
||||
## 事件触发与参数传递
|
||||
|
||||
当用户点击窗口的最小化按钮时，系统会调用 `wfem.notifyEvent('windowFormMinimize', id)` 方法触发该事件。其中 `id` 为窗口的唯一标识符（字符串类型），作为事件回调函数的参数传递给所有监听者。
|
||||
|
||||
事件的接口定义如下：
|
||||
```ts
|
||||
windowFormMinimize: (id: string) => void;
|
||||
```
|
||||
这确保了所有监听器都能接收到被最小化的窗口ID，进而执行相应的UI动画或逻辑处理。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L12-L12)
|
||||
|
||||
## 状态同步与枚举值应用
|
||||
|
||||
在接收到 `windowFormMinimize` 事件后，系统通常会将对应窗口的状态更新为 `'minimized'`。该状态值来源于 `TWindowFormState` 枚举类型，其定义如下：
|
||||
|
||||
```ts
|
||||
export type TWindowFormState = 'default' | 'minimized' | 'maximized';
|
||||
```
|
||||
|
||||
通过将窗口状态设置为 `'minimized'`，可以驱动视图层进行相应的渲染更新，例如隐藏窗口内容、在任务栏显示缩略图标等。这种基于枚举的状态管理模式增强了代码的可读性和类型安全性。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L9-L9)
|
||||
|
||||
## 监听器注册与Pinia状态更新
|
||||
|
||||
在Vue组件中，可通过 `wfem.addEventListener` 方法注册对 `windowFormMinimize` 事件的监听。典型用法如下所示：
|
||||
|
||||
```ts
|
||||
wfem.addEventListener('windowFormMinimize', (id: string) => {
|
||||
// 更新Pinia store中的窗口状态
|
||||
const windowStore = useWindowStore();
|
||||
windowStore.updateState(id, 'minimized');
|
||||
});
|
||||
```
|
||||
|
||||
上述代码展示了如何在事件回调中获取窗口ID并更新Pinia状态仓库中的窗口状态字段。这种方式实现了视图与状态的分离，符合现代前端架构的最佳实践。
|
||||
|
||||
尽管当前项目中未包含 `useWindowStore` 的具体实现，但基于现有技术栈（Vue + Pinia）可合理推断其存在类似的窗口状态管理模块。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L9-L9)
|
||||
|
||||
## 事件解耦设计分析
|
||||
|
||||
`windowFormMinimize` 事件体现了典型的事件驱动解耦设计。多个窗口组件可以各自注册监听器，独立响应最小化事件，而无需彼此知晓或直接通信。事件的发布者仅需调用 `notifyEvent`，由 `EventBuilderImpl` 负责遍历所有订阅者并执行回调。
|
||||
|
||||
该设计的优势包括：
|
||||
- **高内聚低耦合**：各组件专注于自身逻辑，不依赖其他窗口的状态。
|
||||
- **易于扩展**：新增窗口组件只需添加监听器即可参与事件流。
|
||||
- **便于测试**：事件监听逻辑可单独单元测试，无需完整UI环境。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[用户点击最小化按钮] --> B[触发 windowFormMinimize 事件]
|
||||
B --> C{通知所有监听者}
|
||||
C --> D[窗口A监听器: 执行最小化动画]
|
||||
C --> E[窗口B监听器: 更新状态为 minimized]
|
||||
C --> F[任务栏组件: 显示最小化图标]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L12-L12)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L50-L75)
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L50-L75)
|
||||
131
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口聚焦事件.md
Normal file
131
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口聚焦事件.md
Normal file
@@ -0,0 +1,131 @@
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [useClickFocus.ts](file://src/common/hooks/useClickFocus.ts)
|
||||
- [useObservableVue.ts](file://src/common/hooks/useObservableVue.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [窗口聚焦事件](#窗口聚焦事件)
|
||||
2. [用户交互背景](#用户交互背景)
|
||||
3. [技术实现机制](#技术实现机制)
|
||||
4. [多窗口层级管理](#多窗口层级管理)
|
||||
5. [Vue组件中的事件监听](#vue组件中的事件监听)
|
||||
6. [响应式状态更新](#响应式状态更新)
|
||||
7. [用户体验影响](#用户体验影响)
|
||||
|
||||
## 窗口聚焦事件
|
||||
|
||||
`windowFormFocus` 事件是桌面级Vue应用中用于管理窗口激活状态的核心事件。当用户点击或通过其他方式激活某个窗口时，该事件被触发并广播被激活窗口的唯一标识符（id），从而驱动UI层面对应的视觉反馈和状态变更。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L32-L32)
|
||||
|
||||
## 用户交互背景
|
||||
|
||||
在模拟传统桌面操作系统的Web应用中，用户期望拥有与原生应用一致的窗口交互体验。当用户点击一个处于非顶层的窗口时，该窗口应当自动移动到所有其他窗口的前面，并获得输入焦点。这种行为符合用户的直觉认知，即“所见即所得”的交互原则。`windowFormFocus` 事件正是为了捕捉这一关键的用户意图而设计的，它作为用户操作与系统响应之间的桥梁，确保了界面行为的可预测性和一致性。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L30-L34)
|
||||
|
||||
## 技术实现机制
|
||||
|
||||
`windowFormFocus` 事件的技术实现依赖于一个名为 `wfem` (Window Form Event Manager) 的全局事件管理器实例，该实例基于 `EventBuilderImpl` 类构建，提供了一套完整的发布-订阅模式接口。
|
||||
|
||||
事件的触发流程如下：
|
||||
1. **事件定义**：在 `IWindowFormEvent` 接口中明确定义了 `windowFormFocus(id: string)` 方法签名。
|
||||
2. **事件触发**：当检测到用户对特定窗口的点击操作时，业务逻辑代码会调用 `wfem.notifyEvent('windowFormFocus', windowId)` 来广播该事件。
|
||||
3. **事件监听**：任何需要对此事件做出反应的组件都可以通过 `wfem.addEventListener('windowFormFocus', callback)` 注册一个回调函数。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant Window as 窗口组件
|
||||
participant Hook as useClickFocus Hook
|
||||
participant EventManager as wfem (事件管理器)
|
||||
User->>Window : 点击窗口
|
||||
Window->>Hook : 触发内部处理
|
||||
Hook->>EventManager : 调用 notifyEvent('windowFormFocus', id)
|
||||
EventManager->>EventManager : 遍历所有监听器
|
||||
loop 通知所有订阅者
|
||||
EventManager-->>Subscriber : 执行注册的回调函数
|
||||
end
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [useClickFocus.ts](file://src/common/hooks/useClickFocus.ts#L13-L64)
|
||||
|
||||
## 多窗口层级管理
|
||||
|
||||
在存在多个重叠窗口的应用场景下，维护正确的渲染顺序至关重要。`windowFormFocus` 事件在此扮演了核心角色。每当该事件被触发，其携带的窗口ID会被传递给负责管理窗口栈的逻辑模块。该模块会根据ID找到对应的窗口元素，并将其CSS `z-index` 属性提升至最高层级，同时移除之前处于顶层窗口的焦点样式，并为当前窗口应用新的焦点样式（如高亮边框）。这一系列操作确保了被激活的窗口始终位于最前端，解决了视觉遮挡问题，使用户能够清晰地识别出当前正在操作的对象。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L30-L34)
|
||||
|
||||
## Vue组件中的事件监听
|
||||
|
||||
在Vue组件中监听 `windowFormFocus` 事件是一个标准的异步编程实践。开发者可以在组件的 `setup` 函数或 `onMounted` 生命周期钩子中，使用 `wfem.addEventListener` 方法注册一个监听器。最佳实践是将此逻辑封装在一个自定义Hook中，以保证代码的复用性和可维护性。例如，可以创建一个 `useWindowFocusListener` Hook，在组件挂载时订阅事件，并在组件卸载前 (`onBeforeUnmount`) 及时移除监听器，防止内存泄漏。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[组件挂载] --> B["调用 wfem.addEventListener('windowFormFocus', callback)"]
|
||||
B --> C[事件管理器注册回调]
|
||||
D[用户点击窗口] --> E["触发 wfem.notifyEvent('windowFormFocus', id)"]
|
||||
E --> F[事件管理器遍历并执行所有回调]
|
||||
F --> G[组件中的回调函数被调用]
|
||||
G --> H[更新组件内部状态]
|
||||
I[组件卸载] --> J["调用 wfem.removeEventListener 移除监听"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [useClickFocus.ts](file://src/common/hooks/useClickFocus.ts#L13-L64)
|
||||
|
||||
## 响应式状态更新
|
||||
|
||||
为了实现高效且直观的状态管理，建议结合 `useObservableVue` 这一自定义Hook来处理 `windowFormFocus` 事件带来的状态变化。`useObservableVue` 将一个实现了 `IObservable<T>` 接口的可观察对象转换为Vue的响应式对象。当 `windowFormFocus` 事件触发时，其回调函数可以直接修改存储在可观察对象中的 `activeWindow` 状态。由于 `useObservableVue` 内部建立了双向同步机制，对可观察对象的任何修改都会立即反映到Vue的响应式系统中，从而自动触发相关组件的重新渲染，无需手动调用 `forceUpdate` 或进行复杂的 `$emit` 操作。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IObservable~T~ {
|
||||
<<interface>>
|
||||
+subscribe(callback) : () => void
|
||||
+toRefsProxy() : T
|
||||
}
|
||||
class ObservableImpl~T~ {
|
||||
-state : T
|
||||
-observers : Set~() => void~
|
||||
+subscribe(callback) : () => void
|
||||
+toRefsProxy() : T
|
||||
+notify() : void
|
||||
}
|
||||
class useObservableVue {
|
||||
+useObservable(observable) : Reactive~T~
|
||||
}
|
||||
class Component {
|
||||
+setup()
|
||||
+template
|
||||
}
|
||||
IObservable~T~ <|.. ObservableImpl~T~ : 实现
|
||||
useObservableVue --> IObservable~T~ : 使用
|
||||
Component --> useObservableVue : 调用
|
||||
ObservableImpl~T~ --> Component : 通过响应式更新视图
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useObservableVue.ts](file://src/common/hooks/useObservableVue.ts#L13-L87)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L1-L96)
|
||||
|
||||
## 用户体验影响
|
||||
|
||||
`windowFormFocus` 事件对桌面级应用的用户体验具有决定性的影响。它直接决定了应用是否能提供流畅、自然的多任务操作环境。一个正确实现的窗口聚焦机制能够：
|
||||
- **降低认知负荷**：用户无需思考哪个窗口是活动的，视觉反馈清晰明确。
|
||||
- **提高操作效率**：通过简单的点击即可切换上下文，符合肌肉记忆。
|
||||
- **增强应用可信度**：其行为与用户熟悉的操作系统保持一致，提升了应用的专业感和可靠性。
|
||||
|
||||
反之，如果该事件处理不当，例如出现窗口无法置顶、焦点丢失或样式错乱等问题，将严重破坏用户对应用的信任，导致挫败感和使用障碍。因此，确保 `windowFormFocus` 事件的稳定性和准确性是构建高质量桌面级Web应用的关键基石。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L30-L34)
|
||||
196
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口表单事件管理器.md
Normal file
196
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口表单事件管理器.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 窗口表单事件管理器
|
||||
|
||||
<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)
|
||||
120
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口还原事件.md
Normal file
120
.qoder/repowiki/zh/content/事件系统/窗口表单事件管理器/窗口还原事件.md
Normal file
@@ -0,0 +1,120 @@
|
||||
# 窗口还原事件
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心设计与运行机制](#核心设计与运行机制)
|
||||
3. [事件协同关系分析](#事件协同关系分析)
|
||||
4. [Vue组件中的实践应用](#vue组件中的实践应用)
|
||||
5. [在窗口状态机中的角色](#在窗口状态机中的角色)
|
||||
|
||||
## 简介
|
||||
`windowFormRestore` 事件是桌面应用中用于处理窗口从最大化或最小化状态恢复为正常尺寸的关键事件。该事件通过传递窗口唯一标识符（id）来定位目标窗口实例，并触发相应的UI布局重置逻辑。结合 `windowFormDataUpdate` 事件，可实现窗口位置与尺寸信息的同步更新，确保用户界面状态的一致性。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L22-L22)
|
||||
|
||||
## 核心设计与运行机制
|
||||
`windowFormRestore` 事件定义于 `IWindowFormEvent` 接口中，其函数签名接受一个字符串类型的 `id` 参数，用以标识被操作的窗口实例。当用户点击“还原”按钮或通过快捷键执行还原操作时，系统将调用事件管理器 `wfem` 的 `notifyEvent` 方法，广播该事件。
|
||||
|
||||
事件的实际通知行为由通用事件构建器 `EventBuilderImpl` 实现，它维护了一个基于 `Map` 的监听器集合，支持动态添加、移除和触发事件回调。整个流程具备良好的解耦性和扩展性。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[用户触发窗口还原] --> B[调用 wfem.notifyEvent("windowFormRestore", id)]
|
||||
B --> C{是否存在监听器?}
|
||||
C --> |是| D[遍历执行所有注册的 handler]
|
||||
C --> |否| E[无操作]
|
||||
D --> F[各组件响应还原逻辑]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L22-L22)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L7-L60)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L7-L95)
|
||||
|
||||
## 事件协同关系分析
|
||||
`windowFormRestore` 通常与 `windowFormDataUpdate` 事件协同工作。前者仅通知“还原”动作的发生，而后者负责携带具体的窗口状态数据（包括坐标 x/y 和宽高 width/height），实现精确的状态同步。
|
||||
|
||||
例如，在窗口还原过程中：
|
||||
1. 首先触发 `windowFormRestore(id)`，通知所有监听者窗口即将还原；
|
||||
2. 紧接着发送 `windowFormDataUpdate({ id, state: 'default', x, y, width, height })`，提供新的布局参数；
|
||||
3. UI 组件接收到数据后，更新 DOM 元素的位置与尺寸。
|
||||
|
||||
这种分离设计提高了系统的灵活性和可维护性。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User as 用户
|
||||
participant WM as 窗口管理器
|
||||
participant EM as 事件管理器(wfem)
|
||||
participant UI as UI组件
|
||||
User->>WM : 执行还原操作
|
||||
WM->>EM : notifyEvent("windowFormRestore", id)
|
||||
EM->>UI : 执行所有 windowFormRestore 回调
|
||||
WM->>EM : notifyEvent("windowFormDataUpdate", {id, state, x, y, width, height})
|
||||
EM->>UI : 执行所有 windowFormDataUpdate 回调
|
||||
UI->>UI : 更新DOM样式与位置
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L37-L37)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L5-L9)
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L37-L37)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L5-L9)
|
||||
|
||||
## Vue组件中的实践应用
|
||||
在 Vue 组件中，可通过 `wfem.addEventListener` 监听 `windowFormRestore` 事件，并结合响应式数据重置 UI 布局。建议使用 CSS 过渡动画提升用户体验。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class WindowComponent {
|
||||
+windowId : string
|
||||
+position : WindowFormPos
|
||||
+size : {width : number, height : number}
|
||||
+mounted()
|
||||
+beforeUnmount()
|
||||
}
|
||||
class EventManager {
|
||||
+addEventListener(event, handler)
|
||||
+removeEventListener(event, handler)
|
||||
+notifyEvent(event, ...args)
|
||||
}
|
||||
WindowComponent --> EventManager : 使用 wfem
|
||||
note right of WindowComponent
|
||||
在 mounted 中注册事件监听，
|
||||
在 beforeUnmount 中清理资源
|
||||
end note
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L1-L5)
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L60-L60)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L1-L10)
|
||||
|
||||
## 在窗口状态机中的角色
|
||||
`windowFormRestore` 是窗口状态机中从 `maximized` 或 `minimized` 转换至 `default` 状态的关键触发点。它标志着窗口生命周期中的一个重要转变节点，常伴随以下行为：
|
||||
- 恢复原始位置与尺寸
|
||||
- 重新激活窗口焦点
|
||||
- 触发内容区域重渲染
|
||||
- 更新任务栏图标状态
|
||||
|
||||
该事件与其他窗口控制事件（如 `windowFormMinimize`, `windowFormMaximize`）共同构成了完整的状态转换网络，支撑起复杂的桌面交互体验。
|
||||
|
||||
**Section sources**
|
||||
- [WindowFormEventManager.ts](file://src/events/WindowFormEventManager.ts#L7-L42)
|
||||
- [WindowFormTypes.ts](file://src/ui/types/WindowFormTypes.ts#L5-L9)
|
||||
193
.qoder/repowiki/zh/content/响应式布局系统/响应式布局系统.md
Normal file
193
.qoder/repowiki/zh/content/响应式布局系统/响应式布局系统.md
Normal file
@@ -0,0 +1,193 @@
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [basic.css](file://src/css/basic.css)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心组件分析](#核心组件分析)
|
||||
3. [响应式网格布局机制](#响应式网格布局机制)
|
||||
4. [图标位置管理与持久化](#图标位置管理与持久化)
|
||||
5. [视觉呈现与基础样式](#视觉呈现与基础样式)
|
||||
6. [依赖关系图](#依赖关系图)
|
||||
|
||||
## 简介
|
||||
|
||||
本技术文档深入剖析了基于CSS Grid的动态桌面布局系统。该系统以`useDesktopContainerInit`这一核心Vue组合式函数（Hook）为基础，实现了高度响应式的桌面容器功能。通过集成ResizeObserver API、Vue的响应式系统以及localStorage，该系统能够根据容器尺寸动态调整网格布局，并智能地重新排列桌面图标，同时将用户自定义的布局状态持久化存储。整体架构结合了现代前端框架特性与原生Web API，构建了一个灵活、可扩展且用户体验良好的虚拟桌面环境。
|
||||
|
||||
## 核心组件分析
|
||||
|
||||
系统的核心逻辑封装在`useDesktopContainerInit`函数中，该函数作为Vue 3的组合式API被`DesktopContainer.vue`组件所调用。其主要职责是初始化并管理整个桌面容器的状态，包括网格模板参数、计算样式以及桌面图标数据。该函数返回一个包含`gridTemplate`、`appIconsRef`和`gridStyle`三个关键属性的对象，为上层组件提供完整的布局控制能力。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class useDesktopContainerInit {
|
||||
+container : HTMLElement
|
||||
+gridTemplate : IGridTemplateParams
|
||||
+gridStyle : ComputedRef~Object~
|
||||
+ro : ResizeObserver
|
||||
+appIconsRef : Ref~Array<IDesktopAppIcon>~
|
||||
+exceedApp : Ref~Array<IDesktopAppIcon>~
|
||||
+useDesktopContainerInit(containerStr : string) : Object
|
||||
}
|
||||
class IGridTemplateParams {
|
||||
+cellExpectWidth : number
|
||||
+cellExpectHeight : number
|
||||
+cellRealWidth : number
|
||||
+cellRealHeight : number
|
||||
+gapX : number
|
||||
+gapY : number
|
||||
+colCount : number
|
||||
+rowCount : number
|
||||
}
|
||||
class IDesktopAppIcon {
|
||||
+name : string
|
||||
+icon : string
|
||||
+path : string
|
||||
+x : number
|
||||
+y : number
|
||||
}
|
||||
useDesktopContainerInit --> IGridTemplateParams : "包含"
|
||||
useDesktopContainerInit --> IDesktopAppIcon : "管理"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L3-L20)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L3-L14)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## 响应式网格布局机制
|
||||
|
||||
### 动态网格计算流程
|
||||
|
||||
系统的响应式能力源于对`ResizeObserver`的巧妙运用。当`DesktopContainer`组件挂载时，`useDesktopContainerInit`会创建一个`ResizeObserver`实例，并将其绑定到指定的容器元素（如`.desktop-icons-container`）。每当容器的尺寸发生变化，观察者回调就会被触发，执行一系列精确的计算来更新网格布局。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[容器尺寸变化] --> B{ResizeObserver 触发}
|
||||
B --> C[获取容器实际宽高]
|
||||
C --> D[计算列数 colCount]
|
||||
D --> E[计算行数 rowCount]
|
||||
E --> F[计算单元格实际宽度 cellRealWidth]
|
||||
F --> G[计算单元格实际高度 cellRealHeight]
|
||||
G --> H[更新 gridTemplate 响应式对象]
|
||||
H --> I[computed 自动更新 gridStyle]
|
||||
I --> J[DOM 中的 style 属性更新]
|
||||
J --> K[浏览器重绘，应用新布局]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L37-L58)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L37-L58)
|
||||
|
||||
### `gridStyle` 计算属性详解
|
||||
|
||||
`gridStyle`是一个由`computed`创建的计算属性，它直接决定了桌面容器的CSS Grid样式。该属性依赖于`gridTemplate`中的`colCount`、`rowCount`、`cellExpectWidth`、`cellExpectHeight`、`gapX`和`gapY`等值。其核心作用是将这些数值动态地转换为标准的CSS Grid声明：
|
||||
|
||||
- **`gridTemplateColumns`**: 使用`repeat()`函数生成指定数量的列轨道，每列的最小值为预设宽度（`cellExpectWidth`），最大值为`1fr`，确保了列的弹性伸缩。
|
||||
- **`gridTemplateRows`**: 与列同理，生成指定数量的行轨道。
|
||||
- **`gap`**: 设置行与列之间的间距。
|
||||
|
||||
这种设计使得布局的任何变化都能立即反映在UI上，实现了真正的数据驱动视图。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L25-L35)
|
||||
|
||||
## 图标位置管理与持久化
|
||||
|
||||
### 图标初始定位与重排算法
|
||||
|
||||
系统通过`appIconsRef`这个`ref`对象来管理所有桌面图标的集合。在初始化时，函数会尝试从`localStorage`中读取之前保存的图标位置信息（键名为`desktopAppIconInfo`）。对于每个应用，它首先检查是否有历史记录，如果有则使用历史坐标；如果没有，则根据当前的网格行列数进行默认的蛇形排列。
|
||||
|
||||
当网格的行列数因容器大小改变而发生变化时，`watch`监听器会被激活，调用`rearrangeIcons`函数对图标进行智能重排。该算法的核心逻辑如下：
|
||||
1. 遍历现有图标，优先保留那些仍在新网格范围内的图标。
|
||||
2. 对于超出新网格范围或需要移动的图标，尝试在新的网格空间内寻找空闲的位置进行放置。
|
||||
3. 如果没有足够的空间，则将无法显示的图标放入`exceedApp`数组中（可用于后续的“更多”菜单展示）。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Container as DesktopContainer.vue
|
||||
participant Hook as useDesktopContainerInit.ts
|
||||
participant Observer as ResizeObserver
|
||||
participant Storage as localStorage
|
||||
Observer->>Hook : resize事件触发
|
||||
Hook->>Hook : 计算新colCount, rowCount
|
||||
Hook->>Hook : 更新gridTemplate响应式对象
|
||||
Hook->>Hook : watch检测到变化
|
||||
Hook->>Hook : 调用rearrangeIcons()
|
||||
Hook->>Hook : 返回新的appIcons和hideAppIcons
|
||||
Hook->>Hook : 更新appIconsRef.value
|
||||
Hook->>Storage : 将appIconsRef.value序列化并存入localStorage
|
||||
Hook-->>Container : 提供更新后的appIconsRef和gridStyle
|
||||
Container->>Container : Vue自动更新DOM
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L78-L94)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L78-L94)
|
||||
|
||||
### 布局持久化实现
|
||||
|
||||
为了保证用户的个性化设置不丢失，系统利用`localStorage`实现了布局的持久化。通过另一个`watch`监听器，每当`appIconsRef`的值发生改变（无论是因为重排还是用户拖拽），都会立即将最新的图标数组序列化为JSON字符串，并存储到`localStorage`中。当下次页面加载时，初始化代码会优先读取这段存储的数据，从而恢复用户上次的桌面布局。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L88-L92)
|
||||
|
||||
## 视觉呈现与基础样式
|
||||
|
||||
### AppIcon 组件的样式绑定
|
||||
|
||||
`AppIcon.vue`组件负责渲染单个桌面图标。它通过`style`属性直接绑定了`grid-column`和`grid-row`这两个CSS Grid属性，其值来源于`iconInfo`对象的`x`和`y`坐标。例如，`grid-column: 2 / 3`表示该图标占据第2列。这种绑定方式使得图标的物理位置完全由其数据模型决定，实现了布局的动态化。
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L2-L8)
|
||||
|
||||
### basic.css 的基础样式作用
|
||||
|
||||
`basic.css`文件提供了整个应用的基础样式规则，为动态布局奠定了视觉基调。它包含了：
|
||||
- **盒模型重置**: 统一使用`border-box`，简化尺寸计算。
|
||||
- **根元素变量**: 定义了字体、颜色、间距等CSS自定义属性，便于全局主题管理。
|
||||
- **基础元素样式**: 对`body`、`a`、`button`等元素进行了基础美化。
|
||||
- **实用工具类**: 如`.container`用于创建居中的内容区域。
|
||||
- **响应式支持**: 包含了针对减少动画偏好的媒体查询。
|
||||
|
||||
虽然`DesktopContainer`和`AppIcon`组件使用了`scoped`样式，但`basic.css`提供的全局基础样式确保了整个应用的一致性和可用性。
|
||||
|
||||
**Section sources**
|
||||
- [basic.css](file://src/css/basic.css#L1-L134)
|
||||
|
||||
## 依赖关系图
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[basic.css] --> |提供基础样式| B(DesktopContainer.vue)
|
||||
C[useDesktopContainerInit.ts] --> |导出核心逻辑| B
|
||||
B --> |使用| C
|
||||
B --> |渲染| D(AppIcon.vue)
|
||||
D --> |接收props| C
|
||||
C --> |读写| E[localStorage]
|
||||
C --> |监听| F[ResizeObserver]
|
||||
F --> |响应| G[容器尺寸变化]
|
||||
C --> |类型定义| H[IGridTemplateParams.ts]
|
||||
C --> |类型定义| I[IDesktopAppIcon.ts]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
- [basic.css](file://src/css/basic.css#L1-L134)
|
||||
124
.qoder/repowiki/zh/content/响应式布局系统/图标重排与持久化.md
Normal file
124
.qoder/repowiki/zh/content/响应式布局系统/图标重排与持久化.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 图标重排与持久化
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [appIconsRef的创建过程](#appiconsref的创建过程)
|
||||
2. [localStorage数据同步机制](#localstorage数据同步机制)
|
||||
3. [网格变化监听与重排响应](#网格变化监听与重排响应)
|
||||
4. [rearrangeIcons算法详解](#rearrangeicons算法详解)
|
||||
5. [布局状态持久化策略](#布局状态持久化策略)
|
||||
|
||||
## appIconsRef的创建过程
|
||||
|
||||
`appIconsRef` 是一个 Vue 响应式引用，用于管理桌面图标的布局状态。其创建过程始于 `useDesktopContainerInit` 函数的调用，该函数接收容器选择器字符串作为参数并初始化核心布局逻辑。
|
||||
|
||||
在初始化过程中，系统首先从 `localStorage` 中读取键为 `desktopAppIconInfo` 的存储项，尝试恢复之前保存的图标位置信息。若存在历史数据，则解析为 `oldAppIcons` 数组；否则使用空数组作为默认值。随后，系统遍历当前可用的应用程序列表（`appInfos`），为每个应用创建对应的桌面图标对象。
|
||||
|
||||
对于每个新生成的图标，系统优先检查是否存在同名的历史图标记录。如果存在，则继承其坐标（x, y）；若不存在，则根据当前网格的行列数按索引自动分配初始坐标：
|
||||
- 列坐标 x = 当前索引 % 行数 + 1
|
||||
- 行坐标 y = floor(当前索引 / 行数) + 1
|
||||
|
||||
最终，这些图标数据被封装为响应式引用 `appIconsRef`，供视图层绑定使用。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L74-L94)
|
||||
|
||||
## localStorage数据同步机制
|
||||
|
||||
系统通过双向数据绑定机制实现 `appIconsRef` 与 `localStorage` 的实时同步。当用户对桌面图标进行拖拽、重排等操作导致布局变更时，Vue 的响应式系统会触发相应的监听器，将最新状态持久化到本地存储中。
|
||||
|
||||
具体而言，系统注册了一个针对 `appIconsRef.value` 的 `watch` 监听器。每当图标数组内容发生变化（如新增、删除或位置调整），该监听器便会执行回调函数，将更新后的 `appIcons` 数组序列化为 JSON 字符串，并通过 `localStorage.setItem('desktopAppIconInfo', ...)` 方法写入浏览器本地存储。
|
||||
|
||||
此机制确保了用户在刷新页面或重新打开应用后，能够恢复上次关闭时的桌面布局，实现了跨会话的个性化配置记忆功能。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L89-L92)
|
||||
|
||||
## 网格变化监听与重排响应
|
||||
|
||||
为了适应不同屏幕尺寸和窗口大小的变化，系统利用 `ResizeObserver` API 实时监测桌面容器的尺寸变动，并动态计算最优的网格列数（`colCount`）和行数（`rowCount`）。当这些参数发生改变时，系统需要智能地重新排列所有图标以避免重叠或溢出。
|
||||
|
||||
为此，系统设置了一个复合监听器 `watch(() => [gridTemplate.colCount, gridTemplate.rowCount], ...)`, 专门监控 `colCount` 和 `rowCount` 的联合变化。一旦检测到新的网格维度，监听器立即调用 `rearrangeIcons` 函数，传入当前图标列表及新的行列限制，执行自动重排逻辑。
|
||||
|
||||
该监听器包含优化判断：若新旧行列数完全一致，则直接返回，避免不必要的重排计算，提升性能效率。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L86-L88)
|
||||
|
||||
## rearrangeIcons算法详解
|
||||
|
||||
`rearrangeIcons` 函数是整个图标管理系统的核心算法，负责处理图标冲突、寻找空闲位置以及管理超出可视范围的图标。其输入为原始图标数组和目标网格的最大行列数，输出为包含正常显示图标和隐藏图标的结构体。
|
||||
|
||||
### 冲突检测与占用标记
|
||||
|
||||
算法首先创建一个 `Set<string>` 类型的 `occupied` 集合，用于记录已被占用的网格单元。通过辅助函数 `key(x, y)` 将二维坐标转换为唯一字符串标识（如 `"1,2"`），实现高效的哈希查找。
|
||||
|
||||
### 分阶段处理流程
|
||||
|
||||
1. **第一阶段：保留有效位置**
|
||||
- 遍历所有图标，筛选出位于当前网格范围内的图标（即 `x ≤ maxCol && y ≤ maxRow`）
|
||||
- 检查目标位置是否已被占用，若未占用则将其加入结果数组 `appIcons` 并标记为已占用
|
||||
- 对于位置无效或冲突的图标，则暂存至临时数组 `temp`
|
||||
|
||||
2. **第二阶段：填补空位**
|
||||
- 遍历 `temp` 数组中的待安置图标
|
||||
- 若当前已放置图标数量小于网格总容量（`maxCol * maxRow`），则从左上角 `(1,1)` 开始逐行扫描，寻找第一个空闲位置进行安置
|
||||
- 一旦找到合适位置，立即跳出内层循环，继续处理下一个图标
|
||||
|
||||
3. **第三阶段：处理溢出图标**
|
||||
- 若网格已满且仍有剩余图标无法安置，则将其归类至 `hideAppIcons` 数组
|
||||
- 这些图标将在 UI 层面被隐藏，防止界面混乱
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始重排]) --> ValidatePosition["验证图标位置有效性"]
|
||||
ValidatePosition --> InRange{"是否在网格范围内?"}
|
||||
InRange --> |是| CheckOccupied["检查位置是否被占用"]
|
||||
InRange --> |否| ToTemp["加入临时数组 temp"]
|
||||
CheckOccupied --> IsFree{"位置空闲?"}
|
||||
IsFree --> |是| PlaceIcon["放置图标并标记占用"]
|
||||
IsFree --> |否| ToTemp
|
||||
PlaceIcon --> NextIcon["处理下一个图标"]
|
||||
ToTemp --> NextIcon
|
||||
NextIcon --> AllProcessed{"所有图标处理完毕?"}
|
||||
AllProcessed --> |否| ValidatePosition
|
||||
AllProcessed --> |是| FillEmpty["填补空位"]
|
||||
FillEmpty --> HasSpace{"仍有空位?"}
|
||||
HasSpace --> |是| FindSlot["从(1,1)开始寻找空位"]
|
||||
HasSpace --> |否| HideExcess["隐藏超出图标"]
|
||||
FindSlot --> CanPlace{"能否放置?"}
|
||||
CanPlace --> |是| UpdateAppIcons["更新 appIcons 数组"]
|
||||
CanPlace --> |否| HideExcess
|
||||
UpdateAppIcons --> MoreTemp{"temp 数组为空?"}
|
||||
MoreTemp --> |否| FillEmpty
|
||||
MoreTemp --> |是| ReturnResult["返回结果: appIcons + hideAppIcons"]
|
||||
HideExcess --> ReturnResult
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
## 布局状态持久化策略
|
||||
|
||||
系统的布局持久化策略建立在 Vue 的响应式系统与浏览器本地存储的协同工作之上。`appIconsRef` 作为单一数据源（Single Source of Truth），集中管理所有图标的坐标信息。任何对图标的修改操作（无论是用户交互还是程序逻辑）都会反映到该引用上。
|
||||
|
||||
通过 `watch` 监听器，系统实现了从内存状态到持久化存储的单向同步。这种设计具有以下优势：
|
||||
|
||||
- **自动同步**：无需手动调用保存方法，所有变更自动记录
|
||||
- **原子性保证**：每次写入都是完整的数组快照，避免部分更新导致的数据不一致
|
||||
- **跨会话恢复**：页面刷新后可通过 `localStorage.getItem('desktopAppIconInfo')` 重建初始状态
|
||||
- **容错处理**：使用 `JSON.parse(... || '[]')` 确保解析失败时返回安全默认值
|
||||
|
||||
该策略构成了完整的“读取→运行→修改→保存”闭环，保障了用户体验的一致性和数据的安全性。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L89-L92)
|
||||
221
.qoder/repowiki/zh/content/响应式布局系统/布局初始化逻辑.md
Normal file
221
.qoder/repowiki/zh/content/响应式布局系统/布局初始化逻辑.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 布局初始化逻辑
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [核心组件分析](#核心组件分析)
|
||||
3. [生命周期与容器初始化](#生命周期与容器初始化)
|
||||
4. [DOM查询机制与containerStr参数](#dom查询机制与containerstr参数)
|
||||
5. [网格模板初始状态设计](#网格模板初始状态设计)
|
||||
6. [ResizeObserver响应式尺寸监听](#resizeobserver响应式尺寸监听)
|
||||
7. [图标重排逻辑](#图标重排逻辑)
|
||||
8. [依赖关系图](#依赖关系图)
|
||||
|
||||
## 简介
|
||||
`useDesktopContainerInit` 是一个 Vue 3 组合式 API Hook，用于在桌面容器组件挂载时初始化其布局系统。该 Hook 负责建立基于 CSS Grid 的动态网格布局，并通过 `ResizeObserver` 实现响应式行为，确保桌面图标能根据容器尺寸自动调整排列方式。
|
||||
|
||||
## 核心组件分析
|
||||
|
||||
### useDesktopContainerInit 功能概览
|
||||
此 Hook 封装了桌面容器的核心初始化逻辑，包括：
|
||||
- 容器元素的 DOM 查询与绑定
|
||||
- 网格布局参数的初始化与响应式管理
|
||||
- 容器尺寸变化的监听与处理
|
||||
- 桌面图标的持久化存储与位置管理
|
||||
- 图标超出可视区域时的隐藏策略
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## 生命周期与容器初始化
|
||||
|
||||
### onMounted 中的初始化流程
|
||||
`useDesktopContainerInit` 利用 Vue 的 `onMounted` 生命周期钩子，在组件挂载完成后立即执行容器初始化操作。这一时机确保了对应的 DOM 元素已经存在于页面中，可以安全地进行查询和观察。
|
||||
|
||||
在 `onMounted` 回调中，Hook 首先通过 `document.querySelector(containerStr)` 获取指定的容器元素引用，并将其赋值给局部变量 `container`。随后，立即调用 `ResizeObserver` 的 `observe` 方法开始监听该容器的尺寸变化。
|
||||
|
||||
当组件被卸载时，`onUnmounted` 钩子会确保清理工作正确执行：停止对容器的观察（`unobserve`）并断开 `ResizeObserver` 实例（`disconnect`），防止内存泄漏。
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Component as "DesktopContainer组件"
|
||||
participant Hook as "useDesktopContainerInit"
|
||||
participant DOM as "浏览器DOM"
|
||||
participant Observer as "ResizeObserver"
|
||||
Component->>Hook : setup()
|
||||
Hook->>Hook : 初始化gridTemplate等响应式数据
|
||||
Component->>Component : 渲染完成
|
||||
Component->>Hook : onMounted触发
|
||||
Hook->>DOM : querySelector(containerStr)
|
||||
DOM-->>Hook : 返回容器元素
|
||||
Hook->>Observer : new ResizeObserver(callback)
|
||||
Hook->>Observer : observe(container)
|
||||
Note over Hook,Observer : 开始监听容器尺寸变化
|
||||
loop 每次窗口或容器大小改变
|
||||
Observer->>Observer : 触发回调
|
||||
Observer->>Hook : 执行回调函数
|
||||
Hook->>Hook : 重新计算gridTemplate参数
|
||||
Hook->>Hook : 更新gridStyle
|
||||
end
|
||||
Component->>Component : 组件即将销毁
|
||||
Component->>Hook : onUnmounted触发
|
||||
Hook->>Observer : unobserve(container)
|
||||
Hook->>Observer : disconnect()
|
||||
Note over Hook,Observer : 清理资源，防止内存泄漏
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L70-L85)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L70-L85)
|
||||
|
||||
## DOM查询机制与containerStr参数
|
||||
|
||||
### containerStr 参数的作用
|
||||
`containerStr` 是传递给 `useDesktopContainerInit` 函数的一个字符串参数，它代表一个 CSS 选择器。该选择器用于定位需要初始化的桌面容器 DOM 元素。
|
||||
|
||||
在当前实现中，`DesktopContainer.vue` 组件传入的值为 `.desktop-icons-container`，这是一个类选择器，指向模板中具有该类名的 `<div>` 元素。这种设计使得 Hook 具有良好的通用性，可以在不同的容器上复用，只需传入相应的选择器即可。
|
||||
|
||||
```typescript
|
||||
// 在 DesktopContainer.vue 中的调用示例
|
||||
const { appIconsRef, gridStyle, gridTemplate } = useDesktopContainerInit('.desktop-icons-container')
|
||||
```
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L10-L13)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14)
|
||||
|
||||
## 网格模板初始状态设计
|
||||
|
||||
### gridTemplate 初始值的设计意图
|
||||
`gridTemplate` 对象使用 Vue 的 `reactive` 函数创建，使其成为一个响应式对象。其初始状态的设计体现了以下几个关键考量：
|
||||
|
||||
| 属性 | 默认值 | 设计意图 |
|
||||
|------|--------|----------|
|
||||
| `cellExpectWidth` | 90 | 预设每个单元格的理想宽度（像素），作为网格列宽的基础 |
|
||||
| `cellExpectHeight` | 110 | 预设每个单元格的理想高度（像素），作为网格行高的基础 |
|
||||
| `gapX` / `gapY` | 4 | 设置行列之间的间隙，提供视觉呼吸空间，避免图标紧贴 |
|
||||
| `colCount` / `rowCount` | 1 | 初始行列数设为1，表示最小的网格结构，将在首次ResizeObserver回调中被实际尺寸覆盖 |
|
||||
|
||||
这些默认值共同定义了一个合理的起始布局，即使在 `ResizeObserver` 回调执行前，也能保证界面有一个基本的、可预测的显示状态。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class IGridTemplateParams {
|
||||
+readonly cellExpectWidth : number
|
||||
+readonly cellExpectHeight : number
|
||||
+cellRealWidth : number
|
||||
+cellRealHeight : number
|
||||
+gapX : number
|
||||
+gapY : number
|
||||
+colCount : number
|
||||
+rowCount : number
|
||||
}
|
||||
class useDesktopContainerInit {
|
||||
-container : HTMLElement
|
||||
-gridTemplate : IGridTemplateParams
|
||||
-gridStyle : ComputedRef
|
||||
-ro : ResizeObserver
|
||||
+useDesktopContainerInit(containerStr : string) : Object
|
||||
}
|
||||
useDesktopContainerInit --> IGridTemplateParams : "包含"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L4-L20)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L16-L32)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L16-L32)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L4-L20)
|
||||
|
||||
## ResizeObserver响应式尺寸监听
|
||||
|
||||
### 回调中的尺寸计算逻辑
|
||||
`ResizeObserver` 的回调函数是实现响应式布局的核心。每当容器的尺寸发生变化时，该回调都会被触发，执行以下关键步骤：
|
||||
|
||||
1. **获取容器实际尺寸**：通过 `container.getBoundingClientRect()` 获取容器当前的精确几何信息。
|
||||
2. **计算行列数量**：利用容器宽度和预设单元格宽度（含间隙）计算出应显示的列数和行数。
|
||||
```javascript
|
||||
colCount = Math.floor((width + gapX) / (expectWidth + gapX))
|
||||
```
|
||||
3. **计算实际单元格尺寸**：在确定了行列数后，重新分配容器内部空间，计算出每个单元格的实际宽高，确保网格完全填充容器且无多余空白。
|
||||
```javascript
|
||||
realWidth = (totalWidth - totalGapX) / colCount
|
||||
```
|
||||
|
||||
这种“期望尺寸 -> 计算行列 -> 反推实际尺寸”的模式，既保证了图标的相对大小一致性，又实现了完美的空间利用率。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L45-L65)
|
||||
|
||||
## 图标重排逻辑
|
||||
|
||||
### rearrangeIcons 函数的工作机制
|
||||
当网格的行列数发生变化时，`watch` 监听器会触发 `rearrangeIcons` 函数，负责重新安排所有桌面图标的可见性和位置。
|
||||
|
||||
该函数的主要逻辑如下：
|
||||
1. 创建一个 `Set` 来记录已被占用的网格坐标 `(x,y)`。
|
||||
2. 遍历所有图标，优先将位于新网格范围内的图标保留在原位。
|
||||
3. 对于超出新网格范围的图标，尝试在网格内寻找空闲位置进行安置。
|
||||
4. 如果网格已满，则将无法放置的图标放入 `hideAppIcons` 数组，这些图标将被隐藏。
|
||||
|
||||
这确保了用户界面的连续性，尽可能保留用户的原有布局习惯。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[开始重排图标] --> B{遍历所有图标}
|
||||
B --> C["检查(x,y)是否在maxCol/maxRow范围内"]
|
||||
C --> |是| D["检查该位置是否已被占用"]
|
||||
D --> |否| E["将图标加入appIcons数组<br/>标记位置为已占用"]
|
||||
D --> |是| F["跳过，不添加"]
|
||||
C --> |否| G["将图标暂存到temp数组"]
|
||||
G --> H{遍历temp数组}
|
||||
H --> I["检查appIcons数组是否已满"]
|
||||
I --> |否| J["在网格中寻找第一个空位"]
|
||||
J --> K["将图标放入空位<br/>标记位置为已占用"]
|
||||
K --> L["加入appIcons数组"]
|
||||
I --> |是| M["加入hideAppIcons数组"]
|
||||
M --> N[结束]
|
||||
L --> N
|
||||
E --> N
|
||||
F --> N
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
## 依赖关系图
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "UI层"
|
||||
DesktopContainerVue["DesktopContainer.vue"]
|
||||
AppIconVue["AppIcon.vue"]
|
||||
UseHook["useDesktopContainerInit.ts"]
|
||||
end
|
||||
subgraph "类型定义"
|
||||
IGridTemplate["IGridTemplateParams.ts"]
|
||||
IDesktopAppIcon["IDesktopAppIcon.ts"]
|
||||
end
|
||||
DesktopContainerVue --> UseHook : "调用"
|
||||
UseHook --> IGridTemplate : "导入接口"
|
||||
UseHook --> IDesktopAppIcon : "导入接口"
|
||||
DesktopContainerVue --> AppIconVue : "使用组件"
|
||||
UseHook --> AppIconVue : "通过返回值传递数据"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
140
.qoder/repowiki/zh/content/响应式布局系统/网格参数计算机制.md
Normal file
140
.qoder/repowiki/zh/content/响应式布局系统/网格参数计算机制.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# 网格参数计算机制
|
||||
|
||||
<cite>
|
||||
**本文档引用文件**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [basic.css](file://src/css/basic.css)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [引言](#引言)
|
||||
2. [核心数据结构定义](#核心数据结构定义)
|
||||
3. [ResizeObserver中的动态网格计算逻辑](#resizeobserver中的动态网格计算逻辑)
|
||||
4. [实际单元格尺寸的精确控制](#实际单元格尺寸的精确控制)
|
||||
5. [gridStyle样式对象的生成与绑定](#gridstyle样式对象的生成与绑定)
|
||||
6. [图标重排机制分析](#图标重排机制分析)
|
||||
7. [总结](#总结)
|
||||
|
||||
## 引言
|
||||
本项目通过Vue 3组合式API实现了一个响应式的桌面图标容器布局系统。其核心在于利用`ResizeObserver`监听容器尺寸变化，动态计算并调整CSS Grid布局的行列数及单元格大小。该机制确保在不同屏幕尺寸和窗口缩放情况下，桌面图标能够自适应排列，同时保持良好的视觉一致性与交互体验。
|
||||
|
||||
## 核心数据结构定义
|
||||
系统通过接口`IGridTemplateParams`定义了网格布局所需的核心参数集合：
|
||||
|
||||
```typescript
|
||||
export interface IGridTemplateParams {
|
||||
readonly cellExpectWidth: number; // 预期单元格宽度
|
||||
readonly cellExpectHeight: number; // 预期单元格高度
|
||||
cellRealWidth: number; // 实际单元格宽度
|
||||
cellRealHeight: number; // 实际单元格高度
|
||||
gapX: number; // 列间距
|
||||
gapY: number; // 行间距
|
||||
colCount: number; // 总列数
|
||||
rowCount: number; // 总行数
|
||||
}
|
||||
```
|
||||
|
||||
这些参数构成了整个动态网格计算的基础，其中预期尺寸为设计基准值，而实际尺寸则由运行时环境动态决定。
|
||||
|
||||
**Section sources**
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L3-L20)
|
||||
|
||||
## ResizeObserver中的动态网格计算逻辑
|
||||
当容器尺寸发生变化时，`ResizeObserver`回调函数会触发重新计算流程。关键步骤如下：
|
||||
|
||||
1. **获取容器几何信息**：通过`getBoundingClientRect()`获取当前容器的实际宽高。
|
||||
2. **计算列数（colCount）**：
|
||||
```ts
|
||||
gridTemplate.colCount = Math.floor((containerRect.width + gridTemplate.gapX) / (gridTemplate.cellExpectWidth + gridTemplate.gapX));
|
||||
```
|
||||
3. **计算行数（rowCount）**：
|
||||
```ts
|
||||
gridTemplate.rowCount = Math.floor((containerRect.height + gridTemplate.gapY) / (gridTemplate.cellExpectHeight + gridTemplate.gapY));
|
||||
```
|
||||
|
||||
此算法的本质是将容器总宽度（或高度）加上一个间隙值，再除以“单个单元格宽度+列间距”，从而避免因浮点误差导致最后一列无法完整显示的问题。使用`Math.floor`向下取整保证结果为有效整数。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L39-L40)
|
||||
|
||||
## 实际单元格尺寸的精确控制
|
||||
在确定了行列数量后，系统进一步计算每个单元格的实际像素尺寸，以充分利用可用空间并消除边缘空白。
|
||||
|
||||
### 计算公式推导
|
||||
- **可用总宽度** = 容器宽度 - 所有列间隙之和
|
||||
即：`w = containerRect.width - gapX * (colCount - 1)`
|
||||
- **每列实际宽度** = 可用总宽度 ÷ 列数
|
||||
即：`cellRealWidth = w / colCount`
|
||||
|
||||
同理可得行方向上的计算：
|
||||
- `h = containerRect.height - gapY * (rowCount - 1)`
|
||||
- `cellRealHeight = h / rowCount`
|
||||
|
||||
### 浮点数精度控制
|
||||
由于浏览器渲染对小数像素的支持有限，直接使用浮点值可能导致布局抖动或错位。因此系统采用`toFixed(2)`保留两位小数，并通过`Number()`转换回数值类型，既保证精度又提升渲染稳定性。
|
||||
|
||||
```ts
|
||||
gridTemplate.cellRealWidth = Number((w / gridTemplate.colCount).toFixed(2))
|
||||
gridTemplate.cellRealHeight = Number((h / gridTemplate.rowCount).toFixed(2))
|
||||
```
|
||||
|
||||
这种处理方式平衡了空间利用率与视觉平滑性。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L41-L42)
|
||||
|
||||
## gridStyle样式对象的生成与绑定
|
||||
`gridStyle`是一个基于Vue `computed`的响应式计算属性，负责将`gridTemplate`中的参数转化为标准的CSS Grid样式规则。
|
||||
|
||||
### 样式对象结构
|
||||
```ts
|
||||
const gridStyle = computed(() => ({
|
||||
gridTemplateColumns: `repeat(${gridTemplate.colCount}, minmax(${gridTemplate.cellExpectWidth}px, 1fr))`,
|
||||
gridTemplateRows: `repeat(${gridTemplate.rowCount}, minmax(${gridTemplate.cellExpectHeight}px, 1fr))`,
|
||||
gap: `${gridTemplate.gapX}px ${gridTemplate.gapY}px`
|
||||
}))
|
||||
```
|
||||
|
||||
### 关键特性说明
|
||||
- **`minmax()`函数应用**：确保每列最小宽度不低于`cellExpectWidth`，但允许在空间充足时扩展至等分的`1fr`比例。
|
||||
- **动态重复语法**：`repeat(colCount, ...)`自动构建指定数量的轨道定义。
|
||||
- **双向间隙设置**：`gap`属性分别设置横向与纵向间距。
|
||||
|
||||
该样式对象最终通过`:style="gridStyle"`绑定到`.desktop-icons-container`元素上，实现视图层的实时更新。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[容器尺寸变化] --> B{ResizeObserver触发}
|
||||
B --> C[计算colCount/rrowCount]
|
||||
C --> D[计算cellRealWidth/Height]
|
||||
D --> E[更新gridTemplate响应式对象]
|
||||
E --> F[gridStyle重新计算]
|
||||
F --> G[DOM样式自动更新]
|
||||
G --> H[完成布局重绘]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L20-L30)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1)
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L20-L30)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1)
|
||||
|
||||
## 图标重排机制分析
|
||||
每当行列数发生变更时，系统会调用`rearrangeIcons`函数对所有图标进行位置重分配，确保其不超出可视范围且无重叠。
|
||||
|
||||
### 重排策略
|
||||
1. **优先保留原有坐标**：若图标的原位置仍在新网格范围内且未被占用，则保留原位。
|
||||
2. **空位填充机制**：对于越界或冲突的图标，遍历网格寻找首个可用空位（从左上角开始）。
|
||||
3. **溢出图标管理**：当网格已满时，超出部分存入`hideAppIcons`数组，可用于后续提示用户。
|
||||
|
||||
该机制保障了用户体验的一致性，避免图标因窗口缩放而丢失或错乱。
|
||||
|
||||
**Section sources**
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L102-L156)
|
||||
|
||||
## 总结
|
||||
本系统的动态网格计算机制充分体现了响应式设计的思想。通过结合`ResizeObserver`、Vue响应式系统与CSS Grid布局，实现了从容器尺寸→行列数量→单元格尺寸→样式绑定→图标定位的完整闭环。特别是在实际尺寸计算中对间隙总和的扣除与浮点精度的控制，展现了对细节的高度关注。整体架构清晰、逻辑严谨，具备良好的可维护性与扩展性。
|
||||
161
.qoder/repowiki/zh/content/快速开始.md
Normal file
161
.qoder/repowiki/zh/content/快速开始.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# 快速开始
|
||||
|
||||
<cite>
|
||||
**本文档中引用的文件**
|
||||
- [README.md](file://README.md)
|
||||
- [package.json](file://package.json)
|
||||
- [vite.config.ts](file://vite.config.ts)
|
||||
- [main.ts](file://src/main.ts)
|
||||
- [index.html](file://index.html)
|
||||
- [tsconfig.app.json](file://tsconfig.app.json)
|
||||
- [tsconfig.json](file://tsconfig.json)
|
||||
- [tsconfig.node.json](file://tsconfig.node.json)
|
||||
- [env.d.ts](file://env.d.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [开发环境准备](#开发环境准备)
|
||||
3. [项目初始化与依赖安装](#项目初始化与依赖安装)
|
||||
4. [启动开发服务器](#启动开发服务器)
|
||||
5. [构建生产版本](#构建生产版本)
|
||||
6. [package.json 脚本命令详解](#packagejson-脚本命令详解)
|
||||
7. [常见问题排查](#常见问题排查)
|
||||
8. [首次运行效果验证](#首次运行效果验证)
|
||||
|
||||
## 简介
|
||||
|
||||
`vue-desktop` 是一个基于 Vue 3 和 Vite 构建的桌面风格前端项目，模拟操作系统桌面界面，支持图标布局、窗口管理等功能。本指南旨在帮助开发者快速在本地搭建开发环境，完成依赖安装、服务启动和构建发布等核心操作，并提供新手友好的故障排查建议。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L0-L37)
|
||||
|
||||
## 开发环境准备
|
||||
|
||||
在开始之前，请确保您的开发机器满足以下最低要求：
|
||||
|
||||
- **浏览器支持**：Chrome 84+、Edge 84+、Firefox 79+、Safari 14+
|
||||
- **Node.js 版本**：根据 `package.json` 中的 `engines` 字段，推荐使用 Node.js v20.19.0 或更高版本（v22.12.0 及以上），不支持 IE 浏览器。
|
||||
- **包管理工具**：项目使用 `pnpm` 进行依赖管理，需提前安装 pnpm。
|
||||
|
||||
推荐开发环境为 VSCode 配合 Volar 插件，以获得最佳的 `.vue` 文件类型支持和开发体验。
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L5-L7)
|
||||
- [README.md](file://README.md#L0-L6)
|
||||
|
||||
## 项目初始化与依赖安装
|
||||
|
||||
进入项目根目录后，执行以下命令安装项目所需的所有依赖：
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
该命令将根据 `package.json` 和 `pnpm-lock.yaml` 安装所有生产与开发依赖，包括 Vue 3、Pinia、Naive UI、Vite、TypeScript 等核心库。
|
||||
|
||||
安装完成后，您可以在 `node_modules/` 目录下看到所有已安装的依赖包。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L30-L31)
|
||||
- [package.json](file://package.json#L10-L41)
|
||||
|
||||
## 启动开发服务器
|
||||
|
||||
安装完成后，可通过以下命令启动本地开发服务器：
|
||||
|
||||
```bash
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
此命令实际执行的是 `vite` 命令，启动基于 Vite 的开发服务器，具备热更新（HMR）功能，修改代码后浏览器会自动刷新。
|
||||
|
||||
默认情况下，开发服务器将在 `http://localhost:5173` 启动。打开浏览器访问该地址即可查看应用界面。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L33-L34)
|
||||
- [package.json](file://package.json#L12)
|
||||
- [vite.config.ts](file://vite.config.ts#L0-L29)
|
||||
|
||||
## 构建生产版本
|
||||
|
||||
当需要发布应用时，运行以下命令进行生产环境构建：
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
该命令会依次执行：
|
||||
1. `type-check`：使用 `vue-tsc` 对项目进行类型检查
|
||||
2. `build-only`：调用 `vite build` 编译并压缩代码，输出至 `dist/` 目录
|
||||
|
||||
构建完成后，`dist/` 文件夹将包含所有静态资源，可部署到任意静态服务器。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L35-L37)
|
||||
- [package.json](file://package.json#L13-L15)
|
||||
|
||||
## package.json 脚本命令详解
|
||||
|
||||
以下是 `package.json` 中定义的主要脚本及其作用：
|
||||
|
||||
| 脚本名称 | 命令内容 | 功能说明 |
|
||||
|---------|--------|--------|
|
||||
| `dev` | `vite` | 启动 Vite 开发服务器，支持热重载 |
|
||||
| `build` | `run-p type-check "build-only {@}" --` | 并行执行类型检查和构建任务 |
|
||||
| `preview` | `vite preview` | 在本地预览 `dist/` 目录中的生产构建结果 |
|
||||
| `build-only` | `vite build` | 仅执行构建，不进行类型检查 |
|
||||
| `type-check` | `vue-tsc --build` | 使用 `vue-tsc` 对 `.vue` 文件进行类型检查 |
|
||||
| `format` | `prettier --write src/` | 使用 Prettier 格式化 `src/` 目录下的代码 |
|
||||
|
||||
这些脚本通过 `npm-run-all2` 实现并发执行（如 `run-p`），提升构建效率。
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L11-L20)
|
||||
|
||||
## 常见问题排查
|
||||
|
||||
### Node.js 版本不兼容
|
||||
|
||||
如果运行 `pnpm install` 时报错提示 Node.js 版本不符合要求，请检查当前版本：
|
||||
|
||||
```bash
|
||||
node -v
|
||||
```
|
||||
|
||||
确保版本符合 `^20.19.0 || >=22.12.0` 范围。建议使用 [nvm](https://github.com/nvm-sh/nvm) 管理多个 Node.js 版本。
|
||||
|
||||
### 依赖安装失败
|
||||
|
||||
若 `pnpm install` 失败，尝试以下步骤：
|
||||
1. 清除缓存：`pnpm store prune`
|
||||
2. 检查网络，必要时配置镜像源
|
||||
3. 删除 `node_modules` 和 `pnpm-lock.yaml` 后重新安装
|
||||
|
||||
### 类型检查错误
|
||||
|
||||
运行 `pnpm type-check` 时可能出现类型错误，通常是由于 `.vue` 文件的 TypeScript 类型未被正确识别。确保已安装 Volar 插件并禁用 Vetur。
|
||||
|
||||
### 构建失败
|
||||
|
||||
构建失败可能由语法错误或路径别名问题引起。检查 `vite.config.ts` 中的 `@` 别名配置是否正确指向 `src/` 目录。
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L5-L7)
|
||||
- [vite.config.ts](file://vite.config.ts#L18-L22)
|
||||
- [tsconfig.app.json](file://tsconfig.app.json#L0-L24)
|
||||
- [env.d.ts](file://env.d.ts#L0-L1)
|
||||
|
||||
## 首次运行效果验证
|
||||
|
||||
成功运行 `pnpm dev` 并在浏览器中打开 `http://localhost:5173` 后，您应看到一个类桌面风格的界面，包含网格布局的应用图标容器。页面标题为“vue-desktop”，DOM 结构中 `<div id="app">` 已被 Vue 应用挂载。
|
||||
|
||||
主组件 `App.vue` 通过 `main.ts` 初始化，使用了 Pinia 状态管理和 Naive UI 组件库。界面响应式适配窗口大小变化，图标按网格自动排列。
|
||||
|
||||
若能看到图标容器且无控制台报错，则表示环境搭建成功。
|
||||
|
||||
**Section sources**
|
||||
- [index.html](file://index.html#L0-L13)
|
||||
- [main.ts](file://src/main.ts#L0-L15)
|
||||
- [src/ui/desktop-container/DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L0-L22)
|
||||
- [src/ui/desktop-container/useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L0-L37)
|
||||
149
.qoder/repowiki/zh/content/技术栈与依赖.md
Normal file
149
.qoder/repowiki/zh/content/技术栈与依赖.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 技术栈与依赖
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [package.json](file://package.json)
|
||||
- [vite.config.ts](file://vite.config.ts)
|
||||
- [tsconfig.json](file://tsconfig.json)
|
||||
- [uno.config.ts](file://uno.config.ts)
|
||||
- [src/main.ts](file://src/main.ts)
|
||||
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts)
|
||||
- [src/stores/counter.ts](file://src/stores/counter.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [核心框架：Vue 3](#核心框架vue-3)
|
||||
2. [状态管理：Pinia](#状态管理pinia)
|
||||
3. [UI 组件库：Naive UI](#ui-组件库naive-ui)
|
||||
4. [原子化样式：UnoCSS](#原子化样式unocss)
|
||||
5. [构建工具：Vite](#构建工具vite)
|
||||
6. [类型安全：TypeScript](#类型安全typescript)
|
||||
7. [关键依赖项版本与选择理由](#关键依赖项版本与选择理由)
|
||||
|
||||
## 核心框架：Vue 3
|
||||
|
||||
本项目采用 Vue 3 作为核心前端框架，利用其组合式 API（Composition API）实现更灵活、可复用的逻辑组织。在 `main.ts` 文件中通过 `createApp` 初始化应用实例，并挂载根组件 `App.vue`，构成整个应用的入口。
|
||||
|
||||
Vue 3 提供了响应式系统、虚拟 DOM 渲染机制以及强大的组件化能力，使得桌面级 Web 应用的开发更加高效和模块化。结合 Vite 的现代构建流程，实现了极快的冷启动和热更新体验。
|
||||
|
||||
**Section sources**
|
||||
- [src/main.ts](file://src/main.ts#L1-L15)
|
||||
|
||||
## 状态管理：Pinia
|
||||
|
||||
Pinia 作为 Vue 官方推荐的状态管理库，在本项目中用于集中管理全局状态。通过 `defineStore` 创建具有命名空间的 store 实例，如 `useCounterStore`，支持使用 `ref` 和 `computed` 构建响应式状态，并导出操作方法以供组件调用。
|
||||
|
||||
在 `main.ts` 中通过 `app.use(createPinia())` 注册 Pinia 插件，使所有组件均可通过 `useXXXStore()` 获取共享状态，避免了传统 Vuex 的冗余配置，提升了开发效率与类型推断准确性。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class useCounterStore {
|
||||
+count : Ref<number>
|
||||
+doubleCount : ComputedRef<number>
|
||||
+increment() : void
|
||||
}
|
||||
useCounterStore --> ref : "uses"
|
||||
useCounterStore --> computed : "uses"
|
||||
useCounterStore --> defineStore : "created via"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [src/stores/counter.ts](file://src/stores/counter.ts#L3-L11)
|
||||
|
||||
**Section sources**
|
||||
- [src/stores/counter.ts](file://src/stores/counter.ts#L1-L13)
|
||||
- [src/main.ts](file://src/main.ts#L8-L9)
|
||||
|
||||
## UI 组件库：Naive UI
|
||||
|
||||
项目集成 Naive UI 作为 UI 组件解决方案，提供高质量、可定制的 Vue 3 组件集。为优化打包体积并实现按需引入，项目在 `src/common/naive-ui/components.ts` 中手动创建了一个轻量化的 UI 实例，仅注册所需组件（如 `NButton`, `NCard`, `NConfigProvider`），并通过 `create()` 方法生成可被 `app.use()` 注册的插件对象。
|
||||
|
||||
此外，项目还通过 `discrete-api.ts` 导出独立使用的 API（如 message、modal），并在 `theme.ts` 中扩展默认主题，自定义主色调为 `#0070f3`，确保视觉风格统一。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class naiveUi {
|
||||
+components : Array<Component>
|
||||
}
|
||||
naiveUi --> NButton : "includes"
|
||||
naiveUi --> NCard : "includes"
|
||||
naiveUi --> NConfigProvider : "includes"
|
||||
naiveUi --> create : "created via"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts#L1-L11)
|
||||
- [src/common/naive-ui/theme.ts](file://src/common/naive-ui/theme.ts#L2-L14)
|
||||
|
||||
**Section sources**
|
||||
- [src/common/naive-ui/components.ts](file://src/common/naive-ui/components.ts#L1-L11)
|
||||
|
||||
## 原子化样式：UnoCSS
|
||||
|
||||
UnoCSS 是一个即时（on-the-fly）原子化 CSS 引擎，取代传统的 Tailwind CSS 实现方式。它允许开发者直接在模板中使用类名（如 `flex`, `p-4`, `text-lg`），并在构建时动态生成最小化 CSS，极大提升样式编写效率并减少冗余代码。
|
||||
|
||||
项目通过 `unocss/vite` 插件集成 UnoCSS，并在 `uno.config.ts` 中启用 `transformerVariantGroup` 和 `transformerDirectives`，支持嵌套语法（如 `hover:(bg-red-500 text-white)`）和 `@apply` 指令，增强可读性与灵活性。同时，`virtual:uno.css` 被引入 `main.ts`，确保样式正确注入。
|
||||
|
||||
**Section sources**
|
||||
- [uno.config.ts](file://uno.config.ts#L1-L10)
|
||||
- [vite.config.ts](file://vite.config.ts#L15-L16)
|
||||
- [src/main.ts](file://src/main.ts#L6)
|
||||
|
||||
## 构建工具：Vite
|
||||
|
||||
Vite 作为现代前端构建工具，基于 ES 模块原生支持，显著提升了开发服务器的启动速度与热更新性能。项目通过 `vite.config.ts` 配置核心插件：
|
||||
|
||||
- `@vitejs/plugin-vue`：支持 `.vue` 单文件组件解析
|
||||
- `@vitejs/plugin-vue-jsx`：支持 JSX/TSX 语法
|
||||
- `vite-plugin-vue-devtools`：集成 Vue DevTools 调试工具
|
||||
- `unocss/vite`：集成 UnoCSS 样式引擎
|
||||
|
||||
配置中还设置了路径别名 `@` 指向 `src` 目录，便于模块导入。Vite 的开箱即用特性与 TypeScript、JSX、Sass 等技术无缝集成，构成了高效的开发环境基础。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["用户请求 /"] --> B[Vite Dev Server]
|
||||
B --> C{资源类型}
|
||||
C --> |HTML| D[index.html]
|
||||
C --> |.vue 文件| E[Vite 解析 SFC]
|
||||
E --> F[编译 template/script/style]
|
||||
F --> G[返回 ES Module]
|
||||
C --> |TypeScript| H[Vite 实时转译]
|
||||
H --> I[浏览器执行]
|
||||
C --> |UnoCSS 类名| J[UnoCSS 动态生成 CSS]
|
||||
J --> K[注入 style 标签]
|
||||
I & K --> L[页面渲染完成]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||||
|
||||
**Section sources**
|
||||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||||
|
||||
## 类型安全：TypeScript
|
||||
|
||||
TypeScript 在项目中承担关键的角色，提供静态类型检查以预防运行时错误。项目采用分层配置策略，`tsconfig.json` 通过 `references` 引入 `tsconfig.node.json` 和 `tsconfig.app.json`，分别处理 Node.js 环境与应用代码的类型定义。
|
||||
|
||||
`.vue` 文件的类型支持通过 `vue-tsc` 实现，替代标准 `tsc` 进行类型检查，确保模板中的 props、emits 等具备完整类型推断。配合 VSCode 与 Volar 插件，开发者可在编辑器中获得精准的智能提示与错误检测。
|
||||
|
||||
**Section sources**
|
||||
- [tsconfig.json](file://tsconfig.json#L1-L12)
|
||||
- [README.md](file://README.md#L12-L15)
|
||||
|
||||
## 关键依赖项版本与选择理由
|
||||
|
||||
| 依赖包 | 版本范围 | 选择理由 |
|
||||
|-------|--------|---------|
|
||||
| vue | ^3.5.18 | 使用最新稳定版 Vue 3，支持 Composition API 与 Fragment |
|
||||
| pinia | ^3.0.3 | 官方状态管理库，轻量、类型友好、API 简洁 |
|
||||
| naive-ui | ^2.42.0 | 功能丰富、文档完善、支持 Tree-shaking 的 Vue 3 组件库 |
|
||||
| unocss | ^66.4.2 | 即时原子化 CSS，性能优于传统方案，支持高度定制 |
|
||||
| vite | ^7.0.6 | 极速 HMR、原生 ES Modules 支持、生态成熟 |
|
||||
| typescript | ~5.8.0 | 精确控制 TS 版本，避免意外升级导致兼容问题 |
|
||||
| vue-tsc | ^3.0.4 | 专为 Vue + TypeScript 设计的类型检查工具，支持 `<script setup>` 和模板类型校验 |
|
||||
|
||||
这些依赖共同构建了一个现代化、高性能、类型安全的前端开发体系，为项目的长期维护与扩展提供了坚实基础。
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L1-L43)
|
||||
182
.qoder/repowiki/zh/content/构建与部署.md
Normal file
182
.qoder/repowiki/zh/content/构建与部署.md
Normal file
@@ -0,0 +1,182 @@
|
||||
# 构建与部署
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document**
|
||||
- [vite.config.ts](file://vite.config.ts)
|
||||
- [uno.config.ts](file://uno.config.ts)
|
||||
- [package.json](file://package.json)
|
||||
- [README.md](file://README.md)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [构建流程概述](#构建流程概述)
|
||||
2. [开发构建与生产构建的区别](#开发构建与生产构建的区别)
|
||||
3. [Vite 配置解析](#vite-配置解析)
|
||||
4. [UnoCSS 自定义配置](#unocss-自定义配置)
|
||||
5. [构建脚本执行机制](#构建脚本执行机制)
|
||||
6. [静态资源输出结构](#静态资源输出结构)
|
||||
7. [部署最佳实践](#部署最佳实践)
|
||||
|
||||
## 构建流程概述
|
||||
|
||||
本项目基于 Vite 构建工具实现现代化前端工程化流程，结合 Vue 3 和 UnoCSS 原子化 CSS 框架。整体构建流程围绕 `vite` 命令展开，通过 `package.json` 中定义的脚本入口驱动不同环境下的构建行为。
|
||||
|
||||
构建系统支持开发模式热重载、类型检查、代码格式化及生产级优化打包。核心配置文件包括 `vite.config.ts`（构建主配置）、`uno.config.ts`（样式引擎配置）以及 `package.json`（脚本命令定义），三者协同完成从源码到可部署静态资源的转换过程。
|
||||
|
||||
**Section sources**
|
||||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||||
- [package.json](file://package.json#L1-L43)
|
||||
- [README.md](file://README.md#L1-L38)
|
||||
|
||||
## 开发构建与生产构建的区别
|
||||
|
||||
开发构建与生产构建在目标、性能优化和输出内容上存在显著差异：
|
||||
|
||||
| 特性 | 开发构建 | 生产构建 |
|
||||
|------|----------|----------|
|
||||
| **启动命令** | `pnpm dev` | `pnpm build` |
|
||||
| **主要目的** | 快速启动、热更新 | 生成优化后的静态资源 |
|
||||
| **代码压缩** | 否 | 是（Terser 或 SWC） |
|
||||
| **Source Map** | 完整映射 | 可选或隐藏 |
|
||||
| **环境变量** | `.env.development` | `.env.production` |
|
||||
| **依赖预构建** | 动态处理 | 静态分析并缓存 |
|
||||
| **HMR 支持** | 是 | 否 |
|
||||
|
||||
开发构建侧重于提升开发者体验，启用热模块替换（HMR）以实现实时反馈；而生产构建则专注于性能优化，对 JavaScript、CSS 进行压缩与 Tree Shaking，移除调试代码，并生成适合 CDN 分发的静态文件。
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L6-L14)
|
||||
- [README.md](file://README.md#L30-L37)
|
||||
|
||||
## Vite 配置解析
|
||||
|
||||
`vite.config.ts` 是项目的构建核心配置文件，定义了插件集成、路径别名、编译选项等关键设置。
|
||||
|
||||
### 插件集成
|
||||
配置中注册了多个 Vite 插件：
|
||||
- `@vitejs/plugin-vue`：支持 Vue 单文件组件解析，配置了自定义元素忽略规则（`isCustomElement: tag => tag.endsWith('-element')`），避免将特定标签误解析为 Vue 组件。
|
||||
- `@vitejs/plugin-vue-jsx`：启用 JSX/TSX 语法支持。
|
||||
- `vite-plugin-vue-devtools`：集成 Vue DevTools 调试工具。
|
||||
- `unocss/vite`：引入 UnoCSS 样式引擎，实现原子化 CSS 按需生成。
|
||||
|
||||
### 路径别名
|
||||
通过 `resolve.alias` 配置 `@` 指向 `src` 目录，简化模块导入路径，提升代码可读性与维护性。
|
||||
|
||||
### 环境变量处理
|
||||
Vite 原生支持 `.env` 文件加载，根据 `import.meta.env.MODE` 区分不同环境，并自动注入 `import.meta.env.VITE_*` 前缀的环境变量。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["启动 vite"] --> B{开发模式?}
|
||||
B --> |是| C["加载 vite.config.ts"]
|
||||
C --> D["应用插件: vue, vueJsx, devtools, unocss"]
|
||||
D --> E["设置路径别名 @ → src/"]
|
||||
E --> F["启动开发服务器 + HMR"]
|
||||
B --> |否| G["执行 vite build"]
|
||||
G --> H["编译 TS + 处理 SFC"]
|
||||
H --> I["应用 UnoCSS 转换"]
|
||||
I --> J["压缩 JS/CSS"]
|
||||
J --> K["输出 dist/ 目录"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||||
|
||||
**Section sources**
|
||||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||||
|
||||
## UnoCSS 自定义配置
|
||||
|
||||
`uno.config.ts` 文件用于定制 UnoCSS 的行为，当前配置启用了两个重要转换器：
|
||||
|
||||
- `transformerVariantGroup()`：允许使用括号语法进行变体分组，例如 `hover:(bg-red-500 text-white)`，提升类名书写效率。
|
||||
- `transformerDirectives()`：支持在 CSS 中使用 `@apply` 指令复用原子类，以及 `@screen` 响应式控制。
|
||||
|
||||
该配置确保了在模板中可以灵活使用组合式类名，同时保持样式的可维护性和简洁性。
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class UnoCSSConfig {
|
||||
+transformers : Transformer[]
|
||||
}
|
||||
class TransformerVariantGroup {
|
||||
+name : "variant-group"
|
||||
+transform()
|
||||
}
|
||||
class TransformerDirectives {
|
||||
+name : "directives"
|
||||
+transform()
|
||||
}
|
||||
UnoCSSConfig --> TransformerVariantGroup : "包含"
|
||||
UnoCSSConfig --> TransformerDirectives : "包含"
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [uno.config.ts](file://uno.config.ts#L1-L10)
|
||||
|
||||
**Section sources**
|
||||
- [uno.config.ts](file://uno.config.ts#L1-L10)
|
||||
|
||||
## 构建脚本执行机制
|
||||
|
||||
`package.json` 中的 `scripts` 字段定义了标准化的构建命令：
|
||||
|
||||
- `dev`：直接运行 `vite`，启动开发服务器。
|
||||
- `build`：并行执行类型检查与构建任务，使用 `run-p` 实现并发控制。
|
||||
- `build-only`：仅执行 `vite build`，生成生产资源。
|
||||
- `type-check`：调用 `vue-tsc --build` 进行完整的 TypeScript 类型校验。
|
||||
- `preview`：启动本地预览服务器，模拟生产环境。
|
||||
|
||||
这种设计实现了构建流程的解耦与并行化，提升了 CI/CD 流水线效率。
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L6-L14)
|
||||
|
||||
## 静态资源输出结构
|
||||
|
||||
生产构建完成后，Vite 将输出默认的 `dist/` 目录，其典型结构如下：
|
||||
|
||||
```
|
||||
dist/
|
||||
├── assets/ # 打包后的 JS、CSS 资源
|
||||
│ ├── index.[hash].js
|
||||
│ └── style.[hash].css
|
||||
├── index.html # 入口 HTML 文件
|
||||
└── favicon.ico # 可选图标
|
||||
```
|
||||
|
||||
所有资源均经过哈希命名以支持长期缓存，HTML 文件自动注入正确的资源引用路径。
|
||||
|
||||
**Section sources**
|
||||
- [vite.config.ts](file://vite.config.ts#L1-L30)
|
||||
|
||||
## 部署最佳实践
|
||||
|
||||
### 静态服务器部署
|
||||
将 `dist/` 目录内容部署至 Nginx、Apache 或 Caddy 等静态服务器时，需确保：
|
||||
- 正确设置 MIME 类型。
|
||||
- 启用 Gzip/Brotli 压缩。
|
||||
- 配置 SPA 路由回退（将所有非资源请求重定向至 `index.html`）。
|
||||
|
||||
示例 Nginx 配置片段：
|
||||
```nginx
|
||||
location / {
|
||||
try_files $uri $uri/ /index.html;
|
||||
}
|
||||
```
|
||||
|
||||
### CDN 部署建议
|
||||
- 利用 CDN 的边缘缓存能力，设置合理的缓存策略（如 `max-age=31536000` 对带哈希的静态资源）。
|
||||
- 启用 HTTPS 和 HTTP/2。
|
||||
- 使用版本化目录（如 `/v1.0.0/`）便于灰度发布与回滚。
|
||||
|
||||
### 自动化部署
|
||||
推荐结合 GitHub Actions、GitLab CI 或 Jenkins 实现自动化构建与部署流水线，包含以下阶段：
|
||||
1. 依赖安装
|
||||
2. 类型检查
|
||||
3. 生产构建
|
||||
4. 构建产物验证
|
||||
5. 自动上传至对象存储或 CDN
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L30-L37)
|
||||
209
.qoder/repowiki/zh/content/状态管理.md
Normal file
209
.qoder/repowiki/zh/content/状态管理.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# 状态管理
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [counter.ts](file://src/stores/counter.ts)
|
||||
- [main.ts](file://src/main.ts)
|
||||
- [App.vue](file://src/ui/App.vue)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构分析](#项目结构分析)
|
||||
3. [Pinia状态管理模式应用](#pinia状态管理模式应用)
|
||||
4. [Counter Store详解](#counter-store详解)
|
||||
5. [组件中使用Store](#组件中使用store)
|
||||
6. [全局状态同步与扩展用途](#全局状态同步与扩展用途)
|
||||
7. [状态持久化策略](#状态持久化策略)
|
||||
8. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
本项目采用Pinia作为Vue 3的官方推荐状态管理库，实现跨组件的状态共享和管理。文档将详细说明基于Pinia的状态管理模式在桌面系统中的应用，以counter store为例展示store的定义、state暴露和actions使用方法，并探讨其在整个系统中的潜在扩展用途及状态持久化策略。
|
||||
|
||||
## 项目结构分析
|
||||
|
||||
项目遵循典型的Vue + TypeScript架构，状态管理相关代码集中存放在`src/stores`目录下。核心入口文件为`src/main.ts`，负责初始化Pinia实例并将其挂载到Vue应用上。UI组件分布在`src/ui`目录中，通过模块化方式组织桌面容器和应用图标等界面元素。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "核心模块"
|
||||
Stores["src/stores"]
|
||||
UI["src/ui"]
|
||||
Main["src/main.ts"]
|
||||
end
|
||||
Main --> Stores : "导入并使用"
|
||||
Main --> UI : "作为根组件"
|
||||
UI --> Stores : "调用store"
|
||||
Stores --> counter["counter.ts"]
|
||||
UI --> DesktopContainer["DesktopContainer.vue"]
|
||||
DesktopContainer --> AppIcon["AppIcon.vue"]
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [main.ts](file://src/main.ts#L1-L16)
|
||||
- [stores/counter.ts](file://src/stores/counter.ts#L1-L13)
|
||||
- [ui/App.vue](file://src/ui/App.vue#L1-L53)
|
||||
|
||||
## Pinia状态管理模式应用
|
||||
|
||||
Pinia在本项目中被用作全局状态管理中心，通过`createPinia()`创建实例并在主应用中注册，使得所有组件都能访问统一的状态树。这种模式解决了传统Vue应用中深层嵌套组件间通信困难的问题，实现了状态的集中管理和响应式更新。
|
||||
|
||||
### 初始化过程
|
||||
|
||||
Pinia实例在`main.ts`中完成初始化和注册：
|
||||
|
||||
```typescript
|
||||
import { createApp } from 'vue'
|
||||
import { createPinia } from 'pinia'
|
||||
|
||||
const app = createApp(App)
|
||||
app.use(createPinia())
|
||||
app.mount('#app')
|
||||
```
|
||||
|
||||
此配置确保了Pinia插件在整个应用生命周期内可用，为后续的store创建和使用奠定了基础。
|
||||
|
||||
**Section sources**
|
||||
- [main.ts](file://src/main.ts#L1-L16)
|
||||
|
||||
## Counter Store详解
|
||||
|
||||
`counter.ts`文件定义了一个典型的Pinia store示例——useCounterStore，展示了组合式API风格的store定义方式。
|
||||
|
||||
### Store定义
|
||||
|
||||
`useCounterStore`通过`defineStore`函数创建，采用箭头函数语法封装内部逻辑。该store包含以下核心要素：
|
||||
- **State**: 使用`ref`定义的响应式数据`count`
|
||||
- **Getters**: 通过`computed`创建的派生属性`doubleCount`
|
||||
- **Actions**: 可修改state的方法`increment`
|
||||
|
||||
```typescript
|
||||
export const useCounterStore = defineStore('counter', () => {
|
||||
const count = ref(0)
|
||||
const doubleCount = computed(() => count.value * 2)
|
||||
function increment() {
|
||||
count.value++
|
||||
}
|
||||
return { count, doubleCount, increment }
|
||||
})
|
||||
```
|
||||
|
||||
这种定义方式充分利用了Vue 3的Composition API特性，使代码更加直观和易于理解。
|
||||
|
||||
**Section sources**
|
||||
- [counter.ts](file://src/stores/counter.ts#L3-L11)
|
||||
|
||||
### State暴露机制
|
||||
|
||||
Store通过返回对象的方式暴露其内部状态和方法。这种方式实现了良好的封装性，同时保持了使用的便捷性。外部组件可以通过调用`useCounterStore()`获取store实例，进而访问`count`、`doubleCount`和`increment`等属性和方法。
|
||||
|
||||
## 组件中使用Store
|
||||
|
||||
虽然当前代码库中未直接展示counter store在组件中的使用，但可以推断出标准的使用模式。
|
||||
|
||||
### 引入与使用
|
||||
|
||||
在任何Vue组件中，可通过导入`useCounterStore`并在`setup`函数中调用它来使用store：
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { useCounterStore } from '@/stores/counter'
|
||||
|
||||
const counter = useCounterStore()
|
||||
// 使用 counter.count, counter.doubleCount, counter.increment()
|
||||
</script>
|
||||
```
|
||||
|
||||
### 潜在应用场景
|
||||
|
||||
尽管counter store目前仅作为示例存在，但它可被扩展用于多种场景：
|
||||
- 桌面图标的数量统计
|
||||
- 应用启动次数追踪
|
||||
- 用户交互行为计数
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Component as "Vue组件"
|
||||
participant Store as "Pinia Store"
|
||||
participant State as "响应式状态"
|
||||
Component->>Store : 调用useCounterStore()
|
||||
Store-->>Component : 返回store实例
|
||||
Component->>Store : 访问count值
|
||||
Store-->>Component : 提供响应式count
|
||||
Component->>Store : 调用increment()
|
||||
Store->>State : 修改count.value
|
||||
State-->>Store : 触发更新
|
||||
Store-->>Component : 自动更新视图
|
||||
```
|
||||
|
||||
**Diagram sources**
|
||||
- [counter.ts](file://src/stores/counter.ts#L3-L11)
|
||||
- [App.vue](file://src/ui/App.vue#L1-L53)
|
||||
|
||||
## 全局状态同步与扩展用途
|
||||
|
||||
Pinia提供的全局状态管理能力在桌面系统中有广泛的扩展潜力。
|
||||
|
||||
### 多组件状态共享
|
||||
|
||||
设想多个桌面组件需要共享某些状态（如主题设置、布局参数、用户偏好等），可通过创建相应的store实现：
|
||||
|
||||
```typescript
|
||||
// 示例：theme.store.ts
|
||||
export const useThemeStore = defineStore('theme', () => {
|
||||
const darkMode = ref(false)
|
||||
const fontSize = ref(14)
|
||||
|
||||
function toggleDarkMode() {
|
||||
darkMode.value = !darkMode.value
|
||||
}
|
||||
|
||||
return { darkMode, fontSize, toggleDarkMode }
|
||||
})
|
||||
```
|
||||
|
||||
此类store可被任务栏、桌面容器、应用窗口等多个组件同时引用，确保状态的一致性。
|
||||
|
||||
### 系统级状态管理
|
||||
|
||||
更复杂的系统状态（如窗口管理、应用状态、事件总线）也可通过Pinia进行统一管理，形成清晰的状态流架构。
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L24)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L53)
|
||||
|
||||
## 状态持久化策略
|
||||
|
||||
当前项目尚未实现状态持久化功能，但从技术角度看有多种可行方案。
|
||||
|
||||
### 可行的持久化方案
|
||||
|
||||
1. **浏览器存储**: 利用localStorage或sessionStorage保存关键状态
|
||||
2. **IndexedDB**: 对于复杂数据结构，可使用IndexedDB进行持久化
|
||||
3. **第三方插件**: 使用`pinia-plugin-persistedstate`等成熟解决方案
|
||||
|
||||
### 实现建议
|
||||
|
||||
若需实现counter store的持久化，可在定义store时添加持久化配置：
|
||||
|
||||
```typescript
|
||||
// 配置示例（当前未实现）
|
||||
export const useCounterStore = defineStore('counter', () => {
|
||||
// ...原有逻辑
|
||||
}, {
|
||||
persist: true // 启用持久化
|
||||
})
|
||||
```
|
||||
|
||||
值得注意的是，项目中存在`useObservableVue.ts`这一自定义Hook，表明团队可能倾向于使用自定义的状态管理方案配合Pinia使用，这为未来实现更复杂的状态持久化和同步机制提供了灵活性。
|
||||
|
||||
**Section sources**
|
||||
- [useObservableVue.ts](file://src/common/hooks/useObservableVue.ts#L1-L43)
|
||||
- [counter.ts](file://src/stores/counter.ts#L1-L13)
|
||||
|
||||
## 结论
|
||||
|
||||
本项目通过Pinia实现了现代化的Vue状态管理，`counter.ts`中的useCounterStore展示了清晰的组合式API用法。虽然当前store的应用较为基础，但其架构设计为未来的功能扩展留下了充足空间。通过合理利用Pinia的模块化特性，可逐步构建完整的全局状态管理体系，支撑起复杂桌面应用的需求。同时，结合浏览器原生存储机制或专用插件，可进一步完善状态持久化能力，提升用户体验。
|
||||
275
.qoder/repowiki/zh/content/项目概述.md
Normal file
275
.qoder/repowiki/zh/content/项目概述.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 项目概述
|
||||
|
||||
<cite>
|
||||
**Referenced Files in This Document **
|
||||
- [README.md](file://README.md)
|
||||
- [package.json](file://package.json)
|
||||
- [main.ts](file://src/main.ts)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts)
|
||||
- [counter.ts](file://src/stores/counter.ts)
|
||||
- [EventManager.ts](file://src/events/EventManager.ts)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖分析](#依赖分析)
|
||||
7. [性能考量](#性能考量)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
`vue-desktop` 是一个基于 Vue 3 的桌面风格 Web 应用，旨在模拟操作系统桌面环境的用户体验。该项目通过现代化的前端技术栈实现了可拖拽的应用图标、响应式网格布局和高效的状态管理等关键特性。其设计目标是为用户提供直观、交互性强的Web界面，同时为开发者提供清晰的代码结构和可扩展的架构。
|
||||
|
||||
本项目采用 MVVM（Model-View-ViewModel）模式结合 Vue 3 的 Composition API，实现了逻辑与视图的分离，提升了代码的可维护性和复用性。对于初学者而言，该项目提供了理解现代Vue应用开发的良好范例；对于高级开发者，则展示了复杂状态管理和事件系统的设计思路。
|
||||
|
||||
**Section sources**
|
||||
- [README.md](file://README.md#L1-L37)
|
||||
- [package.json](file://package.json#L1-L42)
|
||||
|
||||
## 项目结构
|
||||
`vue-desktop` 项目的目录结构体现了功能模块化的设计理念，各目录职责分明：
|
||||
|
||||
- `src/common`: 存放通用工具函数、自定义Hook和类型定义
|
||||
- `src/css`: 全局样式文件
|
||||
- `src/events`: 事件管理系统，实现组件间解耦通信
|
||||
- `src/stores`: 状态管理模块，使用 Pinia 进行全局状态管理
|
||||
- `src/ui`: 用户界面组件，包含桌面容器、应用图标等核心UI元素
|
||||
- `src/main.ts`: 应用入口文件，负责初始化Vue实例和插件
|
||||
|
||||
这种分层结构使得项目易于理解和维护，新开发者可以快速定位到特定功能的实现位置。
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "源码目录"
|
||||
Common[src/common<br/>通用工具与类型]
|
||||
CSS[src/css<br/>全局样式]
|
||||
Events[src/events<br/>事件系统]
|
||||
Stores[src/stores<br/>状态管理]
|
||||
UI[src/ui<br/>用户界面]
|
||||
Main[src/main.ts<br/>应用入口]
|
||||
end
|
||||
Main --> UI
|
||||
Main --> Stores
|
||||
Main --> Events
|
||||
Main --> CSS
|
||||
Main --> Common
|
||||
UI --> Events
|
||||
UI --> Stores
|
||||
UI --> Common
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [main.ts](file://src/main.ts#L1-L15)
|
||||
- [project_structure](file://#L1-L20)
|
||||
|
||||
**Section sources**
|
||||
- [project_structure](file://#L1-L20)
|
||||
|
||||
## 核心组件
|
||||
项目的核心功能由几个关键组件协同实现：`DesktopContainer` 作为桌面主容器管理整体布局，`AppIcon` 组件代表可交互的应用图标，`useDesktopContainerInit` Hook 负责初始化桌面参数和响应式逻辑，而 `counter` Store 则演示了基础的状态管理机制。
|
||||
|
||||
这些组件共同构成了桌面环境的基础，其中 `DesktopContainer` 和 `AppIcon` 通过 Composition API 实现了高度的灵活性和可复用性。
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
- [counter.ts](file://src/stores/counter.ts#L3-L11)
|
||||
|
||||
## 架构概览
|
||||
`vue-desktop` 采用了典型的现代前端架构模式，以 Vue 3 的 Composition API 为核心，结合 Pinia 进行状态管理，并通过自定义事件系统实现组件间的松耦合通信。
|
||||
|
||||
整个应用从 `main.ts` 启动，创建 Vue 实例并注册 Pinia 和 Naive UI 等插件。UI 层主要由 `DesktopContainer` 和 `AppIcon` 组成，前者使用 `useDesktopContainerInit` Hook 初始化响应式数据，后者则实现了图标的拖拽功能。状态管理通过 Pinia Store 实现，事件通信则依赖于自定义的事件总线机制。
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[main.ts] --> B[Vue App]
|
||||
B --> C[Pinia Store]
|
||||
B --> D[Naive UI]
|
||||
B --> E[DesktopContainer]
|
||||
E --> F[AppIcon]
|
||||
E --> G[useDesktopContainerInit]
|
||||
C --> H[counter]
|
||||
E --> I[EventManager]
|
||||
G --> J[ResizeObserver]
|
||||
F --> K[Drag Events]
|
||||
style A fill:#f9f,stroke:#333
|
||||
style B fill:#bbf,stroke:#333
|
||||
style C fill:#f96,stroke:#333
|
||||
style E fill:#6f9,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [main.ts](file://src/main.ts#L1-L15)
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 桌面容器分析
|
||||
`DesktopContainer` 组件是整个应用的核心容器，负责管理桌面的网格布局和应用图标的渲染。它通过 Composition API 的 `setup` 语法引入 `useDesktopContainerInit` Hook 来获取响应式数据，并使用 Vue 的 `v-for` 指令遍历渲染 `AppIcon` 组件。
|
||||
|
||||
该组件的关键特性包括：
|
||||
- 响应式网格布局，能根据容器大小自动调整行列数
|
||||
- 双击事件处理，用于启动应用程序
|
||||
- 与子组件的 props 通信机制
|
||||
|
||||
#### 组件关系图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class DesktopContainer {
|
||||
+appIconsRef : Ref~Array~
|
||||
+gridStyle : ComputedRef
|
||||
+gridTemplate : Reactive
|
||||
+runApp(appIcon) : void
|
||||
}
|
||||
class AppIcon {
|
||||
+iconInfo : Prop
|
||||
+gridTemplate : Prop
|
||||
+onDragStart(e) : void
|
||||
+onDragEnd(e) : void
|
||||
}
|
||||
class useDesktopContainerInit {
|
||||
+useDesktopContainerInit(containerStr) : Object
|
||||
+rearrangeIcons() : Object
|
||||
}
|
||||
DesktopContainer --> AppIcon : "v-for 渲染"
|
||||
DesktopContainer --> useDesktopContainerInit : "组合式API调用"
|
||||
useDesktopContainerInit ..> IGridTemplateParams : "实现"
|
||||
useDesktopContainerInit ..> IDesktopAppIcon : "使用"
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
- [IGridTemplateParams.ts](file://src/ui/types/IGridTemplateParams.ts#L1-L20)
|
||||
- [IDesktopAppIcon.ts](file://src/ui/types/IDesktopAppIcon.ts#L3-L14)
|
||||
|
||||
**Section sources**
|
||||
- [DesktopContainer.vue](file://src/ui/desktop-container/DesktopContainer.vue#L1-L23)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
### 应用图标分析
|
||||
`AppIcon` 组件实现了桌面图标的可视化和交互功能，支持拖拽操作来重新排列图标位置。当用户拖拽图标并释放时，组件会计算鼠标位置对应的网格坐标，并更新图标的 `x` 和 `y` 属性。
|
||||
|
||||
该组件利用 HTML5 的 Drag and Drop API 实现拖拽功能，并通过 `document.elementFromPoint` 方法检测鼠标释放时的位置元素，确保图标只能放置在有效的桌面区域内。
|
||||
|
||||
#### 拖拽流程图
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Start([开始拖拽]) --> DragStart["onDragStart事件触发"]
|
||||
DragStart --> Wait["等待拖拽结束"]
|
||||
Wait --> DragEnd["onDragEnd事件触发"]
|
||||
DragEnd --> CheckTarget["检查鼠标下方元素"]
|
||||
CheckTarget --> Valid{"是否为有效区域?"}
|
||||
Valid --> |否| End([放弃移动])
|
||||
Valid --> |是| Calculate["计算网格坐标"]
|
||||
Calculate --> Update["更新图标位置(x,y)"]
|
||||
Update --> Persist["持久化到localStorage"]
|
||||
Persist --> End
|
||||
style Start fill:#f9f,stroke:#333
|
||||
style End fill:#f9f,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
|
||||
### 状态与事件系统分析
|
||||
项目中的状态管理采用 Pinia 实现，`counter.ts` 文件展示了最基本的 Store 定义方式，包含响应式状态、计算属性和修改方法。事件系统则通过 `EventManager` 和 `EventBuilderImpl` 类构建了一个类型安全的事件总线，支持添加、移除和触发事件。
|
||||
|
||||
这种设计模式实现了组件间的解耦，使得不同部分的代码可以通过事件进行通信，而不需要直接引用彼此。
|
||||
|
||||
#### 事件系统类图
|
||||
```mermaid
|
||||
classDiagram
|
||||
class EventManager {
|
||||
+eventManager : EventBuilderImpl
|
||||
}
|
||||
class EventBuilderImpl {
|
||||
-_eventHandlers : Map
|
||||
+addEventListener()
|
||||
+removeEventListener()
|
||||
+notifyEvent()
|
||||
+destroy()
|
||||
}
|
||||
class IEventBuilder {
|
||||
<<interface>>
|
||||
+addEventListener()
|
||||
+removeEventListener()
|
||||
+notifyEvent()
|
||||
}
|
||||
EventManager --> EventBuilderImpl : "实例化"
|
||||
EventBuilderImpl ..|> IEventBuilder : "实现"
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [EventManager.ts](file://src/events/EventManager.ts#L4-L4)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L1-L96)
|
||||
|
||||
**Section sources**
|
||||
- [EventManager.ts](file://src/events/EventManager.ts#L4-L4)
|
||||
- [EventBuilderImpl.ts](file://src/events/impl/EventBuilderImpl.ts#L1-L96)
|
||||
|
||||
## 依赖分析
|
||||
`vue-desktop` 项目的依赖体系清晰地分为生产依赖和开发依赖两大类。生产依赖主要包括 Vue 3 核心库、Pinia 状态管理、Lodash 工具函数和 UUID 生成器等。开发依赖则包含了 Vite 构建工具、TypeScript 支持、Prettier 代码格式化等开发辅助工具。
|
||||
|
||||
值得注意的是，项目使用了 UnoCSS 进行原子化CSS管理，以及 Naive UI 作为UI组件库，这些选择体现了对性能和开发效率的重视。
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Vue 3] --> B[vue-desktop]
|
||||
C[Pinia] --> B
|
||||
D[Lodash] --> B
|
||||
E[UUID] --> B
|
||||
F[Naive UI] --> B
|
||||
G[Vite] --> B
|
||||
H[TypeScript] --> B
|
||||
I[UnoCSS] --> B
|
||||
style B fill:#6f9,stroke:#333
|
||||
```
|
||||
|
||||
**Diagram sources **
|
||||
- [package.json](file://package.json#L1-L42)
|
||||
|
||||
**Section sources**
|
||||
- [package.json](file://package.json#L1-L42)
|
||||
|
||||
## 性能考量
|
||||
`vue-desktop` 在性能方面采取了多项优化措施：
|
||||
|
||||
1. **响应式布局优化**：通过 `ResizeObserver` 监听容器尺寸变化，避免了频繁的重排重绘。
|
||||
2. **内存管理**：在组件卸载时正确清理事件监听器和观察者，防止内存泄漏。
|
||||
3. **本地存储**：使用 `localStorage` 持久化图标位置信息，减少重复计算。
|
||||
4. **计算属性缓存**：利用 Vue 的 `computed` 特性缓存网格样式计算结果。
|
||||
|
||||
这些优化确保了即使在大量图标的情况下，应用仍能保持流畅的用户体验。
|
||||
|
||||
## 故障排除指南
|
||||
当遇到常见问题时，可以参考以下解决方案：
|
||||
|
||||
- **图标无法拖拽**：检查浏览器是否支持 HTML5 Drag and Drop API，确认元素的 `draggable` 属性已正确设置。
|
||||
- **布局错乱**：验证容器宽度是否被正确设置，检查 CSS 样式是否有冲突。
|
||||
- **状态不更新**：确保使用了正确的响应式API（ref/reactive），检查 Pinia Store 的使用方式。
|
||||
- **事件未触发**：确认事件监听器已正确注册，检查事件名称拼写是否一致。
|
||||
|
||||
**Section sources**
|
||||
- [AppIcon.vue](file://src/ui/desktop-container/AppIcon.vue#L1-L52)
|
||||
- [useDesktopContainerInit.ts](file://src/ui/desktop-container/useDesktopContainerInit.ts#L14-L94)
|
||||
|
||||
## 结论
|
||||
`vue-desktop` 项目成功实现了一个功能完整的桌面风格Web应用，展示了 Vue 3 生态系统的强大能力。通过 MVVM 架构和 Composition API 的结合，项目实现了良好的代码组织和可维护性。响应式网格布局和拖拽功能为用户提供了直观的交互体验，而 Pinia 和自定义事件系统则确保了复杂状态的有效管理。
|
||||
|
||||
该项目不仅适合作为学习现代前端开发的范例，也为构建类似的操作系统模拟器或仪表盘应用提供了有价值的参考。随着需求的发展，可以在此基础上扩展更多功能，如窗口管理、任务栏、系统托盘等，进一步完善桌面环境的模拟。
|
||||
Reference in New Issue
Block a user