add doc for apache/echarts#11715

apache · Dec 4, 2019 · 1f276b5 · 1f276b5
1 parent 0cd324d
commit 1f276b5
Show file tree

Hide file tree

Showing 10 changed files with 109 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -13,18 +13,23 @@
 
 ## Build and Run Locally
 
-Dev:
+### Dev
+
 ```shell
 # should put <https://github.com/ecomfe/echarts-examples> on the same folder with echarts-doc
 node watch.js --env dev
 # or
 node build.js --env dev
 
 # Run a static server (optional)
-node server.js
+cd ..
+http-server
 ```
 
-Release:
+Open [http://127.0.0.1:8080/echarts-doc/public/en/option.html#title](http://127.0.0.1:8080/echarts-doc/public/en/option.html#title) in a Web Browser.
+
+### Release
+
 Check `incubator-echarts-website/README.md` please.
 
 ## Tips about writing doc

diff --git a/en/option/component/dataset.md b/en/option/component/dataset.md
@@ -5,7 +5,7 @@
 
 `dataset` component is published since ECharts 4. `dataset` brings convenience in data management separated with styles and enables data reuse by different series. More importantly, is enables data encoding from data to visual, which brings convenience in some scenarios.
 
-More details about `dataset` can be checked in the [tutorial](https://echarts.apache.org/en/tutorial.html#Dataset).
+More details about `dataset` can be checked in the [tutorial](tutorial.html#Dataset).
 
 ---
 
@@ -48,7 +48,7 @@ Column based key-value format, where each value represents a column of a table.
 }
 ```
 
-More details about `dataset` can be checked in the [tutorial](https://ecomfe.github.io/echarts-doc/public/en/tutorial.html#dataset).
+More details about `dataset` can be checked in the [tutorial](tutorial.html#dataset).
 
 
 {{use:partial-series-dimensions(

diff --git a/en/option/partial/zr-graphic.md b/en/option/partial/zr-graphic.md
@@ -1174,7 +1174,7 @@ Whether use progressive render to improve performance. Usually used when number
 {{ target: partial-graphic-cpt-style-prop-common }}
 
 
-More attributes in `style` (for example, [rich text](https://ecomfe.github.io/echarts-doc/public/en/tutorial.html#Rich%20Text)), see the `style` related attributes in [zrender/graphic/Displayable](https://ecomfe.github.io/zrender-doc/public/api.html#zrenderdisplayable).
+More attributes in `style` (for example, [rich text](tutorial.html#Rich%20Text)), see the `style` related attributes in [zrender/graphic/Displayable](https://ecomfe.github.io/zrender-doc/public/api.html#zrenderdisplayable).
 
 Notice, the attribute names of the `style` of graphic elements is derived from `zrender`, which may be different from the attribute names in `echarts label`, `echarts itemStyle`, etc., although they have the same meaning. For example:
 

diff --git a/en/option/series/funnel.md b/en/option/series/funnel.md
@@ -85,7 +85,7 @@ The visual guide line style of label. When [label position](~series-funnel.label
 {{use:partial-item-style(prefix="###")}}
 
 
-{{ use: component-rect-layout-width-height(
+{{ use: partial-rect-layout-width-height(
     componentName="funnel chart",
     defaultLeft=80,
     defaultTop=60,

diff --git a/en/option/series/pie.md b/en/option/series/pie.md
@@ -9,6 +9,12 @@ The pie chart is mainly used for showing proportion of different categories. Eac
 
 **Tip:** The pie chart is more suitable for illustrating the numerical proportion. If you just to present the numerical differences of various categories, the [bar graph](bar) chart is more suggested. Because compared to tiny length difference,  people is less sensitive to the minor radian difference. Otherwise, it can also be shown as Nightingale chart by using the [roseType](~series-pie.roseType) to distinguish different data through radius.
 
+Since ECharts v4.6.0, we provide `'labelLine'` and `'edge'` two extra layouts. Check [label.alignTo](~series-pie.label.alignTo) for more information.
+
+~[900x250](${galleryViewPath}pie-alignTo&reset=1&edit=1)
+
+For multiple pie series in a single chart, you may use [left](~series-pie.left), [right](~series-pie.right), [top](~series-pie.top), [bottom](~series-pie.bottom), [width](~series-pie.width), and [height](~series-pie.height) to locate the pies. Percetage values like [radius](~series-pie.radius) or [label.margin](~series-pie.label.margin) are relative to the viewport defined by this setting.
+
 ** The below example shows a customized Nightingale chart: **
 ~[500x400](${galleryViewPath}pie-custom&edit=1&reset=1)
 
@@ -61,6 +67,13 @@ Whether to show sector when all data are zero.
 
 {{ use: partial-cursor }}
 
+{{ use: partial-rect-layout-width-height(
+    componentName="pie chart",
+    defaultLeft=0,
+    defaultTop=0,
+    defaultRight=0,
+    defaultBottom=0
+) }}
 
 ## label(Object)
 {{use:partial-label-desc(name="pie chart")}}
@@ -71,6 +84,38 @@ Whether to show sector when all data are zero.
     formatter=true
 )}}
 
+### alignTo(string) = 'none'
+
+Label aligning policy. Valid only when `position` is `'outer'`.
+
+Since ECharts v4.6.0, we provide `'labelLine'` and `'edge'` two extra valid `alignTo` values.
+
++ `'none'` (default): label lines have fixed length as [labelLine.length](~series-pie.labelLine.length) and [labelLine.length2](~series-pie.labelLine.length2).
++ `'labelLine'`: aligning to the end of label lines and the length of the shortest horizontal label lines is configured by [labelLine.length2](~series-pie.labelLine.length2).
++ `'edge'`: aligning to text and the distance between the edges of text and the viewport is configured by [label.margin](~series-pie.label.margin).
+
+~[900x250](${galleryViewPath}pie-alignTo&reset=1&edit=1)
+
+### margin(string|number) = '25%'
+
+The horitontal distance between text edges and viewport when [label.position](~series-pie.label.position) is `'outer'` and [label.alignTo](~series-pie.label.alignTo) is `'edge'`.
+
+~[900x250](${galleryViewPath}doc-example/pie-label-margin&edit=1&reset=1)
+
+In most cases, you need a small `margin` value like `10` for mobile devices to make sure more text can be shown instead of being `...`. But on larger resolutions, a percentage value should be applied so that the label lines won't be too long. If your chart is used in varied resolutions, it is advised to set [responsive design](tutorial.html#Responsive%20Mobile-End) for different resolutions.
+
+### bleedMargin(number) = 10
+
+The horitontal distance between text and viewport when [label.position](~series-pie.label.position) is `'outer'` and [label.alignTo](~series-pie.label.alignTo) is `'none'` or `'labelLine'`. Longer text will be truncated into `'...'`.
+
+~[800x250](${galleryViewPath}doc-example/pie-label-bleedMargin&edit=1&reset=1)
+
+### distanceToLabelLine(number) = 5
+
+Distance between label line and text.
+
+~[800x250](${galleryViewPath}doc-example/pie-label-distanceToLabelLine&edit=1&reset=1)
+
 ## labelLine(Object)
 The style of visual guide line. Will show when [label position](~series-pie.label.position) is set as `'outside'`.
 

diff --git a/zh/option/component/dataset.md b/zh/option/component/dataset.md
@@ -5,7 +5,7 @@
 
 ECharts 4 开始支持了 `数据集`（`dataset`）组件用于单独的数据集声明，从而数据可以单独管理，被多个组件复用，并且可以自由指定数据到视觉的映射。这在不少场景下能带来使用上的方便。
 
-关于 `dataset` 的详情，请参见[教程](http://echarts.baidu.com/tutorial.html#%E4%BD%BF%E7%94%A8%20dataset%20%E7%AE%A1%E7%90%86%E6%95%B0%E6%8D%AE)。
+关于 `dataset` 的详情，请参见[教程](tutorial.html#%E4%BD%BF%E7%94%A8%20dataset%20%E7%AE%A1%E7%90%86%E6%95%B0%E6%8D%AE)。
 
 
 ---
@@ -48,7 +48,7 @@ ECharts 4 开始支持了 `数据集`（`dataset`）组件用于单独的数据
 }
 ```
 
-关于 `dataset` 的详情，请参见[教程](http://echarts.baidu.com/tutorial.html#%E4%BD%BF%E7%94%A8%20dataset%20%E7%AE%A1%E7%90%86%E6%95%B0%E6%8D%AE)。
+关于 `dataset` 的详情，请参见[教程](tutorial.html#%E4%BD%BF%E7%94%A8%20dataset%20%E7%AE%A1%E7%90%86%E6%95%B0%E6%8D%AE)。
 
 
 {{use:partial-series-dimensions(

diff --git a/zh/option/partial/zr-graphic.md b/zh/option/partial/zr-graphic.md
@@ -1162,7 +1162,7 @@ chart.on('click', function (params) {
 
 {{ target: partial-graphic-cpt-style-prop-common }}
 
-注：关于图形元素中更多的样式设置（例如 [富文本标签](http://echarts.baidu.com/tutorial.html#%E5%AF%8C%E6%96%87%E6%9C%AC%E6%A0%87%E7%AD%BE)），参见 [zrender/graphic/Displayable](https://ecomfe.github.io/zrender-doc/public/api.html#zrenderdisplayable) 中的 style 相关属性。
+注：关于图形元素中更多的样式设置（例如 [富文本标签](tutorial.html#%E5%AF%8C%E6%96%87%E6%9C%AC%E6%A0%87%E7%AD%BE)），参见 [zrender/graphic/Displayable](https://ecomfe.github.io/zrender-doc/public/api.html#zrenderdisplayable) 中的 style 相关属性。
 
 注意，这里图形元素的样式属性名称直接源于 zrender，和 `echarts label`、`echarts itemStyle` 等处同样含义的样式属性名称或有不同。例如，有如下对应：
 

diff --git a/zh/option/series/custom.md b/zh/option/series/custom.md
@@ -11,9 +11,9 @@
 **例如，下面的例子使用 custom series 扩展出了 x-range 图：**
 ~[800x500](${galleryViewPath}custom-profile&reset=1&edit=1)
 
-**更多的例子参见：[custom examples](http://echarts.baidu.com/examples.html#chart-type-custom)**
+**更多的例子参见：[custom examples](examples.html#chart-type-custom)**
 
-**[这里是个教程](http://echarts.baidu.com/tutorial.html#%E8%87%AA%E5%AE%9A%E4%B9%89%E7%B3%BB%E5%88%97)**
+**[这里是个教程](tutorial.html#%E8%87%AA%E5%AE%9A%E4%B9%89%E7%B3%BB%E5%88%97)**
 
 <br>
 **开发者自定义渲染逻辑（renderItem 函数）**

diff --git a/zh/option/series/funnel.md b/zh/option/series/funnel.md
@@ -85,7 +85,7 @@
 {{use:partial-item-style(prefix="###")}}
 
 
-{{ use: component-rect-layout-width-height(
+{{ use: partial-rect-layout-width-height(
     componentName="漏斗图",
     defaultLeft=80,
     defaultTop=60,

diff --git a/zh/option/series/pie.md b/zh/option/series/pie.md
@@ -6,6 +6,12 @@
 
 饼图主要用于表现不同类目的数据在总和中的占比。每个的弧度表示数据数量的比例。
 
+从 ECharts v4.6.0 版本起，我们提供了 `'labelLine'` 与 `'edge'` 两种新的布局方式。详情参见 [label.alignTo](~series-pie.label.alignTo)。
+
+~[900x250](${galleryViewPath}pie-alignTo&reset=1&edit=1)
+
+对于一个图表中有多个饼图的场景，可以使用 [left](~series-pie.left)、[right](~series-pie.right)、[top](~series-pie.top)、[bottom](~series-pie.bottom)、[width](~series-pie.width)、[height](~series-pie.height) 配置每个饼图系列的位置和视口大小。[radius](~series-pie.radius)、[label.margin](~series-pie.label.margin) 等支持百分比的配置项，是相对于该配置项决定的矩形的大小而言的。
+
 **Tip:** 饼图更适合表现数据相对于总数的百分比等关系。如果只是表示不同类目数据间的大小，建议使用 [柱状图](bar)，人们对于微小的弧度差别相比于微小的长度差别更不敏感，或者也可以通过配置 [roseType](~series-pie.roseType) 显示成南丁格尔图，通过半径大小区分数据的大小。
 
 **下面是自定义南丁格尔图的示例：**
@@ -59,6 +65,14 @@
 
 {{ use: partial-cursor }}
 
+{{ use: partial-rect-layout-width-height(
+    componentName="pie chart",
+    defaultLeft=0,
+    defaultTop=0,
+    defaultRight=0,
+    defaultBottom=0
+) }}
+
 ## label(Object)
 {{use:partial-label-desc(name="饼图")}}
 {{use:partial-pie-label(
@@ -68,6 +82,38 @@
     formatter=true
 )}}
 
+### alignTo(string) = 'none'
+
+标签的对齐方式，仅当 `position` 值为 `'outer'` 时有效。
+
+从 ECharts v4.6.0 版本起，我们提供了 `'labelLine'` 与 `'edge'` 两种新的布局方式。
+
++ `'none'`（默认值）：label line 的长度为固定值，分别为 [labelLine.length](~series-pie.labelLine.length) 及 [labelLine.length2](~series-pie.labelLine.length2)。
++ `'labelLine'`：label line 的末端对齐，其中最短的长度由 [labelLine.length2](~series-pie.labelLine.length2) 决定。
++ `'edge'`：文字对齐，文字的边距由 [label.margin](~series-pie.label.margin) 决定。
+
+~[900x250](${galleryViewPath}pie-alignTo&reset=1&edit=1)
+
+### margin(string|number) = '25%'
+
+文字边距，仅当 [label.position](~series-pie.label.position) 为 `'outer'` 并且 [label.alignTo](~series-pie.label.alignTo) 为 `'edge'` 时有效。
+
+~[900x250](${galleryViewPath}doc-example/pie-label-margin&edit=1&reset=1)
+
+通常来说，对于移动端等分辨率较小的情况，`margin` 值设为比较小的值（比如 `10`）能在有限的空间内显示更多文字，而不是被裁剪为 `...`。但是对于分辨率更大的场景，百分比的值可以避免 label line 过长。如果你需要在不同分辨率下使用，建议使用[响应式图表设计](tutorial.html#移动端自适应)为不同的分辨率设置不同的 `margin` 值。
+
+### bleedMargin(number) = 10
+
+文字的出血线大小，超过出血线的文字将被裁剪为 `'...'`。仅当 [label.position](~series-pie.label.position) 为 `'outer'` 并且 [label.alignTo](~series-pie.label.alignTo) 为 `'none'` 或 `'labelLine'` 的情况有效。
+
+~[800x250](${galleryViewPath}doc-example/pie-label-bleedMargin&edit=1&reset=1)
+
+### distanceToLabelLine(number) = 5
+
+文字与 label line 之间的距离。
+
+~[800x250](${galleryViewPath}doc-example/pie-label-distanceToLabelLine&edit=1&reset=1)
+
 ## labelLine(Object)
 标签的视觉引导线样式，在 [label 位置](~series-pie.label.position) 设置为`'outside'`的时候会显示视觉引导线。
 {{ use: partial-pie-label-line(