# mixdashboards 中文文档

规范地址：https://npmcn.com/package/mixdashboards/

版本：1\.1\.158
npm 元数据更新时间：2026-11-04T02:39:57.329Z
中文译文更新时间：2026-11-04T04:45:01.771Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/mixdashboards
原文对照：https://npmcn.com/package/mixdashboards/?lang=original
项目主页：http://192.168.88.6/mixiot/v9/frontend/mixdesign/-/tree/master/packages
源码仓库：https://192.168.88.6/mixiot/v9/frontend/mixdesign

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：19.8 MB，29 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：41 个
- peer 依赖：vue ^3\.4\.0，pinia ^2\.0\.0 \|\| ^3\.0\.0，vue-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
- 首次发布：2025-10-31T08:13:06.112Z
- 最新版本发布：2026-11-04T02:39:57.149Z
- 已发布版本数：235（近 12 个月 230 个）

## 中文简介

MixDashboards显示组件- Show， Pro, App

## 安装

```sh
npm install mixdashboards
```

也可以使用：`pnpm add mixdashboards`、`yarn add mixdashboards`、`bun add mixdashboards`

## README

# mixdashboards

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

当前版本：**1.1.112**

## 组件使用文档与示例

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

## 在 Monorepo 中的定位

本包位于 [mixdesign](http://192.168.88.6/mixiot/v9/frontend/mixdesign) monorepo 的 `packages/` 目录，与 `apps/mixdesign-yunuis`（设计器应用）同属一个仓库：

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

**仓库地址**

```bash
git clone git@192.168.88.6: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 应用中验证：

```bash
# 在 monorepo 根目录
pnpm install

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

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

# 构建 packages + apps
pnpm build
```

### 方式二：外部项目 npm 安装

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

```bash
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。

#### 全局注册

```javascript
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 时组件仍可渲染，但内置文案固定回退为中文。

#### 按需引入

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

## 组件使用示例

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

| 组件 | 适用场景 | 脚本类型 |
| --- | --- | --- |
| `DesignShow` | 大屏、指挥屏、不需要应用菜单的展示页 | 单个 Show 显示板 |
| `DesignPro` | PC 显示板，或需要显式启用 Pro 应用壳 | 单个 Pro 显示板 / Pro 应用整包 |
| `DesignApp` | 移动显示板或由组件自动识别的应用整包 | 单个 App 显示板 / Pro 应用整包 |

### DesignShow

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

```vue
<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`。

```vue
<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 应用整包，可显式启用应用壳：

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

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

### DesignApp

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

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

```vue
<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` 控制显示板：

```javascript
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))
```

### 鉴权配置

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

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

完整 API 列表见：

-   [API\_DOCUMENTATION.md](https://npmcn.com/package/mixdashboards/API_DOCUMENTATION.md) — 详细说明
-   [API\_QUICK\_REFERENCE.md](https://npmcn.com/package/mixdashboards/API_QUICK_REFERENCE.md) — 快速查阅
-   [使用文档.md](https://npmcn.com/package/mixdashboards/%E4%BD%BF%E7%94%A8%E6%96%87%E6%A1%A3.md) — 完整使用手册

## 本地开发

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

```bash
# 安装全部 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

```bash
# 根目录执行，会先触发 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

## 相关链接

-   [Monorepo 仓库](http://192.168.88.6/mixiot/v9/frontend/mixdesign)
-   [Issue 反馈](http://192.168.88.6/mixiot/v9/frontend/mixdesign/-/issues)
-   [设计器应用](https://npmcn.com/package/apps/) — `apps/mixdesign-yunuis`

## 许可证

MIT © Mixlinker Technical Team

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

## 常见问题

### 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 和提交记录判断。