# 创建一个组件

# 1、新建项目

进入 应用创建 -> 项目管理 -> 点击新增

  • 项目名称
  • 所属行业
  • 描述 填写以上内容,然后点击保存

# 2、新建组件

进入 应用创建 -> 组件开发 -> 点击添加组件

  • 组件名称
  • 组件类别(项目组件还是基础组件,基础组件所有项目都能引用)
  • 所属项目
  • 组件分类(组件大类,是2D或者3D,以及对应哪种类型,如2D--柱状图)
  • 标签(组件标签,可以根据组件特点自定义标签,要做到简洁明了)
  • 描述

填写以上内容,然后点击保存。

# 同学,我们这时候已经新建完一张定制化组件了,赶紧进行来开发定制化组件吧。

# 组件目录

├── build
│   ├── webpack.config.dev.js
│   └── webpack.config.production.js
├── package.json
├── options.json
├── .gitignore
├── env.js
└── src
    ├── Component.js
    ├── main.js
    ├── setting.js
    └── settings
        ├── data.js
        └── options.js

# 文件详解

# build/webpack.config.dev.js

组件开发阶段保存对组件进行 webpack 编译打包扩展配置文件,具体请参考更改组件编译配置

# build/webpack.config.production.js

组件导出阶段对组件进行 webpack 编译打包扩展配置文件,具体请参考更改组件编译配置

# package.json

组件信息和依赖,具体请参考添加组件依赖

# options.json

组件开发底部的组件预览大屏的预设,具体请参考增加组件开发大屏预设

# .gitignore

git上传省略设置,具体参考git官方文档 (opens new window)

# env.js

大屏配置,当前组件开发大屏环境配置

# src/main.js

组件注册入口,组件开发会自动产生此文件,如务必要不需要更改。具体请参考注册组件

# src/Component.js

组件代码文件,仅支持原生 Javascript 进行开发,请参考开发组件。如使用 react 开发,请参考React 开发组件

# src/setting.js

组件设置区域注册入口,组件开发会自动产生此文件,如组件有需要开发自定义配置和数据绑定,请打开此文件内注释掉的注册内容

# src/setting/options

组件设置区域组件,需使用 react 开发,具体请参考增加组件配置

# src/setting/data

组件设置数据区域组件,需使用 react 开发,具体请参考增加组件数据配置

# 注册组件

拖拽组件到大屏,大屏会根据组件在大屏上的注册信息,渲染指定的组件。那么,开发组件第一步,我们就应该先注册组件,把组件的信息挂载到大屏。

新建组件会直接创建 src/main.js 文件,内置为创建组件的唯一标识字段为注册组件的标识。默认情况下不需要更改,我们只需要了解,这个文件是在大屏上注册当前组件,能够让大屏正常的渲染组件。

import { registerComponent } from "data-vi/components";

import Component from "./Component";

registerComponent("Test", Component);

这样,我们就往大屏上注册了一个 Test 组件,继续往下来编辑 Component 来开发组件吧。

# 组件开发

开发组件需要依赖于 data-vi/Component 基类,基类中内置了很多 API、生命周期、渲染机制等,详细请参考组件基础,以下是一个 js 原生开发基本代码:

import Component from "data-vi/Component";

export default class Test extends Component {
  // 默认配置
  static defaultConfig = {};
  // 默认选项
  static defaultOptions = {};
  // 系统事件
  static events = {};
  // 是否加载css文件 如当前组件没有样式文件,设置为false
  static enableLoadCssFile = false;

  // 获取默认选项
  getDefaultOptions() {
    return this.constructor.defaultOptions;
  }

  // 获取默认事件
  getDefaultData() {
    return [];
  }

  /**
   * 钩子方法 组件mount挂载时调用
   */
  _mount() {
    const container = this.getContainer();
    container.html("Hello FlyFish !");
    container.css({ color: "#FFF" });
  }
}

# 开发组件使用 React

