Merge pull request #466 from apache/feat-coord-sys

Feat coord sys

Author: 100pah

README.md

@@ -51,6 +51,10 @@ Marking "since version" indicates when a new feature was introduced.
 For example,
 ```
 {{ use: partial-version(version = "6.0.0") }}
+
+{{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
+    That is, if the ${version} is empty or smaller than '6.0.0', use '6.0.0'.
+    Follow the version comparison rules in Semver 2.0 .
 ```
 
 ### Global Variables
@@ -197,6 +201,15 @@ The template syntax follows [etpl](https://github.com/ecomfe/etpl/blob/master/do
 
 Summary of the commonly used syntax:
 ```template
+--- TEMPLATE EXPRESSION ---
+The template syntax and expressions are encolsed by delimiters `{{` and `}}`.
+For example,
+{{ if: condition_expression }} xxx {{ /if }}
+The expressoin within `{{` and `}}` can be considered a (restricted) JS expression.
+For example,
+{{ if: ${someVar1} + 'abc' === '123abc' }} ... {{ /if }}
+{{ if: !${someVar2} }} ... {{ /if }}
+
 --- TEMPLATE VARIABLE ---
 Use a variable:
     some text ${someVariable} some text
@@ -210,7 +223,8 @@ Declaration or assignment of a target-local variable:
     {{ var: myVar = 'some' }}
     {{ var: myVar = 123 }}
     {{ var: myVar = ${someOtherStr} + 'some_str' }}
-
+NOTICE:
+    Within a `{{` `}}` pair, DO NOT write {{ if: '${some}_abc' }}{{ /if }}. It should be {{ if: ${some} + '_abc' }}{{ /if }}, as the sentence within `{{` `}}` pair is treated like a normal JS expression.
 
 --- IF ELSE ---
 {{ if: ${number1} > 0 }}
@@ -220,6 +234,11 @@ some text yyy
 {{ else }}
 some text zzz
 {{ /if }}
+Logical operators can be used in the conditional expression:
+{{ if: ${componentNameInLink} == null && ${seriesType} }}
+This componentNameInLink is null or undefined
+{{ var: componentNameInLink = 'series-' + ${seriesType} }}
+{{ /if }}
 
 
 --- FOR LOOP ---

en/option/component/data-zoom-slider.md

@@ -239,6 +239,16 @@ Whether to update view while dragging. If it is set as `false`, the view will be
     componentName = 'dataZoom-slider'
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "dataZoom",
+    nonSeriesComponentSubType = "slider",
+    coordSysDefault = "'none'",
+    calendar = true,
+    matrix = true,
+    none = true
+) }}
+
 ## width(string|number)
 
 <ExampleUIControlNumber default="30"/>

en/option/component/geo-common.md

@@ -1,6 +1,12 @@
 
 {{ target: geo-common }}
 
+{{ if: ${inMap} }}
+{{ var: componentNameInLink = 'series-map' }}
+{{ else }}
+{{ var: componentNameInLink = 'geo' }}
+{{ /if }}
+
 #${prefix} map(string) = ''
 
 Map name registered in [registerMap](api.html#echarts.registerMap).
@@ -173,9 +179,13 @@ center: project([115.97, 29.71])
 
 #${prefix} aspectScale(number) = 0.75
 
-Used to scale aspect of geo. Will be ignored if `projection` is set.
+Used to scale aspect of geo. It will be ignored if [proejction](~${componentNameInLink}.projection) is set.
+
+The final calculated `pixelWidth` and `pixelHeight` of the map will satisfy `pixelWidth / pixelHeight = lngSpan / latSpan * aspectScale` (assume [proejction](~${componentNameInLink}.projection) is not specified, and [preserveAspect](~${componentNameInLink}.preserveAspect) is truthy).
+
+If no [proejction](~${componentNameInLink}.projection) is applied, the latitudes and longitudes in GeoJSON are linearly mapped to pixel coordinates diarectly. `aspectScale` offers a simple way to visually compensates for the distortion caused by the fact that the longitudinal spacing shrinks as latitude increases. For example, an `aspectScale` can be roughly calculated as `aspectScale = Math.cos(center_latitude * Maht.PI / 180)`, which is similar to a sinusoidal projection.
 
-The final aspect is calculated by: `geoBoundingRect.width / geoBoundingRect.height * aspectScale`.
+See [example](${galleryEditorPath}geo-graph&edit=1&reset=1).
 
 #${prefix} boundingCoords(Array) = null
 

en/option/component/geo.md

@@ -37,6 +37,15 @@ Whether to show the geo component.
     prefix = '#'
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "geo",
+    coordSysDefault = "'none'",
+    calendar = true,
+    matrix = true,
+    none = true
+) }}
+
 ## regions(Array)
 
 Configure style for specified regions.

en/option/component/grid.md

@@ -3,9 +3,15 @@
 
 # grid(Object)
 
-Drawing grid in rectangular coordinate. In a single grid, at most two X and Y axes each is allowed. [Line chart](~series-line), [bar chart](~series-bar), and [scatter chart (bubble chart)](~series-scatter) can be drawn in grid.
+The `grid component` is a rectangular container, used to lay out two-dimensional rectangular coordinate system (also known as `cartesian2d` coordinate system).
 
-In ECharts 2.x, there could only be one single grid component at most in a single echarts instance. But in ECharts 3, there is no limitation.
+A `cartesian2d` coordinate system is composed fo an [xAxis](~xAixs) and a [yAxis](~yAxis). Multiple `cartesian2d` coordinate systems can be arranged within a single `grid component` - that is, multiple [xAxis](~xAixs) and multiple [yAxis](~yAxis) instances can be configured within one `grid component`.
+
+An [xAxis](~xAixs) or a [yAxis](~yAxis) can be shared by multiple `cartesian2d` coordinate systems. For example, one [xAxis](~xAixs) and two [yAxis](~yAxis) form two `cartesian2d` coordinate systems.
+
+[Line chart](~series-line), [bar chart](~series-bar), and [scatter chart (bubble chart)](~series-scatter), etc., can be drawn in `grid component`.
+
+> In ECharts 2.x, there could only be one single grid component at most in a single echarts instance. But since ECharts 3, there is no limitation.
 
 **Following is an example of Anscombe Quartet:**
 
@@ -82,6 +88,7 @@ See also [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&
 
 {{ use: partial-rect-layout-width-height(
     hostName = "`outerBounds`",
+    version = "6.0.0",
     noZ = true,
     prefix = '##',
     defaultLeft = 0,
@@ -113,3 +120,11 @@ See also [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&
 
 {{ use: partial-tooltip-in-coords() }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "grid",
+    coordSysDefault = "'none'",
+    matrix = true,
+    calendar = true,
+    none = true
+) }}

en/option/component/legend.md

@@ -49,6 +49,15 @@ When `'scroll'` used, these options below can be used for detailed configuration
     componentName = "legend"
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "legend",
+    coordSysDefault = "'none'",
+    matrix = true,
+    calendar = true,
+    none = true
+) }}
+
 ## orient(string) = 'horizontal'
 
 <ExampleUIControlEnum options="vertical,horizontal" default="horizontal" />

en/option/component/parallel.md

@@ -20,6 +20,16 @@
     defaultBottom = 60
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "parallel",
+    coordSysDefault = "'none'",
+    matrix = true,
+    calendar = true,
+    none = true
+) }}
+
+
 ## layout(string) = 'horizontal'
 
 <ExampleUIControlEnum options="horizontal,vertical" default="horizontal" />

en/option/component/polar.md

@@ -18,5 +18,14 @@ Polar coordinate can be used in scatter and line chart. Every polar coordinate h
     disableArray = false
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "polar",
+    coordSysDefault = "'none'",
+    matrix = true,
+    calendar = true,
+    none = true
+) }}
+
 {{ use: partial-tooltip-in-coords() }}
 

en/option/component/radar.md

@@ -20,6 +20,15 @@ Here is a custom example of radar component.
     defaultRadius = "75%"
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "radar",
+    coordSysDefault = "'none'",
+    matrix = true,
+    calendar = true,
+    none = true
+) }}
+
 ## startAngle(number) = 90
 
 The start angle of coordinate, which is the angle of the first indicator axis.

en/option/component/timeline.md

@@ -181,6 +181,15 @@ Position of the play button, whose valid values are `'left'` and `'right'`.
     componentName = 'timeline'
 ) }}
 
+{{ use: partial-coord-sys(
+    version = '6.0.0',
+    nonSeriesComponentMainType = "timeline",
+    coordSysDefault = "'none'",
+    matrix = true,
+    calendar = true,
+    none = true
+) }}
+
 ## padding(number|Array) = 5
 
 <ExampleUIControlVector default="5,5,5,5" dims="T,R,B,L" />