280 lines
8.8 KiB
Markdown
280 lines
8.8 KiB
Markdown
# Vue页面可视化设计器项目文档
|
||
|
||
## 项目概述
|
||
|
||
本项目是一个基于 Vite + Vue3 + TypeScript 的**可视化页面设计器**，通过拖拽操作直接编辑真实的Vue页面文件，实现低代码页面快速构建。
|
||
|
||
## 核心特性
|
||
|
||
1. **直接解析Vue文件** - 动态渲染真实的.vue页面
|
||
2. **拖拽式设计** - 将设计组件拖拽到页面的el-row/el-col上
|
||
3. **层级选择** - 通过键盘方向键切换嵌套元素的选中层级
|
||
4. **实时预览** - 拖拽时显示放置方向（上/下/左/右）
|
||
5. **结构化ID** - 自动生成路径ID（如r1c2r1c1）
|
||
|
||
## 技术架构
|
||
|
||
### 核心技术栈
|
||
- **构建工具**: Vite 7.3.0
|
||
- **前端框架**: Vue 3.5.24 (Composition API)
|
||
- **状态管理**: Pinia 3.0.4
|
||
- **类型系统**: TypeScript
|
||
- **拖拽库**: vuedraggable 4.1.0
|
||
- **样式**: CSS Modules + Scoped Styles
|
||
|
||
### 项目结构
|
||
```
|
||
src/
|
||
├── fauto/ # 核心功能模块
|
||
│ ├── components/ # UI组件
|
||
│ │ ├── Header.vue # 顶部菜单栏
|
||
│ │ ├── Footer.vue # 底部状态栏（显示拖拽状态）
|
||
│ │ ├── MainLayout.vue # 主布局容器
|
||
│ │ ├── Panel.vue # 面板容器
|
||
│ │ └── Resizer.vue # 面板分隔器
|
||
│ ├── materials/ # 物料组件系统
|
||
│ │ ├── PageManagement/ # 页面管理（树形选择Vue文件）
|
||
│ │ ├── DesignComponentList/ # 设计组件列表
|
||
│ │ └── DesignCenter/ # 设计中心（动态渲染页面）
|
||
│ ├── designComponents/ # 设计组件库
|
||
│ │ ├── TextInput/ # 文本输入框
|
||
│ │ ├── RadioSelect/ # 单选器
|
||
│ │ └── GridTable/ # 表格组件
|
||
│ ├── plugins/ # 插件系统（交互事件、拖拽管理）
|
||
│ │ ├── interactionStore.ts # 全局交互钩子
|
||
│ │ ├── dragStore.ts # 拖拽状态管理
|
||
│ │ └── pathUtils.ts # 结构化路径工具
|
||
│ ├── stores/ # 状态管理
|
||
│ │ ├── panelStore.ts # 面板布局状态
|
||
│ │ ├── designStore.ts # 设计组件元数据
|
||
│ │ └── vueFileStore.ts # Vue文件选择状态
|
||
│ └── Designer.vue # 设计器主入口
|
||
├── views/ # 示例页面（测试用）
|
||
└── App.vue # 应用入口
|
||
```
|
||
|
||
## 核心功能模块
|
||
|
||
### 1. 页面管理系统
|
||
|
||
#### 功能说明
|
||
- 动态扫描`src/views`目录下的所有Vue文件
|
||
- 以树形结构展示文件夹和页面
|
||
- 点击选中后在设计中心动态渲染
|
||
|
||
#### 技术实现
|
||
```typescript
|
||
// 使用import.meta.glob动态扫描
|
||
const viewModules = import.meta.glob('../../../views/**/*.vue')
|
||
|
||
// 异步加载选中的组件
|
||
const loader = viewModules[selectedFilePath]
|
||
const component = defineAsyncComponent(loader)
|
||
```
|
||
|
||
### 2. 设计中心系统
|
||
|
||
#### InteractiveWrapper（交互包装器）
|
||
**作用**：为动态渲染的Vue页面注入交互事件
|
||
|
||
**核心功能**：
|
||
1. 自动扫描页面中的el-row和el-col
|
||
2. 为每个元素注入结构化路径ID（如`r1c2`）
|
||
3. 绑定交互事件（悬停、点击、拖拽）
|
||
4. 使用MutationObserver监听DOM变化
|
||
|
||
#### DropZone（拖放区域指示器）
|
||
**作用**：拖拽时显示可放置区域
|
||
|
||
**显示规则**：
|
||
- el-row：显示 **上方** 和 **下方** 两个区域
|
||
- el-col：显示 **左侧** 和 **右侧** 两个区域
|
||
|
||
#### DragPreview（拖拽预览）
|
||
跟随鼠标显示正在拖拽的内容，提供视觉反馈。
|
||
|
||
### 3. 插件系统 (fauto/plugins)
|
||
|
||
#### interactionStore（交互状态管理）
|
||
管理所有交互事件的全局状态：
|
||
- `hoverTarget`: 当前悬停的元素
|
||
- `selectedTarget`: 当前选中的元素
|
||
- 提供全局事件钩子（hover, click, longpress, drag, release）
|
||
|
||
#### dragStore（拖拽状态管理）
|
||
管理拖拽操作的复杂状态：
|
||
|
||
**核心状态**：
|
||
- `dragSource`: 拖拽源（设计组件/画布元素）
|
||
- `hierarchyNodes`: 当前悬停位置的所有层级节点
|
||
- `selectedHierarchyIndex`: 当前选中的层级索引
|
||
- `hoverDirection`: 当前悬停的拖放方向
|
||
- `lastDropRecord`: 最后一次拖放记录
|
||
|
||
**层级选择机制**：
|
||
- 鼠标悬停在嵌套元素上时，自动识别所有父级节点
|
||
- 默认选中最深层级
|
||
- **↑键**：切换到父级
|
||
- **↓键**：切换到子级
|
||
- **Esc键**：取消拖拽
|
||
|
||
#### pathUtils（路径工具）
|
||
生成和解析结构化路径ID：
|
||
|
||
**路径格式**：`r{n}c{m}r{x}c{y}...`
|
||
- `r`: el-row
|
||
- `c`: el-col
|
||
- 数字：在同级元素中的索引（从1开始）
|
||
|
||
**示例**：`r1c2r1c3` 表示：
|
||
- 第1个el-row
|
||
- 的第2个el-col
|
||
- 内的第1个el-row
|
||
- 内的第3个el-col
|
||
|
||
## 状态管理设计
|
||
|
||
### PanelStore（面板状态）
|
||
管理整个应用的布局和物料组件状态：
|
||
- `layout`: 三区域面板配置
|
||
- `materialStates`: 物料组件状态独立存储
|
||
- 提供 Tab 操作 API（添加、关闭、移动、激活）
|
||
|
||
### DesignStore（设计组件元数据）
|
||
管理设计组件的元数据：
|
||
- `componentMetas`: 设计组件元数据列表
|
||
- `loadComponentMetas()`: 动态扫描设计组件目录
|
||
- `getComponentMeta()`: 获取指定组件的元数据
|
||
|
||
### VueFileStore（Vue文件状态）
|
||
管理页面管理的选中状态：
|
||
- `selectedFilePath`: 当前选中的文件路径
|
||
- `selectedFileName`: 当前选中的文件名
|
||
- `selectFile()`: 选中指定文件
|
||
|
||
### InteractionStore / DragStore
|
||
见**插件系统**部分
|
||
|
||
## 实现细节
|
||
|
||
### 1. Vue页面规范
|
||
**强制规则**：template的第一层级**有且仅有一个el-row**
|
||
|
||
**目的**：保证布局可解析性，方便自动生成结构化路径
|
||
|
||
示例：
|
||
```vue
|
||
<template>
|
||
<el-row :gutter="20">
|
||
<el-col :span="12">
|
||
<div class="design-component">左侧内容</div>
|
||
</el-col>
|
||
<el-col :span="12">
|
||
<el-row :gutter="10">
|
||
<el-col :span="24">
|
||
<div class="design-component">标题</div>
|
||
</el-col>
|
||
</el-row>
|
||
</el-col>
|
||
</el-row>
|
||
</template>
|
||
```
|
||
|
||
### 2. 拖拽交互优化
|
||
|
||
#### 禁用文本选择
|
||
拖拽时给body添加`is-dragging`类，设置`user-select: none`
|
||
|
||
#### 拖拽预览效果
|
||
DragPreview组件跟随鼠标显示：
|
||
- 组件图标 + 名称
|
||
- 动画效果（缩放 + 淡入）
|
||
- Teleport到body，避免z-index问题
|
||
|
||
### 3. 层级选择实现
|
||
```typescript
|
||
// 递归遍历DOM生成层级节点
|
||
const updateHierarchy = (element: HTMLElement) => {
|
||
const nodes: HierarchyNode[] = []
|
||
let current: HTMLElement | null = element
|
||
|
||
while (current) {
|
||
if (current.classList.contains('el-row') ||
|
||
current.classList.contains('el-col')) {
|
||
nodes.push({ path, type, element, depth })
|
||
}
|
||
current = current.parentElement
|
||
}
|
||
|
||
// 按深度排序，最深的在前
|
||
nodes.sort((a, b) => b.depth - a.depth)
|
||
}
|
||
```
|
||
|
||
### 4. 性能优化
|
||
- 使用 `defineAsyncComponent` 异步加载页面
|
||
- 使用 `MutationObserver` 监听DOM变化
|
||
- 防止重复绑定（`data-fauto-bindend`属性）
|
||
- 使用 `computed` 缓存派生数据
|
||
|
||
## API 设计
|
||
|
||
### 配置管理 API
|
||
```
|
||
GET /api/config # 获取布局配置
|
||
POST /api/config # 保存布局配置
|
||
GET /api/material-states # 获取物料组件状态
|
||
POST /api/material-states # 保存物料组件状态
|
||
```
|
||
|
||
### 设计系统 API
|
||
```
|
||
GET /api/design-components # 获取设计组件元数据
|
||
GET /api/design-state # 获取设计中心状态
|
||
POST /api/design-state # 保存设计中心状态
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
### Vue页面结构规范
|
||
1. template第一层级有且仅有一个el-row
|
||
2. el-row内只能包含el-col或div（设计组件）
|
||
3. div使用class="design-component"标识
|
||
|
||
### 代码规范
|
||
1. 使用 TypeScript 严格模式
|
||
2. 组件 Props 必须明确定义类型
|
||
3. 使用 Composition API 组织代码逻辑
|
||
4. 样式使用 scoped 避免全局污染
|
||
|
||
### 组件开发规范
|
||
1. 遵循物料组件标准化规范
|
||
2. 每个组件包含`index.vue`和`index.json`
|
||
3. 插件相关代码放在`fauto/plugins`目录
|
||
|
||
### 状态管理规范
|
||
1. 使用 Pinia 进行全局状态管理
|
||
2. 状态变更必须通过 Store 的方法
|
||
3. 复杂状态逻辑封装在 Store 内部
|
||
|
||
## 扩展性设计
|
||
|
||
### 新增设计组件
|
||
1. 在 `designComponents/` 目录下创建组件文件夹
|
||
2. 实现 `index.vue` 和 `index.json`
|
||
3. 自动在 DesignComponentList 中显示
|
||
|
||
### 功能扩展
|
||
1. **拖放后修改源文件** - 通过API将拖放操作写入.vue文件
|
||
2. **属性编辑器** - 展示和编辑设计组件属性
|
||
3. **热更新同步** - 修改后自动刷新页面
|
||
|
||
## 总结
|
||
|
||
本项目实现了一个完整的**Vue页面可视化设计器**，通过直接解析和编辑真实的Vue文件，实现了低代码的页面构建方式。
|
||
|
||
**核心亮点**：
|
||
1. **非侵入式设计** - 通过注入式交互，无需修改Vue页面代码
|
||
2. **智能层级选择** - 自动识别嵌套结构，键盘切换层级
|
||
3. **实时视觉反馈** - 拖拽预览 + 拖放区域指示
|
||
4. **结构化路径** - 自动生成可读的元素ID |