193 lines
9.5 KiB
Markdown
193 lines
9.5 KiB
Markdown
<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) |