React 开发组件需要依赖于 data-vi/ReactComponent 基类,data-vi/ReactComponent 基类是由 data-vi/Component 基类再扩展出来的,内置 data-vi/Component 基类所有 API 和生命周期,底层原理为在 data-vi/Component 的_mount 生命周期通过 API getReactComponent 获取到 React 组件使用 ReactDom 将 React 组件挂载在组件 DOM 上,如有特殊需求,也可以自行挂载,或者其他框架也可挂载。

以下是一个 React 开发基本代码:

import ReactComponent from "data-vi/ReactComponent";
import React from "react";

export default class Test extends ReactComponent {
  // 默认配置
  static defaultConfig = {};
  // 默认选项
  static defaultOptions = {};
  // 系统事件
  static events = {};
  // 是否加载css文件 如当前组件没有样式文件,设置为false
  static enableLoadCssFile = false;

  // 获取默认选项
  getDefaultOptions() {
    return this.constructor.defaultOptions;
  }

  // 获取默认事件
  getDefaultData() {
    return [];
  }

  getReactComponent() {
    return ReactTest;
  }
}

class ReactTest extends React.Component {
  render() {
    return "Hello flyFish!";
  }
}

对于 Component 下挂载的 React 组件,支持使用 React Hooks 进行开发,React 组件内组件,参考 React 相关文档开发,理论上没有限制。

组件 API 和组件生命周期,请参考组件基础

# 增加组件自定义设置

公共组件的可配置要求比较高、配置项也很多,那么对于定制化组件,再有需要更改配置使之呈现不同效果的组件需求时,也可以抽离至组件 options 中,使之能够进行动态配置。

# 注册组件设置面板

新建组件会直接创建 src/setting.js 文件,内置为创建组件的唯一标识字段为注册组件设置面板的标识。默认情况下只需要将注释的内容打开,这个文件是在大屏上注册当前组件的设置面板,能够让大屏正常的渲染组件设置面板。

注册挂载的面板组件没有路径限制,新建组件会直接创建 src/settings/setting.js 文件,可直接使用,也可另外创建。

import { registerComponentOptionsSetting } from "datavi-editor/adapter";

import OptionsSetting from "./settings/options";

registerComponentOptionsSetting("Test", OptionsSetting);

# 开发组件设置面板

设置面板组件使用 React + antd 开发,依赖于 datavi-editor/templates 下 ComponentOptionsSetting,ComponentOptionsSetting 基类主要内部提供挂载等操作,提供 getTabs 供自定义扩展设置面板使用。datavi-editor/templates 支持的组件请参考antd.3x (opens new window)

以下为设置面板代码示例:

import React from "react";
import { ComponentOptionsSetting, Input } from "datavi-editor/templates";

export default class OptionsSetting extends ComponentOptionsSetting {
  getTabs() {
    return {
      title: {
        label: "配置",
        content: () => this.renderSetting()
      }
    };
  }
  renderSetting() {
    let { options } = this.props;
    return (
      <Form>
        <FormItem label="页大小">
          <Input
            value={options.title}
            onChange={val => this.updateOptions({ title: e.target.value })}
          />
        </FormItem>
      </Form>
    );
  }
}

# 开发组件绑定数据源

组件默认不支持数据源绑定,需要组件注册数据源面板。

# 注册组件数据源面板

新建组件会直接创建 src/setting.js 文件,内置为创建组件的唯一标识字段为注册组件设置数据源面板的标识。默认情况下只需要将注释的内容打开,这个文件是在大屏上注册当前组件的数据源设置面板,能够让大屏正常的渲染组件数据源设置面板。

注册挂载的面板组件没有路径限制,新建组件会直接创建 src/settings/data.js 文件,可直接使用,也可另外创建。

import { registerComponentDataSetting } from "datavi-editor/adapter";

import DataSetting from "./settings/data";

registerComponentDataSetting("Test", DataSetting);

# 开发组件数据源面板

