配置参数说明

WoodyDashboard 的配置参数分为全局配置和组件配置两大类。本文档详细说明了各种配置参数的含义和使用方法。

全局配置 (globalSetting)

全局配置用于设置整个看板的样式和行为，影响所有组件。

基础配置

参数名	类型	默认值	说明
`bgColor`	string	`#0c1f46`	看板背景颜色，支持十六进制、rgb、rgba等格式
`fontColor`	string	`#ffffff`	全局字体颜色
`globalBorderColor`	string	`#5473bf`	全局边框颜色
`theme`	string	`dark`	主题风格，如 `dark`、`light`
`interval`	number	`5`	数据刷新间隔（秒）

标题配置

参数名	类型	默认值	说明
`title`	string	-	看板显示名称，用于页面顶部或导航
`dashTitle`	string	-	看板主标题，显示在看板内部

示例配置

json

{
  "globalSetting": {
    "bgColor": "#0c1f46",
    "fontColor": "#ffffff", 
    "globalBorderColor": "#5473bf",
    "theme": "dark",
    "interval": 5,
    "title": "生产监控看板",
    "dashTitle": "设备状态监控"
  }
}

边框配置 (borderBar)

边框配置用于定义组件的装饰边框样式和行为。

配置结构

typescript

interface BorderBarConfig {
  type: string;           // 组件类型，固定为 'borderBar'
  i: string;             // 组件唯一标识
  configOption: {        // 配置选项
    barOption: {         // 边框选项
      title: {           // 标题配置
        text: string;    // 标题文本
      };
    };
    rootData: any;       // 根数据
  };
  css: string;           // CSS 样式
  html: string;          // HTML 结构
  script: string;        // JavaScript 脚本
}

边框组件示例

json

{
  "borderBar": {
    "type": "borderBar",
    "i": "borderBar",
    "configOption": {
      "barOption": {
        "title": {
          "text": "蓝色线条标题"
        }
      },
      "rootData": {}
    },
    "css": ".simple-blue-border { border: 2px solid #2196f3; border-radius: 6px; }",
    "html": "<div class='simple-blue-border'><div class='title'>{{barOption?.title?.text}}</div><slot></slot></div>",
    "script": "const dynamicComponent = defineComponent({...}); return { dynamicComponent };"
  }
}

组件配置 (layout)

每个组件都有独立的配置参数，用于控制组件的行为和样式。

基础组件配置

参数名	类型	说明
`type`	string	组件类型：`header`、`component`、`borderBar`
`i`	string	组件唯一标识
`x`	number	组件在网格中的 X 坐标
`y`	number	组件在网格中的 Y 坐标
`w`	number	组件宽度（网格单位）
`h`	number	组件高度（网格单位）
`moved`	boolean	是否已移动过

组件内容配置

参数名	类型	说明
`html`	string	组件的 HTML 模板
`css`	string	组件的 CSS 样式
`script`	string	组件的 JavaScript 逻辑，包含 `getConfigOption` 函数

组件配置示例

json

{
  "layout": [
    {
      "type": "component",
      "i": "wdchart1",
      "x": 0,
      "y": 0,
      "w": 50,
      "h": 30,
      "moved": false,
      "html": "<div class='component'>{{msg}}</div>",
      "css": ".component { color: white; }",
      "script": "const dynamicComponent = defineComponent({...}); const getConfigOption = (configOption, rootData) => { return { hideBorder: false, fullScreen: { show: true, style: { color: 'blue' } } }; }; return { dynamicComponent, getConfigOption };"
    }
  ]
}

数据配置 (rootData & rootFormat)

rootData

存储看板的基础数据，可以是测试数据或实时数据。

json

{
  "rootData": {
    "deviceinfo": {
      "M01": {
        "device_name": "设备1",
        "device_state": 1,
        "values": { ... }
      }
    },
    "alarms": [...],
    "calc": { ... }
  }
}

rootFormat

数据格式化脚本，用于处理数据。

javascript

const rootFormat = async ({ rootData, settings, wss }) => {
  // 处理数据逻辑
  return processedData;
};

const initRootFormat = ({ rootData, settings, wss, setRootData }) => {
  // 初始化逻辑
  wss?.subscribe((event) => {
    // 处理 WebSocket 数据
  });
};

return { rootFormat, initRootFormat };

配置选项详解

getConfigOption 函数

configOption 不是直接在 JSON 中存储的，而是通过 script 中的 getConfigOption 函数动态生成的。这个函数接收 configOption 和 rootData 参数，返回组件的配置选项。

javascript

const getConfigOption = (configOption, rootData) => {
  return {
    rootData,                    // 传递给组件的根数据
    testConfig: { w: 400, h: 500 }, // 测试环境下的组件尺寸
    
    configOption: {
      hideBorder: false,         // 是否隐藏边框
      fullScreen: {              // 全屏按钮配置
        show: true,              // 是否显示全屏按钮
        style: { color: 'blue' } // 全屏按钮样式
      }
    },
    
    barOption: {                 // 边框组件配置
      title: { text: '组件标题' }, // 边框标题
    },
    
    chartOption: {               // ECharts 图表配置（可选）
      // 如果只返回 getConfigOption，可以配置 ECharts
    }
  };
};

