mixdashboards 1.0.2 → 1.0.4

package/README.md

@@ -1,73 +1,337 @@
-# MixDashboards
-
-一个基于Vue 3的工业物联网数据可视化组件库，提供大屏展示、Pro版和移动端适配的显示板组件。
-
-## 简介
-
-MixDashboards（mixdashboards）是一个专注于工业物联网领域的前端组件库，提供了可视化大屏、Pro版和App端的显示板组件，服务于设备监控和数据展示需求。
-
-## 安装
-
-```bash
-npm install mixdashboards
-```
-
-## 使用
-
-### 全局引入
-
-```javascript
-import { createApp } from 'vue'
-import mixdashboards from 'mixdashboards'
-import 'mixdashboards/style'
-
-const app = createApp(App)
-app.use(mixdashboards)
-```
-
-### 按需引入
-
-```javascript
-import { DesignPro, DesignShow, DesignApp } from 'mixdashboards'
-import 'mixdashboards/style'
-```
-
-### 组件使用
-
-```vue
-<template>
-  <DesignShow :uid="uid" :script="script" />
-  <DesignPro :uid="uid" :script="script" />
-  <DesignApp :uid="uid" :script="script" />
-</template>
-
-<script setup>
-const uid = '设备唯一标识'
-const script = {
-  // 组件配置脚本
-}
-</script>
-```
-
-## 组件说明
-
-- `DesignShow` - 大屏显示板组件，适用于PC端大型数据可视化界面
-- `DesignPro` - Pro级显示板组件，支持复杂的布局与交互逻辑
-- `DesignApp` - App端适配的显示板组件，适用于移动端或轻量化场景
-
-## 主要特性
-
-- 所有组件通过 `script` 脚本配置驱动，实现高度动态化渲染
-- 支持通过 `uid` 指定数据源对象，便于绑定具体设备或实体的数据流
-- 提供暗色主题支持
-- 内置拖拽布局能力
-
-## 依赖
-
-- Vue 3.5+
-- Element Plus 2.9+
-- ECharts 5.6+
-
-## 许可证
-
-MIT
+# MixDashboards
+
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/mixdashboards.svg)](https://www.npmjs.com/package/mixdashboards)
+[![license](https://img.shields.io/npm/l/mixdashboards.svg)](https://github.com/mixlinker/mixdashboards/blob/main/LICENSE)
+
+MixDashboards - 新一代企业级可视化组件库
+
+专为工业物联网和数据可视化场景设计的 Vue 3 组件库
+
+</div>
+
+---
+
+## ✨ 特性
+
+- 🎯 **开箱即用** - 内置丰富的图表和可视化组件
+- 🚀 **实时数据** - 基于 WebSocket 的实时数据推送
+- 🎨 **高度可定制** - 灵活的配置系统，满足各种业务需求
+- 📱 **响应式设计** - 完美适配桌面和大屏展示
+- 🔧 **Vue 3 + TypeScript** - 基于最新技术栈构建
+- 🌐 **多场景支持** - Pro、Show、App、Pad 四种展示模式
+
+---
+
+## 📦 安装
+
+```bash
+# 使用 npm
+npm install mixdashboards vue element-plus
+
+# 使用 pnpm
+pnpm add mixdashboards vue element-plus
+
+# 使用 yarn
+yarn add mixdashboards vue element-plus
+```
+
+### 依赖要求
+
+- Vue 3.5+
+- Element Plus 2.11+
+
+```bash
+npm install vue@^3.5.0 element-plus@^2.11.0
+```
+
+---
+
+## 🚀 快速开始
+
+### 方式一：按需引入（推荐）
+
+```vue
+<script setup lang="ts">
+import { DesignPro } from 'mixdashboards'
+import 'mixdashboards/dist/style.css'
+import 'element-plus/dist/index.css'
+
+const config = {
+  name: "销售数据看板",
+  type: "pro",
+  version: "2.0.0",
+  sheets: [
+    {
+      name: "概览",
+      components: [
+        {
+          type: "bar",
+          name: "月度销售额",
+          common: {
+            object_id: "3713089264"  // 数据对象ID
+          },
+          data: [{
+            fv: "sales_amount",       // 数据字段
+            name: "销售额"
+          }]
+        }
+      ]
+    }
+  ]
+}
+</script>
+
+<template>
+  <DesignPro 
+    :script="config" 
+    uid="sales-dashboard"
+    :enableWebSocket="true"
+  />
+</template>
+```
+
+### 方式二：完整引入
+
+```typescript
+// main.ts
+import { createApp } from 'vue'
+import ElementPlus from 'element-plus'
+import 'element-plus/dist/index.css'
+import MixDashboards from 'mixdashboards'
+import 'mixdashboards/dist/style.css'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(ElementPlus)
+app.use(MixDashboards)
+app.mount('#app')
+```
+
+然后在组件中直接使用：
+
+```vue
+<template>
+  <DesignPro :script="config" uid="dashboard-001" />
+</template>
+```
+
+---
+
+## 📚 组件说明
+
+### DesignPro - 专业版仪表盘
+
+功能最完整的仪表盘组件，支持实时数据、交互操作等。
+
+**Props**
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+|------|------|--------|------|------|
+| `script` | `Object` | - | ✅ | 仪表盘配置对象 |
+| `uid` | `String` | - | ✅ | 唯一标识符，用于区分不同实例 |
+| `enableWebSocket` | `Boolean` | `false` | ❌ | 是否启用 WebSocket 实时数据 |
+
+**使用示例**
+
+```vue
+<DesignPro 
+  :script="dashboardConfig"
+  uid="prod-dashboard-001"
+  :enableWebSocket="true"
+/>
+```
+
+---
+
+### DesignShow - 展示版
+
+只读展示模式，适合大屏展示场景。
+
+```vue
+<DesignShow :script="config" uid="show-001" />
+```
+
+---
+
+### DesignApp - 应用版
+
+移动端优化版本。
+
+```vue
+<DesignApp :script="config" uid="app-001" />
+```
+
+---
+
+### DesignPad - 平板版
+
+平板设备优化版本。
+
+```vue
+<DesignPad :script="config" uid="pad-001" />
+```
+
+---
+
+## 🔌 WebSocket 实时数据
+
+### 启用实时数据
+
+设置 `enableWebSocket="true"` 即可启用实时数据推送：
+
+```vue
+<DesignPro 
+  :script="config" 
+  uid="dashboard"
+  :enableWebSocket="true"
+/>
+```
+
+### 用户认证
+
+组件会自动从 localStorage 读取用户信息进行认证：
+
+```typescript
+// 在组件挂载前设置用户信息
+localStorage.setItem('user', JSON.stringify({
+  token: 'YOUR_AUTH_TOKEN',
+  id: 1,
+  username: 'admin'
+}))
+```
+
+### 数据订阅
+
+在组件配置中指定 `object_id` 和 `fv` 字段来订阅数据：
+
+```typescript
+{
+  type: "bar",
+  common: {
+    object_id: "3713089264"  // 数据对象ID
+  },
+  data: [{
+    fv: "temperature",        // 要订阅的字段
+    name: "温度"
+  }]
+}
+```
+
+## 配置结构
+
+```typescript
+interface DashboardConfig {
+  name: string              // 仪表盘名称
+  type: 'pro' | 'show'     // 类型
+  version: string          // 版本号
+  sheets: Sheet[]          // 页面列表
+  currentPage: number      // 当前页码
+}
+
+interface Sheet {
+  name: string            // 页面名称
+  components: Component[] // 组件列表
+  background?: string     // 背景设置
+}
+
+interface Component {
+  type: string           // 组件类型（如 'bar', 'line', 'pie' 等）
+  name: string           // 组件名称
+  options: object        // 组件配置
+  data: DataItem[]       // 数据配置
+  common: CommonConfig   // 通用配置
+}
+```
+
+---
+
+## 💡 开发模式
+
+### 静态数据模式（开发调试）
+
+```vue
+<!-- 适合开发调试，不需要后端连接 -->
+<DesignPro :script="config" uid="dev-001" />
+```
+
+### 实时数据模式（生产环境）
+
+```vue
+<!-- 连接后端实时数据推送 -->
+<DesignPro :script="config" uid="prod-001" :enableWebSocket="true" />
+```
+
+---
+
+## 🎨 支持的图表类型
+
+- 📊 **柱状图 (bar)** - 横向/纵向柱状图
+- 📈 **折线图 (line)** - 单线/多线图
+- 🥧 **饼图 (pie)** - 饼图/环形图
+- 📉 **散点图 (scatter)** - 散点分布图
+- 🎯 **仪表盘 (gauge)** - 仪表盘图表
+- 🗺️ **地图 (map)** - 地理数据可视化
+- 📊 **竞赛条图 (raceBar)** - 动态排名图
+- 🔢 **数字 (number)** - 数值展示组件
+- 📝 **表格 (table)** - 数据表格
+- 还有更多...
+
+---
+
+## ❓ 常见问题
+
+### 1. 样式没有生效？
+
+确保导入了样式文件：
+
+```typescript
+import 'mixdashboards/dist/style.css'
+import 'element-plus/dist/index.css'
+```
+
+### 2. WebSocket 连接失败？
+
+检查以下几点：
+1. 确保设置了 `enableWebSocket="true"`
+2. 确保 localStorage 中有用户 token
+3. 检查网络连接和后端服务状态
+
+### 3. 图表不显示数据？
+
+确保配置中包含：
+- `common.object_id` - 数据对象ID
+- `data[].fv` - 数据字段名
+
+### 4. 如何自定义主题？
+
+可以通过 CSS 变量覆盖默认样式：
+
+```css
+:root {
+  --primary-color: #409EFF;
+  --background-color: #1a1a1a;
+}
+```
+
+---
+
+## 🔗 相关链接
+
+- [在线文档](https://docs.mixlinker.com/mixdashboards)
+- [GitHub 仓库](http://192.168.88.6/mixiot/v8/frontend/newui/mixdashboards)
+- [更新日志](./CHANGELOG.md)
+- [问题反馈](http://192.168.88.6/mixiot/v8/frontend/newui/mixdashboards/issues)
+
+---
+
+## 📄 许可证
+
+MIT © 2025 Mixlinker Technical Team
+
+---
+
+<div align="center">
+Made with ❤️ by Mixlinker
+</div>