dashboard-viewer

v1.0.3

Published

4 months ago

MixDashboard显示板JSON脚本预览器

0High
0Medium
0Low

xiangxiaochong

dashboard viewer preview vue3 visualization

Dashboard Viewer

MixDashboard 显示板 JSON 脚本预览器 - Vue 3 组件库

一个用于解析和渲染 MixDashboard 显示板 JSON 脚本的 Vue 3 组件库，支持 PC、大屏、移动端三种显示板类型。

✨ 功能特性

📁 JSON 脚本解析 - 完整支持显示板 JSON 脚本格式
🎨 多图层渲染 - 支持图层系统，包括透明度、可见性等属性
📄 多页签支持 - 支持多个 Sheet 页签切换
📱 响应式布局 - 支持 PC、大屏、移动端三种显示板类型
🔄 实时数据 - 支持 WebSocket 连接，实时更新数据
🎯 自适应缩放 - 大屏显示板自动适配屏幕尺寸
🔧 TypeScript - 完整的类型定义支持
🎨 自定义组件 - 支持注册自定义组件替换默认占位符

📦 安装

npm install dashboard-viewer
# 或
yarn add dashboard-viewer
# 或
pnpm add dashboard-viewer

依赖要求

Vue 3.3+
Element Plus 2.0+

确保你的项目已安装这些依赖：

npm install vue element-plus

🚀 快速开始

1. 全局注册（推荐）

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import DashboardViewer from 'dashboard-viewer'
import 'dashboard-viewer/style.css'

import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.use(DashboardViewer)
app.mount('#app')

2. 按需引入

<template>
  <DashboardViewer :data="dashboardData" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { DashboardViewer } from 'dashboard-viewer'
import 'dashboard-viewer/style.css'
import type { DashboardData } from 'dashboard-viewer'

const dashboardData = ref<DashboardData>({
  name: '我的显示板',
  id: 'dashboard-001',
  type: 'pro',
  version: '2.0.0',
  sheets: [{
    name: '首页',
    col: 20,
    screenWidth: 1920,
    screenHeight: 1080,
    layers: [{
      id: 'layer_1',
      name: '图层1',
      visible: true,
      opacity: 100,
      order: 0,
      locked: false,
      components: []
    }]
  }]
})
</script>

样式导入方式

支持以下任意一种方式导入样式：

// 方式1：简洁路径（推荐）
import 'dashboard-viewer/style.css'

// 方式2：带 dist 路径
import 'dashboard-viewer/dist/style.css'

// 方式3：完整文件名
import 'dashboard-viewer/dist/dashboard-viewer.css'

📖 组件 API

DashboardViewer Props

| 属性名 | 类型 | 默认值 | 说明 | |--------|------|--------|------| | data | DashboardData | 必填 | 显示板数据 | | wsUrl | string | - | WebSocket 服务器地址（可选） | | wsToken | string | - | WebSocket 访问令牌（可选） | | showHeader | boolean | true | 是否显示头部 | | showTabs | boolean | true | 是否显示页签切换 |

DashboardViewer Slots

| 插槽名 | 说明 | |--------|------| | header-left | 自定义头部左侧内容 | | header-right | 自定义头部右侧内容 |

使用示例

<template>
  <DashboardViewer :data="data" :ws-url="wsUrl" :ws-token="wsToken">
    <template #header-left>
      <el-button @click="goBack">返回</el-button>
    </template>
    <template #header-right>
      <el-button @click="refresh">刷新</el-button>
    </template>
  </DashboardViewer>
</template>

🔧 工具类使用

DashboardParser - JSON 解析器

import { DashboardParser } from 'dashboard-viewer'

// 从文件解析
const file = event.target.files[0]
const data = await DashboardParser.parseFile(file)

// 从 JSON 字符串解析
const jsonString = '{"name":"显示板",...}'
const data = DashboardParser.parseJSON(jsonString)

// 验证文件类型
const isValid = DashboardParser.isValidFile(file)

ComponentLoader - 组件加载器

import { ComponentLoader } from 'dashboard-viewer'
import MyBarChart from './components/MyBarChart.vue'

// 注册单个组件
ComponentLoader.registerComponent('bar', MyBarChart)

// 批量注册组件
ComponentLoader.registerComponents({
  bar: MyBarChart,
  pie: MyPieChart
})

WebSocketManager - WebSocket 管理

import { WebSocketManager } from 'dashboard-viewer'

const wsManager = new WebSocketManager(
  'wss://your-server.com/websocket',
  'your-token'
)

wsManager.on('connected', () => {
  console.log('已连接')
})

wsManager.on('message', (data) => {
  console.log('收到消息:', data)
})

wsManager.connect()

📋 JSON 脚本格式

显示板 JSON 脚本的基本结构：

interface DashboardData {
  name: string          // 显示板名称
  id: string           // 唯一标识
  type: 'pro' | 'show' | 'app'  // 显示板类型
  version: string      // 版本号
  sheets: Sheet[]      // 页签数组
}