数据源面板组件使用 React + antd 开发,依赖于 datavi-editor/templates 下 ComponentDataSetting,ComponentDataSetting 基类主要内部提供挂载等操作。datavi-editor/templates 支持的组件请参考antd.3x (opens new window)

以下为设置面板代码示例:

import React from "react";
import { ComponentDataSetting } from "datavi-editor/templates";
export default class DataSetting extends ComponentDataSetting {
  render() {
    const { fields, config } = this.props;
    return <div></div>;
  }
}

# 组件使用大屏全局变量

对于组件中有如下两种访问方式访问:

  • 全局变量访问方式
window.DATAVI_ENV.globalOptions;
  • 加载依赖包访问
import config from "data-vi/config";
config.globalOptions;

# 组件使用大屏请求前缀

组件中有如下访问方式访问:

  • 加载依赖包访问
import config from "data-vi/config";
config.componentApiDomain;

# 组件发送 http 请求

默认请使用组件数据源进行数据交互,不建议直接使用 http 请求获取数据,符合以下情况建议使用:

  • 组件需要发送多个 http 请求,且接口不可合并。
  • 需要先进行鉴权操作,才能发送 http 请求的,且鉴权操作不能放在后端进行的。
  • 需要串行化发送 http 请求,接口相互依赖,且依赖部分不能放在后端进行的。

以下为发送 http 请求示例:

import { getHttpData } from "data-vi/api";
import { componentApiDomain } from "data-vi/config";

getHttpData(componentApiDomain + url, "POST", {})
  .done(request => {})
  .fail((request, xhr, msg) => {});

# 添加组件依赖

修改 package.json 文件,添加依赖到指定位置,保存文件后,点击右上角安装依赖按钮,即可下载相关依赖。

package.json 文件示例:

{
  "name": "Test",
  "version": "v1.0.0",
  "description": "",
  "dependencies": {},
  "devDependencies": {},
  "scripts": {
    "build-dev": "NODE_ENV=dev ../../node_modules/.bin/webpack --config ./build/webpack.config.dev.js",
    "build-production": "NODE_ENV=production ../../node_modules/.bin/webpack --config ./build/webpack.config.production.js"
  }
}

# 增加组件开发大屏预设

便捷组件开发中,组件频繁修改编译刷新预览区域,预览区域更改的设置不能被保留。修改 options.json 预设设置即可保留设置。大屏预设具体内容,请参考大屏 JSON 解析

# 预设基础内容

{
  "options": {
    "width": 1920,
    "height": 1080,
    "name": "本地测试大屏",
    "scaleMode": "origin",
    "backgroundColor": "#162C51",
    "backgroundImage": "",
    "css": ""
  },
  "events": [],
  "functions": [],
  "dataSources": [],
  "components": []
}

# 预设增加当前开发中组件

只能增加当前开发的组件,其他组件并未注册在此预览区域,组件注册请参考注册组件

往 options.json 内 components 增加如下对象:

  • type 当前组件唯一标识
  • id 参考格式可随意定制
  • config 组件基础设置,具体配置项可参考组件基础
  • options 组件的自定义设置
  • dataSource 组件数据源 具体可参考组件绑定数据源
{
  "type": "Test",
  "id": "UBKO-08U1-C9L4-6OJF-3OMB-3OFN",
  "config": {
    "left": 534,
    "top": 242,
    "width": 883,
    "height": 420,
    "index": 0
  },
  "options": {
    "defaultActiveName": "基础监控"
  },
  "dataSource": {
    "type": "json",
    "options": {
      "json": "{}"
    }
  }
}

# 预设增加全局数据集

往 options.json 内 dataSources 增加如下对象:

  • name 数据集唯一标识
  • type 对应数据集类型下拉框三个值(json、model、http)
  • options 数据集自定义配置,可配置项请参考数据集基本构成
{
  "name": "",
  "type": "json",
  "options": {}
}

# 更改组件编译配置

