开源库Magicodes.ECharts使用教程

目录

1 概要    2

博客使用Word发博,发布后,排版会出现很多问题,一一修正工作量极大,敬请谅解。可加群获取原始文档。

  1. 概要

Magicodes.ECharts是心莱团队基于百度EChart封装的开源的.NET类库,以便让用户更快更便捷的上手开发EChart图表。本篇主要讲解Magicodes.ECharts的相关使用。

注意:EChart图表插件是由百度提供的一套前端图表库,可以流畅运行在PC端和移动设备上。Echarts具备完善的兼容性和丰富的图表类型,目前已经存在2.0和3.0两个版本,Magicodes.ECharts针对的是最新版本的封装。ECharts的官网为:http://echarts.baidu.com/

官方博客:http://www.cnblogs.com/codelove/

相关开源库地址:https://github.com/xin-lai

在开始之前,您需要了解以下内容:

  • Magicodes.ECharts是基于百度EChart封装的开源的.NET类库,封装的目的便于使用强类型语言约束后台代码,以便于更好维护和重构代码,并且封装自身业务
  • Magicodes.EChartsJS是基于knockoutJs封装的组件,结合Magicodes.ECharts能够很方便的利用Ajax加载Echart图表
  • 目前Magicodes.ECharts已经支持大部分图表,但是尚不能支持所有图表和所有情形
  • 本着按需设计的原则,在遇到不支持的情形,希望您能够自行扩展并贡献自己的代码。众人拾材火焰高,Magicodes.ECharts在不断地实践中会更加完善的
  • 在设计上,我们不会过多设计,但是后续版本可能会不断地进行重构
  1. Magicodes.ECharts工作原理
  1. 架构说明

Magicodes.ECharts目前主要由以下部分组成:

  1. Axis

直角坐标系 grid 中的轴的相关配置封装,比如x轴、y轴等。

  1. CommonDefinitions

通用定义,目前定义了以下内容:

  • Align(水平对齐)
  • Label(标签)
  • Orients(图例列表的布局朝向)
  • Symbols(标记的图形)
  • TextAlign(标题文本水平对齐)
  • TextStyles(文本样式)
  • VerticalAlign(垂直对齐)
  1. Components

组件定义。目前定义了以下内容:

  • DataZoom(区域缩放)
    • DataZoomInside(内置型数据区域缩放组件)
    • DataZoomSlider(滑动条型数据区域缩放组件)
  • Grid(直角坐标系内绘图网格)
  • Legend(图例组件)
  • TimeLine(timeline 组件)
  • Title(标题)
  • ToolBox(工具箱)
  • ToolTip(提示框组件)
  1. JsonConverter

定义了一些自定义实现的JSON转换器,依赖自JSON.NET。

  • ValueConverter

ValueConverter用于相关值JSON转换,需要实现IValue<T>接口。如下面例子:

/// <summary>

/// 小数数组

/// </summary>

[JsonConverter(typeof(ValueConverter<double[]>))]

public class ArrayNumberValue : IValue<double[]>, INumberOrArrayNumberValue

{

public double[] Value { get; set; }

}

/// <summary>

/// 数值

/// </summary>

[JsonConverter(typeof(ValueConverter<double>))]

public class NumberValue : ILeftValue, ITopValue, IRightValue, IBottomValue, IValue<double>, INumberOrArrayNumberValue, INumberOrStringValue

{

public NumberValue(double? value = null)

{

if (value.HasValue)

{

Value = value.Value;

}

}

public double Value { get; set; }

}

接下来,在DataZoom组件上用到了我们的定义,如下所示:

public abstract class DataZoom

{

….省略其他代码

/// <summary>

/// 设置 dataZoom-inside 组件控制的 y轴(即yAxis,是直角坐标系中的概念,参见 grid)。

/// 不指定时,当 dataZoom-inside.orient 为 'vertical'时,默认控制和 dataZoom 平行的第一个 yAxis。但是不建议使用默认值,建议显式指定。

/// 如果是 number 表示控制一个轴,如果是 Array 表示控制多个轴。

/// </summary>

public INumberOrArrayNumberValue XAxisIndex { get; set; }

}

在使用时,我们可以这样赋值:

new DataZoomInside()

