254 lines
8.8 KiB
Markdown
254 lines
8.8 KiB
Markdown
# 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;
|
||
}
|
||
```
|
||
|
||
以上扩展应在保持原有接口兼容性的前提下进行，确保不影响现有功能。 |