ECharts组件开发

使用echarts-easyv命令行工具快速把echarts转换成easyv组件，面向具备easyv组件开发和echarts开发技术的人员，目前支持React的开发方式。

工程目录结构

一个较为完整的项目结构如下：

echarts-components

│

├── package.json

└── src

       ├── build

       │     ├── fieldLanguage.js    // 全局的字段语言库

       │     ├── fieldConfig.js    // 全局的字段配置

│

│

├── common

│     └── EChartsComponent.jsx    // Easyv组件的基类

│

└── components

       │

       └── echartsBasicBar    // 单个EasyV组件的目录

              │

       ├── index.jsx    // EasyV组件入口文件

              ├── options.js    // Echarts组件的option代码

              ├── build

              │     ├── fieldLanguage.js    // 组件自定义的字段语言库

              │     └── fieldConfig.js    // 组件自定义的字段配置

              │

              └── config

                     │

                     ├── main.json    // 生成的EasyV配置项

                     └── main.data.json   // 生成的EasyV组件的默认数据

快速生成EasyV组件的流程

安装全局库

在全局安装npm库echarts-easyv： npm i echarts-easyv -g

如下所示：

C:\Users\Xie\Documents\dtstack\echarts-group> npm i echarts-easyv -g
C:\Users\Xie\AppData\Roaming\npm\echarts-easyv -> C:\Users\Xie\AppData\Roaming\npm\node_modules\echarts-easyv\index.js 
+ echarts-easyv@1.0.0
updated 1 package in 0.994s

创建新项目

使用创建EasyV组件的命令行创建一个空的项目：easyv create <project name>

初始化

在空项目的根目录执行初始化目录结构：echarts-easyv init

一个空项目只能初始化一次，初始化会在package.json中插入依赖库，清空src/components下的原有文件。

C:\Users\Xie\Documents\dtstack\echarts-group> echarts-easyv init
初始化成功

添加新组件

在项目根目录执行命令添加新的组件：echarts-easyv add <组件模块名称> <组件中文名称>

C:\Users\Xie\Documents\dtstack\echarts-group> echarts-easyv add basicLine 基本折线图
添加成功

复制Option

从ECharts官网的Demo页面选择一个图表，从示例编辑标签页下复制出该图表使用的option。

复制到项目结构中的options.js文件中。

注意：需要将option的对象默认导出，默认使用es6的导出模式。

如下所示：

export default {
    xAxis: {
        type: 'category',
        data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
    },
    yAxis: {
        type: 'value'
    },
    series: [{
        data: [150, 230, 224, 218, 135, 147, 260],
        type: 'line'
    }]
};

编译时会把代码中的export default替换成return，然后将option.js中的代码文本作为函数调用，获取调用结果用于实际转换的option。实现的伪代码如下：

let optionCodeStr; //读取option.js文件后获取的字符串
option = Function(optionCodeStr.replace("export default", "return"))();
//option用于转换成main.json和main.data.json

执行构建命令

在项目根目录执行命令：echarts-easyv build <组件模块名称>

componentName为要编译的组件的组件名。是可选参数，若为空，则编译components目录下的所有组件。

C:\Users\Xie\Documents\dtstack\echarts-group> echarts-easyv build basicLine
start build: basicLine
build success: basicLine

编译时将option.js中的option对象编译转换，输出配置项到main.json，输出组件默认数据到main.data.json。

至此，简单的ECharts组件的转换基本完成（还需安装npm库），可作为EasyV组件在本地运行组件或发布。

字段转换设置

字段转换设置包括字段配置和语言库两个配置文件，也分为全局设置和自定义设置。

全局设置

项目中build目录下有fieldLanguage.js和fieldConfig.js，是所有组件转换时通用的字段转换设置。

自定义设置

单个组件的build目录下也有fieldLanguage.js和fieldConfig.js，是当前组件转换时专属的字段转换设置。build目录和两个文件初始时不存在，需要的时候，按照目录结构新建对应的文件即可。在编译转换时，自定义设置将合并（已存在的覆盖，不存在的新增）到全局设置中。

字段配置

字段配置控制某个字段转换成main.json时的转换方式或额外的配置信息，也可用于指定字段转换后的main.json中EasyV配置项字段的固定值。

字段配置的文件fieldConfig.js中的代码文本，在编译转换时会作为一个函数来调用，并取返回值作为最终的配置对象，同上述的option.js的作用方式。

例如，组件的option.js如下所示：（代码A）