interface Sheet {
  name: string         // 页签名称
  col: number          // 列数
  screenWidth?: number // 屏幕宽度
  screenHeight?: number // 屏幕高度
  background?: string  // 背景图
  layers: Layer[]      // 图层数组
}

interface Layer {
  id: string           // 图层ID
  name: string         // 图层名称
  visible: boolean     // 是否可见
  opacity: number      // 透明度 (0-100)
  order: number        // 层级顺序
  locked: boolean      // 是否锁定
  components: ComponentItem[]  // 组件数组
}

interface ComponentItem {
  x: number            // X坐标
  y: number            // Y坐标
  w: number            // 宽度
  h: number            // 高度
  i: string            // 唯一标识
  id: string           // 组件ID
  type: string         // 组件类型
  name: string         // 组件名称
  options: any         // 组件配置
  data?: any[]         // 组件数据
}

完整示例：

{
  "name": "销售数据看板",
  "id": "dashboard-001",
  "type": "show",
  "version": "2.0.0",
  "sheets": [
    {
      "name": "首页",
      "col": 20,
      "screenWidth": 1920,
      "screenHeight": 1080,
      "background": "",
      "layers": [
        {
          "id": "layer_1",
          "name": "数据层",
          "visible": true,
          "opacity": 100,
          "order": 0,
          "locked": false,
          "components": [
            {
              "x": 0,
              "y": 0,
              "w": 8,
              "h": 4,
              "i": "comp_1",
              "id": "chart_001",
              "type": "bar",
              "name": "柱状图",
              "options": {
                "title": "月度销售"
              },
              "data": []
            }
          ]
        }
      ]
    }
  ]
}

🌐 显示板类型

PC 显示板 (type: "pro")

适用于桌面浏览器
响应式布局
默认列数: 20

大屏显示板 (type: "show")

适用于大屏幕展示
自动缩放适配
固定宽高比
默认分辨率: 1920x1080

移动端显示板 (type: "app")

适用于移动设备
最大宽度: 375px
默认列数: 4

🎨 支持的组件类型

图表类

bar - 柱状图
raceBar - 竞赛柱状图
pie - 饼图
line - 折线图
gauge - 仪表盘
radar - 雷达图
sankey - 桑基图

控制类

btn - 按钮
card - 卡片

其他

textbox - 文本框
gridview - 表格
list - 列表
swiper - 轮播
tabs - 选项卡

注意: 默认使用占位符组件，可通过 ComponentLoader 注册真实组件。

💡 完整示例

文件上传预览

<template>
  <div class="app">
    <div v-if="!data" class="upload-section">
      <el-upload
        drag
        accept=".json"
        :auto-upload="false"
        :on-change="handleFileChange"
      >
        <el-icon><upload-filled /></el-icon>
        <div>拖拽或点击上传 JSON 文件</div>
      </el-upload>
    </div>

    <DashboardViewer v-else :data="data">
      <template #header-left>
        <el-button @click="data = null">重新上传</el-button>
      </template>
    </DashboardViewer>
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ElMessage } from 'element-plus'
import { UploadFilled } from '@element-plus/icons-vue'
import { DashboardViewer, DashboardParser } from 'dashboard-viewer'
import type { DashboardData } from 'dashboard-viewer'

const data = ref<DashboardData | null>(null)

const handleFileChange = async (file: any) => {
  try {
    data.value = await DashboardParser.parseFile(file.raw)
    ElMessage.success('加载成功')
  } catch (error: any) {
    ElMessage.error(error.message || '解析失败')
  }
}
</script>

📚 更多文档

🔨 技术栈

框架: Vue 3 + TypeScript
构建工具: Vite
UI 组件: Element Plus
布局: Grid Layout Plus
样式: SCSS + Tailwind CSS

📝 注意事项

样式引入: 必须引入样式文件 import 'dashboard-viewer/style.css'
Element Plus: 确保项目中已全局注册 Element Plus
文件格式: 只支持 .json 格式的显示板脚本
WebSocket: WebSocket 配置是可选的，不影响静态预览
组件注册: 自定义组件需要在使用前注册

📦 包信息

包大小:
- ES 模块: ~56KB (gzipped)
- UMD 模块: ~49KB (gzipped)
依赖:
- Vue 3.3+
- Element Plus 2.0+

🔄 版本历史

v1.0.1 (2025-10-30)

🐛 修复样式导入路径问题
✨ 支持多种样式导入方式
📝 更新文档

v1.0.0 (2025-10-30)

🎉 首次发布
✨ 支持三种显示板类型
✨ 完整的 TypeScript 支持
✨ 支持 WebSocket 实时数据

📄 许可证

🤝 贡献

欢迎提交 Issue 和 Pull Request！

💬 支持

如有问题或建议：

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 文档: 完整文档

⭐ Star History

如果这个项目对你有帮助，请给个 Star ⭐️

Made with ❤️ by xxc_2025