目錄
博客使用Word發博，發布后，排版會出現很多問題，一一修正工作量極大，敬請諒解。可加群獲取原始文檔。
-
概要
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在不斷地實踐中會更加完善的
- 在設計上，我們不會過多設計，但是后續版本可能會不斷地進行重構
-
Magicodes.ECharts工作原理
-
架構說明
Magicodes.ECharts目前主要由以下部分組成：
-
Axis
直角坐標系 grid 中的軸的相關配置封裝，比如x軸、y軸等。
-
CommonDefinitions
通用定義，目前定義了以下內容：
- Align（水平對齊）
- Label（標簽）
- Orients（圖例列表的布局朝向）
- Symbols（標記的圖形）
- TextAlign（標題文本水平對齊）
- TextStyles（文本樣式）
- VerticalAlign（垂直對齊）
-
Components
組件定義。目前定義了以下內容：
-
DataZoom（區域縮放）
- DataZoomInside（內置型數據區域縮放組件）
- DataZoomSlider（滑動條型數據區域縮放組件）
- Grid（直角坐標系內繪圖網格）
- Legend（圖例組件）
- TimeLine（timeline 組件）
- Title（標題）
- ToolBox（工具箱）
- ToolTip（提示框組件）
-
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，如下圖所示：
-
Series
定義了系列。每個系列通過 Type 決定自己的圖表類型。
目前定義有：
- BarSeries
- LineSeries
- 其他圖表類型大都可以通過實例化基類然后指定系列類型
-
ValueTypes
值類型。因EChart的許多屬性配置均可以支持不同的數據類型和對象，Magicodes.Echarts特對此進行了封裝，以進行約束。目前定義有以下值類型：
- AlignValue
- ArrayNumberValue
- DoubleValue
- IBottomValue
- ILeftValue
- INumberOrArrayNumberValue
- INumberOrStringValue
- IRightValue
- ISymbolValue
- ITopValue
- IValue
- NumberValue
- StringValue
- SymbolValue
- VerticalAlignValue
具體使用請參考本框架源碼。
-
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);
}
-
TimelineOptions
Timeline配置基類。允許設置各個組件和對象來定義Echart。
-
Magicodes.EchartsJs
Magicodes.EChartsJs為針對Echart封裝的Ajax加載的knockoutjs庫，需要依賴以下javascript庫：
- Jquery
- Knockoutjs
關於Magicodes.EChartsJs，你可以在開源庫源碼中的項目Magicodes.ECharts.Demo找到。
該組件主要有以下配置：
-
全局配置
基於window.mcs.echarts.settings進行配置，比如設置全局主題：
mcs.echarts.settings.theme="macarons"
-
組件配置
- ajaxUrl:Ajax加載路徑
- isBlockUI:是否顯示加載遮罩層
- theme:主題
-
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>
-
5分鍾上手Magicodes.EChart
-
獲取EChart
-
你可以在此下載EChart：http://echarts.baidu.com/download.html
-
引用Magicodes.ECharts
使用Nuget包下載，請分別下載：
- Magicodes.ECharts
- Magicodes.ECharts.Mvc
- Magicodes.EChartsJs
相關操作如下圖所示：
也可以在Github下載源代碼引用，地址為：https://github.com/xin-lai/Magicodes.ECharts
-
引用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腳本是必須的，其他請按需引用。
-
編寫第一個圖表
-
編寫控制器代碼
-
首先我們需要編寫控制器代碼，以便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序列化內容。
-
編寫前端代碼
前端組件代碼如下：
<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組件，請務必添加。
-
效果
至此，代碼編寫完畢，效果如下所示：
-
編寫動態圖表
有時候，我們希望圖表能夠即時的進行數據刷新並動態變化，那么使用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');
-
相關示例
目前在開源庫中，定義了4個Demo，如下圖所示：
下面是我們使用該組件在實踐中的一些示例：
目前Magicodes.ECharts尚不能支持所有圖表和所有情形，如果你對本項目有興趣，可以貢獻自己的代碼哦。本着按需設計的原則，Magicodes.ECharts在不斷地實踐中會更加完善的。