# vue-dashboard-builder

**Repository Path**: nocjb/vue-dashboard-builder

## Basic Information

- **Project Name**: vue-dashboard-builder
- **Description**: 一个交互式的可视化首页仪表板设计工具，允许用户通过拖放操作创建和自定义个性化仪表板。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-25
- **Last Updated**: 2025-06-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, TypeScript

## README

# Vue 仪表板构建器 (Vue Dashboard Builder)

一个交互式的可视化首页仪表板设计工具，允许用户通过拖放操作创建和自定义个性化仪表板。

基于Vue 3的拖拽式首页布局设计器，支持模板管理、角色绑定和多种布局模式，为不同用户提供个性化的首页体验。

## 功能特点

- 🖱️ **拖拽式设计**：直观的拖拽界面，轻松布局组件
- 📱 **响应式布局**：支持网格模式和自由模式两种布局方式
- 🧩 **丰富组件**：内置多种常用组件和业务统计卡片
- 💾 **模板管理**：支持保存、加载和管理多种布局模板
- 👥 **角色绑定**：可将模板绑定到特定角色，实现角色化首页配置
- 👤 **用户自定义**：支持用户自定义布局并保存个人设置
- 📤 **导入导出**：支持JSON格式导入导出布局配置
- 👀 **即时预览**：随时切换到预览模式查看效果

## 技术栈

- ⚡ Vue 3 + Vite + TypeScript - 现代前端开发框架
- 🔄 Pinia 状态管理 - 轻量高效的状态管理方案
- 🧰 Ant Design Vue - 企业级UI组件库
- 📐 grid-layout-plus - 强大的栅格布局系统

## 项目结构

```
src/
├── api/                # API接口
│   └── designer/       # 设计器相关API和模拟数据
├── hooks/              # 自定义钩子
│   └── designer/       # 设计器相关钩子
├── store/              # Pinia状态管理
│   └── modules/        # 状态模块
│       ├── designer.ts # 设计器状态
│       └── template.ts # 模板状态
├── utils/              # 工具函数
│   └── designer/       # 设计器工具函数
└── views/              # 视图组件
    ├── designer/       # 设计器相关组件
    │   ├── components/ # 设计器子组件
    │   └── types/      # 类型定义
    ├── home/           # 首页组件
    └── template/       # 模板管理组件
        ├── components/ # 模板管理子组件
        └── types/      # 模板类型定义
```

## 组件说明

### 核心组件

- **HomeDesigner**: 主设计器组件，包含整体布局和控制逻辑
  - 左侧组件面板、中间设计画布、右侧属性面板三栏布局
  - 顶部工具栏提供预览、保存、导入导出等操作
  
- **DesignerCanvas**: 中央设计画布，处理拖拽和组件渲染
  - 基于grid-layout实现的可视化设计区域
  - 支持组件拖拽、调整大小、删除等操作
  
- **LeftPanel**: 左侧组件面板，提供可添加的组件列表
  - 支持组件分类和搜索
  - 拖拽添加组件到画布
  
- **RightPanel**: 右侧属性面板，配置布局和组件属性
  - 包含全局设置和组件属性两个选项卡
  - 提供布局参数和组件参数调整
  
- **HomePreview**: 预览组件，展示最终效果
  - 实时渲染当前布局配置的效果

### 模板管理组件

- **TemplateManager**: 模板管理中心，提供模板列表和角色分配功能
- **TemplateCard**: 模板卡片，展示模板信息和操作按钮
- **TemplateForm**: 模板表单，用于新增或编辑模板
- **TemplateImport**: 模板导入组件，支持多种导入方式
- **RoleTemplateMapping**: 角色模板映射组件，管理角色与模板的关联

### 状态管理

使用Pinia管理设计器状态，主要包括：
- **designerStore**: 布局设计器状态
  - 布局配置数据
  - 组件类型映射
  - UI状态控制
  - 用户信息管理
- **templateStore**: 模板管理状态
  - 模板列表管理
  - 角色模板关联
  - 默认模板设置

## 使用方法

### 基本操作

1. 从左侧面板选择组件拖入画布
2. 拖动组件调整位置，拖动边缘调整大小
3. 点击组件配置属性
4. 使用顶部按钮预览、保存或导出布局

### 布局模式

- **自由模式**：组件可任意位置放置，支持自定义宽度，适合复杂布局
- **限制模式**：组件宽度固定为1列，便于创建规则的栅格布局

### 模板管理

1. 管理员可在"模板管理"中创建和管理模板
2. 可将模板设为默认模板，供新用户使用
3. 可将特定模板绑定到角色，实现角色化首页

### 用户布局

1. 用户可编辑并保存个人首页布局
2. 可随时重置为角色模板或默认模板
3. 可导出个人布局配置

## 开发指南

### 添加新组件

1. 在`src/utils/designer/componentRegistry.ts`中注册组件
   ```typescript
   registerComponent({
     name: '组件名称',
     component: '组件引用',
     category: '组件分类'
   });
   ```
2. 创建组件文件并确保符合布局组件接口规范
3. 组件将自动动态加载到系统中

### 自定义布局系统

布局系统基于`grid-layout-plus`，可以通过修改以下文件自定义：
- `src/hooks/designer/useLayout.ts`：布局逻辑，包括添加组件、切换布局模式等
- `src/store/modules/designer.ts`：布局状态管理，包括布局数据和UI状态