// 代码A
// option.js
export default {
  xAxis: {
    type: "time",
    axisLabel: {
      color: "#fff"
    }
};

为了指定对xAxis.type的字段配置，可在fieldConfig.js写入如下代码：（代码B）

// 代码B
// fieldConfig.js
return {
  __global__: {
		color: {
			type: "multicolor"
    }
  },
  xAxis:{
    type: {
        _hidden: true, //隐藏该字段
        _options: ['log', 'time'] //下拉列表的所有下拉选项
    }
  }
};

还需配置语言库fieldLanguage.js：

// 代码C
// fieldLanguage.js
export default {
  xAxis:"X轴",
  type:"类型",
  axisLabel:"轴标签",
  color:"颜色"
};

以上文件将生成如下的main.json：

// main.json
{
  // ...
  //省略了config字段相关内容
  
	"configuration": [
    {
      "name":"xAxis",
      "dispalyName":"X轴",
      "value":[
        // 以下为实际不会生成的内容，因为xAxis.type配置了隐藏
        //{
          //"name":"type",
          //"dispalyName":"类型",
          //"value":"time",
          //"type":"select",
          //"config":{
            //"options":[
              //{
                //"name":"日志",
                //"value":"log"
              //},
              //{
                //"name":"时间",
                //"value":"time"
              //}
            //]
          //}
        //},
        {
          "name":"axisLabel",
          "dispalyName":"轴标签",
          "value":[
            {
              "name":"color",
              "dispalyName":"颜色",
              "value":"#fff",
              // type字段的值默认解析成"color"
              // 由于在option.js中指定了全局的color字段的type
              // 所以最终用"multicolor"覆盖"color"
              "type":"multicolor" 
            }
          ]
        }
      ]
    }
	]
}

在fieldConfig.js中写入与option.js一样的层级结构，即可指定该字段的字段配置。

编译转换时，fieldConfig.js中同层级结构的字段下的所有字段都将合并（已存在的覆盖，不存在的新增）到main.json对应层级结构的EasyV配置项下。

保留字段

fieldConfig.js的层级结构中，非保留字段的字段名都被认为是option.js中对应层级结构的字段的字段配置，而保留字段有特殊的意义，不可用于指定字段。

保留字段分类两类：

一种是以下划线开头的，该类型的字段作用于自身的上一层结构的字段名。在代码B中，_hidden作用于xAxis.type，表示在main.json中隐藏该字段。

另一个种是“__name__”结构（名字左右两边都是双下划线）的字段。在代码B中，__global__是特殊意义的字段名，表示全局字段。

目前支持的保留字段如下：

字段语言库

如上文中的代码C所示，这种表示英文到中文的映射结构，即为字段名转换时用到的语言库，编译转换时将转换的EasyV配置项的displayName字段替换成该中文。

index.jsx文件

生成的EasyV组件必须继承EChartsComponent抽象类，并从外部引入option配置项的JS对象，在构造函数中调用父类方法setOption设置实例类的option。

import EChartsComponent from "../../common/EChartsComponent";
import option from "./options";

export default class EChartsBasicBar extends EChartsComponent {
    constructor(props) {
        super(props);
        this.setOption(option);
    }
}

组件定制化的配置

完善配置项

在option.js中包含的配置才会转化到main.json中，才能在配置面板上显示以便用户使用。官网实例的option一般较为简单，只包含能实现该类组件的基本字段。一般需要开发者根据组件需求，在option.js补全所需配置。

配置下拉菜单选项

某些配置项的值是字符串，且只能取自某些字符串的集合。如borderType字段只能取自['solid', 'dashed', 'dotted']三者中的一个。为了更佳的用户体验，这种字段一般在配置面板上显示成下拉菜单的样式。所以需要查阅官方文档，在字段配置中列举该字段的取值集合。全局字段配置中默认配置了一些常用字段的取值集合，除此之处的，需要开发者自行配置。

完善语言配置

全局语言配置中默认配置常用字段的中文名，除此之外的，需要开发者自行配置。或者某些字段翻译不准确的，可配置在组件的字段配置中，以覆盖全局配置。

无法转换的字段类型

option.js中写入的字段，如果是复合类型、函数类型、对象类型，则无法成功转换成easyv配置项，或者转换不准确。

echarts中有些字段可以取多种类型的值，全局字段配置中配置了强制将某些字段转换为某一种类型，如果该类型不符合组件需求，则可在组件的配置中覆盖全局配置。若没有在字段配置中强制配置类型，则取该字段option.js中的值的类型作为easyv配置项的类型。

图表类型

可支持的图表类型

是一些有轴（包含xAxis, yAxis, singleAxis, radiusAxis, angleAxis）的一般的基本图表，包括：折线图、柱状图、饼图、K线图、雷达图、热力图、漏斗图。

不支持的图标类型

以下图表可能会完全不支持或者兼容性不佳，包括但不限于：散点图、地理坐标/地图、盒须图、关系图、路径图、树图、矩形树图、旭日图、平行坐标系、桑基图、仪表盘、象形柱图、主题河流图、日历坐标图、自定义系列、（各种3d组件）。

错误码

如遇其他使用问题，可扫描下方二维码，获取更多产品支持~