mixdashboards

mixdashboards

MixIoT 显示板组件库 — 支持显示屏（Show）、大屏（Pro）、移动端（App）三种展示模式

当前版本：1.1.112

在 Monorepo 中的定位

本包位于 mixdesign monorepo 的 packages/ 目录，与 apps/mixdesign-yunuis（设计器应用）同属一个仓库：

mixdesign/
├── packages/          ← 本包（mixdashboards）：展示组件、元素库、预览运行时
├── apps/              ← mixdesign-yunuis：可视化设计器
├── pnpm-workspace.yaml
└── package.json

仓库地址

git clone git@192.168.88.6:mixiot/v9/frontend/mixdesign.git

特性

• 三种显示模式：DesignShow（显示屏）、DesignPro（大屏）、DesignApp（移动端）
• 丰富元素库：图表、地图、3D、视频、表格等 40+ 可视化组件（src/elements/）
• 完整运行时 API：页签、图层、弹窗、主题、WebSocket 数据订阅
• LinkHub 通讯：跨组件频道发布/订阅
• 主题切换：亮色 / 暗色，支持运行时切换
• TypeScript：源码为 TS + Vue 3 SFC

目录结构

packages/
├── src/
│   ├── DesignShow.vue      # 显示屏入口
│   ├── DesignPro.vue       # 大屏入口
│   ├── DesignApp.vue       # 移动端入口
│   ├── index.ts            # 包导出入口
│   ├── elements/           # 可视化元素组件（bar、pie、map、3D…）
│   ├── preview/            # 预览运行时（弹窗、菜单、页签栏等）
│   ├── hooks/              # 公共 hooks
│   ├── service/            # API / WebSocket / 鉴权代理
│   ├── utils/              # 工具函数
│   ├── pinia/              # 状态管理
│   ├── i18n/               # 国际化
│   ├── components/         # 公共 UI 组件
│   └── lib/                # 内嵌库（grid-layout-plus、mixment 等）
├── dist/                   # 构建产物（npm 发布）
├── vite.config.ts
└── package.json

使用方式

方式一：Monorepo 内联开发（推荐）

apps/mixdesign-yunuis 在开发/构建时通过 Vite alias 直接引用 packages/src，改 packages 源码后无需重新 link 即可在 design 应用中验证：

# 在 monorepo 根目录
pnpm install

# 仅启动 packages 本地预览（端口 4000）
pnpm dev:dashboards

# 启动设计器应用（端口见 apps/vite.config.ts）
pnpm dev

# 构建 packages + apps
pnpm build

方式二：外部项目 npm 安装

独立项目可通过 npm 安装已发布的包：

pnpm add mixdashboards vue-i18n@11.2.7
# 或
npm install mixdashboards vue-i18n@11.2.7

vue-i18n 是包的 peer dependency。宿主只负责提供当前 locale，组件内置的 button、fields、message、tabs 词典由 mixdashboards 自己维护，不需要也不应合并到宿主 messages。

全局注册

import { createApp } from 'vue'
import { createPinia } from 'pinia'
import { createI18n } from 'vue-i18n'
import ElementPlus from 'element-plus'
import MixDashboards from 'mixdashboards'
import 'element-plus/dist/index.css'
import 'mixdashboards/style'

const app = createApp(App)
const i18n = createI18n({
  legacy: false,
  locale: 'zh-CN',
  fallbackLocale: 'en',
  messages: {
    'zh-CN': {},
    en: {}
  }
})

app.use(createPinia())
app.use(ElementPlus)
app.use(i18n)
app.use(MixDashboards)
app.mount('#app')

切换 i18n.global.locale.value 后，组件内置文案会跟随更新；宿主同名 key 不会覆盖包内词条。 未配置 i18n provider 时组件仍可渲染，但内置文案固定回退为中文。

按需引入

import { DesignShow, DesignPro, DesignApp } from 'mixdashboards'
import 'mixdashboards/style'

组件使用示例

script 是设计器发布的完整脚本对象，也可以是宿主接口返回的脚本数据。三个入口都需要一个有明确高度的宿主容器。

DesignShow

用于渲染单个 Show 显示板。ready 会在全局加载结束且首帧画布绘制完成后触发。

<template>
  <div class="dashboard-host">
    <DesignShow
      :script="showScript"
      uid="show-instance-001"
      mixiot-dashboard-uid="dashboard-001"
      :enable-web-socket="true"
      :follow-host-theme="true"
      :is-product="true"
      @ready="handleReady"
    />
  </div>
</template>

<script setup lang="ts">
import { DesignShow } from 'mixdashboards'
import 'mixdashboards/style'
import showScript from './show-script.json'

function handleReady() {
  console.log('Show 显示板已完成首帧绘制')
}
</script>

<style scoped>
.dashboard-host {
  width: 100%;
  height: 100vh;
  overflow: hidden;
}
</style>

DesignPro

