This is an automated email from the ASF dual-hosted git repository.
sushuang pushed a commit to branch release
in repository https://gitbox.apache.org/repos/asf/incubator-echarts-doc.git
The following commit(s) were added to refs/heads/release by this push:
new f2bcc77 feature: add en doc of basic concepts overview.
new e549dc6 Merge branch 'release' of
github.com:apache/incubator-echarts-doc into release
f2bcc77 is described below
commit f2bcc779fd2ab3814f2c103ce602f5cf1ae31e0f
Author: 100pah <[email protected]>
AuthorDate: Thu Dec 26 23:17:44 2019 +0800
feature: add en doc of basic concepts overview.
---
en/tutorial/basic-concept-overview.md | 4 -
en/tutorial/basic-concepts-overview.md | 202 +++++++++++++++++++++++++++++++++
en/tutorial/tutorial.md | 1 +
zh/tutorial/basic-concepts-overview.md | 37 +++++-
4 files changed, 235 insertions(+), 9 deletions(-)
diff --git a/en/tutorial/basic-concept-overview.md
b/en/tutorial/basic-concept-overview.md
deleted file mode 100644
index fd40910..0000000
--- a/en/tutorial/basic-concept-overview.md
+++ /dev/null
@@ -1,4 +0,0 @@
-
-
-
-
diff --git a/en/tutorial/basic-concepts-overview.md
b/en/tutorial/basic-concepts-overview.md
new file mode 100644
index 0000000..09e6ee5
--- /dev/null
+++ b/en/tutorial/basic-concepts-overview.md
@@ -0,0 +1,202 @@
+{{ target: basic-concepts-overview }}
+
+# ECharts Basic Concepts Overview
+
+This chapter describes some of the common concepts and terms of echarts.
+
+
+## ECharts instance
+
+We can create multiple `echarts instances` in a webpage. In each `echarts
instance` we can create multiple diagrams, coordinate systems, etc. (described
by `option`). With a DOM element prepared (as the container of an echarts
instance), we can create a `echarts instance` based on that element. Each
`echarts instance` takes its DOM element exclusively.
+
+<br>
+
+
+
+
+## Series
+
+[series](option.html#series) is a very common term. In echarts,
[series](option.html#series) represents a series of value and the diagram
generated from them. So the concept [series](option.html#series) includes these
key points: a series of value, the type of the diagram (`series.type`) and
other parameters specified for the mapping from the values to a diagram.
+
+In echarts, the `series.type` and the "diagram type" are the same concept.
`series.type` includes: [line](option.html#series-line) (line plot),
[bar](option.html#series-bar) (bar chart), [pie](option.html#series-pie) (pie
chart), [scatter](option.html#series-scatter) (scatter plot),
[graph](option.html#series-graph) (graph plot), [tree](option.html#series-tree)
(tree plot), etc.
+
+In the example below, there are three [series](option.html#series)
([pie](option.html#series-pie), [line](option.html#series-line),
[bar](option.html#series-bar)) declared in the `option` on the right, where
[series.data](option.html#series.data) are declared in each series:
+
+<br>
+
+
+
+<br>
+
+Similarly, the following example shows another style of `option`, where each
series retrieves data from [dataset](option.html#dataset):
+
+<br>
+
+
+
+
+## Component
+
+Over series, the entities in echarts are abstracted using the term
"component". For example, echarts includes these components:
[xAxis](option.html#xAxis) (the x axis of Cartesian coordinate system),
[yAxis](option.html#yAxis) (the y axis of Cartesian coordinate system),
[grid](option.html#grid) (the baseboard of Cartesian coordinate system),
[angleAxis](option.html#angleAxis) (the angle axis of polar coordinate system),
[radiusAxis](option.html#radiusAxis) (the radius axis of polar coor [...]
+
+Notice that [series](option.html#series) is a kind of component, a component
for rendering diagram.
+
+Check the example below. Components (including series) are declared in
`option` on the right, and the are finally rendered in the echarts instance.
+
+<br>
+
+
+
+<br>
+
+Notice: although [series](option.html#series) is a kind of component,
sometimes we can see phrases like "series and components". The term "component"
in this context actually means "components except series".
+
+
+## Define charts using option
+
+We have met the term `option` above. Users should use `option` to describe all
of their requirements and input it to echarts. The requirements includes: "what
does the data like", "what the diagram we need", "what components we need",
"what the user interactions we need", etc. In short, `option` defines: `data`,
`visual mapping`, `interaction`.
+
+```js
+// Create an echarts instance.
+var dom = document.getElementById('dom-id');
+var chart = echarts.init(dom);
+
+// Use option to describe `data`, `visual mapping`, `interaction`, ...
+// `option` is a big JavaScript object.
+var option = {
+ // Each property represents a kind of components.
+ legend: {...},
+ grid: {...},
+ tooltip: {...},
+ toolbox: {...},
+ dataZoom: {...},
+ visualMap: {...},
+ // If there are more than one components in one kind, we use an array.
+ // For example, there are three x axes here.
+ xAxis: [
+ // Each item represents an instance of component.
+ // `type` is used to indicate the sub-type of the component.
+ {type: 'category', ...},
+ {type: 'category', ...},
+ {type: 'value', ...}
+ ],
+ yAxis: [{...}, {...}],
+ // There are multiple series, using an array.
+ series: [
+ // `type` is also used to indicate the sub-type
+ // (i.e., diagram type) of each series.
+ {type: 'line', data: [['AA', 332], ['CC', 124], ['FF', 412], ... ]},
+ {type: 'line', data: [2231, 1234, 552, ... ]},
+ {type: 'line', data: [[4, 51], [8, 12], ... ]}
+ }]
+};
+
+// Call `setOption` and input the `option`. And then the
+// echarts instance processes data and renders charts.
+chart.setOption(option);
+```
+
+Data is put in [series.data](option.html#series.data) in the above example.
And we give another example showing another way, where each series retrieves
data from [dataset](option.html#dataset):
+
+```js
+var option = {
+ dataset: {
+ source: [
+ [121, 'XX', 442, 43.11],
+ [663, 'ZZ', 311, 91.14],
+ [913, 'ZZ', 312, 92.12],
+ ...
+ ]
+ },
+ xAxis: {},
+ yAxis: {},
+ series: [
+ // Each series retrieves data from `dataset`. The values in `encode`
+ // are the indices of the dimensions (i.e., column) of
`dataset.source`.
+ {type: 'bar', encode: {x: 1, y: 0}},
+ {type: 'bar', encode: {x: 1, y: 2}},
+ {type: 'scatter', encode: {x: 1, y: 3}},
+ ...
+ ]
+};
+```
+
+
+
+## Position a component
+
+These approaches are used to Position a component.
+
+<br>
+
+**[Absolute positioning like CSS]**
+
+<br>
+
+Most components and series can be absolutely positioned according to `top` /
`right` / `down` / `left` / `width` / `height`. This approach is like the
absolute positioning in CSS. The absolute positioning is based on the container
DOM element of the echarts.
+
+The value of each attribute can be:
++ Absolute value (like `bottom: 54`, means: the distance from the boundary of
the echarts container to bottom boundary of the component is `54` pixel).
++ Or the percentage based on the width/height of the echarts container (like
`right: '20%'`, means: the distance from the boundary of the echarts container
to the right boundary of this component is `20%` of the width of the echarts
container).
+
+Check the example below, where the [grid](option.html#grid) component (that is
the baseboard of a Cartesian coordinate system) are configured with
`left`、`right`、`height`、`bottom`.
+
+<br>
+
+
+
+<br>
+
+Note that `left` `right` `width` are one group of attributes for horizontal
layout, while `top` `bottom` `height` are another group of attributes for
vertical layout. The two groups have nothing to do with each other. In each
group, it is enough to set only one or at most two attributes. For example,
when `left` and `right` have been specified, `width` can be automatically
calculated by them.
+
+<br>
+
+**[Center-radius positioning]**
+
+<br>
+
+A few circular components or series need to be positioned by "center" and
"radius". For example, [pie](option.html#series-pie) (pie
chart)、[sunburst](option.html#series-sunburst) (sunburst
chart)、[polar](option.html#polar) (polar coordinate system).
+
+As the name implies, it position the component according to
[center](option.html#series-pie.center) and
[radius](option.html#series-pie.radius).
+
+<br>
+
+**[Other positioning]**
+
+<br>
+
+A few other components may has their own specific positioning approach. Check
their docs before using them.
+
+
+## Coordinate system
+
+Many series, like [line](option.html#series-line),
[bar](option.html#series-bar), [scatter](option.html#series-scatter),
[heatmap](option.html#series-heatmap), etc., need to work on a coordinate
system. Coordinate system is used to layout each graphic elements and display
some ticks and labels. For example, echarts at least provides these coordinate
systems: [Cartesian coordinate system](option.html#grid), [polar coordinate
system](option.html#polar), [GEO coordinate system](option.html# [...]
+
+A coordinate system may consist of several components. For example, Cartesian
coordinate system consists of [xAxis](option.html#xAxis),
[yAxis](option.html#yAxis) and [grid](option.html#grid) (the baseboard).
[xAxis](option.html#xAxis) and [yAxis](option.html#yAxis) are referenced and
assembled by `grid` and work together cooperatively.
+
+The following example demonstrates the most simple way to use a Cartesian
coordinate system, where only [xAxis](option.html#xAxis),
[yAxis](option.html#yAxis) and a [scatter series](option.html#series-scatter)
are declared, and `echarts` create and a `grid` implicitly to link them.
+
+<br>
+
+
+
+<br>
+
+And the following example demonstrates a more complicated case, where two
[yAxis](option.html#yAxis) share one [xAxis](option.html#xAxis). And the two
`series` are also share the [xAxis](option.html#xAxis), but use different
[yAxis](option.html#yAxis) respectively. The property
[yAxisIndex](option.html#series-line.yAxisIndex) is used to specify which
[yAxis](option.html#yAxis) is used.
+
+<br>
+
+
+
+<br>
+
+The following echarts instance contain more than one [grid](option.html#grid).
Each [grid](option.html#grid) has its own [xAxis](option.html#xAxis) and
[yAxis](option.html#yAxis). The properties
[xAxisIndex](option.html#series-line.xAxisIndex),
[yAxisIndex](option.html#series-line.yAxisIndex) and
[gridIndex](option.html#yAxis.gridIndex) are used to specify the reference
relationships.
+
+<br>
+
+
+
+<br>
+
+Moreover, a type of series is usually available on various coordinate systems.
For example, a [scatter series](option.html#series-scatter) can work on
[Cartesian coordinate system](option.html#grid), [polar coordinate
system](option.html#polar), [GEO coordinate system](option.html#geo) or other
coordinate systems. Similarly, a coordinate system can serve different type of
series. As the examples shown above, a [Cartesian coordinate
system](option.html#grid) serves several [line series](o [...]
+
diff --git a/en/tutorial/tutorial.md b/en/tutorial/tutorial.md
index c3d6520..443cbfa 100644
--- a/en/tutorial/tutorial.md
+++ b/en/tutorial/tutorial.md
@@ -3,6 +3,7 @@
{{ import: getting-started }}
{{ import: custom-build }}
{{ import: npm-webpack }}
+{{ import: basic-concepts-overview }}
{{ import: styling }}
{{ import: style-overview }}
{{ import: dynamic-data }}
diff --git a/zh/tutorial/basic-concepts-overview.md
b/zh/tutorial/basic-concepts-overview.md
index cd9d9b2..05f53ba 100644
--- a/zh/tutorial/basic-concepts-overview.md
+++ b/zh/tutorial/basic-concepts-overview.md
@@ -6,23 +6,31 @@
## echarts 实例
-一个网页中可以创建多个 `echarts 实例`。每个 `echarts 实例` 中可以创建多个图表和坐标系等等。准备一个 DOM 节点（作为
echarts 的渲染容器），就可以在上面创建一个 echarts 实例。每个 echarts 实例独占一个 DOM 节点。
+一个网页中可以创建多个 `echarts 实例`。每个 `echarts 实例` 中可以创建多个图表和坐标系等等（用 `option` 来描述）。准备一个
DOM 节点（作为 echarts 的渲染容器），就可以在上面创建一个 echarts 实例。每个 echarts 实例独占一个 DOM 节点。
+
+<br>
## 系列（series）
-`系列`（[series](option.html#series)）是很常见的名词。在 echarts
里，`系列`（[series](option.html#series)）是指：一组数值以及他们映射成的图。“系列”这个词原本可能来源于“一系列的数据”，而在
echarts 中取其扩展的概念，不仅表示数据，也表示数据映射成为的图。所以，一个 `系列`
包含的要素有：一组数值、图表类型（`series.type`）、以及其他的对于该图的的设定参数。
+`系列`（[series](option.html#series)）是很常见的名词。在 echarts
里，`系列`（[series](option.html#series)）是指：一组数值以及他们映射成的图。“系列”这个词原本可能来源于“一系列的数据”，而在
echarts 中取其扩展的概念，不仅表示数据，也表示数据映射成为的图。所以，一个 `系列`
包含的要素至少有：一组数值、图表类型（`series.type`）、以及其他的关于这些数据如何映射成图的参数。
echarts
里系列类型（`series.type`）就是图表类型。系列类型（`series.type`）至少有：[line](option.html#series-line)（折线图）、[bar](option.html#series-bar)（柱状图）、[pie](option.html#series-pie)（饼图）、[scatter](option.html#series-scatter)（散点图）、[graph](option.html#series-graph)（关系图）、[tree](option.html#series-tree)（树图）、...
如下图，右侧的 `option` 中声明了三个
`系列`（[series](option.html#series)）：[pie](option.html#series-pie)（饼图系列）、[line](option.html#series-line)（折线图系列）、[bar](option.html#series-bar)（柱状图系列），每个系列中有他所需要的数据（[series.data](option.html#series.data)）。
+<br>
+
+<br>
+
类同地，下图中是另一种配置方式，系列的数据从 [dataset](option.html#dataset) 中取：
+<br>
+
@@ -34,8 +42,12 @@ echarts 里系列类型（`series.type`）就是图表类型。系列类型（`s
如下图，右侧的 `option` 中声明了各个组件（包括系列），各个组件就出现在图中。
+<br>
+
+<br>
+
注：因为系列是一种特殊的组件，所以有时候也会出现 “组件和系列” 这样的描述，这种语境下的 “组件” 是指：除了 “系列” 以外的其他组件。
## 用 option 描述图表
@@ -121,10 +133,14 @@ var option = {
+ 绝对数值（例如 `bottom: 54` 表示：距离 echarts 容器底边界 `54` 像素）。
+ 或者基于 echarts 容器高宽的百分比（例如 `right: '20%'` 表示：距离 echarts 容器右边界的距离是 echarts
容器高度的 `20%`）。
-如下图的例子，对 `grid` 组件（也就是直角坐标系的底板）设置 `left`、`right`、`height`、`bottom` 达到的效果。
+如下图的例子，对 [grid](option.html#grid) 组件（也就是直角坐标系的底板）设置
`left`、`right`、`height`、`bottom` 达到的效果。
+
+<br>
+<br>
+
我们可以注意到，`left` `right` `width` 是一组（横向）、`top` `bottom` `height`
是另一组（纵向）。这两组没有什么关联。每组中，至多设置两项就可以了，第三项会被自动算出。例如，设置了 `left` 和 `right`
就可以了，`width` 会被自动算出。
<br>
@@ -143,27 +159,38 @@ var option = {
<br>
-少数组件和系列可能有自己的特殊的定位方式。
+少数组件和系列可能有自己的特殊的定位方式。在他们的文档中会有说明。
## 坐标系
-很多系列，例如
[line](option.html#series-line)（折线图）、[bar](option.html#series-bar)（柱状图）、[scatter](option.html#series-scatter)（散点图）、[heatmap](option.html#series-heatmap)（热力图）等等，需要运行在
“坐标系” 上。坐标系用于布局这些图，以及显示数据的刻度等等。例如 echarts
中至少支持这些坐标系：[直角坐标系](option.html#grid)、[极坐标系](option.html#polar)、[地理坐标系（GEO）](option.html#geo)、[日历坐标系](option.html#calendar)
等。其他一些系列，例如
[pie](option.html#series-pie)（饼图）、[tree](option.html#series-tree)（树图）等等，并不依赖坐标系，能独立存在。还有一些图，例如
[graph](option.html#series-graph)（关系图）等，既能独立存在 [...]
+很多系列，例如
[line](option.html#series-line)（折线图）、[bar](option.html#series-bar)（柱状图）、[scatter](option.html#series-scatter)（散点图）、[heatmap](option.html#series-heatmap)（热力图）等等，需要运行在
“坐标系” 上。坐标系用于布局这些图，以及显示数据的刻度等等。例如 echarts
中至少支持这些坐标系：[直角坐标系](option.html#grid)、[极坐标系](option.html#polar)、[地理坐标系（GEO）](option.html#geo)、[单轴坐标系](option.html#singleAxis)、[日历坐标系](option.html#calendar)
等。其他一些系列，例如
[pie](option.html#series-pie)（饼图）、[tree](option.html#series-tree)（树图）等等，并不依赖坐标系，能独立存在。还有一些图，例如
[graph](option [...]
一个坐标系，可能由多个组件协作而成。我们以最常见的直角坐标系来举例。直角坐标系中，包括有 [xAxis](option.html#xAxis)（直角坐标系
X 轴）、[yAxis](option.html#yAxis)（直角坐标系 Y
轴）、[grid](option.html#grid)（直角坐标系底板）三种组件。`xAxis`、`yAxis` 被 `grid`
自动引用并组织起来，共同工作。
我们来看下图，这是最简单的使用直角坐标系的方式：只声明了 `xAxis`、`yAxis` 和一个 `scatter`（散点图系列），echarts
暗自为他们创建了 `grid` 并关联起他们：
+<br>
+
+<br>
+
再来看下图，两个 `yAxis`，共享了一个 `xAxis`。两个 `series`，也共享了这个 `xAxis`，但是分别使用不同的 `yAxis`，使用
[yAxisIndex](option.html#series-line.yAxisIndex) 来指定它自己使用的是哪个 `yAxis`：
+<br>
+
+<br>
+
再来看下图，一个 echarts 实例中，有多个 `grid`，每个 `grid` 分别有 `xAxis`、`yAxis`，他们使用
`xAxisIndex`、`yAxisIndex`、`gridIndex` 来指定引用关系：
+<br>
+
+<br>
另外，一个系列，往往能运行在不同的坐标系中。例如，一个 [scatter](option.html#series-scatter)（散点图）能运行在
[直角坐标系](option.html#grid)、[极坐标系](option.html#polar)
、[地理坐标系（GEO）](option.html#geo)
等各种坐标系中。同样，一个坐标系，也能承载不同的系列，如上面出现的各种例子，[直角坐标系](option.html#grid) 里承载了
[line](option.html#series-line)（折线图）、[bar](option.html#series-bar)（柱状图）等等。
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
