# 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**: 1
- **Created**: 2025-05-25
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Vue, TypeScript

## README

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

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

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

## 功能特点

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

## 技术栈

- ⚡ Vue 3.5 + Vite 6 + TypeScript - 现代前端开发框架
- 🔄 Pinia 3.0 状态管理 - 轻量高效的状态管理方案
- 🧰 Ant Design Vue 4.2 - 企业级UI组件库
- 📐 grid-layout-plus - 强大的栅格布局系统
- 💡 @vueuse/core - 实用的Vue组合式API工具集
- 🖼️ Ant Design Icons - 优雅的图标系统

## 项目结构

```
src/
├── api/                # API接口
│   └── designer/       # 设计器相关API和模拟数据
├── hooks/              # 自定义钩子
│   └── designer/       # 设计器相关钩子
│       └── useLayout.ts # 布局相关逻辑
├── store/              # Pinia状态管理
│   └── modules/        # 状态模块
│       ├── designer.ts # 设计器状态
│       └── template.ts # 模板状态
├── utils/              # 工具函数
│   └── designer/       # 设计器工具函数
│       ├── componentLoader.ts # 组件动态加载
│       ├── componentRegistry.ts # 组件注册
│       └── validSytle.ts # 样式验证
└── views/              # 视图组件
    ├── designer/       # 设计器相关组件
    │   ├── components/ # 设计器子组件
    │   │   ├── DesignerCanvas.vue # 设计画布
    │   │   ├── HomePreview.vue # 预览组件
    │   │   ├── LeftPanel.vue # 左侧面板
    │   │   └── RightPanel.vue # 右侧面板
    │   ├── types/      # 类型定义
    │   │   └── designer.ts # 设计器类型定义
    │   └── HomeDesigner.vue # 主设计器组件
    ├── home/           # 首页组件
    └── template/       # 模板管理组件
        ├── components/ # 模板管理子组件
        │   ├── TemplateForm.vue # 模板表单
        │   └── TemplateImport.vue # 模板导入
        ├── types/      # 模板类型定义
        └── TemplateManager.vue # 模板管理器
```

## 组件说明

### 核心组件

- **HomeDesigner**: 主设计器组件，包含整体布局和控制逻辑
  - 左侧组件面板、中间设计画布、右侧属性面板三栏布局
  - 顶部工具栏提供预览、保存、导入导出等操作
  - 支持管理员和用户两种模式切换
  - 集成模板管理和布局操作功能
  
- **DesignerCanvas**: 中央设计画布，处理拖拽和组件渲染
  - 基于grid-layout实现的可视化设计区域
  - 支持组件拖拽、调整大小、删除等操作
  - 实时反馈布局变化
  
- **LeftPanel**: 左侧组件面板，提供可添加的组件列表
  - 提供普通组件和业务统计卡片两种分类
  - 支持设置组件初始尺寸
  - 根据布局模式自动调整组件宽度
  
- **RightPanel**: 右侧属性面板，配置布局和组件属性
  - 包含全局设置、组件属性和首页信息三个选项卡
  - 全局设置提供布局参数和UI控制
  - 组件属性提供选中组件的配置选项
  - 首页信息显示用户与模板状态
  
- **HomePreview**: 预览组件，展示最终效果
  - 实时渲染当前布局配置的效果
  - 模拟真实用户界面体验

### 模板管理组件

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

### 状态管理

使用Pinia管理设计器状态，主要包括：
- **designerStore**: 布局设计器状态
  - 布局配置数据（layout、layoutMap）
  - 布局设置（colNum、rowHeight、margin等）
  - UI状态控制（面板展开/折叠状态）
  - 组件管理（dynamicComponents、homeModes）
  - 用户信息管理（userInfo、userType、userTemplate）
- **templateStore**: 模板管理状态
  - 模板列表管理
  - 角色模板关联
  - 默认模板设置
  - 模板布局数据映射

## 使用方法

### 基本操作

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

### 布局模式

- **自由模式**：组件可任意位置放置，支持自定义宽度，适合复杂布局
  - 可利用"应用排版"快速应用1、2、3、4、6、12列排版
  - 组件宽度可自由调整，适合创建自定义布局
- **限制模式**：组件宽度固定为1列，便于创建规则的栅格布局
  - 可设置网格列数，控制布局分列
  - 自动优化组件位置，确保布局整齐

### 设计器界面控制

1. 使用顶部面板的"预览"按钮切换设计/预览模式
2. 左右两侧面板可通过折叠/展开按钮控制显示状态
3. 组件交互模式支持"遮罩层"和"仅拖动把手"两种方式

### 模板管理

1. 管理员可在"模板管理"中创建和管理模板
2. 可将模板设为默认模板，供新用户使用
3. 可将特定模板绑定到角色，实现角色化首页
4. 支持模板的导入导出，便于跨系统迁移

### 用户布局

1. 用户可编辑并保存个人首页布局
2. 可随时重置为角色模板或默认模板
3. 可导出个人布局配置
4. 系统会记录用户布局类型（自定义、角色模板或默认模板）

## 开发指南

### 添加新组件

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状态

### 样式和界面定制

- 可通过修改组件样式自定义界面外观
- 组件样式采用scoped方式，方便独立修改
- 支持自定义背景色和内边距等布局参数

### 布局数据格式

布局数据采用标准JSON格式，包含以下主要结构：
```typescript
interface LayoutPojo {
  layout: LayoutItem[]; // 组件布局数组
  setting: {
    colNum: number; // 列数
    gridMode: boolean; // 是否为网格模式
    homePadding?: string; // 内边距
    bgColor?: string; // 背景色
    rowHeight?: number; // 行高
    margin?: [number, number]; // 外边距
  }
}
```