{

Start=30,

End=70,

XAxisIndex=new ArrayNumberValue() {Value=new double[] { 0,1} }

}

当然也可以给其赋予数值:

new DataZoomInside()

{

Start=30,

End=70,

//XAxisIndex=new ArrayNumberValue() {Value=new double[] { 0,1} }

XAxisIndex=new NumberValue(1)

}

在生成JSON时,改转换器会生成对应正确的JSON,如下图所示:

  1. Series

定义了系列。每个系列通过 Type 决定自己的图表类型。

目前定义有:

  • BarSeries
  • LineSeries
  • 其他图表类型大都可以通过实例化基类然后指定系列类型
  1. ValueTypes

值类型。因EChart的许多属性配置均可以支持不同的数据类型和对象,Magicodes.Echarts特对此进行了封装,以进行约束。目前定义有以下值类型:

  • AlignValue
  • ArrayNumberValue
  • DoubleValue
  • IBottomValue
  • ILeftValue
  • INumberOrArrayNumberValue
  • INumberOrStringValue
  • IRightValue
  • ISymbolValue
  • ITopValue
  • IValue
  • NumberValue
  • StringValue
  • SymbolValue
  • VerticalAlignValue

具体使用请参考本框架源码。

  1. EChartsOptions

EChart配置基类。允许设置各个组件和对象来定义Echart。

如下面Demo:

[HttpGet]

public JavaScriptJsonResult Demo1()

{

var provinces = new List<object>() { "岳阳", "长沙", "北京", "上海", "武汉", "贵州", "大连", "成都", "深圳" };

var valueList = new List<object>() { 50, 100, 130, 39, 31, 66, 11, 34, 9 };

var chartOptions = new EChartsOption

{

Title = new Title("粉丝分布统计图") { Left = new AlignValue(Align.center) },

Series = new Series.Series[]

{

new BarSeries

{

Name = "粉丝分布",

Data = valueList,

MarkPoint = new MarkPoint

{

Data = new List<MarkData>

{

new MarkData {Type = MarkPointDataTypes.max, Name = "最大值"},

new MarkData {Type = MarkPointDataTypes.min, Name = "最小值"}

}

},

MarkLine = new MarkLine

{

Data = new List<MarkData>

{

new MarkData {Type = MarkPointDataTypes.average, Name = "平均值"}

}

}

}

},

XAxis = new XAxis[1] { new XAxis { Type = AxisTypes.category, Data = provinces } },

YAxis = new YAxis[1] { new YAxis { Type = AxisTypes.value } }

};

return this.ToEChartResult(chartOptions);

}

  1. TimelineOptions

Timeline配置基类。允许设置各个组件和对象来定义Echart。

  1. Magicodes.EchartsJs

Magicodes.EChartsJs为针对Echart封装的Ajax加载的knockoutjs库,需要依赖以下javascript库:

  • Jquery
  • Knockoutjs

关于Magicodes.EChartsJs,你可以在开源库源码中的项目Magicodes.ECharts.Demo找到。

该组件主要有以下配置:

  1. 全局配置

基于window.mcs.echarts.settings进行配置,比如设置全局主题:

mcs.echarts.settings.theme="macarons"

  1. 组件配置
  • ajaxUrl:Ajax加载路径
  • isBlockUI:是否显示加载遮罩层
  • theme:主题
  1. Demo

<div data-bind='component:{name: "echart",params: { ajaxUrl: "/ChartDemo/Demo1" ,theme:"macarons"}}' style="height: 280px; width: 100%"></div>

<div data-bind='component:{name: "echart",params: { ajaxUrl: "/ChartDemo/Demo2" ,theme:"macarons"}}' style="height: 280px; width: 100%"></div>

<div data-bind='component:{name: "echart",params: { ajaxUrl: "/ChartDemo/Demo3" ,theme:"macarons"}}' style="height: 800px;width: 100%"></div>

  1. 5分钟上手Magicodes.EChart
    1. 获取EChart

你可以在此下载EChart:http://echarts.baidu.com/download.html

  1. 引用Magicodes.ECharts

使用Nuget包下载,请分别下载:

  • Magicodes.ECharts
  • Magicodes.ECharts.Mvc
  • Magicodes.EChartsJs

相关操作如下图所示:

