mixdashboards

中文文档

1.1.158发布于 2026/11/04MITES Module

MixDashboards显示组件- Show， Pro, App

文档目录22 节

组件使用文档与示例
在 Monorepo 中的定位
特性
目录结构
使用方式
方式一：Monorepo 内联开发（推荐）
方式二：外部项目 npm 安装
组件使用示例
DesignShow
DesignPro
DesignApp
Props 与事件
运行时 API
鉴权配置
本地开发
发布到 npm
依赖要求
Peer Dependencies
主要内置依赖
浏览器支持
相关链接
许可证

mixdashboards

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

当前版本：1.1.112

组件使用文档与示例

交互组件大类全部 10 个现有组件，以及柱状图的操作步骤、配置参考和数据示例见组件使用文档。在仓库根目录运行 pnpm docs:components 可查看交互 demo 和同步配置。

在 Monorepo 中的定位

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

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

仓库地址

git clone [email protected]:mixiot/v9/frontend/mixdesign.git

包名	目录	说明
`mixdashboards`	`packages/`	显示板展示组件库，可独立发布 npm
`mixdesign-yunuis`	`apps/`	设计器前端，开发时通过 Vite alias 直接引用 `packages/src` 源码

特性

三种显示模式：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 [email protected]
# 或
npm install mixdashboards [email protected]

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 显示板
`DesignPro`	PC 显示板，或需要显式启用 Pro 应用壳	单个 Pro 显示板 / Pro 应用整包
`DesignApp`	移动显示板或由组件自动识别的应用整包	单个 App 显示板 / Pro 应用整包

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 与事件

三个组件共用以下参数：

属性	类型	默认值	说明
`script`	`any`	—	设计器发布的完整脚本，必填
`uid`	`string`	—	当前运行实例/显示板标识
`mixiotDashboardUid`	`string`	—	MixIoT 显示板脚本 UID
`enableWebSocket`	`boolean`	`true`	是否启用实时数据连接
`followHostTheme`	`boolean`	`false`	是否跟随宿主深浅色主题，不改写 `document` 根主题
`isProduct`	`boolean`	`true`	生产模式下，未绑定数据源的图表不使用随机模拟数据
`agent`	`string`	`''`	嵌入代理服务标识
`@ready`	`() => void`	—	全局 loading 结束且首帧绘制完成

组件特有参数：

组件	属性	说明
`DesignShow`	`releaseEmbedAgentOnUnmount`	卸载时是否释放嵌入代理状态，默认 `true`
`DesignPro`	`hostProMenuTitle`	按宿主菜单名定位初始 Sheet
`DesignPro`	`hostMenuToSheetRules`	显式配置宿主菜单名与 Sheet 名称的对应关系
`DesignPro`	`proShell`	启用 Pro 应用菜单、Tab 和多显示板应用壳
`DesignPro`	`mobileShell`	强制移动应用壳；传 `null` 时根据脚本自动判断
`DesignApp`	`mobileEmbed`	单个移动显示板是否铺满宿主容器，默认 `false`
`DesignApp`	`releaseEmbedAgentOnUnmount`	卸载时是否释放嵌入代理状态，默认 `true`

运行时 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

包	版本
`vue`	^3.4.0
`pinia`	^2.0.0 \|\| ^3.0.0
`element-plus`	^2.0.0
`@univerjs/presets`	^0.17.0（可选，表格组件）
`@univerjs/preset-sheets-core`	^0.17.0（可选）

主要内置依赖

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

浏览器支持

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

许可证

版本与发布记录

mixdashboards 共发布 235 个版本，首次发布于 2025/10/31；过去 12 个月发布了 230 个版本。

版本	发布日期	距今
`1.1.158`latest	2026/11/04	今天
`1.1.157`	2026/11/03	1 天前
`1.1.156`	2026/11/02	2 天前
`1.1.155`	2026/10/29	6 天前
`1.1.154`	2026/10/28	7 天前
`1.1.153`	2026/10/27	8 天前

关于 mixdashboards 的常见问题

mixdashboards 是什么？

MixDashboards显示组件- Show， Pro, App

如何安装 mixdashboards？

在项目目录运行 npm install mixdashboards，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vue（^3.4.0）、pinia（^2.0.0 || ^3.0.0）、vue-i18n（^11.2.7）、element-plus（^2.0.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

mixdashboards 支持 TypeScript 吗？

该包的 package.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/mixdashboards 是否存在。

mixdashboards 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

mixdashboards 可以商用吗？

mixdashboards 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

mixdashboards 还在维护吗？

最新版本 1.1.158 发布于 2026/11/04（今天）；至今共发布 235 个版本，其中过去 12 个月发布了 230 个；首次发布于 2025/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install mixdashboards

pnpmpnpm add mixdashboards
yarnyarn add mixdashboards
bunbun add mixdashboards

peer 依赖vue ^3.4.0pinia ^2.0.0 || ^3.0.0vue-i18n ^11.2.7@vueuse/core ^13.0.0可选element-plus ^2.0.0@univerjs/presets ^0.17.0可选@univerjs/preset-sheets-core ^0.17.0可选

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

最新版本1.1.158发布于今天

开源许可MIT宽松许可

包体积19.8 MB29 个文件 · 解压后

运行依赖41 个另有 7 个 peer 依赖

模块格式ES Module

TypeScript未声明类型可查找 @types/mixdashboards

发布版本235 个近 12 个月 230 个

首次发布2025/10/311 年前

元数据更新2026/11/04

每一个软件包背后，
都有分享与创造的人。

mixdashboards

mixdashboards

组件使用文档与示例

在 Monorepo 中的定位

特性

目录结构

使用方式

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

方式二：外部项目 npm 安装

全局注册

按需引入

组件使用示例

DesignShow

DesignPro

DesignApp

Props 与事件

运行时 API

鉴权配置

本地开发

发布到 npm

依赖要求

Peer Dependencies

主要内置依赖

浏览器支持

相关链接

许可证

版本与发布记录

关于 mixdashboards 的常见问题

mixdashboards 是什么？

如何安装 mixdashboards？

mixdashboards 支持 TypeScript 吗？

mixdashboards 支持 ESM 还是 CommonJS？

mixdashboards 可以商用吗？

mixdashboards 还在维护吗？