npm package: @sec-fe/v-grid-layout
Description: 一个基于 Vue 3 + Element Plus 的可视化大屏网格布局编辑/查看组件库，内置 Pinia 状态，提供 JSON 数据读写能力。
Latest version: 0.0.2

# @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：

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

使用 npm：

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

使用 yarn：

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

## 快速开始

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

```typescript
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. 编辑器示例

```vue
<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. 查看器示例

```vue
<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` 实例使用内部能力。

## 开发

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

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 代码检查
pnpm lint
```

## 参考资源

### 可视化大屏设计

- [阿里云 DataV](https://data.aliyun.com/visual/datav)
- [百度 Sugar](https://cloud.baidu.com/product/sugar.html)
- [腾讯云图](https://cloud.tencent.com/product/yuntu)
- [FineReport](http://www.finereport.com/)
- [大屏数据可视化](https://github.com/yyhsong/iDataV)

### 可视化工具

- [rawgraphs](https://rawgraphs.io/)
- [chartjs](https://www.chartjs.org/)
- [d3js](https://d3js.org/)
- [fusioncharts](https://www.fusioncharts.com/)
- [JavaScript InfoVis Toolkit](http://philogb.github.io/jit/)
- [zingchart](https://www.zingchart.com/)
- [flotcharts](http://www.flotcharts.org/)
- [gephi](https://gephi.org/)
- [infogram](https://infogram.com/)
- [icharts](https://www.icharts.net/)

### 图表工具

- [echarts](https://echarts.baidu.com/)
- [antv](http://antv.alipay.com)
- [highcharts](https://www.highcharts.com.cn/)

## License

Copyright © 2024 All rights reserved.