ECharts组件

文档基于ECharts组件v1.0.1版本（当前版本引用v5.2.1版本ECharts库）

组件说明

ECharts组件位于组件-->第三方组件栏。

ECharts是应用最为广泛的开源图表库之一，EasyV为提高产品开放度并拓展官方图表组件的能力对ECharts图表库进行了集成。

下文中“ECharts组件”简称“EC组件”，以区别“ECharts的组件”的概念。

EC组件本身是一个标准的EasyV组件，是一个可以在EasyV平台上运行ECharts图表库的容器。可以把任意合法的ECharts代码写入到组件配置项中，同时沿用EasyV官方组件配置化接入数据和配置交互。

（目前在EC组件还不支持接入百度地图sdk，所以和百度地图相关的组件都是暂时无法使用的，后续将会推出一套支持的方案）

效果演示

如下案例演示EasyV添加ECharts组件及添加ECharts官网组件样式。

此处为语雀视频卡片，点击链接查看：echarts组件.mov

一、样式

初始化

代码输入框里本身是一个JavaScript代码环境，输入框里输入的代码也是最终作为一个函数来调用，函数必须返回一个ECharts实例。一般是调用echarts.init()方法来创建实例，此处可写入初始化相关的操作。这个函数在「配置项」的函数之前执行。

函数的形式参数如下：

参数名	类型	说明
dom	HTMLDivElement	echarts的dom容器。用于echarts.init()方法的第一个参数的传入。
echarts	object	全局 echarts 对象。可用来注册地图数据、主题，以及echarts.graphic相关的辅助方法。
DATA	any[ ]	EasyV组件接入的数据。可在代码中把数据处理成能接入echarts的数据。
$	any	jQuery的全局对象，主要是为了兼容ECharts官方的demo而引入的。可使用jQuery提供的各种方法。
RES	{ [id:string] : string }	资源引用对象。（详见下文）

这个函数本身是一个异步函数，可返回一个Promise来实现异步操作，即可支持异步创建ECharts实例。例如：

//异步创建ECharts实例
return new Promise((resolve)=>{
  //通过接口请求主题文件，需预先在资源配置中上传ID为purple-passion的json文件
  $.getJSON(RES["purple-passion"], function(themeJSON) {
    //请求到json之后注册主题
    echarts.registerTheme('purple-passion', themeJSON);
    //返回ECharts实例并使用新主题，设置渲染模式为svg
    resolve(echarts.init(dom, 'purple-passion', { renderer: 'svg' }));
  });
});

配置项

*组件默认补充了该配置项书写说明的注释，注释较长，可进入全屏模式查看编辑

代码输入框里本身是一个JavaScript代码环境，并且输入框中的代码最终会当做函数体来调用函数，并且该函数有如下形式参数：

参数名	类型	说明
myChart	echartsInstance	当前ECharts实例的引用。API参见echarts官方文档的echartsInstance。
DATA	any[ ]	EasyV组件接入的数据。可在代码中把数据处理成能接入echarts的数据。
echarts	object	全局 echarts 对象。可用来注册地图数据、主题，以及echarts.graphic相关的辅助方法。
app	React.Component	当前EasyV组件实例的引用。EC组件本身是一个基于React开发的EasyV组件，该React组件的this对象赋值给了app变量。所以通过app变量可以访问到props下的所有对象。
option	object \| undefined	echarts配置项要赋值给option变量，函数执行后option变量的值会作为echartsInstance.setOption的参数来设置echarts组件的配置项。
RES	{ [id:string] : string }	资源引用对象。（详见下文）
relative	RelativeFunction（见下文）	包装过的用于发送EasyV组件回调的函数。（详见下文）
$	any	jQuery的全局对象，主要是为了兼容ECharts官方的demo而引入的。可使用jQuery提供的各种方法。
ecStat	any	主要是为了兼容ECharts官方的demo而引入的echarts-stat库的对象。
ROOT_PATH	string	主要是为了兼容ECharts官方的demo而引入一个静态字符串。

代码必须把一个合法的echarts的配置项对象赋值给option，以使得组件把配置项传入echarts。

