This is an automated email from the ASF dual-hosted git repository.
shenyi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/echarts-handbook.git
The following commit(s) were added to refs/heads/master by this push:
new 441fb85 update articles
441fb85 is described below
commit 441fb856102ddc64ba8ad497b898eca54b0ef115
Author: pissang <[email protected]>
AuthorDate: Wed Jul 21 13:58:16 2021 +0800
update articles
---
components/markdown/Live.vue | 1 +
.../zh/application/chart-types/bar/basic-bar.md | 24 +-
contents/zh/application/interaction/drag.md | 255 ++++++++++
contents/zh/application/label/rich-text.md | 524 +++++++++++++++++++++
contents/zh/basics/download.md | 32 +-
contents/zh/basics/import.md | 115 +++++
contents/zh/basics/inspiration.md | 2 +-
contents/zh/basics/resource.md | 2 +-
contents/zh/best-practice/canvas-vs-svg.md | 28 +-
contents/zh/concepts/axis.md | 85 +++-
contents/zh/concepts/data-transform.md | 235 ++++-----
contents/zh/concepts/event.md | 4 +-
contents/zh/concepts/legend.md | 8 -
contents/zh/concepts/style.md | 324 +++++++++++++
contents/zh/posts.yml | 30 +-
nuxt.config.js | 14 +-
16 files changed, 1493 insertions(+), 190 deletions(-)
diff --git a/components/markdown/Live.vue b/components/markdown/Live.vue
index 42a10b6..8ab3eb7 100644
--- a/components/markdown/Live.vue
+++ b/components/markdown/Live.vue
@@ -153,6 +153,7 @@ export default defineComponent({
}
.md-live-preview {
@apply flex-1;
+ height: auto;
}
}
}
diff --git a/contents/zh/application/chart-types/bar/basic-bar.md
b/contents/zh/application/chart-types/bar/basic-bar.md
index e32caa4..9040d77 100644
--- a/contents/zh/application/chart-types/bar/basic-bar.md
+++ b/contents/zh/application/chart-types/bar/basic-bar.md
@@ -10,9 +10,7 @@
最简单的柱状图可以这样设置：
-<!-- embed -->
-
-```js
+```js [live]
option = {
xAxis: {
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
@@ -33,9 +31,7 @@ option = {
我们可以用一个系列表示一组相关的数据，如果需要实现多系列的柱状图，只需要在 `series` 多添加一项就可以了——
-<!-- embed -->
-
-```js
+```js [live]
option = {
xAxis: {
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
@@ -66,9 +62,7 @@ option = {
- 柱条透明度（`opacity`）；
- 阴影（`shadowBlur`、`shadowColor`、`shadowOffsetX`、`shadowOffsetY`）。
-<!-- embed -->
-
-```js
+```js [live]
option = {
xAxis: {
data: ['A', 'B', 'C', 'D', 'E']
@@ -95,9 +89,7 @@ option = {
柱条宽度可以通过 [`barWidth`](${optionPath}#series-bar.barWidth) 设置。比如在下面的例子中，将
`barWidth` 设为 `'20%'`，表示每个柱条的宽度就是类目宽度的 20%。由于这个例子中，每个系列有 5 个数据，20% 的类目宽度也就是整个 x
轴宽度的 4%。
-<!-- embed -->
-
-```js
+```js [live]
option = {
xAxis: {
data: ['A', 'B', 'C', 'D', 'E']
@@ -124,9 +116,7 @@ option = {
柱条间距分为两种，一种是不同系列在同一类目下的距离
[`barWidth`](${optionPath}series-bar.barWidth)，另一种是类目与类目的距离
[`barCategoryGap`](${optionPath}series-bar.barCategoryGap)。
-<!-- embed -->
-
-```js
+```js [live]
option = {
xAxis: {
data: ['A', 'B', 'C', 'D', 'E']
@@ -157,9 +147,7 @@ option = {
有时，我们希望能够为柱条添加背景色。从 ECharts 4.7.0 版本开始，这一功能可以简单地用
[`showBackground`](${optionPath}series-bar.showBackground) 开启，并且可以通过
[`backgroundStyle`](${optionPath}series-bar.backgroundStyle) 配置。
-<!-- embed -->
-
-```js
+```js [live]
option = {
xAxis: {
type: 'category',
diff --git a/contents/zh/application/interaction/drag.md
b/contents/zh/application/interaction/drag.md
new file mode 100644
index 0000000..157e727
--- /dev/null
+++ b/contents/zh/application/interaction/drag.md
@@ -0,0 +1,255 @@
+# 拖拽的实现
+
+本篇通过介绍一个实现拖拽的小例子来介绍如何在 Apache ECharts<sup>TM</sup> 中实现复杂的交互。
+
+这个例子主要做到了这样一件事，用鼠标可以拖拽曲线的点，从而改变曲线的形状。例子很简单，但是有了这个基础我们还可以做更多的事情，比如在图中进行可视化得编辑。所以我们从这个简单的例子开始。
+
+echarts 本身没有提供封装好的“拖拽改变图表”这样比较业务定制的功能。但是这个功能开发者可以通过 API 扩展实现。
+
+## 实现基本的拖拽功能
+
+在这个例子中，基础的图表是一个 [折线图 (series-line)](${optionPath}series-line)。参见如下配置：
+
+```js
+var symbolSize = 20;
+
+// 这个 data 变量在这里单独声明，在后面也会用到。
+var data = [
+ [15, 0],
+ [-50, 10],
+ [-56.5, 20],
+ [-46.5, 30],
+ [-22.1, 40]
+];
+
+myChart.setOption({
+ xAxis: {
+ min: -100,
+ max: 80,
+ type: 'value',
+ axisLine: { onZero: false }
+ },
+ yAxis: {
+ min: -30,
+ max: 60,
+ type: 'value',
+ axisLine: { onZero: false }
+ },
+ series: [
+ {
+ id: 'a',
+ type: 'line',
+ smooth: true,
+ symbolSize: symbolSize, // 为了方便拖拽，把 symbolSize 尺寸设大了。
+ data: data
+ }
+ ]
+});
+```
+
+既然折线中原生的点没有拖拽功能，我们就为它加上拖拽功能：用 [graphic](${optionPath}graphic)
组件，在每个点上面，覆盖一个隐藏的可拖拽的圆点。
+
+```js
+myChart.setOption({
+ // 声明一个 graphic component，里面有若干个 type 为 'circle' 的 graphic elements。
+ // 这里使用了 echarts.util.map 这个帮助方法，其行为和 Array.prototype.map 一样，但是兼容 es5 以下的环境。
+ // 用 map 方法遍历 data 的每项，为每项生成一个圆点。
+ graphic: echarts.util.map(data, function(dataItem, dataIndex) {
+ return {
+ // 'circle' 表示这个 graphic element 的类型是圆点。
+ type: 'circle',
+
+ shape: {
+ // 圆点的半径。
+ r: symbolSize / 2
+ },
+ // 用 transform 的方式对圆点进行定位。position: [x, y] 表示将圆点平移到 [x, y] 位置。
+ // 这里使用了 convertToPixel 这个 API 来得到每个圆点的位置，下面介绍。
+ position: myChart.convertToPixel('grid', dataItem),
+
+ // 这个属性让圆点不可见（但是不影响他响应鼠标事件）。
+ invisible: true,
+ // 这个属性让圆点可以被拖拽。
+ draggable: true,
+ // 把 z 值设得比较大，表示这个圆点在最上方，能覆盖住已有的折线图的圆点。
+ z: 100,
+ // 此圆点的拖拽的响应事件，在拖拽过程中会不断被触发。下面介绍详情。
+ // 这里使用了 echarts.util.curry 这个帮助方法，意思是生成一个与 onPointDragging
+ // 功能一样的新的函数，只不过第一个参数永远为此时传入的 dataIndex 的值。
+ ondrag: echarts.util.curry(onPointDragging, dataIndex)
+ };
+ })
+});
+```
+
+上面的代码中，使用 [convertToPixel](api.html#echartsInstance.convertToPixel) 这个
API，进行了从 data
到“像素坐标”的转换，从而得到了每个圆点应该在的位置，从而能绘制这些圆点。`myChart.convertToPixel('grid', dataItem)`
这句话中，第一个参数 `'grid'` 表示 `dataItem` 在 [grid](${optionPath}grid)
这个组件中（即直角坐标系）中进行转换。所谓“像素坐标”，就是以 echarts 容器 dom element 的左上角为零点的以像素为单位的坐标系中的坐标。
+
+注意这件事需要在第一次 setOption 后再进行，也就是说，须在坐标系（[grid](${optionPath}grid)）初始化后才能调用
`myChart.convertToPixel('grid', dataItem)`。
+
+有了这段代码后，就有了诸个能拖拽的点。接下来要为每个点，加上拖拽响应的事件：
+
+```js
+// 拖拽某个圆点的过程中会不断调用此函数。
+// 此函数中会根据拖拽后的新位置，改变 data 中的值，并用新的 data 值，重绘折线图，从而使折线图同步于被拖拽的隐藏圆点。
+function onPointDragging(dataIndex) {
+ // 这里的 data 就是本文最初的代码块中声明的 data，在这里会被更新。
+ // 这里的 this 就是被拖拽的圆点。this.position 就是圆点当前的位置。
+ data[dataIndex] = myChart.convertFromPixel('grid', this.position);
+ // 用更新后的 data，重绘折线图。
+ myChart.setOption({
+ series: [
+ {
+ id: 'a',
+ data: data
+ }
+ ]
+ });
+}
+```
+
+上面的代码中，使用了 [convertFromPixel](api.html#echartsInstance.convertFromPixel) 这个
API。它是 [convertToPixel](api.html#echartsInstance.convertToPixel)
的逆向过程。`myChart.convertFromPixel('grid', this.position)` 表示把当前像素坐标转换成
[grid](${optionPath}grid) 组件中直角坐标系的 dataItem 值。
+
+最后，为了使 dom 尺寸改变时，图中的元素能自适应得变化，加上这些代码：
+
+```js
+window.addEventListener('resize', function() {
+ // 对每个拖拽圆点重新计算位置，并用 setOption 更新。
+ myChart.setOption({
+ graphic: echarts.util.map(data, function(item, dataIndex) {
+ return {
+ position: myChart.convertToPixel('grid', item)
+ };
+ })
+ });
+});
+```
+
+## 添加 tooltip 组件
+
+到此，拖拽的基本功能就完成了。但是想要更进一步得实时看到拖拽过程中，被拖拽的点的 data 值的变化状况，我们可以使用
[tooltip](${optionPath}tooltip) 组件来实时显示这个值。但是，tooltip
有其默认的“显示”“隐藏”触发规则，在我们拖拽的场景中并不适用，所以我们还要手动定制 tooltip 的“显示”“隐藏”行为。
+
+在上述代码中分别添加如下定义：
+
+```js
+myChart.setOption({
+ ...,
+ tooltip: {
+ // 表示不使用默认的“显示”“隐藏”触发规则。
+ triggerOn: 'none',
+ formatter: function (params) {
+ return 'X: ' + params.data[0].toFixed(2) + '<br>Y: ' +
params.data[1].toFixed(2);
+ }
+ }
+});
+```
+
+```js
+myChart.setOption({
+ graphic: echarts.util.map(data, function (item, dataIndex) {
+ return {
+ type: 'circle',
+ ...,
+ // 在 mouseover 的时候显示，在 mouseout 的时候隐藏。
+ onmousemove: echarts.util.curry(showTooltip, dataIndex),
+ onmouseout: echarts.util.curry(hideTooltip, dataIndex),
+ };
+ })
+});
+
+function showTooltip(dataIndex) {
+ myChart.dispatchAction({
+ type: 'showTip',
+ seriesIndex: 0,
+ dataIndex: dataIndex
+ });
+}
+
+function hideTooltip(dataIndex) {
+ myChart.dispatchAction({
+ type: 'hideTip'
+ });
+}
+```
+
+这里使用了 [dispatchAction](api.html#echartsInstance.dispatchAction) 来显示隐藏
tooltip。用到了
[showTip](api.html#action.tooltip.showTip)、[hideTip](api.html#action.tooltip.hideTip)。
+
+## 全部代码
+
+总结一下，全部的代码如下：
+
+```js
+import echarts from 'echarts';
+
+var symbolSize = 20;
+var data = [
+ [15, 0],
+ [-50, 10],
+ [-56.5, 20],
+ [-46.5, 30],
+ [-22.1, 40]
+];
+var myChart = echarts.init(document.getElementById('main'));
+myChart.setOption({
+ tooltip: {
+ triggerOn: 'none',
+ formatter: function(params) {
+ return (
+ 'X: ' +
+ params.data[0].toFixed(2) +
+ '<br />Y: ' +
+ params.data[1].toFixed(2)
+ );
+ }
+ },
+ xAxis: { min: -100, max: 80, type: 'value', axisLine: { onZero: false } },
+ yAxis: { min: -30, max: 60, type: 'value', axisLine: { onZero: false } },
+ series: [
+ { id: 'a', type: 'line', smooth: true, symbolSize: symbolSize, data: data }
+ ]
+});
+myChart.setOption({
+ graphic: echarts.util.map(data, function(item, dataIndex) {
+ return {
+ type: 'circle',
+ position: myChart.convertToPixel('grid', item),
+ shape: { r: symbolSize / 2 },
+ invisible: true,
+ draggable: true,
+ ondrag: echarts.util.curry(onPointDragging, dataIndex),
+ onmousemove: echarts.util.curry(showTooltip, dataIndex),
+ onmouseout: echarts.util.curry(hideTooltip, dataIndex),
+ z: 100
+ };
+ })
+});
+window.addEventListener('resize', function() {
+ myChart.setOption({
+ graphic: echarts.util.map(data, function(item, dataIndex) {
+ return { position: myChart.convertToPixel('grid', item) };
+ })
+ });
+});
+function showTooltip(dataIndex) {
+ myChart.dispatchAction({
+ type: 'showTip',
+ seriesIndex: 0,
+ dataIndex: dataIndex
+ });
+}
+function hideTooltip(dataIndex) {
+ myChart.dispatchAction({ type: 'hideTip' });
+}
+function onPointDragging(dataIndex, dx, dy) {
+ data[dataIndex] = myChart.convertFromPixel('grid', this.position);
+ myChart.setOption({
+ series: [
+ {
+ id: 'a',
+ data: data
+ }
+ ]
+ });
+}
+```
+
+有了这些基础，就可以定制更多的功能了。可以加 [dataZoom](${optionPath}dataZoom)
组件，可以制作一个直角坐标系上的绘图板等等。可以发挥想象力。
diff --git a/contents/zh/application/label/rich-text.md
b/contents/zh/application/label/rich-text.md
new file mode 100644
index 0000000..728bc69
--- /dev/null
+++ b/contents/zh/application/label/rich-text.md
@@ -0,0 +1,524 @@
+# 富文本标签
+
+Apache ECharts<sup>TM</sup> 中的文本标签从 v3.7 开始支持富文本模式，能够：
+
+- 定制文本块整体的样式（如背景、边框、阴影等）、位置、旋转等。
+- 对文本块中个别片段定义样式（如颜色、字体、高宽、背景、阴影等）、对齐方式等。
+- 在文本中使用图片做小图标或者背景。
+- 特定组合以上的规则，可以做出简单表格、分割线等效果。
+
+开始下面的介绍之前，先说明一下下面会使用的两个名词的含义：
+
+- 文本块（Text Block）：文本标签块整体。
+- 文本片段（Text fragment）：文本标签块中的部分文本。
+
+如下图示例：
+~[340x240](${galleryViewPath}doc-example/text-block-fragment&edit=1&reset=1)
+
+## 文本样式相关的配置项
+
+echarts 提供了丰富的文本标签配置项，包括：
+
+- 字体基本样式设置：`fontStyle`、`fontWeight`、`fontSize`、`fontFamily`。
+- 文字颜色：`color`。
+- 文字描边：`textBorderColor`、`textBorderWidth`。
+-
文字阴影：`textShadowColor`、`textShadowBlur`、`textShadowOffsetX`、`textShadowOffsetY`。
+- 文本块或文本片段大小：`lineHeight`、`width`、`height`、`padding`。
+- 文本块或文本片段的对齐：`align`、`verticalAlign`。
+-
文本块或文本片段的边框、背景（颜色或图片）：`backgroundColor`、`borderColor`、`borderWidth`、`borderRadius`。
+- 文本块或文本片段的阴影：`shadowColor`、`shadowBlur`、`shadowOffsetX`、`shadowOffsetY`。
+- 文本块的位置和旋转：`position`、`distance`、`rotate`。
+
+可以在各处的 `rich` 属性中定义文本片段样式。例如
[series-bar.label.rich](option.html#series-bar.label.rich)
+
+例如：
+
+```js
+labelOption = {
+ // 在文本中，可以对部分文本采用 rich 中定义样式。
+ // 这里需要在文本中使用标记符号：
+ // `{styleName|text content text content}` 标记样式名。
+ // 注意，换行仍是使用 '\n'。
+ formatter: [
+ '{a|这段文本采用样式a}',
+ '{b|这段文本采用样式b}这段用默认样式{x|这段用样式x}'
+ ].join('\n'),
+
+ // 这里是文本块的样式设置：
+ color: '#333',
+ fontSize: 5,
+ fontFamily: 'Arial',
+ borderWidth: 3,
+ backgroundColor: '#984455',
+ padding: [3, 10, 10, 5],
+ lineHeight: 20,
+
+ // rich 里是文本片段的样式设置：
+ rich: {
+ a: {
+ color: 'red',
+ lineHeight: 10
+ },
+ b: {
+ backgroundColor: {
+ image: 'xxx/xxx.jpg'
+ },
+ height: 40
+ },
+ x: {
+ fontSize: 18,
+ fontFamily: 'Microsoft YaHei',
+ borderColor: '#449933',
+ borderRadius: 4
+ }
+ }
+};
+```
+
+> 注意：如果不定义 `rich`，不能指定文字块的 `width` 和 `height`。
+
+## 文本、文本框、文本片段的基本样式和装饰
+
+每个文本可以设置基本的字体样式：`fontStyle`、`fontWeight`、`fontSize`、`fontFamily`。
+
+可以设置文字的颜色 `color` 和边框的颜色 `textBorderColor`、`textBorderWidth`。
+
+文本框可以设置边框和背景的样式：`borderColor`、`borderWidth`、`backgroundColor`、`padding`。
+
+文本片段也可以设置边框和背景的样式：`borderColor`、`borderWidth`、`backgroundColor`、`padding`。
+
+例如：
+
+```js [live]
+option = {
+ series: [
+ {
+ type: 'scatter',
+ symbolSize: 1,
+ data: [
+ {
+ value: [0, 0],
+ label: {
+ normal: {
+ show: true,
+ formatter: [
+ 'Plain text',
+ '{textBorder|textBorderColor + textBorderWidth}',
+ '{textShadow|textShadowColor + textShadowBlur +
textShadowOffsetX + textShadowOffsetY}',
+ '{bg|backgroundColor + borderRadius + padding}',
+ '{border|borderColor + borderWidth + borderRadius + padding}',
+ '{shadow|shadowColor + shadowBlur + shadowOffsetX +
shadowOffsetY}'
+ ].join('\n'),
+ backgroundColor: '#eee',
+ borderColor: '#333',
+ borderWidth: 2,
+ borderRadius: 5,
+ padding: 10,
+ color: '#000',
+ fontSize: 14,
+ shadowBlur: 3,
+ shadowColor: '#888',
+ shadowOffsetX: 0,
+ shadowOffsetY: 3,
+ lineHeight: 30,
+ rich: {
+ textBorder: {
+ fontSize: 20,
+ textBorderColor: '#000',
+ textBorderWidth: 3,
+ color: '#fff'
+ },
+ textShadow: {
+ fontSize: 16,
+ textShadowBlur: 5,
+ textShadowColor: '#000',
+ textShadowOffsetX: 3,
+ textShadowOffsetY: 3,
+ color: '#fff'
+ },
+ bg: {
+ backgroundColor: '#339911',
+ color: '#fff',
+ borderRadius: 15,
+ padding: 5
+ },
+ border: {
+ color: '#000',
+ borderColor: '#449911',
+ borderWidth: 1,
+ borderRadius: 3,
+ padding: 5
+ },
+ shadow: {
+ backgroundColor: '#992233',
+ padding: 5,
+ color: '#fff',
+ shadowBlur: 5,
+ shadowColor: '#336699',
+ shadowOffsetX: 6,
+ shadowOffsetY: 6
+ }
+ }
+ }
+ }
+ }
+ ]
+ }
+ ],
+ xAxis: {
+ axisLabel: { show: false },
+ axisLine: { show: false },
+ splitLine: { show: false },
+ axisTick: { show: false },
+ min: -1,
+ max: 1
+ },
+ yAxis: {
+ axisLabel: { show: false },
+ axisLine: { show: false },
+ splitLine: { show: false },
+ axisTick: { show: false },
+ min: -1,
+ max: 1
+ }
+};
+```
+
+## 标签的位置
+
+对于折线图、柱状图、散点图等，均可以使用 `label` 来设置标签。标签的相对于图形元素的位置，一般使用
[label.position](option.html#series-scatter.label.position)、[label.distance](option.html#series-scatter.label.distance)
来配置。
+
+试试在下面例子中修改`position`和`distance` 属性：
+
+```js [live]
+option = {
+ series: [
+ {
+ type: 'scatter',
+ symbolSize: 160,
+ symbol: 'roundRect',
+ data: [[1, 1]],
+ label: {
+ normal: {
+ // 修改 position 和 distance 的值试试
+ // 支持：'left', 'right', 'top', 'bottom', 'inside', 'insideTop',
'insideLeft', 'insideRight', 'insideBottom', 'insideTopLeft', 'insideTopRight',
'insideBottomLeft', 'insideBottomRight'
+ position: 'top',
+ distance: 10,
+
+ show: true,
+ formatter: ['Label Text'].join('\n'),
+ backgroundColor: '#eee',
+ borderColor: '#555',
+ borderWidth: 2,
+ borderRadius: 5,
+ padding: 10,
+ fontSize: 18,
+ shadowBlur: 3,
+ shadowColor: '#888',
+ shadowOffsetX: 0,
+ shadowOffsetY: 3,
+ textBorderColor: '#000',
+ textBorderWidth: 3,
+ color: '#fff'
+ }
+ }
+ }
+ ],
+ xAxis: {
+ max: 2
+ },
+ yAxis: {
+ max: 2
+ }
+};
+```
+
+> 注意：`position` 在不同的图中可取值有所不同。`distance` 并不是在每个图中都支持。详情请参见 [option
文档](option.html)。
+
+## 标签的旋转
+
+某些图中，为了能有足够长的空间来显示标签，需要对标签进行旋转。例如：
+
+```js [live-lr]
+const labelOption = {
+ show: true,
+ rotate: 90,
+ formatter: '{c} {name|{a}}',
+ fontSize: 16,
+ rich: {
+ name: {}
+ }
+};
+
+option = {
+ xAxis: [
+ {
+ type: 'category',
+ data: ['2012', '2013', '2014', '2015', '2016']
+ }
+ ],
+ yAxis: [
+ {
+ type: 'value'
+ }
+ ],
+ series: [
+ {
+ name: 'Forest',
+ type: 'bar',
+ barGap: 0,
+ label: labelOption,
+ emphasis: {
+ focus: 'series'
+ },
+ data: [320, 332, 301, 334, 390]
+ },
+ {
+ name: 'Steppe',
+ type: 'bar',
+ label: labelOption,
+ emphasis: {
+ focus: 'series'
+ },
+ data: [220, 182, 191, 234, 290]
+ }
+ ]
+};
+```
+
+这种场景下，可以结合 [align](option.html#series-bar.label.align) 和
[verticalAlign](option.html#series-bar.label.verticalAlign) 来调整标签位置。
+
+注意，逻辑是，先使用 `align` 和 `verticalAlign` 定位，再旋转。
+
+## 文本片段的排版和对齐
+
+关于排版方式，每个文本片段，可以想象成 CSS 中的 `inline-block`，在文档流中按行放置。
+
+每个文本片段的内容盒尺寸（`content box size`），默认是根据文字大小决定的。但是，也可以设置 `width`、`height`
来强制指定，虽然一般不会这么做（参见下文）。文本片段的边框盒尺寸（`border box size`），由上述本身尺寸，加上文本片段的 `padding`
来得到。
+
+只有 `'\n'` 是换行符，能导致换行。
+
+一行内，会有多个文本片段。每行的实际高度，由 `lineHeight` 最大的文本片段决定。文本片段的 `lineHeight` 可直接在 `rich`
中指定，也可以在 `rich` 的父层级中统一指定而采用到 `rich` 的所有项中，如果都不指定，则取文本片段的边框盒尺寸（`border box
size`）。
+
+在一行的 `lineHeight` 被决定后，一行内，文本片段的竖直位置，由文本片段的 `verticalAlign` 来指定（这里和 CSS
中的规则稍有不同）：
+
+- `'bottom'`：文本片段的盒的底边贴住行底。
+- `'top'`：文本片段的盒的顶边贴住行顶。
+- `'middle'`：居行中。
+
+文本块的宽度，可以直接由文本块的 `width` 指定，否则，由最长的行决定。宽度决定后，在一行中进行文本片段的放置。文本片段的 `align`
决定了文本片段在行中的水平位置：
+
+- 首先，从左向右连续紧靠放置 `align` 为 `'left'` 的文本片段盒。
+- 然后，从右向左连续紧靠放置 `align` 为 `'right'` 的文本片段盒。
+- 最后，剩余的没处理的文本片段盒，紧贴着，在中间剩余的区域中居中放置。
+
+关于文字在文本片段盒中的位置：
+
+- 如果 `align` 为 `'center'`，则文字在文本片段盒中是居中的。
+- 如果 `align` 为 `'left'`，则文字在文本片段盒中是居左的。
+- 如果 `align` 为 `'right'`，则文字在文本片段盒中是居右的。
+
+## 特殊效果：图标、分割线、标题块、简单表格
+
+看下面的例子：
+
+```js [live-lr]
+option = {
+ series: [
+ {
+ type: 'scatter',
+ data: [
+ {
+ value: [0, 0],
+ label: {
+ normal: {
+ formatter: [
+ '{tc|Center Title}{titleBg|}',
+ ' Content text xxxxxxxx {sunny|} xxxxxxxx {cloudy|} ',
+ '{hr|}',
+ ' xxxxx {showers|} xxxxxxxx xxxxxxxxx '
+ ].join('\n'),
+ rich: {
+ titleBg: {
+ align: 'right'
+ }
+ }
+ }
+ }
+ },
+ {
+ value: [0, 1],
+ label: {
+ normal: {
+ formatter: [
+ '{titleBg|Left Title}',
+ ' Content text xxxxxxxx {sunny|} xxxxxxxx {cloudy|} ',
+ '{hr|}',
+ ' xxxxx {showers|} xxxxxxxx xxxxxxxxx '
+ ].join('\n')
+ }
+ }
+ },
+ {
+ value: [0, 2],
+ label: {
+ normal: {
+ formatter: [
+ '{titleBg|Right Title}',
+ ' Content text xxxxxxxx {sunny|} xxxxxxxx {cloudy|} ',
+ '{hr|}',
+ ' xxxxx {showers|} xxxxxxxx xxxxxxxxx '
+ ].join('\n'),
+ rich: {
+ titleBg: {
+ align: 'right'
+ }
+ }
+ }
+ }
+ }
+ ],
+ symbolSize: 1,
+ label: {
+ normal: {
+ show: true,
+ backgroundColor: '#ddd',
+ borderColor: '#555',
+ borderWidth: 1,
+ borderRadius: 5,
+ color: '#000',
+ fontSize: 14,
+ rich: {
+ titleBg: {
+ backgroundColor: '#000',
+ height: 30,
+ borderRadius: [5, 5, 0, 0],
+ padding: [0, 10, 0, 10],
+ width: '100%',
+ color: '#eee'
+ },
+ tc: {
+ align: 'center',
+ color: '#eee'
+ },
+ hr: {
+ borderColor: '#777',
+ width: '100%',
+ borderWidth: 0.5,
+ height: 0
+ },
+ sunny: {
+ height: 30,
+ align: 'left',
+ backgroundColor: {
+ image:
+
'https://echarts.apache.org/examples/data/asset/img/weather/sunny_128.png'
+ }
+ },
+ cloudy: {
+ height: 30,
+ align: 'left',
+ backgroundColor: {
+ image:
+
'https://echarts.apache.org/examples/data/asset/img/weather/cloudy_128.png'
+ }
+ },
+ showers: {
+ height: 30,
+ align: 'left',
+ backgroundColor: {
+ image:
+
'https://echarts.apache.org/examples/data/asset/img/weather/showers_128.png'
+ }
+ }
+ }
+ }
+ }
+ }
+ ],
+ xAxis: {
+ show: false,
+ min: -1,
+ max: 1
+ },
+ yAxis: {
+ show: false,
+ min: 0,
+ max: 2,
+ inverse: true
+ }
+};
+```
+
+文本片段的 `backgroundColor` 可以指定为图片后，就可以在文本中使用图标了：
+
+```js
+labelOption = {
+ rich: {
+ Sunny: {
+ // 这样设定 backgroundColor 就可以是图片了。
+ backgroundColor: {
+ image: './data/asset/img/weather/sunny_128.png'
+ },
+ // 可以只指定图片的高度，从而图片的宽度根据图片的长宽比自动得到。
+ height: 30
+ }
+ }
+};
+```
+
+分割线实际是用 border 实现的：
+
+```js
+labelOption = {
+ rich: {
+ hr: {
+ borderColor: '#777',
+ // 这里把 width 设置为 '100%'，表示分割线的长度充满文本块。
+ // 注意，这里是文本块内容盒（content box）的 100%，而不包含 padding。
+ // 虽然这和 CSS 相关的定义有所不同，但是在这类场景中更加方便。
+ width: '100%',
+ borderWidth: 0.5,
+ height: 0
+ }
+ }
+};
+```
+
+标题块是使用 `backgroundColor` 实现的：
+
+```js
+labelOption = {
+ // 标题文字居左
+ formatter: '{titleBg|Left Title}',
+ rich: {
+ titleBg: {
+ backgroundColor: '#000',
+ height: 30,
+ borderRadius: [5, 5, 0, 0],
+ padding: [0, 10, 0, 10],
+ width: '100%',
+ color: '#eee'
+ }
+ }
+};
+
+// 标题文字居中。
+// 这个实现有些 tricky，但是，能够不引入更复杂的排版规则而实现这个效果。
+labelOption = {
+ formatter: '{tc|Center Title}{titleBg|}',
+ rich: {
+ titleBg: {
+ align: 'right',
+ backgroundColor: '#000',
+ height: 30,
+ borderRadius: [5, 5, 0, 0],
+ padding: [0, 10, 0, 10],
+ width: '100%',
+ color: '#eee'
+ }
+ }
+};
+```
+
+简单表格的设定，其实就是给不同行上纵向对应的文本片段设定同样的宽度就可以了。
diff --git a/contents/zh/basics/download.md b/contents/zh/basics/download.md
index 02e7bd7..6fc0906 100644
--- a/contents/zh/basics/download.md
+++ b/contents/zh/basics/download.md
@@ -1,23 +1,16 @@
-# 下载
+# 获取 Apache ECharts
Apache ECharts 提供了多种安装方式，你可以根据项目的实际情况选择以下任意一种方式安装。
-1. 从官网获取
-2. 从 GitHub 获取
-3. 从 npm 获取
-4. 从 CDN 获取
-5. 在线定制
+- 从 GitHub 获取
+- 从 npm 获取
+- 从 CDN 获取
+- 在线定制
接下来我们将分别介绍这些安装方式，以及下载后的目录结构。
## 安装方式
-### 从官网获取
-
-[Apache ECharts 官网下载界面](https://echarts.apache.org/download.html)
提供了镜像网站下载源码，并且核对签名的方式——这可以保证下载的代码与发布的代码一致。
-
-具体的方法参见[官网下载页面](${mainSitePath}/download.html)。
-
### 从 GitHub 获取
[apache/echarts](https://github.com/apache/echarts) 项目的
[release](https://github.com/apache/echarts/releases) 页面可以找到各个版本的链接。点击下载页面下方
Assets 中的 Source code，解压后 `dist` 目录下的 `echarts.js` 即为包含完整 ECharts 功能的文件。
@@ -28,23 +21,12 @@ Apache ECharts 提供了多种安装方式，你可以根据项目的实际情
npm install echarts --save
```
-详见[在 webpack 中使用
echarts](https://echarts.apache.org/tutorial.html#%E5%9C%A8%20webpack%20%E4%B8%AD%E4%BD%BF%E7%94%A8%20ECharts)。
+详见[在项目中引入 Apache ECharts](${lang}/basics/import)。
### 从 CDN 获取
-在 jsDelivr 的 [echarts](https://www.jsdelivr.com/package/npm/echarts) 项目中找到
`dist/echarts.js`，下载到本地使用。
+推荐从 jsDelivr 引用 [echarts](https://www.jsdelivr.com/package/npm/echarts)。
### 在线定制
如果只想引入部分模块以减少包体积，可以使用 [ECharts 在线定制](${mainSitePath}/builder.html)功能。
-
-## 目录结构
-
-下面介绍项目 [`dist`](https://github.com/apache/echarts/tree/master/dist) 目录下各个文件的意义：
-
-- `echarts.js`：包含了完整 ECharts 功能的代码，没有经过压缩；推荐调试时使用。
-- `echarts.min.js`：`echarts.js` 的压缩结果；推荐线上使用。
-- `echarts.simple.js`：包含折线图、柱状图、饼图的代码；推荐不需要其他系列类型的项目使用。
-- `echarts.common.js`：包含了常用组件和系列类型的代码，完整支持的内容参见
[echarts.common.js](https://github.com/apache/echarts/blob/master/echarts.common.js)
-
-带有 `-en` 的文件是对应的英文版本，带有 `.min` 的文件是对应的压缩版本。
diff --git a/contents/zh/basics/import.md b/contents/zh/basics/import.md
new file mode 100644
index 0000000..db50498
--- /dev/null
+++ b/contents/zh/basics/import.md
@@ -0,0 +1,115 @@
+# 在项目中引入 Apache ECharts
+
+假如你的开发环境使用了`npm`或者`yarn`等包管理工具，并且使用 Webpack 等打包工具进行构建，本文将会介绍如何引入 Apache
ECharts<sup>TM</sup> 并通过 treeshaking 特性只打包需要的模块。
+
+## NPM 安装 ECharts
+
+你可以使用如下命令通过 npm 安装 ECharts
+
+```shell
+npm install echarts --save
+```
+
+## 引入 ECharts
+
+```js
+import * as echarts from '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 图表和组件
+
+上面的代码会引入所有 ECharts 中所有的图表和组件，但是假如你不想引入所有组件，也可以使用 ECharts 提供的按需引入的接口来打包必须的组件。
+
+```js
+// 引入 echarts 核心模块，核心模块提供了 echarts 使用必须要的接口。
+import * as echarts from 'echarts/core';
+// 引入柱状图图表，图表后缀都为 Chart
+import {
+ BarChart
+} from 'echarts/charts';
+// 引入提示框，标题，直角坐标系组件，组件后缀都为 Component
+import {
+ TitleComponent,
+ TooltipComponent,
+ GridComponent
+} from 'echarts/components';
+// 引入 Canvas 渲染器，注意引入 CanvasRenderer 或者 SVGRenderer 是必须的一步
+import {
+ CanvasRenderer
+} from 'echarts/renderers';
+
+// 注册必须的组件
+echarts.use(
+ [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]
+);
+
+// 接下来的使用就跟之前一样，初始化图表，设置配置项
+var myChart = echarts.init(document.getElementById('main'));
+myChart.setOption({
+ ...
+});
+```
+
+> 需要注意的是注意为了保证打包的体积是最小的，ECharts
按需引入的时候不再提供任何渲染器，所以需要选择引入`CanvasRenderer`或者`SVGRenderer`作为渲染器。这样的好处是假如你只需要使用
svg 渲染模式，打包的结果中就不会再包含无需使用的`CanvasRenderer`模块。
+
+我们在示例编辑页的“完整代码”标签提供了非常方便的生成按需引入代码的功能。这个功能会根据当前的配置项动态生成最小的按需引入的代码。你可以直接在你的项目中使用。
+
+## 在 TypeScript 中按需引入
+
+对于使用了 TypeScript 来开发 ECharts
的开发者，我们提供了类型接口来组合出最小的`EChartsOption`类型。这个更严格的类型可以有效帮助你检查出是否少加载了组件或者图表。
+
+```ts
+import * as echarts from 'echarts/core';
+import {
+ BarChart,
+ // 系列类型的定义后缀都为 SeriesOption
+ BarSeriesOption,
+ LineChart,
+ LineSeriesOption
+} from 'echarts/charts';
+import {
+ TitleComponent,
+ // 组件类型的定义后缀都为 ComponentOption
+ TitleComponentOption,
+ GridComponent,
+ GridComponentOption
+} from 'echarts/components';
+import {
+ CanvasRenderer
+} from 'echarts/renderers';
+
+// 通过 ComposeOption 来组合出一个只有必须组件和图表的 Option 类型
+type ECOption = echarts.ComposeOption<
+ BarSeriesOption | LineSeriesOption | TitleComponentOption |
GridComponentOption
+>;
+
+// 注册必须的组件
+echarts.use(
+ [TitleComponent, TooltipComponent, GridComponent, BarChart, CanvasRenderer]
+);
+
+var option: ECOption = {
+ ...
+}
+```
diff --git a/contents/zh/basics/inspiration.md
b/contents/zh/basics/inspiration.md
index b91438b..82ceb39 100644
--- a/contents/zh/basics/inspiration.md
+++ b/contents/zh/basics/inspiration.md
@@ -4,4 +4,4 @@
- [ECharts 官方实例](${mainSitePath}/examples/zh/index.html)
- 本手册的“应用篇 - 常用图表类型”
-- [makeapie.com](https://www.makeapie.com/)
+- [makeapie.com](https://www.makeapie.com/) 社区用户的作品集
diff --git a/contents/zh/basics/resource.md b/contents/zh/basics/resource.md
index 2531681..ae5139e 100644
--- a/contents/zh/basics/resource.md
+++ b/contents/zh/basics/resource.md
@@ -9,5 +9,5 @@
## 社区
-- [ECharts Gallery](https://gallery.echartsjs.com/)：社区用户的作品集
+- [MakeAPie](https://www.makeapie.com)：社区用户的作品集
- [awesome-echarts](https://github.com/ecomfe/awesome-echarts)：各种 ECharts
相关的资源，包括 AngularJS、Vue 等框架的支持，Java、Python、R 等语言的 ECharts 版本，ECharts VSCode 插件等工具
diff --git a/contents/zh/best-practice/canvas-vs-svg.md
b/contents/zh/best-practice/canvas-vs-svg.md
index 2f70881..14f2cad 100644
--- a/contents/zh/best-practice/canvas-vs-svg.md
+++ b/contents/zh/best-practice/canvas-vs-svg.md
@@ -2,38 +2,44 @@
浏览器端图表库大多会选择 SVG 或者 Canvas
进行渲染。对于绘制图表来说，这两种技术往往是可替换的，效果相近。但是在一些场景中，他们的表现和能力又有一定差异。于是，对它们的选择取舍，就成为了一个一直存在的不易有标准答案的话题。
-ECharts 从初始一直使用 Canvas 绘制图表（除了对 IE8- 使用 VML）。而 [ECharts
v4.0](https://github.com/apache/echarts/releases) 发布了 SVG
渲染器，从而提供了一种新的选择。只须在初始化一个图表实例时，设置 [renderer
参数](http://echarts.baidu.com/api.html#echarts.init) 为 `'canvas'` 或 `'svg'`
即可指定渲染器，比较方便。
+ECharts 从初始一直使用 Canvas 绘制图表。而 [ECharts
v4.0](https://github.com/apache/echarts/releases) 发布了 SVG
渲染器，从而提供了一种新的选择。只须在初始化一个图表实例时，设置 [renderer
参数](${mainSitePath}/api.html#echarts.init) 为 `'canvas'` 或 `'svg'` 即可指定渲染器，比较方便。
> SVG 和 Canvas 这两种使用方式差异很大的技术，能够做到同时被透明支持，主要归功于 ECharts 底层库
> [ZRender](https://github.com/ecomfe/zrender) 的抽象和实现，形成可互换的 SVG 渲染器和 Canvas
> 渲染器。
## 选择哪种渲染器
-一般来说，Canvas
更适合绘制图形元素数量非常大（这一般是由数据量大导致）的图表（如热力图、地理坐标系或平行坐标系上的大规模线图或散点图等），也利于实现某些视觉
[特效](examples/editor.html?c=lines-bmap-effect)。但是，在不少场景中，SVG
具有重要的优势：它的内存占用更低（这对移动端尤其重要）、渲染性能略高、并且用户使用浏览器内置的缩放功能时不会模糊。
+一般来说，Canvas
更适合绘制图形元素数量较多（这一般是由数据量大导致）的图表（如热力图、地理坐标系或平行坐标系上的大规模线图或散点图等），也利于实现某些视觉
[特效](${mainSitePath}/examples/editor.html?c=lines-bmap-effect)。但是，在不少场景中，SVG
具有重要的优势：它的内存占用更低（这对移动端尤其重要）、并且用户使用浏览器内置的缩放功能时不会模糊。
选择哪种渲染器，我们可以根据软硬件环境、数据量、功能需求综合考虑。
-- 在软硬件环境较好，数据量不大的场景下（例如 PC 端做商务报表），两种渲染器都可以适用，并不需要太多纠结。
+- 在软硬件环境较好，数据量不大的场景下，两种渲染器都可以适用，并不需要太多纠结。
- 在环境较差，出现性能问题需要优化的场景下，可以通过试验来确定使用哪种渲染器。比如有这些经验：
- 在须要创建很多 ECharts 实例且浏览器易崩溃的情况下（可能是因为 Canvas 数量多导致内存占用超出手机承受能力），可以使用 SVG
渲染器来进行改善。大略得说，如果图表运行在低端安卓机，或者我们在使用一些特定图表如
[水球图](https://ecomfe.github.io/echarts-liquidfill/example/) 等，SVG 渲染器可能效果更好。
- - 数据量很大、较多交互时，可以选用 Canvas 渲染器。
+ - 数据量较大（经验判断 > 1k）、较多交互时，建议选择 Canvas 渲染器。
我们强烈欢迎开发者们[反馈](https://github.com/apache/echarts/issues/new)给我们使用的体验和场景，帮助我们更好的做优化。
-注：除了某些特殊的渲染可能依赖
Canvas：如[炫光尾迹特效](option.html#series-lines.effect)、[带有混合效果的热力图](examples/editor.html?c=heatmap-bmap)等，绝大部分功能
SVG 都是支持的。
+注：当前某些特殊的渲染依然需要依赖
Canvas：如[炫光尾迹特效](${optionPath}series-lines.effect)、[带有混合效果的热力图](examples/editor.html?c=heatmap-bmap)等。
## 如何使用渲染器
-ECharts 默认使用 Canvas 渲染。如果想使用 SVG 渲染，ECharts 代码中须包括有 SVG 渲染器模块。
+如果是用如下的方式完整引入`echarts`，代码中已经包含了 SVG 渲染器和 Canvas 渲染器
-- ECharts 的[预构建文件](https://www.jsdelivr.com/package/npm/echarts)
中，[常用版](https://cdn.jsdelivr.net/npm/echarts/dist/echarts.common.min.js) 和
[完整版](https://cdn.jsdelivr.net/npm/echarts/dist/echarts.min.js) 已经包含了 SVG
渲染器，可直接使用。而
[精简版](https://cdn.jsdelivr.net/npm/echarts/dist/echarts.simple.min.js) 没有包括。
-- 如果[在线自定义构建 ECharts](builder.html)，则需要勾上页面下方的 “SVG 渲染”。
-- 如果[线下自定义构建
ECharts](tutorial.html#%E8%87%AA%E5%AE%9A%E4%B9%89%E6%9E%84%E5%BB%BA%20ECharts)，则须引入
SVG 渲染器模块，即：
+```js
+import * as echarts from 'echarts';
+```
+
+如果你是按照 [在项目中引入 Apache ECharts](${lang}/basics/import)
一文中的介绍使用按需引入，则需要手动引入需要的渲染器
```js
-import 'zrender/lib/svg/svg';
+import * as echarts from 'echarts/core';
+// 可以根据需要选用只用到的渲染器
+import { SVGRenderer, CanvasRenderer } from 'echarts/renderers';
+
+echarts.use([SVGRenderer, CanvasRenderer]);
```
-然后，我们就可以在代码中，初始化图表实例时，[传入参数](api.html#echarts.init) 选择渲染器类型：
+然后，我们就可以在代码中，初始化图表实例时，[传入参数](${mainSitePath}/api.html/api.html#echarts.init)
选择渲染器类型：
```js
// 使用 Canvas 渲染器（默认）
diff --git a/contents/zh/concepts/axis.md b/contents/zh/concepts/axis.md
index 5ea6f0f..baa50a4 100644
--- a/contents/zh/concepts/axis.md
+++ b/contents/zh/concepts/axis.md
@@ -173,9 +173,86 @@ option = {
图左侧的 y 轴代表东京月平均气温，右侧的 y 轴表示东京降水量，x 轴表示时间。两组 y 轴在一起，反映了平均气温和降水量间的趋势关系。
-<!-- src 需要替换 -->
-<iframe max-width="830" width="100%" height="400"
- src="https://gallery.echartsjs.com/view-lite.html?cid=xrJYBh__4z";>
-</iframe>
+```js [live]
+option = {
+ tooltip: {
+ trigger: 'axis',
+ axisPointer: { type: 'cross' }
+ },
+ legend: {},
+ xAxis: [
+ {
+ type: 'category',
+ axisTick: {
+ alignWithLabel: true
+ },
+ data: [
+ '1月',
+ '2月',
+ '3月',
+ '4月',
+ '5月',
+ '6月',
+ '7月',
+ '8月',
+ '9月',
+ '10月',
+ '11月',
+ '12月'
+ ]
+ }
+ ],
+ yAxis: [
+ {
+ type: 'value',
+ name: '降水量',
+ min: 0,
+ max: 250,
+ position: 'right',
+ axisLabel: {
+ formatter: '{value} ml'
+ }
+ },
+ {
+ type: 'value',
+ name: '温度',
+ min: 0,
+ max: 25,
+ position: 'left',
+ axisLabel: {
+ formatter: '{value} °C'
+ }
+ }
+ ],
+ series: [
+ {
+ name: '降水量',
+ type: 'bar',
+ yAxisIndex: 0,
+ data: [6, 32, 70, 86, 68.7, 100.7, 125.6, 112.2, 78.7, 48.8, 36.0, 19.3]
+ },
+ {
+ name: '温度',
+ type: 'line',
+ smooth: true,
+ yAxisIndex: 1,
+ data: [
+ 6.0,
+ 10.2,
+ 10.3,
+ 11.5,
+ 10.3,
+ 13.2,
+ 14.3,
+ 16.4,
+ 18.0,
+ 16.5,
+ 12.0,
+ 5.2
+ ]
+ }
+ ]
+};
+```
这里简要介绍了坐标轴相关的常用配置项及用法，更多关于坐标轴配置项及用法请移步[官网](${optionPath}xAxis)。
diff --git a/contents/zh/concepts/data-transform.md
b/contents/zh/concepts/data-transform.md
index 5638880..6ee2cf8 100644
--- a/contents/zh/concepts/data-transform.md
+++ b/contents/zh/concepts/data-transform.md
@@ -325,27 +325,32 @@ option = {
```js
option = {
- dataset: [{
- source: [...]
- }, {
- transform: {
- type: 'filter',
- config: {
- // 使用 and 操作符。
- // 类似地，同样的位置也可以使用 “or” 或 “not”。
- // 但是注意 “not” 后应该跟一个 {...} 而非 [...] 。
- and: [
- { dimension: 'Year', '=': 2011 },
- { dimension: 'Price', '>=': 20, '<': 30 }
- ]
- }
- // 这个表达的是，选出 2011 年价格大于等于 20 但小于 30 的数据项。
+ dataset: [
+ {
+ source: [
+ // ...
+ ]
+ },
+ {
+ transform: {
+ type: 'filter',
+ config: {
+ // 使用 and 操作符。
+ // 类似地，同样的位置也可以使用 “or” 或 “not”。
+ // 但是注意 “not” 后应该跟一个 {...} 而非 [...] 。
+ and: [
+ { dimension: 'Year', '=': 2011 },
+ { dimension: 'Price', '>=': 20, '<': 30 }
+ ]
}
- }],
- series: {
- type: 'pie',
- datasetIndex: 1
+ // 这个表达的是，选出 2011 年价格大于等于 20 但小于 30 的数据项。
+ }
}
+ ],
+ series: {
+ type: 'pie',
+ datasetIndex: 1
+ }
};
```
@@ -353,26 +358,26 @@ option = {
```js
transform: {
- type: 'filter',
- config: {
- or: [{
- and: [{
- dimension: 'Price', '>=': 10, '<': 20
- }, {
- dimension: 'Sales', '<': 100
- }, {
- not: { dimension: 'Product', '=': 'Tofu' }
- }]
- }, {
- and: [{
- dimension: 'Price', '>=': 10, '<': 20
- }, {
- dimension: 'Sales', '<': 100
- }, {
- not: { dimension: 'Product', '=': 'Cake' }
- }]
- }]
- }
+ type: 'filter',
+ config: {
+ or: [{
+ and: [{
+ dimension: 'Price', '>=': 10, '<': 20
+ }, {
+ dimension: 'Sales', '<': 100
+ }, {
+ not: { dimension: 'Product', '=': 'Tofu' }
+ }]
+ }, {
+ and: [{
+ dimension: 'Price', '>=': 10, '<': 20
+ }, {
+ dimension: 'Sales', '<': 100
+ }, {
+ not: { dimension: 'Product', '=': 'Cake' }
+ }]
+ }]
+ }
}
```
@@ -388,26 +393,32 @@ transform: {
```js
option = {
- dataset: [{
- source: [
- ['Product', 'Sales', 'Price', 'Date'],
- ['Milk Tee', 311, 21, '2012-05-12'],
- ['Cake', 135, 28, '2012-05-22'],
- ['Latte', 262, 36, '2012-06-02'],
- ['Milk Tee', 359, 21, '2012-06-22'],
- ['Cake', 121, 28, '2012-07-02'],
- ['Latte', 271, 36, '2012-06-22'],
- ...
- ]
- }, {
- transform: {
- type: 'filter',
- config: {
- { dimension: 'Date', '>=': '2012-05', '<': '2012-06', parser:
'time' }
- }
+ dataset: [
+ {
+ source: [
+ ['Product', 'Sales', 'Price', 'Date'],
+ ['Milk Tee', 311, 21, '2012-05-12'],
+ ['Cake', 135, 28, '2012-05-22'],
+ ['Latte', 262, 36, '2012-06-02'],
+ ['Milk Tee', 359, 21, '2012-06-22'],
+ ['Cake', 121, 28, '2012-07-02'],
+ ['Latte', 271, 36, '2012-06-22']
+ // ...
+ ]
+ },
+ {
+ transform: {
+ type: 'filter',
+ config: {
+ dimension: 'Date',
+ '>=': '2012-05',
+ '<': '2012-06',
+ parser: 'time'
}
- }]
-}
+ }
+ }
+ ]
+};
```
**形式化定义：**
@@ -458,31 +469,34 @@ type DimensionIndex = number;
```js
option = {
- dataset: [{
- dimensions: ['name', 'age', 'profession', 'score', 'date'],
- source: [
- [' Hannah Krause ', 41, 'Engineer', 314, '2011-02-12'],
- ['Zhao Qian ', 20, 'Teacher', 351, '2011-03-01'],
- [' Jasmin Krause ', 52, 'Musician', 287, '2011-02-14'],
- ['Li Lei', 37, 'Teacher', 219, '2011-02-18'],
- [' Karle Neumann ', 25, 'Engineer', 253, '2011-04-02'],
- [' Adrian Groß', 19, 'Teacher', null, '2011-01-16'],
- ['Mia Neumann', 71, 'Engineer', 165, '2011-03-19'],
- [' Böhm Fuchs', 36, 'Musician', 318, '2011-02-24'],
- ['Han Meimei ', 67, 'Engineer', 366, '2011-03-12'],
- ]
- }, {
- transform: {
- type: 'sort',
- // 按分数排序
- config: { dimension: 'score', order: 'asc' }
- }
- }],
- series: {
- type: 'bar',
- datasetIndex: 1
+ dataset: [
+ {
+ dimensions: ['name', 'age', 'profession', 'score', 'date'],
+ source: [
+ [' Hannah Krause ', 41, 'Engineer', 314, '2011-02-12'],
+ ['Zhao Qian ', 20, 'Teacher', 351, '2011-03-01'],
+ [' Jasmin Krause ', 52, 'Musician', 287, '2011-02-14'],
+ ['Li Lei', 37, 'Teacher', 219, '2011-02-18'],
+ [' Karle Neumann ', 25, 'Engineer', 253, '2011-04-02'],
+ [' Adrian Groß', 19, 'Teacher', null, '2011-01-16'],
+ ['Mia Neumann', 71, 'Engineer', 165, '2011-03-19'],
+ [' Böhm Fuchs', 36, 'Musician', 318, '2011-02-24'],
+ ['Han Meimei ', 67, 'Engineer', 366, '2011-03-12']
+ ]
},
- ...
+ {
+ transform: {
+ type: 'sort',
+ // 按分数排序
+ config: { dimension: 'score', order: 'asc' }
+ }
+ }
+ ],
+ series: {
+ type: 'bar',
+ datasetIndex: 1
+ }
+ // ...
};
```
@@ -503,34 +517,37 @@ option = {
```js
option = {
- dataset: [{
- dimensions: ['name', 'age', 'profession', 'score', 'date'],
- source: [
- [' Hannah Krause ', 41, 'Engineer', 314, '2011-02-12'],
- ['Zhao Qian ', 20, 'Teacher', 351, '2011-03-01'],
- [' Jasmin Krause ', 52, 'Musician', 287, '2011-02-14'],
- ['Li Lei', 37, 'Teacher', 219, '2011-02-18'],
- [' Karle Neumann ', 25, 'Engineer', 253, '2011-04-02'],
- [' Adrian Groß', 19, 'Teacher', null, '2011-01-16'],
- ['Mia Neumann', 71, 'Engineer', 165, '2011-03-19'],
- [' Böhm Fuchs', 36, 'Musician', 318, '2011-02-24'],
- ['Han Meimei ', 67, 'Engineer', 366, '2011-03-12'],
- ]
- }, {
- transform: {
- type: 'sort',
- config: [
- // 对两个维度按声明的优先级分别排序。
- { dimension: 'profession', order: 'desc' },
- { dimension: 'score', order: 'desc' }
- ]
- }
- }],
- series: {
- type: 'bar',
- datasetIndex: 1
+ dataset: [
+ {
+ dimensions: ['name', 'age', 'profession', 'score', 'date'],
+ source: [
+ [' Hannah Krause ', 41, 'Engineer', 314, '2011-02-12'],
+ ['Zhao Qian ', 20, 'Teacher', 351, '2011-03-01'],
+ [' Jasmin Krause ', 52, 'Musician', 287, '2011-02-14'],
+ ['Li Lei', 37, 'Teacher', 219, '2011-02-18'],
+ [' Karle Neumann ', 25, 'Engineer', 253, '2011-04-02'],
+ [' Adrian Groß', 19, 'Teacher', null, '2011-01-16'],
+ ['Mia Neumann', 71, 'Engineer', 165, '2011-03-19'],
+ [' Böhm Fuchs', 36, 'Musician', 318, '2011-02-24'],
+ ['Han Meimei ', 67, 'Engineer', 366, '2011-03-12']
+ ]
},
- ...
+ {
+ transform: {
+ type: 'sort',
+ config: [
+ // 对两个维度按声明的优先级分别排序。
+ { dimension: 'profession', order: 'desc' },
+ { dimension: 'score', order: 'desc' }
+ ]
+ }
+ }
+ ],
+ series: {
+ type: 'bar',
+ datasetIndex: 1
+ }
+ //...
};
```
diff --git a/contents/zh/concepts/event.md b/contents/zh/concepts/event.md
index a6aa915..21ddddd 100644
--- a/contents/zh/concepts/event.md
+++ b/contents/zh/concepts/event.md
@@ -1,8 +1,8 @@
# 事件与行为
-在 ECharts
的图表中用户的操作将会触发相应的事件。开发者可以监听这些事件，然后通过回调函数做相应的处理，比如跳转到一个地址，或者弹出对话框，或者做数据下钻等等。
+在 Apache ECharts
的图表中用户的操作将会触发相应的事件。开发者可以监听这些事件，然后通过回调函数做相应的处理，比如跳转到一个地址，或者弹出对话框，或者做数据下钻等等。
-从 ECharts 3 开始，事件名称对应 DOM 事件名称，均为小写的字符串，如下是一个绑定点击操作的示例。
+ECharts 中的事件名称对应 DOM 事件名称，均为小写的字符串，如下是一个绑定点击操作的示例。
```js
myChart.on('click', function(params) {
diff --git a/contents/zh/concepts/legend.md b/contents/zh/concepts/legend.md
index a988e4e..1dd68dc 100644
--- a/contents/zh/concepts/legend.md
+++ b/contents/zh/concepts/legend.md
@@ -134,11 +134,3 @@ option = {
```
当图表只有一种数据信息时，用图表标题说明数据信息即可。建议此时不要加上图例。
-
-## 示例
-
-<iframe max-width="830" width="100%" height="400"
- src="https://gallery.echartsjs.com/preview.html?c=xkyleg0ydW&v=2";>
-</iframe>
-
-这里简要介绍了坐标轴相关的常用配置项及用法，更多关于坐标轴配置项及用法请移步[官网](${optionPath}legend)
diff --git a/contents/zh/concepts/style.md b/contents/zh/concepts/style.md
new file mode 100644
index 0000000..ba2ef00
--- /dev/null
+++ b/contents/zh/concepts/style.md
@@ -0,0 +1,324 @@
+# ECharts 中的样式简介
+
+本文主要是大略概述，用哪些方法，可以在 Apache ECharts<sup>TM</sup> 中设置样式，改变图形元素或者文字的颜色、明暗、大小等。
+
+> 之所以用“样式”这种可能不很符合数据可视化思维的词，是因为，比较通俗易懂。
+
+本文介绍这几种方式，他们的功能范畴可能会有交叉（即同一种细节的效果可能可以用不同的方式实现），但是他们各有各的场景偏好。
+
+- 颜色主题（Theme）
+- 调色盘
+- 直接样式设置（itemStyle、lineStyle、areaStyle、label、...）
+- 视觉映射（visualMap）
+
+## 颜色主题（Theme）
+
+最简单的更改全局样式的方式，是直接采用颜色主题（theme）。例如，在
[示例集合](${websitePath}/examples/zh/index.html) 中，可以选择 “Theme”，直接看到采用主题的效果。
+
+ECharts4 开始，除了一贯的默认主题外，新内置了两套主题，分别为 `'light'` 和 `'dark'`。可以这么来使用它们：
+
+```js
+var chart = echarts.init(dom, 'light');
+```
+
+或者
+
+```js
+var chart = echarts.init(dom, 'dark');
+```
+
+其他的主题，没有内置在 ECharts 中，需要自己加载。这些主题可以在
[主题编辑器](https://echarts.apache.org/zh/theme-builder.html)
里访问到。也可以使用这个主题编辑器，自己编辑主题。下载下来的主题可以这样使用：
+
+如果主题保存为 JSON 文件，那么可以自行加载和注册，例如：
+
+```js
+// 假设主题名称是 "vintage"
+$.getJSON('xxx/xxx/vintage.json', function(themeJSON) {
+ echarts.registerTheme('vintage', JSON.parse(themeJSON));
+ var chart = echarts.init(dom, 'vintage');
+});
+```
+
+如果保存为 UMD 格式的 JS 文件，那么支持了自注册，直接引入 JS 文件即可：
+
+```js
+// HTML 引入 vintage.js 文件后（假设主题名称是 "vintage"）
+var chart = echarts.init(dom, 'vintage');
+// ...
+```
+
+## 调色盘
+
+调色盘，可以在 option 中设置。它给定了一组颜色，图形、系列会自动从其中选择颜色。
+可以设置全局的调色盘，也可以设置系列自己专属的调色盘。
+
+```js
+option = {
+ // 全局调色盘。
+ color: ['#c23531','#2f4554', '#61a0a8', '#d48265', '#91c7ae','#749f83',
'#ca8622', '#bda29a','#6e7074', '#546570', '#c4ccd3'],
+
+ series: [{
+ type: 'bar',
+ // 此系列自己的调色盘。
+ color:
['#dd6b66','#759aa0','#e69d87','#8dc1a9','#ea7e53','#eedd78','#73a373','#73b9bc','#7289ab',
'#91ca8c','#f49f42'],
+ ...
+ }, {
+ type: 'pie',
+ // 此系列自己的调色盘。
+ color: ['#37A2DA', '#32C5E9', '#67E0E3', '#9FE6B8',
'#FFDB5C','#ff9f7f', '#fb7293', '#E062AE', '#E690D1', '#e7bcf3', '#9d96f5',
'#8378EA', '#96BFFF'],
+ ...
+ }]
+}
+```
+
+## 直接的样式设置 itemStyle, lineStyle, areaStyle, label, ...
+
+直接的样式设置是比较常用设置方式。纵观 ECharts 的 [option](${optionPath}) 中，很多地方可以设置
[itemStyle](${optionPath}#series-bar.itemStyle)、[lineStyle](${optionPath}#series-line.lineStyle)、[areaStyle](${optionPath}#series-line.areaStyle)、[label](${optionPath}#series-bar.label)
等等。这些的地方可以直接设置图形元素的颜色、线宽、点的大小、标签的文字、标签的样式等等。
+
+一般来说，ECharts 的各个系列和组件，都遵从这些命名习惯，虽然不同图表和组件中，`itemStyle`、`label` 等可能出现在不同的地方。
+
+在下面例子中我们给气泡图设置了阴影，渐变色等复杂的样式，你可以修改代码中的样式看修改后的效果：
+
+```js [live]
+var data = [
+ [
+ [28604, 77, 17096869, 'Australia', 1990],
+ [31163, 77.4, 27662440, 'Canada', 1990],
+ [1516, 68, 1154605773, 'China', 1990],
+ [13670, 74.7, 10582082, 'Cuba', 1990],
+ [28599, 75, 4986705, 'Finland', 1990],
+ [29476, 77.1, 56943299, 'France', 1990],
+ [31476, 75.4, 78958237, 'Germany', 1990],
+ [28666, 78.1, 254830, 'Iceland', 1990],
+ [1777, 57.7, 870601776, 'India', 1990],
+ [29550, 79.1, 122249285, 'Japan', 1990],
+ [2076, 67.9, 20194354, 'North Korea', 1990],
+ [12087, 72, 42972254, 'South Korea', 1990],
+ [24021, 75.4, 3397534, 'New Zealand', 1990],
+ [43296, 76.8, 4240375, 'Norway', 1990],
+ [10088, 70.8, 38195258, 'Poland', 1990],
+ [19349, 69.6, 147568552, 'Russia', 1990],
+ [10670, 67.3, 53994605, 'Turkey', 1990],
+ [26424, 75.7, 57110117, 'United Kingdom', 1990],
+ [37062, 75.4, 252847810, 'United States', 1990]
+ ],
+ [
+ [44056, 81.8, 23968973, 'Australia', 2015],
+ [43294, 81.7, 35939927, 'Canada', 2015],
+ [13334, 76.9, 1376048943, 'China', 2015],
+ [21291, 78.5, 11389562, 'Cuba', 2015],
+ [38923, 80.8, 5503457, 'Finland', 2015],
+ [37599, 81.9, 64395345, 'France', 2015],
+ [44053, 81.1, 80688545, 'Germany', 2015],
+ [42182, 82.8, 329425, 'Iceland', 2015],
+ [5903, 66.8, 1311050527, 'India', 2015],
+ [36162, 83.5, 126573481, 'Japan', 2015],
+ [1390, 71.4, 25155317, 'North Korea', 2015],
+ [34644, 80.7, 50293439, 'South Korea', 2015],
+ [34186, 80.6, 4528526, 'New Zealand', 2015],
+ [64304, 81.6, 5210967, 'Norway', 2015],
+ [24787, 77.3, 38611794, 'Poland', 2015],
+ [23038, 73.13, 143456918, 'Russia', 2015],
+ [19360, 76.5, 78665830, 'Turkey', 2015],
+ [38225, 81.4, 64715810, 'United Kingdom', 2015],
+ [53354, 79.1, 321773631, 'United States', 2015]
+ ]
+];
+
+option = {
+ backgroundColor: {
+ type: 'radial',
+ x: 0.3,
+ y: 0.3,
+ r: 0.8,
+ colorStops: [
+ {
+ offset: 0,
+ color: '#f7f8fa'
+ },
+ {
+ offset: 1,
+ color: '#cdd0d5'
+ }
+ ]
+ },
+ grid: {
+ left: 10,
+ containLabel: true,
+ bottom: 10,
+ top: 10,
+ right: 30
+ },
+ xAxis: {
+ splitLine: {
+ show: false
+ }
+ },
+ yAxis: {
+ splitLine: {
+ show: false
+ },
+ scale: true
+ },
+ series: [
+ {
+ name: '1990',
+ data: data[0],
+ type: 'scatter',
+ symbolSize: function(data) {
+ return Math.sqrt(data[2]) / 5e2;
+ },
+ emphasis: {
+ focus: 'series',
+ label: {
+ show: true,
+ formatter: function(param) {
+ return param.data[3];
+ },
+ position: 'top'
+ }
+ },
+ itemStyle: {
+ shadowBlur: 10,
+ shadowColor: 'rgba(120, 36, 50, 0.5)',
+ shadowOffsetY: 5,
+ color: {
+ type: 'radial',
+ x: 0.4,
+ y: 0.3,
+ r: 1,
+ colorStops: [
+ {
+ offset: 0,
+ color: 'rgb(251, 118, 123)'
+ },
+ {
+ offset: 1,
+ color: 'rgb(204, 46, 72)'
+ }
+ ]
+ }
+ }
+ },
+ {
+ name: '2015',
+ data: data[1],
+ type: 'scatter',
+ symbolSize: function(data) {
+ return Math.sqrt(data[2]) / 5e2;
+ },
+ emphasis: {
+ focus: 'series',
+ label: {
+ show: true,
+ formatter: function(param) {
+ return param.data[3];
+ },
+ position: 'top'
+ }
+ },
+ itemStyle: {
+ shadowBlur: 10,
+ shadowColor: 'rgba(25, 100, 150, 0.5)',
+ shadowOffsetY: 5,
+ color: {
+ type: 'radial',
+ x: 0.4,
+ y: 0.3,
+ r: 1,
+ colorStops: [
+ {
+ offset: 0,
+ color: 'rgb(129, 227, 238)'
+ },
+ {
+ offset: 1,
+ color: 'rgb(25, 183, 207)'
+ }
+ ]
+ }
+ }
+ }
+ ]
+};
+```
+
+## 高亮的样式：emphasis
+
+在鼠标悬浮到图形元素上时，一般会出现高亮的样式。默认情况下，高亮的样式是根据普通样式自动生成的。但是高亮的样式也可以自己定义，主要是通过
[emphasis](${optionPath}#series-bar.emphasis)
属性来定制。[emphsis](${optionPath}#series-bar.emphasis) 中的结构，和普通样式的结构相同，例如：
+
+```js
+option = {
+ series: {
+ type: 'scatter',
+
+ // 普通样式。
+ itemStyle: {
+ // 点的颜色。
+ color: 'red'
+ },
+ label: {
+ show: true,
+ // 标签的文字。
+ formatter: 'This is a normal label.'
+ },
+
+ // 高亮样式。
+ emphasis: {
+ itemStyle: {
+ // 高亮时点的颜色。
+ color: 'blue'
+ },
+ label: {
+ show: true,
+ // 高亮时标签的文字。
+ formatter: 'This is a emphasis label.'
+ }
+ }
+ }
+};
+```
+
+注意：在 ECharts4 以前，高亮和普通样式的写法，是这样的：
+
+```js
+option = {
+ series: {
+ type: 'scatter',
+
+ itemStyle: {
+ // 普通样式。
+ normal: {
+ // 点的颜色。
+ color: 'red'
+ },
+ // 高亮样式。
+ emphasis: {
+ // 高亮时点的颜色。
+ color: 'blue'
+ }
+ },
+
+ label: {
+ // 普通样式。
+ normal: {
+ show: true,
+ // 标签的文字。
+ formatter: 'This is a normal label.'
+ },
+ // 高亮样式。
+ emphasis: {
+ show: true,
+ // 高亮时标签的文字。
+ formatter: 'This is a emphasis label.'
+ }
+ }
+ }
+};
+```
+
+这种写法 **仍然被兼容**，但是，不再推荐。事实上，多数情况下，使用者只会配置普通状态下的样式，而使用默认的高亮样式。所以在 ECharts4
中，支持不写 `normal` 的配置方法（即本文开头的那种写法），使得配置项更扁平简单。
+
+## 通过 visualMap 组件设定样式
+
+[visualMap 组件](${optionPath}#visualMap) 能指定数据到颜色、图形尺寸的映射规则，详见
[数据的视觉映射](${lang}/concepts/visual-map)。
diff --git a/contents/zh/posts.yml b/contents/zh/posts.yml
index a72b383..17ffd2f 100644
--- a/contents/zh/posts.yml
+++ b/contents/zh/posts.yml
@@ -3,10 +3,13 @@
- title: 入门篇
dir: basics
children:
- - title: 下载
+ - title: 获取 ECharts
dir: download
+ - title: 在项目中引入 ECharts
+ dir: import
- title: 资源列表
dir: resource
+ draft: true
- title: 获取灵感
dir: inspiration
- title: 寻求帮助
@@ -28,6 +31,8 @@
- title: 系列
dir: series
draft: true
+ - title: 样式
+ dir: style
- title: 数据集
dir: dataset
- title: 数据转换
@@ -41,9 +46,6 @@
dir: visual-map
- title: 图例
dir: legend
- - title: 提示框
- dir: tooltip
- draft: true
- title: 事件与行为
dir: event
- title: 应用篇
@@ -118,6 +120,16 @@
- title: 数据下钻
dir: drilldown
draft: true
+ - title: 标签
+ dir: label
+ children:
+ - title: 富文本标签
+ dir: rich-text
+ - title: 交互
+ dir: interaction
+ children:
+ - title: 拖拽的实现
+ dir: drag
- title: 多图联动
dir: connect
draft: true
@@ -131,11 +143,11 @@
dir: canvas-vs-svg
- title: 无障碍访问
dir: aria
- - title: 可视化设计原则
- dir: design
- children:
- - title: 用颜色增强可视化效果
- dir: color-enhance
+ # - title: 可视化设计原则
+ # dir: design
+ # children:
+ # - title: 用颜色增强可视化效果
+ # dir: color-enhance
# - title: 可视化规范
# dir: chart-specificatio
# children:
diff --git a/nuxt.config.js b/nuxt.config.js
index fe7366e..53aa710 100644
--- a/nuxt.config.js
+++ b/nuxt.config.js
@@ -38,6 +38,8 @@ export default {
},
hooks: {
'content:file:beforeParse': file => {
+ // TODO better way to detect?
+ const lang = file.path.match('contents/zh') ? 'zh' : 'en'
if (file.extension === '.md') {
// Replace variables
;[
@@ -56,13 +58,14 @@ export default {
)
})
}
+ file.data = file.data.replace(/\$\{lang\}/g, lang)
}
},
/*
** Headers of the page
*/
head: {
- title: process.env.npm_package_name || '',
+ title: 'Handbook - Apache ECharts',
meta: [
{ charset: 'utf-8' },
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
@@ -72,7 +75,14 @@ export default {
content: process.env.npm_package_description || ''
}
],
- link: [{ rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' }]
+ link: [
+ {
+ rel: 'icon',
+ type: 'image/x-icon',
+ href:
+
'https://cdn.jsdelivr.net/gh/apache/echarts-website@asf-site/zh/images/favicon.png'
+ }
+ ]
},
content: {
dir: 'contents',
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
