mixdashboards 1.0.12 → 1.0.13

package/README.md

@@ -5,7 +5,7 @@
 [![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 - 新一代企业级可视化组件库
+**MixDashboards** - 新一代企业级可视化大屏组件库
 
 专为工业物联网和数据可视化场景设计的 Vue 3 组件库
 
@@ -15,12 +15,13 @@ MixDashboards - 新一代企业级可视化组件库
 
 ## ✨ 特性
 
-- 🎯 **开箱即用** - 内置丰富的图表和可视化组件
+- 🎯 **开箱即用** - 内置 70+ 图表和可视化组件
 - 🚀 **实时数据** - 基于 WebSocket 的实时数据推送
 - 🎨 **高度可定制** - 灵活的配置系统，满足各种业务需求
-- 📱 **响应式设计** - 完美适配桌面和大屏展示
+- 📱 **响应式设计** - 完美适配桌面和大屏展示（自动缩放）
 - 🔧 **Vue 3 + TypeScript** - 基于最新技术栈构建
 - 🌐 **多场景支持** - Pro、Show、App、Pad 四种展示模式
+- 📦 **图层系统** - 支持多图层叠加，灵活控制组件层级
 
 ---
 
@@ -28,24 +29,29 @@ MixDashboards - 新一代企业级可视化组件库
 
 ```bash
 # 使用 npm
-npm install mixdashboards vue element-plus
+npm install mixdashboards
 
 # 使用 pnpm
-pnpm add mixdashboards vue element-plus
+pnpm add mixdashboards
 
 # 使用 yarn
-yarn add mixdashboards vue element-plus
+yarn add mixdashboards
 ```
 
-### 依赖要求
+### 必需的依赖
 
-- Vue 3.5+
-- Element Plus 2.11+
+mixdashboards 需要以下 peer dependencies：
 
 ```bash
-npm install vue@^3.5.0 element-plus@^2.11.0
+npm install vue@^3.5.0 echarts@^5.6.0 three@^0.180.0
 ```
 
+| 依赖 | 版本 | 说明 |
+|------|------|------|
+| `vue` | ^3.5.0 | Vue 3 核心框架 |
+| `echarts` | ^5.6.0 | 图表渲染引擎 |
+| `three` | ^0.180.0 | 3D 可视化支持 |
+
 ---
 
 ## 🚀 快速开始
@@ -145,12 +151,84 @@ app.mount('#app')
 
 ---
 
-### DesignShow - 展示版
+### MixDesignShow - 大屏展示版 ⭐
+
+全屏只读展示模式，专为大屏展示场景设计。**自动缩放适配任意分辨率屏幕**。
 
-只读展示模式，适合大屏展示场景。
+**Props**
+
+| 属性 | 类型 | 默认值 | 必填 | 说明 |
+|------|------|--------|------|------|
+| `script` | `Object` | - | ✅ | 仪表盘配置对象 |
+| `uid` | `String` | - | ❌ | 唯一标识符 |
+| `enableWebSocket` | `Boolean` | `true` | ❌ | 是否启用 WebSocket 实时数据 |
+
+**完整使用示例**
 
 ```vue
-<DesignShow :script="config" uid="show-001" />
+<template>
+  <MixDesignShow :script="dashboardData" />
+</template>
+
+<script setup>
+import { MixDesignShow } from 'mixdashboards'
+import 'mixdashboards/style'
+
+const dashboardData = {
+  "dashboard": [{
+    "name": "生产监控大屏",
+    "id": "SHOW001",
+    "type": "show",
+    "version": "3.0.0",
+    "sheets": [{
+      "name": "主页面",
+      "id": "sheet_001",
+      "col": 100,
+      "screenWidth": 1920,
+      "screenHeight": 1080,
+      "background": "defaultBg1",
+      "layers": [
+        {
+          "id": "layer_001",
+          "name": "图层 1",
+          "visible": true,
+          "opacity": 100,
+          "order": 0,
+          "components": [
+            {
+              "x": 4, "y": 8, "w": 39, "h": 48,
+              "i": "001",
+              "type": "pie",
+              "id": "pie_001",
+              "name": "饼状图",
+              "options": {
+                "titleColor": "#111",
+                "bgColor": "#fff"
+              }
+            }
+          ]
+        },
+        {
+          "id": "layer_002",
+          "name": "图层 2",
+          "visible": true,
+          "opacity": 100,
+          "order": 1,
+          "components": [
+            {
+              "x": 50, "y": 30, "w": 45, "h": 50,
+              "i": "002",
+              "type": "circleBar",
+              "id": "circleBar_002",
+              "name": "环形图"
+            }
+          ]
+        }
+      ]
+    }]
+  }]
+}
+</script>
 ```
 
 ---
@@ -219,32 +297,84 @@ localStorage.setItem('user', JSON.stringify({
 }
 ```
 
-## 配置结构
+## 📋 配置结构
+
+### 完整配置示例
 
 ```typescript
 interface DashboardConfig {
-  name: string              // 仪表盘名称
-  type: 'pro' | 'show'     // 类型
-  version: string          // 版本号
-  sheets: Sheet[]          // 页面列表
-  currentPage: number      // 当前页码
+  dashboard: [{
+    name: string              // 仪表盘名称
+    id: string                // 唯一ID
+    type: 'pro' | 'show'      // 类型：pro=专业版, show=展示版
+    version: string           // 版本号
+    sheets: Sheet[]           // 页面列表
+    currentPage?: number      // 当前页码
+  }]
 }
 
 interface Sheet {
-  name: string            // 页面名称
-  components: Component[] // 组件列表
-  background?: string     // 背景设置
+  name: string              // 页面名称
+  id: string                // 页面ID
+  col: number               // 列数（推荐 100）
+  screenWidth: number       // 设计宽度（如 1920）
+  screenHeight: number      // 设计高度（如 1080）
+  background?: string       // 背景：颜色值或 'defaultBg1'/'defaultBg2'
+  layers: Layer[]           // 图层列表
+}
+
+interface Layer {
+  id: string                // 图层ID
+  name: string              // 图层名称
+  visible: boolean          // 是否可见
+  opacity: number           // 透明度 0-100
+  order: number             // 层级顺序（数字越大越靠上）
+  locked?: boolean          // 是否锁定
+  components: Component[]   // 该图层的组件列表
 }
 
 interface Component {
-  type: string           // 组件类型（如 'bar', 'line', 'pie' 等）
-  name: string           // 组件名称
-  options: object        // 组件配置
-  data: DataItem[]       // 数据配置
-  common: CommonConfig   // 通用配置
+  x: number                // X 坐标（网格单位）
+  y: number                // Y 坐标（网格单位）
+  w: number                // 宽度（网格单位）
+  h: number                // 高度（网格单位）
+  i: string                // 唯一标识
+  id: string               // 组件ID
+  type: string             // 组件类型（如 'bar', 'line', 'pie' 等）
+  name: string             // 组件名称
+  options?: object         // 组件配置项
+  data?: DataItem[]        // 数据配置
+  common?: CommonConfig    // 通用配置（数据源）
+}
+
+interface DataItem {
+  fv: string               // 字段变量名
+  name: string             // 显示名称
+}
+
+interface CommonConfig {
+  object_id: string        // 数据对象ID
 }
 ```
 
+### 图层系统说明
+
+图层按 `order` 值从小到大渲染，`order` 值大的图层显示在上层：
+
+```
+┌─────────────────────────────┐
+│  图层2 (order: 1) - 最上层   │
+│  ┌─────────────────┐        │
+│  │   环形图         │        │
+│  └─────────────────┘        │
+├─────────────────────────────┤
+│  图层1 (order: 0) - 底层     │
+│  ┌─────────────────┐        │
+│  │   饼状图         │        │
+│  └─────────────────┘        │
+└─────────────────────────────┘
+```
+
 ---
 
 ## 💡 开发模式
@@ -265,18 +395,50 @@ interface Component {
 
 ---
 
-## 🎨 支持的图表类型
-
-- 📊 **柱状图 (bar)** - 横向/纵向柱状图
-- 📈 **折线图 (line)** - 单线/多线图
-- 🥧 **饼图 (pie)** - 饼图/环形图
-- 📉 **散点图 (scatter)** - 散点分布图
-- 🎯 **仪表盘 (gauge)** - 仪表盘图表
-- 🗺️ **地图 (map)** - 地理数据可视化
-- 📊 **竞赛条图 (raceBar)** - 动态排名图
-- 🔢 **数字 (number)** - 数值展示组件
-- 📝 **表格 (table)** - 数据表格
-- 还有更多...
+## 🎨 支持的组件类型
+
+### 📊 图表类组件
+
+| 类型 | 名称 | 说明 |
+|------|------|------|
+| `bar` | 柱状图 | 横向/纵向柱状图 |
+| `line` | 折线图 | 单线/多线趋势图 |
+| `pie` | 饼图 | 饼图/扇形图 |
+| `circleBar` | 环形图 | 环形进度图 |
+| `gauge` | 仪表盘 | 仪表盘图表 |
+| `scatter` | 散点图 | 散点分布图 |
+| `radar` | 雷达图 | 多维数据对比 |
+| `funnel` | 漏斗图 | 转化率分析 |
+| `raceBar` | 竞赛条图 | 动态排名图 |
+
+### 🔢 数据展示组件
+
+| 类型 | 名称 | 说明 |
+|------|------|------|
+| `number` | 数字 | 大数字展示 |
+| `table` | 表格 | 数据表格 |
+| `list` | 列表 | 滚动列表 |
+| `progress` | 进度条 | 进度展示 |
+| `rank` | 排名 | 排行榜 |
+
+### 🎥 媒体组件
+
+| 类型 | 名称 | 说明 |
+|------|------|------|
+| `video` | 视频 | 视频播放/RTMP推流 |
+| `audio` | 音频 | 音频播放器 |
+| `image` | 图片 | 图片展示 |
+| `fileViewer` | 文件查看器 | PDF/Office 预览 |
+
+### �️ 其他组件
+
+| 类型 | 名称 | 说明 |
+|------|------|------|
+| `clock` | 时钟 | 时间显示 |
+| `text` | 文本 | 富文本展示 |
+| `border` | 边框 | 装饰边框 |
+| `map` | 地图 | 地理数据可视化 |
+| `model3d` | 3D模型 | Three.js 3D展示 |
 
 ---
 
@@ -287,34 +449,51 @@ interface Component {
 确保导入了样式文件：
 
 ```typescript
+import 'mixdashboards/style'
+// 或者
 import 'mixdashboards/dist/mixdashboards.css'
-import 'element-plus/dist/index.css'
 ```
 
-### 2. WebSocket 连接失败？
+### 2. ECharts 报错 "Can't get DOM width or height"？
+
+这是因为容器在 ECharts 初始化时还没有尺寸。MixDesignShow 组件已内置处理，确保：
+- 父容器有明确的宽高
+- 或者使用 MixDesignShow（会自动全屏）
+
+### 3. WebSocket 连接失败？
 
 检查以下几点：
 1. 确保设置了 `enableWebSocket="true"`
-2. 确保 localStorage 中有用户 token
-3. 检查网络连接和后端服务状态
+2. 确保 localStorage 中有用户 token：
+```javascript
+localStorage.setItem('user', JSON.stringify({ token: 'xxx' }))
+```
+3. 检查后端 WebSocket 服务是否正常
 
-### 3. 图表不显示数据？
+### 4. 图表不显示数据？
 
 确保配置中包含：
 - `common.object_id` - 数据对象ID
 - `data[].fv` - 数据字段名
 
-### 4. 如何自定义主题？
-
-可以通过 CSS 变量覆盖默认样式：
+### 5. 大屏显示比例不对？
 
-```css
-:root {
-  --primary-color: #409EFF;
-  --background-color: #1a1a1a;
+检查 Sheet 配置中的 `screenWidth` 和 `screenHeight` 是否正确设置：
+```javascript
+{
+  "screenWidth": 1920,
+  "screenHeight": 1080,
+  "col": 100
 }
 ```
 
+### 6. 缺少依赖报错？
+
+确保安装了所有必需的 peer dependencies：
+```bash
+npm install vue echarts three
+```
+
 ---
 
 ## 🔗 相关链接