configOption 参数

通过 getConfigOption 函数返回的 configOption 可以包含以下参数：

参数名	类型	默认值	说明
`hideBorder`	boolean	`false`	是否隐藏边框
`fullScreen`	object	-	全屏按钮配置
`fullScreen.show`	boolean	`false`	是否显示全屏按钮
`fullScreen.style`	object	-	全屏按钮样式

barOption 参数

传递给边框组件的参数：

参数名	类型	说明
`title.text`	string	边框标题文本
`title.style`	object	标题样式

chartOption 参数

ECharts 图表配置（仅当组件为图表类型时）：

javascript

const chartOption = {
  xAxis: { type: 'category', data: ['Mon', 'Tue', 'Wed'] },
  yAxis: { type: 'value' },
  series: [{ data: [120, 200, 150], type: 'line' }]
};

配置最佳实践

1. 命名规范

组件 ID (i) 使用有意义的名称，如 deviceStatus、alarmList
CSS 类名使用唯一标识符，避免样式冲突
变量名使用驼峰命名法

2. 性能优化

合理设置 interval 值，避免过于频繁的数据刷新
使用 computed 进行数据计算，避免重复计算
及时清理定时器和事件监听器

3. 样式管理

使用 CSS 变量统一管理颜色主题
避免内联样式，使用 CSS 类
考虑响应式设计，适配不同屏幕尺寸

4. 数据安全

对用户输入进行验证和过滤
使用 try-catch 处理数据异常
避免在模板中直接执行用户代码

配置示例

完整的看板配置

json

{
  "globalSetting": {
    "bgColor": "#0c1f46",
    "fontColor": "#ffffff",
    "globalBorderColor": "#5473bf",
    "theme": "dark",
    "interval": 5,
    "title": "生产监控看板",
    "dashTitle": "设备状态监控"
  },
  "layout": [
    {
      "type": "header",
      "i": "wdchart0",
      "x": 0,
      "y": 0,
      "w": 100,
      "h": 10,
      "html": "<div class='header'>{{globalSetting?.title}}</div>",
      "css": ".header { text-align: center; font-size: 24px; }",
      "script": "const dynamicComponent = defineComponent({ name: 'Header', setup() { return {}; } }); return { dynamicComponent };"
    },
    {
      "type": "component",
      "i": "wdchart1",
      "x": 0,
      "y": 10,
      "w": 50,
      "h": 30,
      "html": "<div class='component'>{{msg}}</div>",
      "css": ".component { color: white; }",
      "script": "const dynamicComponent = defineComponent({ props: ['rootData'], setup(props) { const msg = ref('Hello'); return { msg }; } }); const getConfigOption = (configOption, rootData) => { return { configOption: { hideBorder: false }, barOption: { title: { text: '组件标题' } } }; }; return { dynamicComponent, getConfigOption };"
    }
  ],
  "rootData": {
    "deviceinfo": {},
    "alarms": [],
    "calc": {}
  },
  "rootFormat": "const rootFormat = async ({ rootData, settings, wss }) => { return {}; }; return { rootFormat };",
  "settingShow": true
}

重要说明

configOption 的生成机制

不是静态存储：configOption 字段不会直接存储在 JSON 配置中
动态生成：通过 script 中的 getConfigOption 函数动态生成
运行时计算：在组件渲染时，框架会调用 getConfigOption 函数来获取配置
参数传递：函数接收 configOption 和 rootData 两个参数

默认配置

默认的看板 JSON 配置中，组件通常只包含：

type、i、x、y、w、h 等基础布局信息
html、css、script 等组件内容
不包含 configOption 字段

通过以上配置参数，您可以完全自定义 WoodyDashboard 的外观和行为，创建符合需求的大屏看板。

配置参数说明 ​

全局配置 (globalSetting) ​

基础配置 ​

标题配置 ​

示例配置 ​

边框配置 (borderBar) ​

配置结构 ​

边框组件示例 ​

组件配置 (layout) ​

基础组件配置 ​

组件内容配置 ​

组件配置示例 ​

数据配置 (rootData & rootFormat) ​

rootData ​

rootFormat ​

配置选项详解 ​

getConfigOption 函数 ​

configOption 参数 ​

barOption 参数 ​

chartOption 参数 ​

配置最佳实践 ​

1. 命名规范 ​

2. 性能优化 ​

3. 样式管理 ​

4. 数据安全 ​

配置示例 ​

完整的看板配置 ​

重要说明 ​

configOption 的生成机制 ​

默认配置 ​

配置参数说明

全局配置 (globalSetting)

基础配置

标题配置

示例配置

边框配置 (borderBar)

配置结构

边框组件示例

组件配置 (layout)

基础组件配置

组件内容配置

组件配置示例

数据配置 (rootData & rootFormat)

rootData

rootFormat

配置选项详解

getConfigOption 函数

configOption 参数

barOption 参数

chartOption 参数

配置最佳实践

1. 命名规范

2. 性能优化

3. 样式管理

4. 数据安全

配置示例

完整的看板配置

重要说明

configOption 的生成机制

默认配置