@sec-fe/v-grid-layout

一个基于 Vue 3 + Element Plus 的可视化大屏网格布局编辑/查看组件库，内置 Pinia 状态，提供 JSON 数据读写能力。

特性

• 基于 Vue 3 + TypeScript + Pinia，自动注入全局状态
• 可视化网格编辑 + 预览一体，支持组件面板与属性面板
• 内置图表类型占位节点，支持自定义业务数据/样式
• JSON 数据读写（getPureJsonData / initPureJsonData），版本号 0.0.1
• 主题类型：dashboard / fullPage，全局/单元格样式可配置
• 以插件方式注册组件，附带必要的全局依赖注册

安装

前置依赖

在安装本包之前，请确保项目中已安装（或在项目中可被打包）以下依赖。它们在构建时被标记为 external/peer：

• vue (> 3.4.21)
• element-plus (^2.10.4) 及其样式 element-plus/dist/index.css
• pinia (^2.3.1)
• modern-normalize (^3.0.1)
• file-saver (^2.0.5)
• lodash (^4.17.21)
• @element-plus/icons-vue (^2.3.1)
• @vueuse/core (^13.5.0)
• @vueuse/integrations (^13.5.0)
• @kjgl77/datav-vue3 (^1.3.3)
• universal-cookie (^8.0.1)

  注意：上述依赖版本仅供参考，具体版本请根据项目需求选择兼容版本。

安装包

使用 pnpm：

pnpm add @sec-fe/v-grid-layout

使用 npm：

npm install @sec-fe/v-grid-layout

使用 yarn：

yarn add @sec-fe/v-grid-layout

快速开始

1. 在入口注册插件并导入样式

import { VGridLayoutEditor, VGridLayoutViewer } from '@sec-fe/v-grid-layout';
// main.ts
import { createApp } from 'vue';
import App from './App.vue';
import '@sec-fe/v-grid-layout/style.css';
import 'element-plus/dist/index.css';

const app = createApp(App);
app.use(VGridLayoutEditor); // 注册编辑器所需的全局组件与 Pinia
app.use(VGridLayoutViewer); // 注册查看器组件与 Pinia
app.mount('#app');

2. 编辑器示例

<template>
  <VGridLayoutEditor
    :data="savedJson"
    :show-tab="false"
    @init="handleInit"
    @save="handleSave"
    @go-back="handleBack"
  />
</template>

<script setup lang="ts">
import type { UseMainStoreReturn } from '@sec-fe/v-grid-layout/types';
import { ref } from 'vue';

const savedJson = localStorage.getItem('grid-json') || '';

function handleInit(store: UseMainStoreReturn) {
  store.initRowAndColArr();
  if (savedJson) store.initPureJsonData(savedJson);
}

function handleSave(json: string) {
  localStorage.setItem('grid-json', json);
}

function handleBack() {
  // 自定义返回逻辑
}
</script>

3. 查看器示例

<template>
  <VGridLayoutViewer :data="savedJson" theme-type="dashboard" @mounted="handleMounted">
    <!-- 透传插槽可自定义单元格内部内容 -->
    <template #default="{ cell }">
      <div>{{ cell?.data?.reportName }}</div>
    </template>
  </VGridLayoutViewer>
</template>

<script setup lang="ts">
import type { UseMainStoreReturn } from '@sec-fe/v-grid-layout/types';

const savedJson = localStorage.getItem('grid-json') || '';

function handleMounted(store: UseMainStoreReturn) {
  // 可根据需要调整主题或其他状态
  store.changeThemeType('dashboard');
}
</script>

API 文档

VGridLayoutEditor Props

| 属性 | 类型 | 默认值 | 说明 | | --------- | --------- | ------- | --------------------------------------------------------------------------------------- | | data | string | '' | 通过 getPureJsonData() 生成的 JSON 字符串，包含网格/主题/单元格数据，版本需为 0.0.1 | | showTab | boolean | false | 是否在组件面板中显示系统/自定义 Tab |

VGridLayoutEditor Events

| 事件 | 参数 | 说明 | | --------- | ----------------------------- | -------------------------------------------------------------- | | save | (json: string) | 触发保存时返回纯净 JSON 字符串（内部调用 getPureJsonData()） | | go-back | () | 点击返回按钮时触发 | | init | (store: UseMainStoreReturn) | 组件挂载后触发，暴露主 Store 以便外部初始化/注入数据 |

VGridLayoutViewer Props

| 属性 | 类型 | 默认值 | 说明 | | ----------- | --------------------------- | ------------- | -------------------------- | | data | string | '' | 纯净 JSON 字符串，结构同上 | | themeType | 'fullPage' \| 'dashboard' | 'dashboard' | 设置初始主题类型 |

VGridLayoutViewer Events

| 事件 | 参数 | 说明 | | --------- | ----------------------------- | --------------------------------------------------- | | mounted | (store: UseMainStoreReturn) | 组件挂载后触发，暴露主 Store 以便调整主题或读取状态 |

数据结构与版本

• 数据版本：0.0.1（常量 DATA_VERSION）。
• 核心字段：
  • gridData：rows / cols / rowGap / colGap 以及 rowArr / colArr。
  • gridCells：以单元格 id 为键的对象，存储 area、mergedCellIds、data、themes。
  • subjectData：主题基础信息。
  • themes 与 themeType：主题配置与当前主题类型（dashboard / fullPage）。
• 获取/加载：
  • 保存时使用 store.getPureJsonData()。
  • 加载时使用 store.initPureJsonData(json)，返回 { ok: true } 或 { ok: false, reason }。

工具函数

• getDropGridIndex(event: DragEvent)：根据拖拽事件定位目标网格索引，同时触发选中交互。

高级用法

当前版本未对外暴露独立 Hook（useGrid / useTheme / useEditor），如需访问可通过 init / mounted 事件获取的 UseMainStoreReturn 实例使用内部能力。

开发

# 克隆项目
git clone https://github.com/roojay/v-grid-layout.git

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint

参考资源

可视化大屏设计

• 阿里云 DataV
• 百度 Sugar
• 腾讯云图
• FineReport
• 大屏数据可视化

可视化工具

• rawgraphs
• chartjs
• d3js
• fusioncharts
• JavaScript InfoVis Toolkit
• zingchart
• flotcharts
• gephi
• infogram
• icharts

图表工具

• echarts
• antv
• highcharts

License

Copyright © 2024 All rights reserved.