适用于需要更改 webpack 打包编译配置。组件编译已内置完善的 webpack 配置,如有特殊需求,需要追加 webpack 配置,可根据实际需求修改 build/webpack.config.dev.js 和 build/webpack.config.production.js。

组件编译分为 build-dev 和 build-production。build-dev 为组件开发中保存之后组件进行编译的命令,组件开发中实时预览展示组件使用,默认含有 sourceMap。build-production 为组件导出时进行组件编译打包的命令,默认不含有 sourceMap。

部分追加配置的情况下,更改 build/webpack.config.dev.js 和 build/webpack.config.production.js 文件,即可满足需求。

build/webpack.config.dev.js 示例如下:

const baseConf = require("../../../webpack.config.base");
const path = require("path");
const _ = require("lodash");

module.exports = _.defaultsDeep(
  {
    // 用于生成源代码的mapping
    devtool: "#source-map",
    mode: "development",
    entry: {
      "Test/main": "./src/main.js",
      "Test/setting": "./src/setting.js"
    },
    output: {
      // 编译的目录
      path: path.resolve(__dirname, "../") + "/components/"
    }
  },
  baseConf
);

build/webpack.config.production.js 示例如下:

const baseConf = require("../../../webpack.config.base");
const path = require("path");
const _ = require("lodash");
const webpack = require("webpack");
const UglifyJsPlugin = require("uglifyjs-webpack-plugin");

module.exports = _.defaultsDeep(
  {
    mode: "production",
    entry: {
      "Test/main": "./src/main.js",
      "Test/setting": "./src/setting.js"
    },
    output: {
      // 编译的目录
      path: path.resolve(__dirname, "../") + "/release/"
    },
    optimization: {
      minimizer: [
        // 优化js
        new UglifyJsPlugin({
          cache: true,
          parallel: true,
          sourceMap: false,
          uglifyOptions: {
            output: {
              // 最紧凑的输出
              beautify: false,
              // 删除所有的注释
              comments: false
            },
            compress: {
              // 在UglifyJs删除没有用到的代码时不输出警告
              warnings: false,

              drop_console: false,
              // 内嵌定义了但是只用到一次的变量
              collapse_vars: true,
              // 提取出出现多次但是没有定义成变量去引用的静态值
              reduce_vars: true
            }
          }
        })
      ]
    },
    plugins: []
  },
  baseConf
);

全部定制配置的情况下,重写 build/webpack.config.dev.js 和 build/webpack.config.production.js 文件。需要遵循以下规范即可全部定制 wenpack 打包编译配置。

以下配置必须保留,否则组件不能被大屏渲染:

{
  externals: {
        react: 'React',
        moment: 'moment',
        'react-dom': 'ReactDom',
        'prop-types': 'PropTypes',
        jquery: 'jQuery',
        'jquery-ui': 'jQuery',
        'data-vi': 'dv',
        'data-vi/Component': 'dv.adapter.Component',
        'data-vi/ReactComponent': 'dv.adapter.ReactComponent',
        'data-vi/Event': 'dv.adapter.Event',
        'data-vi/Model': 'dv.adapter.Model',
        'data-vi/Screen': 'dv.adapter.Screen',
        'data-vi/config': 'dv.adapter.config',
        'data-vi/helpers': 'dv.adapter._',
        'data-vi/storage': 'dv.adapter',
        'data-vi/locale': 'dv.adapter',
        'data-vi/modal': 'dv.adapter',
        'data-vi/components': 'dv.adapter',
        'data-vi/models': 'dv.adapter',
        'data-vi/resources': 'dv.adapter',
        'data-vi/requirejs': 'dv.adapter',
        'datavi-editor/adapter': 'dvEditorAdapter',
        'datavi-editor/templates': 'dvEditorAdapter.templates',
        'data-vi/api': 'dv.adapter',
    },
}

development 情况下,需要输出的目录为 path.resolve(__dirname, '../') + '/components/'

production 情况下,需要输出的目录为 path.resolve(__dirname, '../') + '/release/'

上次更新: 2022/5/8 16:29:46