也可以在Github下载源代码引用,地址为:https://github.com/xin-lai/Magicodes.ECharts

  1. 引用Echart相关脚本

推荐使用ASP.NET Bundle技术,配置如下所示:

//echarts

bundles.Add(new ScriptBundle("~/plugins/echarts").Include(

"~/Scripts/plugins/echart/echarts.js",

"~/Scripts/plugins/echart/theme/macarons.js",

"~/Scripts/components/magicodes.echart.js"));

注意:如果使用到了相关主题,请注意引用主题脚本。

那么在View页引用如下:

@Scripts.Render("~/bundles/jquery")

@Scripts.Render("~/bundles/knockout")

@Scripts.Render("~/bundles/bootstrap")

@Scripts.Render("~/plugins/echarts")

其中,Jquery、Knockoutjs、Echarts脚本是必须的,其他请按需引用。

  1. 编写第一个图表
    1. 编写控制器代码

首先我们需要编写控制器代码,以便Ajax调用。如下所示:

[HttpGet]

public JavaScriptJsonResult Demo2()

{

var data = new List<object>() {

new {value=400, name= "搜索引擎"},

new {value=335, name="直接访问"},

new {value=310, name="邮件营销"},

new {value=274, name="联盟广告"},

new {value=235, name="视频广告"}

};

var chartOptions = new EChartsOption

{

Title = new Title("搜索来源") { Left = new AlignValue(Align.center) },

Series = new Series.Series[]

{

new Series.Series

{

Name = "访问来源'",

Data = data,

Type=SeriesTypes.pie,

Radius="55%",

}

}

};

return this.ToEChartResult(chartOptions);

}

请注意引用相关命名空间,并注意,ToEChartResult为扩展方法,用于将上述配置对象输出为JSON序列化内容。

  1. 编写前端代码

前端组件代码如下:

<div data-bind='component:{name: "echart",params: { ajaxUrl: "/ChartDemo/Demo2" ,theme:"macarons"}}' style="height: 280px; width: 100%"></div>

注意,定义好Echart组件之后,我们还需要在页面上添加以下代码:

@section Scripts

{

<script>

$(function () {

ko.applyBindings({});

});

</script>

}

该脚本用于绑定KO组件,请务必添加。

  1. 效果

至此,代码编写完毕,效果如下所示:

  1. 编写动态图表

有时候,我们希望图表能够即时的进行数据刷新并动态变化,那么使用Magicodes.EChartsJs就比较简单了,如下面Demo:

<script>

$(function () {

var viewModel = function () {

var self = this;

this.demo4Url = ko.observable('/ChartDemo/Demo1');

this.init = function () {

//设置定时器

setInterval(function () {

//可以通过Url传参

self.demo4Url(self.demo4Url() == '/ChartDemo/Demo1' ? '/ChartDemo/Demo2' : '/ChartDemo/Demo1');

}, 2000);

};

self.init();

};

ko.applyBindings(new viewModel());

});

</script>

HTML:

<div class="row">

<div class="col-md-12">

<h2>Demo4——动态图</h2>

<div data-bind='component:{name: "echart",params: { ajaxUrl: demo4Url ,theme:"macarons"}}' style="height: 400px;width: 100%"></div>

</div>

</div>

上述Demo实现了图表每隔两秒的刷新,会自动从Demo1切换为Demo2的图表,在实际应用中,您可以可以通过Url传参或者按照自身业务来动态加载图表数据。

由上面代码得知,Magicodes.EChartsJs组件的ajaxUrl参数不仅仅支持字符串,还支持绑定ko的监视器,如果图表需要即时刷新,只需要给监视器赋值就可以了,当值产生变化时,图表会自动刷新,如下面代码:

self.demo4Url(self.demo4Url() == '/ChartDemo/Demo1' ? '/ChartDemo/Demo2' : '/ChartDemo/Demo1');

  1. 相关示例

目前在开源库中,定义了4个Demo,如下图所示:

下面是我们使用该组件在实践中的一些示例:

目前Magicodes.ECharts尚不能支持所有图表和所有情形,如果你对本项目有兴趣,可以贡献自己的代码哦。本着按需设计的原则,Magicodes.ECharts在不断地实践中会更加完善的。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

扫码关注云+社区

领取腾讯云代金券