用于渲染单个 PC Pro 显示板。组件对外暴露 switchSheetByPageKey(pageKey)，可按 Sheet 的 id、name 或 caption 切换页面；成功返回 Sheet 下标，未找到返回 -1。

<template>
  <div class="dashboard-host">
    <DesignPro
      ref="designProRef"
      :script="proScript"
      uid="pro-instance-001"
      :enable-web-socket="true"
      :follow-host-theme="true"
      :is-product="true"
      @ready="handleReady"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { DesignPro } from 'mixdashboards'
import 'mixdashboards/style'
import proScript from './pro-script.json'

type DesignProInstance = {
  switchSheetByPageKey: (pageKey: string) => number
}

const designProRef = ref<DesignProInstance | null>(null)

function handleReady() {
  // 可以传 Sheet 的 id、name 或 caption
  designProRef.value?.switchSheetByPageKey('总览')
}
</script>

<style scoped>
.dashboard-host {
  width: 100%;
  height: 100vh;
  overflow: hidden;
}
</style>

如果 script 是包含 pro.menu 和多个显示板映射的 Pro 应用整包，可显式启用应用壳：

<DesignPro
  :script="proApplicationScript"
  pro-shell
  :mobile-shell="null"
  @ready="handleReady"
/>

pro-shell 模式下由应用壳管理菜单、Tab 和显示板切换，不使用 switchSheetByPageKey() 切换应用菜单。

DesignApp

DesignApp 是应用级自适应入口：传入单个移动显示板时直接渲染移动画布；传入 Pro 应用整包时，会自动切换到 Pro 应用壳，无需由宿主判断脚本类型。

以下示例演示将单个移动显示板嵌入宿主页面：

<template>
  <div class="app-host">
    <DesignApp
      :script="appScript"
      uid="app-instance-001"
      :enable-web-socket="true"
      :follow-host-theme="true"
      :is-product="true"
      :mobile-embed="true"
      @ready="handleReady"
    >
      <template #placeholder="{ placeholderName }">
        <div class="custom-placeholder">
          {{ placeholderName }}
        </div>
      </template>
    </DesignApp>
  </div>
</template>

<script setup lang="ts">
import { DesignApp } from 'mixdashboards'
import 'mixdashboards/style'
import appScript from './app-script.json'

function handleReady() {
  console.log('App 画布已就绪')
}
</script>

<style scoped>
.app-host {
  width: 100%;
  height: 100vh;
  overflow: hidden;
}

.custom-placeholder {
  display: grid;
  width: 100%;
  height: 100%;
  place-items: center;
}
</style>

mobile-embed 仅影响单个移动显示板：为 true 时画布铺满宿主容器；为 false 时使用独立移动预览宽度。

Props 与事件

三个组件共用以下参数：

组件特有参数：

运行时 API

组件挂载后，可通过全局对象 window.MixDashboard 控制显示板：

const dashboard = window.MixDashboard

dashboard.on('onReady', () => {
  console.log('Dashboard 已就绪')
})

dashboard.switchSheet(1)

dashboard.showModal({ layerId: 'layer-detail', width: 80, height: 60 })

dashboard.updateComponent('comp-123', {
  data: [{ value: 100, label: '数据' }]
})

dashboard.toggleTheme()

// LinkHub 跨组件通讯
dashboard.publish('sensor-data', { temperature: 25.5 })
dashboard.subscribe('sensor-data', (data) => console.log(data))

鉴权配置

import { configureAuth, getAuthToken, getWsUrl } from 'mixdashboards'

configureAuth({
  // 按项目接入方式配置，详见 service/authProxy.ts
})

完整 API 列表见：

• API_DOCUMENTATION.md — 详细说明
• API_QUICK_REFERENCE.md — 快速查阅
• 使用文档.md — 完整使用手册

本地开发

在 monorepo 根目录执行（不要只在 packages/ 内单独 npm install）：

# 安装全部 workspace 依赖
pnpm install

# packages 独立开发预览 → http://localhost:4000
pnpm dev:dashboards

# 类型检查
pnpm -F mixdashboards type-check

# 仅构建 packages
pnpm build:packages

# 构建并生成类型声明
pnpm -F mixdashboards build:with-types

发布到 npm

# 根目录执行，会先触发 prepublishOnly 构建
pnpm publish

发布前请更新 packages/package.json 中的 version 字段。

依赖要求

Peer Dependencies

主要内置依赖

ECharts、Three.js、Leaflet、AG Grid、hls.js、flv.js 等已打包进组件库，外部项目无需重复安装。

浏览器支持

• Chrome >= 90
• Firefox >= 88
• Safari >= 14
• Edge >= 90

相关链接

• Monorepo 仓库
• Issue 反馈
• 设计器应用 — apps/mixdesign-yunuis

许可证

MIT © Mixlinker Technical Team

Copyright © 2014–2026 Mixlinker Networks Inc. All rights reserved.