app.props

通过app.props可以访问到EasyV组件的props，这样就能访问到开发中必要的数据，如下：

app.props.data EasyV组件的数据，可以处理成echarts所需的数据格式
app.props.configuration EasyV组件配置项对象。对于EC组件来说，configuration主要是可以在回调开发时用来获取回调的配置
app.props.emit 发送自定义事件的函数
app.props.onRelative 发送EasyV回调的函数

资源

ECharts图表有时候依赖外部的图像、json文件等资源。一般来说可以在「初始化」、「配置项」中的代码输入框里通过调用接口的形式获取资源，引用的资源接口必须与EasyV平台网络环境相通且支持跨域。EC组件也提供了在EasyV平台上传资源在代码中引用的方式。

ID

输入资源的唯一标识，该标识可在上文中提到的RES资源对象上引用（如RES.img）的形式获取到资源的url。

文件

可以上传任意格式的文件资源，大小限制为150MB。

二、数据

EasyV组件的各种数据源经过过滤器和字段映射之后的数据，都通过DATA变量在「配置项」的代码输入框里使用。

如下示例代码所示为把EasyV组件xys字段格式转换为Echarts数据格式。

function xys2Dataset(data) {
    const xMap = {};
    data.forEach(e => {
        if (!xMap[e.x]) {
            xMap[e.x] = {};
        }
        xMap[e.x][e.s] = e.y;
    });

    const sMap = {};
    data.forEach(e => {
        sMap[e.s] = true;
    });

    const sList = Object.keys(sMap);
    const source = [
        ["product", ...sList]
    ];

    for (const x in xMap) {
        const s2y = xMap[x], tmp = [x];
        sList.forEach(s => {
            tmp.push(s2y[s]);
        });
        source.push(tmp);
    }
    return [{ source }];
}

在Echarts配置项中只需要调用对应方法即可：

示例代码：

  dataset:xys2Dataset(DATA)

注意：在数据面板中接入数据时，请先确认所选ECharts图表所需的数据格式。

以上示例只是xys字段和Echarts组件数据接入的方法，其他字段格式数据需要您根据情况进行代码开发。

三、交互

EasyV下实现组件之间交互和联动的方式主要有回调和自定义事件，这两个都需要有一个触发时机，echarts提供了事件监听机制，可以在各种事件触发的回调函数中编写EasyV回调和自定义事件的代码。

回调开发

可在“配置项”的代码中调用relative函数发送回调，上文中relative()函数是RelativeFunction的类型，RelativeFunction的类型声明如下：

type RelativeFunction = ((
  out:{ [target:string]:any },
  config:{ type:string, target:string }
) => void) => void;

以下是一个示例：

myChart.on('click', 'series.line', function(params) {
  relative((out,config) => {
    if(config.type == "点击折线"){
     out[config.target] = params.data; 
    }
  });
});

示例中写了一个类型为“点击折线”的回调。通过ECharts提供的事件监听方法，在回调函数中调用relative()，并且判断类型来把要发送的数据写入out对象中。

relative()本身基于EasyV组件的props.onRelative()函数封装，可直接基于该函数开发回调（参见EasyV组件回调开发文档）。可用app.props.onRelative调用EasyV提供的函数直接发回调。

自定义事件

首先要注册事件类型，在交互面板的自定义事件类型下添加一个事件类型，包括两个配置项：引用名和事件名。

引用名是将会在自定义事件的事件类型的下拉列表中出现的名字，一般是便于用户理解的中文名。

事件名是该事件在代码中使用的名字，用于emit的第一个参数。

通过在echarts的事件触发的回调函数中调用app.props.emit发送自定义事件。如下所示：

myChart.on("click","series.bar",(e)=>{
  app.props.emit("click",{
    x:e.name,
    y:e.data
  });
});

上面的例子中，点击柱状系列之后发送了一个事件名为"click"的自定义事件，数据中给了一个xy结构的对象，以在自定义事件的条件中使用。

四：案例下载

📎ECharts案例_541279.screen.zip

*下载zip格式后需解压为screen格式，在【我的应用】中可进行导入。