327 lines
12 KiB
Markdown
327 lines
12 KiB
Markdown
# 拖拽面板设计器 - 项目上下文总结
|
||
|
||
> **用途**：用于在新电脑快速恢复 AI 协作上下文
|
||
> **生成时间**：2025-12-20
|
||
> **项目路径**：`/Volumes/mypan/ui/draggable-panels`
|
||
|
||
---
|
||
|
||
## 📋 项目概述
|
||
|
||
这是一个基于 **Vue3 + TypeScript + Vite** 的**可拖拽面板设计器**项目，类似 IDE 界面（IDEA/VS Code）的多面板布局，支持：
|
||
|
||
- 🎯 三栏面板布局（左/中/右可调整宽度）
|
||
- 🎨 Tab 可拖拽、跨面板移动
|
||
- 🧩 物料组件系统（自动扫描注册）
|
||
- 🎭 设计组件系统（可视化编辑、属性绑定）
|
||
- 💾 状态持久化（通过模拟 API）
|
||
|
||
---
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
draggable-panels/
|
||
├── src/
|
||
│ ├── fauto/ # 🔥 设计器核心代码（所有功能都在这里）
|
||
│ │ ├── Designer.vue # 设计器主入口页面
|
||
│ │ ├── components/ # 设计器基础组件
|
||
│ │ │ ├── Header.vue # 顶部菜单栏（打开项目/窗口菜单）
|
||
│ │ │ ├── Footer.vue # 底部状态栏
|
||
│ │ │ ├── MainLayout.vue # 三栏布局容器
|
||
│ │ │ ├── Panel.vue # 单个面板（含 Tab 列表 + 内容区）
|
||
│ │ │ └── Resizer.vue # 面板间拖拽分割线
|
||
│ │ │
|
||
│ │ ├── materials/ # 🎁 物料组件（8个）
|
||
│ │ │ ├── index.ts # ✅ 自动扫描所有 */index.vue 和 */index.json
|
||
│ │ │ ├── DesignComponentList/ # 可选设计组件列表
|
||
│ │ │ ├── TreeViewer/ # 树形结构查看器（已添加实例列表）
|
||
│ │ │ ├── DesignCenter/ # 设计中心（组件预览面板）
|
||
│ │ │ ├── DataTable/ # 属性表格编辑器
|
||
│ │ │ ├── TextEditor/ # 文本编辑器（支持状态持久化）
|
||
│ │ │ ├── TestWidget1/2/3/ # 测试组件
|
||
│ │ │ └── [每个物料包含]
|
||
│ │ │ ├── index.vue # 组件实现
|
||
│ │ │ └── index.json # 组件元数据（name/description）
|
||
│ │ │
|
||
│ │ ├── designComponents/ # 🎨 设计组件（3个）
|
||
│ │ │ ├── TextInput/ # 文本输入框
|
||
│ │ │ ├── RadioSelect/ # 单选器
|
||
│ │ │ ├── GridTable/ # 表格
|
||
│ │ │ └── [每个设计组件包含]
|
||
│ │ │ ├── index.vue # Vue 组件定义
|
||
│ │ │ └── index.json # 元数据（name/description/props）
|
||
│ │ │
|
||
│ │ ├── stores/ # 🗄️ Pinia 状态管理
|
||
│ │ │ ├── panelStore.ts # 面板布局 + 物料状态管理
|
||
│ │ │ └── designStore.ts # 设计组件实例管理（✅ 本地自动扫描）
|
||
│ │ │
|
||
│ │ └── types/ # 📝 TypeScript 类型定义
|
||
│ │ └── index.ts # Panel/TabItem/MaterialInfo 等
|
||
│ │
|
||
│ ├── views/ # 普通视图
|
||
│ │ └── HelloWorld.vue # 首页欢迎页
|
||
│ │
|
||
│ ├── router.ts # 🛤️ 路由配置（/ 和 /draggable）
|
||
│ ├── main.ts # 应用入口
|
||
│ ├── App.vue # 根组件（仅路由容器）
|
||
│ └── style.css # 全局样式
|
||
│
|
||
├── package.json # 依赖配置
|
||
└── vite.config.ts # Vite 配置
|
||
```
|
||
|
||
---
|
||
|
||
## 🔑 核心技术要点
|
||
|
||
### 1. **路由设计**
|
||
|
||
```typescript
|
||
// src/router.ts
|
||
'/' → HelloWorld 欢迎页
|
||
'/draggable' → Designer 设计器主页面（fauto/Designer.vue）
|
||
```
|
||
|
||
### 2. **物料组件自动注册** ⭐
|
||
|
||
**文件**：`src/fauto/materials/index.ts`
|
||
|
||
```typescript
|
||
// ✅ 使用 import.meta.glob 自动扫描
|
||
const vueModules = import.meta.glob('./*/index.vue')
|
||
const jsonModules = import.meta.glob('./*/index.json', { eager: true })
|
||
|
||
// 自动构建组件映射表和信息列表
|
||
export const materialComponents: Record<string, Component> = {}
|
||
export const materialList: MaterialInfo[] = []
|
||
```
|
||
|
||
**新增物料步骤**：
|
||
1. 在 `materials/` 下创建新目录（如 `MyWidget/`）
|
||
2. 添加 `index.vue`（组件实现）
|
||
3. 添加 `index.json`（元数据）
|
||
4. **无需修改任何注册代码**，自动生效！
|
||
|
||
### 3. **设计组件自动加载** ⭐
|
||
|
||
**最近修复**（2025-12-20）：
|
||
|
||
**designStore.ts** - 从远程 API 改为本地扫描：
|
||
```typescript
|
||
// ✅ 使用 eager: true 同步加载
|
||
const designComponentMetaModules = import.meta.glob('../designComponents/*/index.json', { eager: true })
|
||
|
||
// 自动构建元数据列表
|
||
const loadComponentMetas = async () => {
|
||
const metas: DesignComponentMeta[] = []
|
||
for (const path in designComponentMetaModules) {
|
||
const id = match[1] // 如 'TextInput'
|
||
metas.push({ id, name, description, props })
|
||
}
|
||
componentMetas.value = metas
|
||
}
|
||
```
|
||
|
||
**DesignCenter.vue** - 组件预览渲染：
|
||
```typescript
|
||
// ✅ 使用 eager: true 确保同步加载
|
||
const designComponentModules = import.meta.glob('../../designComponents/*/index.vue', { eager: true })
|
||
|
||
// 构建组件映射（用于 <component :is="...">）
|
||
const designComponentMap: Record<string, any> = {}
|
||
for (const path in designComponentModules) {
|
||
const mod = designComponentModules[path] as any
|
||
designComponentMap[id] = markRaw(mod.default || mod)
|
||
}
|
||
```
|
||
|
||
### 4. **状态同步机制** ⭐
|
||
|
||
**TreeViewer.vue** - 实例列表实时同步（最近修复）：
|
||
```typescript
|
||
// ✅ 改用 watch 替代 $subscribe（更稳定）
|
||
watch(
|
||
() => designStore.components,
|
||
(newVal) => {
|
||
localComponents.value = [...newVal]
|
||
},
|
||
{ deep: true, immediate: true }
|
||
)
|
||
```
|
||
|
||
### 5. **状态持久化**
|
||
|
||
- **panelStore**：管理面板布局 + 物料组件状态
|
||
- `loadConfig()` / `saveConfig()` → `/api/config`
|
||
- `getMaterialState()` / `updateMaterialState()` → `/api/material-states`
|
||
|
||
- **designStore**：管理设计组件实例
|
||
- `loadState()` / `saveState()` → `/api/design-state`
|
||
|
||
**注意**：目前使用 `fetch('/api/...')` 模拟持久化，实际会失败但不影响运行。如需真实持久化，可改用 localStorage 或搭建后端。
|
||
|
||
---
|
||
|
||
## 🎯 数据流图
|
||
|
||
```
|
||
用户操作
|
||
↓
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Header.vue - 点击"窗口"菜单 │
|
||
│ → panelStore.openMaterial('TreeViewer') │
|
||
└─────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Panel.vue - 渲染 Tab + 加载物料组件 │
|
||
│ → <component :is="getMaterialComponent(id)"> │
|
||
└─────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────┐
|
||
│ DesignComponentList - 点击"文本输入框" │
|
||
│ → designStore.addComponent('TextInput') │
|
||
└─────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────┐
|
||
│ TreeViewer - watch 监听 components 变化 │
|
||
│ → 自动刷新实例列表 │
|
||
└─────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────┐
|
||
│ DesignCenter - 渲染组件预览 │
|
||
│ → <component :is="getComponent(componentId)"> │
|
||
└─────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────┐
|
||
│ DataTable - 编辑属性 │
|
||
│ → designStore.updateComponentProps(id, key, val)│
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 🐛 已解决的关键问题
|
||
|
||
### 问题 1：设计组件列表不显示
|
||
**时间**：2025-12-20
|
||
**原因**：`designStore.loadComponentMetas()` 使用 `fetch('/api/design-components')`，无后端导致 `componentMetas` 为空
|
||
**解决**：改用 `import.meta.glob` 自动扫描本地 `designComponents/*/index.json`
|
||
|
||
### 问题 2：TreeViewer 列表不更新
|
||
**原因**：使用 Pinia 的 `$subscribe` 监听 mutation，逻辑复杂且不稳定
|
||
**解决**：改用 Vue 的 `watch(() => designStore.components)` 直接监听
|
||
|
||
### 问题 3：DesignCenter 组件不渲染
|
||
**原因**：`import.meta.glob` 未设置 `eager: true`，导致组件映射表构建失败
|
||
**解决**：添加 `{ eager: true }` 并使用 `mod.default || mod` 获取组件定义
|
||
|
||
---
|
||
|
||
## 📦 依赖清单
|
||
|
||
```json
|
||
{
|
||
"dependencies": {
|
||
"vue": "^3.5.24", // Vue 3 框架
|
||
"vue-router": "^4.6.4", // 路由管理
|
||
"pinia": "^3.0.4", // 状态管理
|
||
"vuedraggable": "^4.1.0" // 拖拽功能
|
||
},
|
||
"devDependencies": {
|
||
"vite": "^7.2.4", // 构建工具
|
||
"typescript": "~5.9.3", // TypeScript
|
||
"@vitejs/plugin-vue": "^6.0.1"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 启动命令
|
||
|
||
```bash
|
||
# 1. 安装依赖
|
||
npm install
|
||
|
||
# 2. 启动开发服务器
|
||
npm run dev
|
||
# 访问 http://localhost:5173/draggable
|
||
|
||
# 3. 构建生产版本
|
||
npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 后续可优化方向
|
||
|
||
### 🔧 功能增强
|
||
1. **真实持久化**
|
||
- 选项 A：改用 `localStorage` 替代模拟 API
|
||
- 选项 B：搭建 Node.js 后端（Express + fs.writeFile）
|
||
|
||
2. **拖拽增强**
|
||
- 支持面板间 Tab 跨级拖动
|
||
- 树形组件支持父子节点拖拽
|
||
|
||
3. **设计器功能**
|
||
- 实现拖拽生成 Vue 文件（模板引擎）
|
||
- 接入 Element Plus 组件库作为设计组件源
|
||
|
||
4. **开发体验**
|
||
- 添加 ESLint + Prettier 代码规范
|
||
- 添加单元测试（Vitest）
|
||
|
||
### 🎨 界面优化
|
||
- 添加主题切换（暗色/亮色）
|
||
- 面板大小记忆功能
|
||
- 快捷键支持（Ctrl+S 保存等）
|
||
|
||
---
|
||
|
||
## 💡 给 AI 的关键提示
|
||
|
||
### 如果遇到"自动扫描不生效"
|
||
1. 检查是否添加了 `{ eager: true }` 选项
|
||
2. 确认路径匹配正则是否正确（`/designComponents\/(.+)\/index\.vue$/`）
|
||
3. 验证文件夹下是否有 `index.vue` 和 `index.json`
|
||
|
||
### 如果组件不渲染
|
||
1. 检查 `import.meta.glob` 是否使用 `eager: true`
|
||
2. 确认使用 `mod.default || mod` 获取组件
|
||
3. 对于动态组件，确保使用 `markRaw()` 包装
|
||
|
||
### 如果状态不同步
|
||
1. 优先使用 Vue 的 `watch` 而非 Pinia 的 `$subscribe`
|
||
2. 设置 `{ deep: true, immediate: true }` 确保深度监听
|
||
3. 使用 `[...array]` 创建新数组触发响应式更新
|
||
|
||
---
|
||
|
||
## 📞 联系方式
|
||
|
||
**项目负责人**：[你的信息]
|
||
**Git 仓库**：[如果有的话]
|
||
**文档更新**：2025-12-20
|
||
|
||
---
|
||
|
||
## ✅ 快速检查清单（给新 AI）
|
||
|
||
当你接手这个项目时，请确认以下内容：
|
||
|
||
- [ ] 项目已正常启动（`npm run dev`）
|
||
- [ ] 访问 `/draggable` 能看到设计器界面
|
||
- [ ] 点击"窗口"菜单能打开物料组件
|
||
- [ ] "设计组件列表"显示 3 个组件（TextInput/RadioSelect/GridTable）
|
||
- [ ] 点击设计组件后，TreeViewer 能显示新实例
|
||
- [ ] DesignCenter 能正确渲染组件预览
|
||
- [ ] DataTable 能编辑组件属性
|
||
|
||
如果以上任一项失败，请参考"已解决的关键问题"章节。
|
||
|
||
---
|
||
|
||
**🎉 恭喜！你已经完全掌握了这个项目的上下文，可以继续开发了！**
|