官網:https://www.echartsjs.com/zh/index.html
GitHub:https://github.com/apache/incubator-echarts
特性介紹
百度的
ECharts
目前在國內使用的比較多,ECharts
一個純Javascript
的圖表庫,可以流暢的運行在PC
和移動設備上,兼容當前絕大部分瀏覽器(IE8/9/10/11,Chrome,Firefox,Safari等),底層依賴輕量級的Canvas
類庫ZRender
,提供直觀,生動,可交互,可高度個性化定制的數據可視化圖表。
ECharts 3
中更是加入了更多豐富的交互功能以及更多的可視化效果,并且對移動端做了深度的優化。
獲取 ECharts
你可以通過以下幾種方式獲取 ECharts。
從官網下載界面選擇你需要的版本下載,根據開發者功能和體積上的需求,我們提供了不同打包的下載,如果你在體積上沒有要求,可以直接下載完整版本。開發環境建議下載源代碼版本,包含了常見的錯誤提示和警告。
在 ECharts 的 GitHub 上下載最新的
release
版本,解壓出來的文件夾里的dist
目錄里可以找到最新版本的 echarts 庫。通過 npm 獲取 echarts,
npm install echarts --save
,詳見“在 webpack 中使用 echarts”
引入 ECharts
ECharts 3
開始不再強制使用AMD
的方式按需引入,代碼里也不再內置AMD
加載器。因此引入方式簡單了很多,只需要像普通的JavaScript
庫一樣用script
標簽引入。
<!DOCTYPE html>
<html>
<header>
<meta charset="utf-8">
<!-- 引入 ECharts 文件 -->
<script src="echarts.min.js"></script>
</header>
</html>
繪制一個簡單的圖表
在繪圖前我們需要為 ECharts 準備一個具備高寬的 DOM 容器。
<body>
<!-- 為 ECharts 準備一個具備大小(寬高)的 DOM -->
<div id="main" style="width: 600px;height:400px;"></div>
</body>
然后就可以通過 echarts.init 方法初始化一個 echarts 實例并通過 setOption 方法生成一個簡單的柱狀圖,下面是完整代碼。
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>ECharts</title>
<!-- 引入 echarts.js -->
<script src="echarts.min.js"></script>
</head>
<body>
<!-- 為ECharts準備一個具備大小(寬高)的Dom -->
<div id="main" style="width: 600px;height:400px;"></div>
<script type="text/javascript">
// 基于準備好的dom,初始化echarts實例
var myChart = echarts.init(document.getElementById('main'));
// 指定圖表的配置項和數據
var option = {
title: {
text: 'ECharts 入門示例'
},
tooltip: {},
legend: {
data:['銷量']
},
xAxis: {
data: ["襯衫","羊毛衫","雪紡衫","褲子","高跟鞋","襪子"]
},
yAxis: {},
series: [{
name: '銷量',
type: 'bar',
data: [5, 20, 36, 10, 10, 20]
}]
};
// 使用剛指定的配置項和數據顯示圖表。
myChart.setOption(option);
</script>
</body>
</html>
這樣你的第一個圖表就誕生了!
在 webpack 中使用 ECharts
Webpack 是目前比較流行的模塊打包工具,你可以在使用
webpack
的項目中輕松的引入和打包ECharts
,這里假設你已經對webpack
具有一定的了解并且在自己的項目中使用。
npm 安裝 ECharts
在 3.1.1 版本之前
ECharts
在npm
上的package
是非官方維護的,從 3.1.1 開始由官方 EFE 維護npm
上ECharts
和zrender
的package
。
你可以使用如下命令通過 npm 安裝 ECharts
npm install echarts --save
引入 ECharts
通過
npm
上安裝的ECharts
和zrender
會放在node_modules
目錄下。可以直接在項目代碼中require('echarts')
得到ECharts
。
var echarts = require('echarts');
// 基于準備好的dom,初始化echarts實例
var myChart = echarts.init(document.getElementById('main'));
// 繪制圖表
myChart.setOption({
title: { text: 'ECharts 入門示例' },
tooltip: {},
xAxis: {
data: ["襯衫","羊毛衫","雪紡衫","褲子","高跟鞋","襪子"]
},
yAxis: {},
series: [{
name: '銷量',
type: 'bar',
data: [5, 20, 36, 10, 10, 20]
}]
});
按需引入 ECharts 圖表和組件
默認使用
require('echarts')
得到的是已經加載了所有圖表和組件的ECharts
包,因此體積會比較大,如果在項目中對體積要求比較苛刻,也可以只按需引入需要的模塊。
例如上面示例代碼中只用到了柱狀圖,提示框和標題組件,因此在引入的時候也只需要引入這些模塊,可以有效的將打包后的體積從 400 多 KB 減小到 170 多 KB。
// 引入 ECharts 主模塊
var echarts = require('echarts/lib/echarts');
// 引入柱狀圖
require('echarts/lib/chart/bar');
// 引入提示框和標題組件
require('echarts/lib/component/tooltip');
require('echarts/lib/component/title');
// 基于準備好的dom,初始化echarts實例
var myChart = echarts.init(document.getElementById('main'));
// 繪制圖表
myChart.setOption({
title: { text: 'ECharts 入門示例' },
tooltip: {},
xAxis: {
data: ["襯衫","羊毛衫","雪紡衫","褲子","高跟鞋","襪子"]
},
yAxis: {},
series: [{
name: '銷量',
type: 'bar',
data: [5, 20, 36, 10, 10, 20]
}]
});
對于另一個流行的模塊打包工具 browserify 也是同樣的用法,這里就不贅述了。
繪制南丁格爾圖
餅圖主要是通過扇形的弧度表現不同類目的數據在總和中的占比,它的數據格式比柱狀圖更簡單,只有一維的數值,不需要給類目。因為不在直角坐標系上,所以也不需要
xAxis
,yAxis
。
myChart.setOption({
series : [{
name: '訪問來源',
type: 'pie',
radius: '55%',
data:[
{value:400, name:'搜索引擎'},
{value:335, name:'直接訪問'},
{value:310, name:'郵件營銷'},
{value:274, name:'聯盟廣告'},
{value:235, name:'視頻廣告'}
]
}]
})
異步數據加載和更新
異步加載
入門示例中的數據是在初始化后
setOption
中直接填入的,但是很多時候可能數據需要異步加載后再填入。ECharts
中實現異步數據的更新非常簡單,在圖表初始化后不管任何時候只要通過jQuery
等工具異步獲取數據后通過setOption
填入數據和配置項就行。
var myChart = echarts.init(document.getElementById('main'));
$.get('data.json').done(function (data) {
myChart.setOption({
title: {
text: '異步數據加載示例'
},
tooltip: {},
legend: {
data:['銷量']
},
xAxis: {
data: ["襯衫","羊毛衫","雪紡衫","褲子","高跟鞋","襪子"]
},
yAxis: {},
series: [{
name: '銷量',
type: 'bar',
data: [5, 20, 36, 10, 10, 20]
}]
});
});
var myChart = echarts.init(document.getElementById('main'));
// 顯示標題,圖例和空的坐標軸
myChart.setOption({
title: {
text: '異步數據加載示例'
},
tooltip: {},
legend: {
data:['銷量']
},
xAxis: {
data: []
},
yAxis: {},
series: [{
name: '銷量',
type: 'bar',
data: []
}]
});
// 異步加載數據
$.get('data.json').done(function (data) {
// 填入數據
myChart.setOption({
xAxis: {
data: data.categories
},
series: [{
// 根據名字對應到相應的系列
name: '銷量',
data: data.data
}]
});
});
ECharts 中在更新數據的時候需要通過name
屬性對應到相應的系列,上面示例中如果name
不存在也可以根據系列的順序正常更新,但是更多時候推薦更新數據的時候加上系列的name
數據。
loading 動畫
如果數據加載時間較長,一個空的坐標軸放在畫布上也會讓用戶覺得是不是產生
bug
了,因此需要一個loading
的動畫來提示用戶數據正在加載。
ECharts 默認有提供了一個簡單的加載動畫。只需要調用 showLoading 方法顯示。數據加載完成后再調用 hideLoading 方法隱藏加載動畫。
myChart.showLoading();
$.get('data.json').done(function (data) {
myChart.hideLoading();
myChart.setOption(...);
});
移動端自適應
ECharts
工作在用戶指定高寬的DOM
節點(容器)中。ECharts
的『組件』和『系列』都在這個DOM
節點中,每個節點都可以由用戶指定位置。圖表庫內部并不適宜實現DOM
文檔流布局,因此采用類似絕對布局的簡單容易理解的布局方式。但是有時候容器尺寸極端時,這種方式并不能自動避免組件重疊的情況,尤其在移動端小屏的情況下。
另外,有時會出現一個圖表需要同時在PC、移動端上展現的場景。這需要 ECharts 內部組件隨著容器尺寸變化而變化的能力。
為了解決這個問題,ECharts 完善了組件的定位設置,并且實現了類似 CSS Media Query 的自適應能力。
ECharts組件的定位和布局
大部分『組件』和『系列』會遵循兩種定位方式:
1)left/right/top/bottom/width/height 定位方式:
這六個量中,每個量都可以是『絕對值』或者『百分比』或者『位置描述』
-
絕對值
單位是瀏覽器像素(px),用
number
形式書寫(不寫單位)。例如{left: 23, height: 400}
。 -
百分比
表示占 DOM 容器高寬的百分之多少,用
string
形式書寫。例如{right: '30%', bottom: '40%'}
。 -
位置描述
- 可以設置
left: 'center'
,表示水平居中。 - 可以設置
top: 'middle'
,表示垂直居中。
- 可以設置
這六個量的概念,和 CSS 中六個量的概念類似:
- left:距離 DOM 容器左邊界的距離。
- right:距離 DOM 容器右邊界的距離。
- top:距離 DOM 容器上邊界的距離。
- bottom:距離 DOM 容器下邊界的距離。
- width:寬度。
- height:高度。
在橫向,left
、right
、width
三個量中,只需兩個量有值即可,因為任兩個量可以決定組件的位置和大小,例如 left
和right
或者 right
和 width
都可以決定組件的位置和大小。 縱向,top
、bottom
、height
三個量,和橫向類同不贅述。
2)center / radius`定位方式:
-
center
是一個數組,表示
[x, y]
,其中,x
、y
可以是『絕對值』或者『百分比』,含義和前述相同。 -
radius
是一個數組,表示
[內半徑, 外半徑]
,其中,內外半徑可以是『絕對值』或者『百分比』,含義和前述相同。在自適應容器大小時,百分比設置是很有用的。
橫向(horizontal)和縱向(vertical)
- ECharts的『外觀狹長』型的組件(如
legend
、visualMap
、dataZoom
、timeline
等),大多提供了『橫向布局』『縱向布局』的選擇。例如,在細長的移動端屏幕上,可能適合使用『縱向布局』;在PC寬屏上,可能適合使用『橫向布局』。 - 橫縱向布局的設置,一般在『組件』或者『系列』的
orient
或者layout
配置項上,設置為'horizontal'
或者'vertical'
。
于 ECharts2 的兼容:
- ECharts2 中的
x/x2/y/y2
的命名方式仍被兼容,對應于left/right/top/bottom
。但是建議寫left/right/top/bottom
。 - 位置描述中,為兼容 ECharts2,可以支持一些看起來略奇怪的設置:
left: 'right'
、left: 'left'
、top: 'bottom'
、top: 'top'
。這些語句分別等效于:right: 0
、left: 0
、bottom: 0
、top: 0
,寫成后者就不奇怪了。
Media Query
Media Query 提供了『隨著容器尺寸改變而改變』的能力。
如下例子,可嘗試拖動右下角的圓點,隨著尺寸變化,legend 和 系列會自動改變布局位置和方式。
要在 option 中設置 Media Query 須遵循如下格式:
option = {
baseOption: { // 這里是基本的『原子option』。
title: {...},
legend: {...},
series: [{...}, {...}, ...],
...
},
media: [{ // 這里定義了 media query 的逐條規則。
query: {...}, // 這里寫規則。
option: { // 這里寫此規則滿足下的option。
legend: {...},
...
}
},
{
query: {...}, // 第二個規則。
option: { // 第二個規則對應的option。
legend: {...},
...
}
},
{ // 這條里沒有寫規則,表示『默認』,
option: { // 即所有規則都不滿足時,采納這個option。
legend: {...},
...
}
}]
};
上面的例子中,baseOption
、以及 media
每個 option 都是『原子 option』,即普通的含有各組件、系列定義的 option。而由『原子option』組合成的整個 option,我們稱為『復合 option』。baseOption
是必然被使用的,此外,滿足了某個 query
條件時,對應的 option 會被使用 chart.mergeOption()
來 merge 進去。
query:
每個 query
類似于這樣:
{
minWidth: 200,
maxHeight: 300,
minAspectRatio: 1.3
}
現在支持三個屬性:width
、height
、aspectRatio
(長寬比)。每個屬性都可以加上 min
或 max
前綴。比如,minWidth: 200
表示『大于等于200px寬度』。兩個屬性一起寫表示『并且』,比如:{minWidth: 200, maxHeight: 300}
表示『大于等于200px寬度,并且小于等于300px高度』。
option:
media
中的 option 既然是『原子 option』,理論上可以寫任何 option 的配置項。但是一般我們只寫跟布局定位相關的,例如截取上面例子中的一部分 query option:
media: [
...,
{
query: {
maxAspectRatio: 1 // 當長寬比小于1時。
},
option: {
legend: { // legend 放在底部中間。
right: 'center',
bottom: 0,
orient: 'horizontal' // legend 橫向布局。
},
series: [{ // 兩個餅圖左右布局。
radius: [20, '50%'],
center: ['50%', '30%']
},
{
radius: [30, '50%'],
center: ['50%', '70%']
}]
}
},
{
query: {
maxWidth: 500 // 當容器寬度小于 500 時。
},
option: {
legend: {
right: 10, // legend 放置在右側中間。
top: '15%',
orient: 'vertical' // 縱向布局。
},
series: [{ // 兩個餅圖上下布局。
radius: [20, '50%'],
center: ['50%', '30%']
},
{
radius: [30, '50%'],
center: ['50%', '75%']
}]
}
},
...
]
多個 query 被滿足時的優先級:
注意,可以有多個 query
同時被滿足,會都被 mergeOption
,定義在后的后被 merge(即優先級更高)。
默認 query:
如果 media
中有某項不寫 query
,則表示『默認值』,即所有規則都不滿足時,采納這個option。
容器大小實時變化時的注意事項:
- 在不少情況下,并不需要容器DOM節點任意隨著拖拽變化大小,而是只是根據不同終端設置幾個典型尺寸。
- 但是如果容器DOM節點需要能任意隨著拖拽變化大小,那么目前使用時需要注意這件事:某個配置項,如果在某一個
query option
中出現,那么在其他query option
中也必須出現,否則不能夠回歸到原來的狀態。(left/right/top/bottom/width/height
不受這個限制。) - 『復合 option』 中的
media
不支持 merge - 也就是說,當第二(或三、四、五 ...)次
chart.setOption(rawOption)
時,如果rawOption
是復合option
(即包含media
列表),那么新的rawOption.media
列表不會和老的media
列表進行 merge,而是簡單替代。當然,rawOption.baseOption
仍然會正常和老的 option 進行merge。 - 其實,很少有場景需要使用『復合 option』來多次
setOption
,而我們推薦的做法是,使用 mediaQuery 時,第一次setOption使用『復合 option』,后面setOption
時僅使用 『原子 option』,也就是僅僅用 setOption 來改變baseOption
。