diff --git a/.gitignore b/.gitignore index 28eee55c4..e3f8c7597 100644 --- a/.gitignore +++ b/.gitignore @@ -188,4 +188,6 @@ slides/webgl /tool/blocks-zh.json /zh-src -/en-src \ No newline at end of file +/en-src + +/config/env.*-local.js diff --git a/README.md b/README.md index e2259be55..0aa1c614c 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ This project is part of the source of [The Apache ECharts Official Website](http ## Development -### Document content development +### Document Content Development Do not need other project. @@ -28,46 +28,59 @@ It will: + Watch doc site src change and rebuild. + Watch doc markdown change and rebuild. +### Local Config -## Tips about writing doc +To customize the links of `echarts-examples` and other configurations, you can create a local config file `echarts-doc/config/env.dev-local.js`, which is not tracked by git. The content can be copied from `echarts-doc/config/env.dev.js`, and then modify it as needed. `npm run dev` will use this local config file, if it exists, to replace `echarts-doc/config/env.dev.js`. -### "Since version" is necessary in doc + +## Tips About Writing Doc + +### "Since Version" +"Since Version" is necessary in doc. Marking "since version" indicates when a new feature was introduced. For example, ``` {{ use: partial-version(version = "6.0.0") }} ``` -### Global variables can be used in doc +### Global Variables + +These global variables can be used in doc: ++ `${galleryViewPath}` ++ `${galleryEditorPath}` ++ `${websitePath}` -+ galleryViewPath -+ galleryEditorPath -+ websitePath +See samples in "Reference of echarts-examples or other links" -For example: -Embed a example in doc: +### Reference of echarts-examples or Other Links + +Embed an example in doc: ```md +~[700X300](${galleryEditorPath}pie-legend&edit=1&reset=1) ~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1) ``` -Provide a example link in doc: + +Provide an example link in doc: ```md [vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1) +[aria pie](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1) ``` + Provide a website link in doc: ```md [Apache ECharts website](${websitePath}/en/download.html) ``` -### Reference of option +### Reference of Other ECharts Option A `~` can be used to refer to a option item in the same doc. For example: - ```md [xAxis.name](~xAxis.name) ``` If intending to reference an anchor in different doc, it can be: ```md +In api.html, reference [itemStyle](option.html#series.itemStyle) ``` @@ -112,6 +125,60 @@ It indicates the range of saturation (color alpha) {{ if: ${prefix} !== '#' }}fo ``` +### Doc Structure + ++ Entries: + + the entry in source code is like `en/api/api.md`, `en/api/option.md`, they will be compiled to webpage like `api.html`, `option.html` + ++ Shared targets (text blocks): + + All of the shared targets should be put into the `partial` folder, such as, `en/api/partial/xxx`, `en/optino/partial/xxx`, and named with a prefix `partial-`. + ++ Subtitles: + + The doc is structured by subtitles. + + For example: + ``` + # series.bar(Object) + ## propA(number|string) = null + some desc xxx + ## propB(number|string) = null + some desc yyy + ## propC(string) = ${defaultPropC|default("'auto'")} + + #${prefix} someOtherProp(Object) + some desc zzz + ``` + + `(xxx|yyy)` is the data type in that subtitle: + + Can only be `number`, `string`, `boolean`, `Object`, `Array`, `Function` + + Can be an union, such as `number|string`. + + `= xxx` is the default value in that subtitle: + + Can be omitted. + + Typically be `null`, `undefined`, `true`, `false`, `90` (a literal number), `some literal string`, `[0, 90]` (an literal array). + + The default value can be specified by a template variable, such as, `= ${someVar}`, `= ${someVar|default(123)}`, `= ${someVar|default("'auto'")}`. + + The top level subtitles: + + For example, `# series.bar(Object)`, the dot symbol represents a special meaning: the component main type is `'series'` and the component sub-type is `'bar'`. + + The variable `${prefix}` + + It is commonly used in "target: partial-xxx", which serves different subtitle levels. The value of `${prefix}` is like `'#'`, `'##'`, `'###'`, ... + + Typical usage: + ```tpl + When we define a "target" + {{ target: partial-abc-1 }} + #${prefix} propLayout(Object) + All of the subtitles should uses that prefix variable. + ##${prefix} x(number) + some desc + ##${prefix} y(number) + some desc + {{ /target }} + {{ target: partial-target-2 }} + ``` + ```tpl + When we use that "partial-abc-1" + {{ target: partial-def-2 }} + #${prefix|default('#')} somePropA(Object) + {{ use: partial-abc-1( + prefix: ${prefix} + '#' + ) }} + ``` ### Template Syntax @@ -120,11 +187,22 @@ The template syntax follows [etpl](https://github.com/ecomfe/etpl/blob/master/do Summary of the commonly used syntax: ```template -VARIABLE: -some text ${someVariable} some text - - -IF ELSE: +--- TEMPLATE VARIABLE --- +Use a variable: + some text ${someVariable} some text +Variable scope: + The scope of any variable is "target" (see below). +Variable filter: + Some predefined filters can be used in the template variable, e.g., + ${someVariable|default("'auto'")} means using the string "'auto'" + as the default if ${someVariable} is '' or null or undefined. +Declaration or assignment of a target-local variable: + {{ var: myVar = 'some' }} + {{ var: myVar = 123 }} + {{ var: myVar = ${someOtherStr} + 'some_str' }} + + +--- IF ELSE --- {{ if: ${number1} > 0 }} some text xxx {{ elif: ${string1} === 'abc' }} @@ -134,34 +212,40 @@ some text zzz {{ /if }} -FOR LOOP: +--- FOR LOOP --- {{ for: ${persons} as ${person}, ${index} }} some text ${index}: ${person.name} {{ /for }} -TARGET (DEFINE A BLOCK): +--- TARGET (DEFINE A TEXT BLOCK) --- {{ target: a_predefined_block_name_1 }} The input varA is ${varA} The input varB is ${varB} The input varC is ${varC} -some other text xxx -(The close target can be omitted, but not recommended.) +Notice: +- The scope of the "target name" is the entire webpage (such as, `option.html`, `api.html`), so name conflicts should be avoided. +- "target" is not shared across webpage (such as, `option.html`, `api.html`). +- The close tag of "target" can be omitted, but not recommended. {{ /target }} -USE (USE A BLOCK): -{{ use: a_predefined_block_name_1( +--- USE (USE A PREDEFINED TEXT BLOCK) --- +{{ use: a_predefined_block_name_1 }} +{{ use: a_predefined_block_name_2( varA = ${myVarX}, varB = 123, - varC = 'some string' -)}} -{{ use: a_predefined_block_name_2 }} + varC = 'some string', + prefix: ${prefix} + '##' +) }} +Concatenation operator `+` can be used in that string. ``` ### Document Embedded Examples +This is the embedded example that can be opened by clicking "try it" and then appears on the right side of the doc page. + Declare the base echarts options (`ExampleBaseOption`), whose scope is each echarts component or series. A `ExampleBaseOption` can be shared by multiple options. e.g., ```md @@ -199,7 +283,7 @@ npm run format Make sure have a double review on the git diff after formatted. -## Sync docs between different languages. +## Sync Docs Between Different Languages After you finished editing doc of one language. You can use following script to sync it to another language. diff --git a/build.js b/build.js index 0f5e71f04..22e6e7299 100644 --- a/build.js +++ b/build.js @@ -46,6 +46,11 @@ function initEnv() { let config = require('./config/env.' + envType); + const localOverridePath = './config/env.' + envType + '-local.js'; + if (fs.existsSync(path.join(__dirname, localOverridePath))) { + config = require(localOverridePath); + } + assert(path.isAbsolute(config.releaseDestDir) && path.isAbsolute(config.ecWWWGeneratedDir)); config.envType = envType; diff --git a/en/api/version.md b/en/api/version.md index 936383605..191ddadd7 100644 --- a/en/api/version.md +++ b/en/api/version.md @@ -1,5 +1,9 @@ {{ target: partial-version }} +{{ if: ${deprecated} }} +> Deprecated since `v${version}`. ${deprecated} +{{ else }} > Since `v${version}` +{{ /if }} {{ // this line break is necessary for md quote }} diff --git a/en/option-gl/partial/version.md b/en/option-gl/partial/version.md index 4c4bf9379..c0ff95323 100644 --- a/en/option-gl/partial/version.md +++ b/en/option-gl/partial/version.md @@ -1,5 +1,8 @@ {{ target: partial-version }} +{{ if: ${deprecated} }} +> Deprecated since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`. ${deprecated} +{{ else }} > Since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` - +{{ /if }} diff --git a/en/option/component/grid.md b/en/option/component/grid.md index 6e9134e39..0b502e336 100644 --- a/en/option/component/grid.md +++ b/en/option/component/grid.md @@ -22,7 +22,7 @@ In ECharts 2.x, there could only be one single grid component at most in a singl Whether to show the grid in rectangular coordinate. {{ use: partial-rect-layout-width-height( - componentName = "grid ", + componentName = "grid", defaultLeft = "'10%'", defaultTop = 60, defaultRight = "'10%'", @@ -30,9 +30,10 @@ Whether to show the grid in rectangular coordinate. ) }} ## containLabel(boolean) = false - +{{ use: partial-version(version = "6.0.0", deprecated = 'See [grid.outerBoundsMode](~grid.outerBoundsMode).') }} + Whether the grid region contains [axis tick label](~yAxis.axisLabel). + When containLabel is `false`: @@ -42,6 +43,68 @@ Whether the grid region contains [axis tick label](~yAxis.axisLabel). + `grid.left` `grid.right` `grid.top` `grid.bottom` `grid.width` `grid.height` decide the location and size of the rectangle that contains the axes, and the labels of the axes. + Setting to `true` will help when the length of axis labels is dynamic and is hard to approximate. This will avoid labels from overflowing the container or overlapping other components. +## outerBoundsMode(string) = 'auto' +{{ use: partial-version(version = "6.0.0") }} + +The "outer bounds" is a constraint rectangle used to prevent axis labels and axis names from overflowing. `outerBoundsMode` defines the strategy for determining the "outer bounds". + +In most cases, we do not need to specify [grid.outerBoundsMode](~grid.outerBoundsMode), [grid.outerBounds](~grid.outerBounds), [grid.outerBoundsContain](~grid.outerBoundsContain) and [grid.containLabel](~grid.containLabel), as the default settings can prevent axis labels and axis names from overflowing the canvas. + +The grid component (Cartesian) layout strategy: ++ First, lay out axis lines based on the rect defined by [grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height). This can meet the requirement of aligning axis lines across multiple grids. ++ Then, if axis labels and/or axis names overflow the "outer bounds", shrink the rectangle to prevent that overflow. [grid.outerBoundsContain](~grid.outerBoundsContain) determines whether axis label and axis name is confined by the "outer bounds". + +Options of `outerBoundsMode`: +- `'auto'`/`null`/`undefined` (default): + - Behave the same as `outerBoundsMode: 'same'` when `grid.containLabel: true`. + - Otherwise, the "outer bounds" is determined by [grid.outerBounds](~grid.outerBounds) if specified. + - Otherwise, automatically determine the "outer bounds" - typically defaulting to the current canvas, or a assigned layout rectangle if this `grid` is laid out in another coordinate system (see [grid.coordinateSystem](~grid.coordinateSystem)). +- `'none'`: Force the "outer bounds" to be infinity (i.e., no constraint), regardless of the specified [grid.outerBounds](~grid.outerBounds). +- `'same'`: Force the "outer bounds" to be the same as the layout rectangle defined by [grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height), regardless of the specified [grid.outerBounds](~grid.outerBounds). + +> The "outer bounds" encompasses the functionality of [grid.containLabel](~grid.containLabel); therefore, [grid.containLabel](~grid.containLabel) is deprecated. `grid.containLabel: true` is equivalent to `grid: {outerBoundsMode: 'same', outerBoundsContain: 'axisLabel'}`. +> The effect might be slightly different, but usually indiscernible. You can use the code below to enforce the previous effect, though it's unnecessary in most cases. +> ```js +> import {use} from 'echarts/core'; +> import {LegacyGridContainLabel} from 'echarts/features'; +> use([LegacyGridContainLabel]); +> ``` + +**Demo**: [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1). + + +## outerBounds(Object) +{{ use: partial-version(version = "6.0.0") }} + +See details in [grid.outerBoundsMode](~grid.outerBoundsMode). + +See also [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1). + +{{ use: partial-rect-layout-width-height( + hostName = "`outerBounds`", + noZ = true, + prefix = '##', + defaultLeft = 0, + defaultTop = 0, + defaultRight = 0, + defaultBottom = 0 +) }} + +## outerBoundsContain(boolean) = 'auto' +{{ use: partial-version(version = "6.0.0") }} + +Options: +- `'auto'`/`null`/`undefined` (default): + - Behave the same as `outerBoundsContain: 'axisLabel'` if `containLabel: true`. + - Otherwise, behave the same as `outerBoundsContain: 'all'`. +- `'all'`: The "outer bounds" constrain the grid (Cartesian) rectangle (determined by the x-axis and y-axis lines) and axis labels and axis names. +- `'axisLabel'`: The "outer bounds" constrain the grid (Cartesian) rectangle (determined by the x-axis and y-axis lines) and axis labels, but exclude axis names. + +For more details, see [grid.outerBoundsMode](~grid.outerBoundsMode). + +See also [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1). + + {{ use: partial-component-common-style( componentName = "grid", prefix = '#', diff --git a/en/option/component/parallel.md b/en/option/component/parallel.md index 04ecbd9a2..defb41566 100644 --- a/en/option/component/parallel.md +++ b/en/option/component/parallel.md @@ -13,7 +13,7 @@ ) }} {{ use: partial-rect-layout-width-height( - componentName = 'parallel ', + componentName = 'parallel', defaultLeft = 80, defaultRight = 80, defaultTop = 60, diff --git a/en/option/component/title.md b/en/option/component/title.md index 9814f59ce..69df32f30 100644 --- a/en/option/component/title.md +++ b/en/option/component/title.md @@ -113,7 +113,7 @@ Set this to `true` to enable triggering events The gap between the main title and subtitle. {{ use: partial-rect-layout( - componentName = "title " + componentName = "title" ) }} {{ use: partial-component-common-style( diff --git a/en/option/component/visual-map.md b/en/option/component/visual-map.md index f9e09e7bf..bb2baf7a0 100644 --- a/en/option/component/visual-map.md +++ b/en/option/component/visual-map.md @@ -358,7 +358,7 @@ Define visual channels that will mapped from dataValues that are **out of select See available configurations in [${visualMapName}.inRange](~${visualMapName}.inRange) {{ use: partial-rect-layout( - componentName = "visualMap ", + componentName = "visualMap", defaultZ = "4", defaultLeft = "0", defaultRight = "auto", diff --git a/en/option/partial/rect-layout-width-height.md b/en/option/partial/rect-layout-width-height.md index b47290d25..463c388a3 100644 --- a/en/option/partial/rect-layout-width-height.md +++ b/en/option/partial/rect-layout-width-height.md @@ -1,19 +1,27 @@ {{ target: partial-rect-layout-width-height }} +{{ if: ${hostName} }} +{{ var: hostNameStr = ${hostName} }} +{{ else }} +{{ var: hostNameStr = ${componentName} + ' component' }} +{{ /if }} + {{ use: partial-rect-layout( - componentName = ${componentName}, + hostName = ${hostName}, + noZ = ${noZ}, + prefix = ${prefix}, defaultLeft = ${defaultLeft}, defaultTop = ${defaultTop}, defaultRight = ${defaultRight}, defaultBottom = ${defaultBottom} ) }} -## width(string|number) = ${defaultWidth|default("'auto'")} +#${prefix|default("#")} width(string|number) = ${defaultWidth|default("'auto'")} -Width of ${componentName} component. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if }} +Width of ${hostNameStr}. {{ if: !${defaultWidth} }}Adaptive by default.{{ /if }} -## height(string|number) = ${defaultHeight|default("'auto'")} +#${prefix|default("#")} height(string|number) = ${defaultHeight|default("'auto'")} -Height of ${componentName} component. {{ if: !${defaultHeight} }}Adaptive by default.{{ /if }} +Height of ${hostNameStr}. {{ if: !${defaultHeight} }}Adaptive by default.{{ /if }} diff --git a/en/option/partial/rect-layout.md b/en/option/partial/rect-layout.md index 3f9e07280..c0c705012 100644 --- a/en/option/partial/rect-layout.md +++ b/en/option/partial/rect-layout.md @@ -1,6 +1,12 @@ {{ target: partial-rect-layout }} +{{ if: ${hostName} }} +{{ var: hostNameStr = ${hostName} }} +{{ else }} +{{ var: hostNameStr = ${componentName} + ' component' }} +{{ /if }} + {{ if: !${noZ} }} {{ use: partial-z-zlevel( prefix = ${prefix}, @@ -11,7 +17,7 @@ #${prefix|default("#")} left(string|number) = ${defaultLeft|default("'auto'")} -Distance between ${componentName} component and the left side of the container. +Distance between ${hostNameStr} and the left side of the container. `left` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`; and it can also be `'left'`, `'center'`, or `'right'`. @@ -19,7 +25,7 @@ If the `left` value is set to be `'left'`, `'center'`, or `'right'`, then the co #${prefix|default("#")} top(string|number) = ${defaultTop|default("'auto'")} -Distance between ${componentName} component and the top side of the container. +Distance between ${hostNameStr} and the top side of the container. `top` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`; and it can also be `'top'`, `'middle'`, or `'bottom'`. @@ -27,7 +33,7 @@ If the `top` value is set to be `'top'`, `'middle'`, or `'bottom'`, then the com #${prefix|default("#")} right(string|number) = ${defaultRight|default("'auto'")} -Distance between ${componentName} component and the right side of the container. +Distance between ${hostNameStr} and the right side of the container. `right` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`. @@ -35,7 +41,7 @@ Distance between ${componentName} component and the right side of the container. #${prefix|default("#")} bottom(string|number) = ${defaultBottom|default("'auto'")} -Distance between ${componentName} component and the bottom side of the container. +Distance between ${hostNameStr} and the bottom side of the container. `bottom` can be a pixel value like `20`; it can also be a percentage value relative to container width like `'20%'`. diff --git a/en/option/partial/version.md b/en/option/partial/version.md index 2cbf7aeea..ab87c8c82 100644 --- a/en/option/partial/version.md +++ b/en/option/partial/version.md @@ -1,5 +1,9 @@ {{ target: partial-version }} +{{ if: ${deprecated} }} +> Deprecated since `v${version}`. ${deprecated} +{{ else }} > Since `v${version}` +{{ /if }} diff --git a/en/option/series/funnel.md b/en/option/series/funnel.md index b6cba3213..143fa1c84 100644 --- a/en/option/series/funnel.md +++ b/en/option/series/funnel.md @@ -167,7 +167,7 @@ Configurations of select state. Available when [selectedMode](~series-funnel.sel ) }} {{ use: partial-rect-layout-width-height( - componentName = "Funnel", + componentName = "funnel", defaultLeft = 80, defaultTop = 60, defaultRight = 80, diff --git a/en/option/series/graph.md b/en/option/series/graph.md index d15ecf6d6..0e3355545 100644 --- a/en/option/series/graph.md +++ b/en/option/series/graph.md @@ -596,6 +596,7 @@ Alias of [links](~series-graph.links) ) }} {{ use: partial-rect-layout-width-height( + hostName = "graph series", defaultLeft = "'center'", defaultTop = "'middle'", defaultWidth = 'auto', diff --git a/en/option/series/pie.md b/en/option/series/pie.md index 92231986d..140a04e86 100644 --- a/en/option/series/pie.md +++ b/en/option/series/pie.md @@ -124,7 +124,7 @@ The precision of the percentage value. The default value is `2`. {{ use: partial-cursor() }} {{ use: partial-rect-layout-width-height( - componentName = "pie chart", + hostName = "pie series", defaultLeft = 0, defaultTop = 0, defaultRight = 0, diff --git a/en/option/series/sankey.md b/en/option/series/sankey.md index 5f46a071f..4ad79a43c 100644 --- a/en/option/series/sankey.md +++ b/en/option/series/sankey.md @@ -27,7 +27,7 @@ In addition, the edge between two small rectangles in the diagram encodes the `l {{ use: partial-series-name() }} {{ use: partial-rect-layout-width-height( - componentName = 'sankey', + hostName = 'sankey series', defaultLeft = '5%', defaultRight = '20%', defaultTop = '5%', diff --git a/en/option/series/themeRiver.md b/en/option/series/themeRiver.md index 85c236ea7..fde8ec7a2 100644 --- a/en/option/series/themeRiver.md +++ b/en/option/series/themeRiver.md @@ -32,7 +32,7 @@ What's more, the time attribute of the orinigal dataset would map to a single ti ) }} {{ use: partial-rect-layout-width-height( - componentName = 'thmemRiver', + hostName = 'themeRiver series', defaultLeft = '5%', defaultRight = '5%', defaultTop = '5%', diff --git a/en/option/series/tree.md b/en/option/series/tree.md index 1ab9040ec..2767600fc 100644 --- a/en/option/series/tree.md +++ b/en/option/series/tree.md @@ -26,7 +26,7 @@ The tree diagram is mainly used to visualize the tree data structure, which is a {{ use: partial-series-name() }} {{ use: partial-rect-layout-width-height( - componentName = 'tree', + hostName = 'tree series', defaultLeft = '12%', defaultRight = '12%', defaultTop = '12%', diff --git a/en/option/series/treemap.md b/en/option/series/treemap.md index 3fecdd39e..47885af7b 100644 --- a/en/option/series/treemap.md +++ b/en/option/series/treemap.md @@ -50,7 +50,7 @@ Notice: There are some difference in treemap configuration between ECharts3 and {{ use: partial-series-name() }} {{ use: partial-rect-layout-width-height( - componentName = 'treemap ', + hostName = 'treemap series', defaultLeft = 'center', defaultRight = null, defaultTop = 'middle', @@ -133,7 +133,7 @@ To show the path of the current node. Whether to show the breadcrumb. {{ use: partial-rect-layout( - componentName = "breadcrumb ", + hostName = "breadcrumb", prefix = "##", noZ = true, defaultLeft = "'center'", diff --git a/zh/api/version.md b/zh/api/version.md index ddb5bcd46..aea7002e6 100644 --- a/zh/api/version.md +++ b/zh/api/version.md @@ -1,5 +1,9 @@ {{ target: partial-version }} +{{ if: ${deprecated} }} +> 从 `v${version}` 开始不推荐使用(deprecated)。${deprecated} +{{ else }} > 从 `v${version}` 开始支持 +{{ /if }} {{ // this line break is necessary for md quote }} diff --git a/zh/option-gl/partial/version.md b/zh/option-gl/partial/version.md index dfa8120d7..45166dd61 100644 --- a/zh/option-gl/partial/version.md +++ b/zh/option-gl/partial/version.md @@ -1,5 +1,8 @@ {{ target: partial-version }} +{{ if: ${deprecated} }} +> 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始不推荐使用(deprecated)。${deprecated} +{{ else }} > 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始支持 - +{{ /if }} diff --git a/zh/option/component/calendar.md b/zh/option/component/calendar.md index 224312e84..8997b64f9 100644 --- a/zh/option/component/calendar.md +++ b/zh/option/component/calendar.md @@ -98,7 +98,7 @@ const option = { ) }} {{ use: partial-rect-layout-width-height( - componentName = "calendar", + componentName = "日历(calendar)", defaultLeft = "80", defaultTop = "60" ) }} diff --git a/zh/option/component/grid.md b/zh/option/component/grid.md index 7bef5940a..a46fa2521 100644 --- a/zh/option/component/grid.md +++ b/zh/option/component/grid.md @@ -59,7 +59,7 @@ const option = { 是否显示直角坐标系网格。 {{ use: partial-rect-layout-width-height( - componentName = "grid ", + componentName = "直角坐标系(grid)", defaultLeft = "'10%'", defaultTop = 60, defaultRight = "'10%'", @@ -68,6 +68,8 @@ const option = { ## containLabel(boolean) = false +{{ use: partial-version(version = "6.0.0", deprecated = '参考 [grid.outerBoundsMode](~grid.outerBoundsMode)。') }} + grid 区域是否包含坐标轴的[刻度标签](~yAxis.axisLabel)。 @@ -79,8 +81,70 @@ grid 区域是否包含坐标轴的[刻度标签](~yAxis.axisLabel)。 + `grid.left` `grid.right` `grid.top` `grid.bottom` `grid.width` `grid.height` 决定的是包括了坐标轴标签在内的所有内容所形成的矩形的位置。 + 这常用于『防止标签溢出』的场景,标签溢出指的是,标签长度动态变化时,可能会溢出容器或者覆盖其他组件。 +## outerBoundsMode(string) = 'auto' +{{ use: partial-version(version = "6.0.0") }} + +外边界(outer bounds)是一个用于限制轴标签和轴名称溢出的矩形区域。`outerBoundsMode` 用于定义如何确定该“外边界”的策略。 + +在大多数情况下,无需显式指定 [grid.outerBoundsMode](~grid.outerBoundsMode)、[grid.outerBounds](~grid.outerBounds)、[grid.outerBoundsContain](~grid.outerBoundsContain) 和 [grid.containLabel](~grid.containLabel),因为默认配置已经能够有效防止轴标签和轴名称溢出画布。 + +直角坐标系组件(grid)的布局策略如下: ++ 首先,根据 [grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height) 所定义的矩形区域布置轴线。这可以满足多个 grid 对齐轴线的需求。 ++ 然后,如果轴标签或轴名称超出了外边界(outer bounds),则会收缩该矩形区域以避免溢出。其中,[grid.outerBoundsContain](~grid.outerBoundsContain) 可决定轴标签和轴名称是否受外边界的限制。 + +`outerBoundsMode` 的可选值有: +- `'auto'`/`null`/`undefined`(默认值): + - 当 `grid.containLabel: true` 时,行为等同于 `outerBoundsMode: 'same'`。 + - 否则,如果设置了 [grid.outerBounds](~grid.outerBounds),则使用该值作为外边界(outer bounds)。 + - 否则,自动确定外边界(outer bounds)—— 通常默认为当前 canvas 区域;或者,假如该 grid 被布局在其他坐标系中时(参见 [grid.coordinateSystem](~grid.coordinateSystem)),使用其他坐标系提指定的布局矩形作为外边界。 +- `'none'`:强制将外边界(outer bounds)设为无限大(即不作任何限制),无视是否设置了 [grid.outerBounds](~grid.outerBounds)。 +- 'same':强制将外边界(outer bounds)设置为由 [grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height) 所定义的矩形,无视是否设置了 [grid.outerBounds](~grid.outerBounds)。 + +> 外边界(outer bounds)已涵盖 [grid.containLabel](~grid.containLabel) 的功能,因此 [grid.containLabel](~grid.containLabel) 被不再推荐使用(deprecated)。 +> `grid.containLabel: true` 等价于 `grid: {outerBoundsMode: 'same', outerBoundsContain: 'axisLabel'}`。效果上可能会有细微差别,但通常难以察觉。你可以使用以下代码来强制保持原有效果,不过一般并无此必要。 +> ```js +> import {use} from 'echarts/core'; +> import {LegacyGridContainLabel} from 'echarts/features'; +> use([LegacyGridContainLabel]); +> ``` + +**示例**: [outerBounds 示例](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1). + + +## outerBounds(Object) +{{ use: partial-version(version = "6.0.0") }} + +详见 [grid.outerBoundsMode](~grid.outerBoundsMode). + +也参见 [outerBounds 示例](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1). + +{{ use: partial-rect-layout-width-height( + hostName = "外边界(`outerBounds`)", + noZ = true, + prefix = '##', + defaultLeft = 0, + defaultTop = 0, + defaultRight = 0, + defaultBottom = 0 +) }} + +## outerBoundsContain(boolean) = 'auto' +{{ use: partial-version(version = "6.0.0") }} + +可选值: +- `'auto'`/`null`/`undefined`(默认): + - 若设置了 `containLabel: true`,行为等同于 `outerBoundsContain: 'axisLabel'`。 + - 否则,行为等同于 `outerBoundsContain: 'all'`。 +- `'all'`:外边界(outer bounds)会限制直角坐标系(grid)由 x 轴线和 y 轴线决定的矩形区域、轴标签(axis label)和轴名称(axis name)。 +- `'axisLabel'`:外边界(outer bounds)会限制直角坐标系(grid)由 x 轴线和 y 轴线决定矩形区域和轴标签(axis label);不会限制轴名称(axis name)。 + +更多信息参见 [grid.outerBoundsMode](~grid.outerBoundsMode). + +也参见 [outerBounds 示例](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1). + + {{ use: partial-component-common-style( - componentName = "网格", + componentName = "直角坐标系(grid)", prefix = '#', needShow = true ) }} diff --git a/zh/option/component/legend.md b/zh/option/component/legend.md index 7e7e7da9b..998c095eb 100644 --- a/zh/option/component/legend.md +++ b/zh/option/component/legend.md @@ -129,7 +129,7 @@ const option = { {{ use: partial-rect-layout-width-height( - componentName = "图例" + componentName = "图例(legend)" ) }} ## orient(string) = 'horizontal' diff --git a/zh/option/component/matrix.md b/zh/option/component/matrix.md index 2fd632491..c6a57b8d2 100644 --- a/zh/option/component/matrix.md +++ b/zh/option/component/matrix.md @@ -36,7 +36,7 @@ ) }} {{ use: partial-rect-layout-width-height( - componentName = "matrix", + componentName = "矩阵坐标系(matrix)", defaultLeft = "10%", defaultTop = "10%" ) }} diff --git a/zh/option/component/parallel.md b/zh/option/component/parallel.md index c04ad470d..97e15d650 100644 --- a/zh/option/component/parallel.md +++ b/zh/option/component/parallel.md @@ -445,7 +445,7 @@ const option = { ) }} {{ use: partial-rect-layout-width-height( - componentName = 'parallel ', + componentName = '平行坐标系(parallel)', defaultLeft = 80, defaultRight = 80, defaultTop = 60, diff --git a/zh/option/component/single-axis.md b/zh/option/component/single-axis.md index 196e0c8b1..2acefee0d 100644 --- a/zh/option/component/single-axis.md +++ b/zh/option/component/single-axis.md @@ -12,7 +12,7 @@ ) }} {{ use: partial-rect-layout-width-height( - componentName = "single", + componentName = "单轴(singleAxis)", defaultLeft = "'5%'", defaultTop = "'5%'", defaultRight = "'5%'", diff --git a/zh/option/component/timeline.md b/zh/option/component/timeline.md index 0b6da990a..99a961ee4 100644 --- a/zh/option/component/timeline.md +++ b/zh/option/component/timeline.md @@ -540,7 +540,7 @@ const option = { 表示『播放』按钮的位置。可选值:`'left'`、`'right'`。 {{ use: partial-rect-layout( - componentName = 'timeline' + componentName = '时间轴(timeline)' ) }} ## padding(number|Array) = 5 diff --git a/zh/option/component/title.md b/zh/option/component/title.md index dffeef3f5..5fa0b625e 100644 --- a/zh/option/component/title.md +++ b/zh/option/component/title.md @@ -130,7 +130,7 @@ const option = { 主副标题之间的间距。 {{ use: partial-rect-layout( - componentName = "title " + componentName = "标题(title)" ) }} {{ use: partial-component-common-style( diff --git a/zh/option/component/toolbox.md b/zh/option/component/toolbox.md index 03d82ba01..4c199364d 100644 --- a/zh/option/component/toolbox.md +++ b/zh/option/component/toolbox.md @@ -560,7 +560,7 @@ feature: { ) }} {{ use: partial-rect-layout-width-height( - componentName = "工具栏" + componentName = "工具栏(toolbox)" ) }} ## tooltip(Object) diff --git a/zh/option/component/visual-map.md b/zh/option/component/visual-map.md index 962cfbe73..15c89b4e5 100644 --- a/zh/option/component/visual-map.md +++ b/zh/option/component/visual-map.md @@ -332,7 +332,7 @@ visualMap 组件中,`控制器` 的 `inRange` `outOfRange` 设置。如果没 配置参考 [${visualMapName}.inRange](~${visualMapName}.inRange) {{ use: partial-rect-layout( - componentName = "visualMap ", + componentName = "视觉映射(visualMap)", defaultZ = "4", defaultLeft = "0", defaultRight = "auto", diff --git a/zh/option/partial/rect-layout-width-height.md b/zh/option/partial/rect-layout-width-height.md index 6bdc73906..0594a4556 100644 --- a/zh/option/partial/rect-layout-width-height.md +++ b/zh/option/partial/rect-layout-width-height.md @@ -1,23 +1,31 @@ {{ target: partial-rect-layout-width-height }} +{{ if: ${hostName} }} +{{ var: hostNameStr = ${hostName} }} +{{ else }} +{{ var: hostNameStr = ${componentName} + '组件' }} +{{ /if }} + {{ use: partial-rect-layout( - componentName = ${componentName}, + hostName = ${hostName}, + noZ = ${noZ}, + prefix = ${prefix}, defaultLeft = ${defaultLeft}, defaultTop = ${defaultTop}, defaultRight = ${defaultRight}, defaultBottom = ${defaultBottom} ) }} -## width(string|number) = ${defaultWidth|default("'auto'")} +#${prefix|default("#")} width(string|number) = ${defaultWidth|default("'auto'")} -${componentName}组件的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }} +${hostNameStr}的宽度。{{ if: !${defaultWidth} }}默认自适应。{{ /if }} -## height(string|number) = ${defaultHeight|default("'auto'")} +#${prefix|default("#")} height(string|number) = ${defaultHeight|default("'auto'")} -${componentName}组件的高度。{{ if: !${defaultHeight} }}默认自适应。{{ /if }} +${hostNameStr}的高度。{{ if: !${defaultHeight} }}默认自适应。{{ /if }} diff --git a/zh/option/partial/rect-layout.md b/zh/option/partial/rect-layout.md index d62c5dd6e..1b58267ef 100644 --- a/zh/option/partial/rect-layout.md +++ b/zh/option/partial/rect-layout.md @@ -1,6 +1,12 @@ {{ target: partial-rect-layout }} +{{ if: ${hostName} }} +{{ var: hostNameStr = ${hostName} }} +{{ else }} +{{ var: hostNameStr = ${componentName} + '组件' }} +{{ /if }} + {{ if: !${noZ} }} {{ use: partial-z-zlevel( prefix = ${prefix}, @@ -13,7 +19,7 @@ -${componentName}组件离容器左侧的距离。 +${hostNameStr}离容器左侧的距离。 `left` 的值可以是像 `20` 这样的具体像素值,可以是像 `'20%'` 这样相对于容器高宽的百分比,也可以是 `'left'`, `'center'`, `'right'`。 @@ -23,7 +29,7 @@ ${componentName}组件离容器左侧的距离。 -${componentName}组件离容器上侧的距离。 +${hostNameStr}离容器上侧的距离。 `top` 的值可以是像 `20` 这样的具体像素值,可以是像 `'20%'` 这样相对于容器高宽的百分比,也可以是 `'top'`, `'middle'`, `'bottom'`。 @@ -33,7 +39,7 @@ ${componentName}组件离容器上侧的距离。 -${componentName}组件离容器右侧的距离。 +${hostNameStr}离容器右侧的距离。 `right` 的值可以是像 `20` 这样的具体像素值,可以是像 `'20%'` 这样相对于容器高宽的百分比。 @@ -43,7 +49,7 @@ ${componentName}组件离容器右侧的距离。 -${componentName}组件离容器下侧的距离。 +${hostNameStr}离容器下侧的距离。 bottom 的值可以是像 `20` 这样的具体像素值,可以是像 `'20%'` 这样相对于容器高宽的百分比。 diff --git a/zh/option/partial/version.md b/zh/option/partial/version.md index 17e0d5ebc..8f2d72e37 100644 --- a/zh/option/partial/version.md +++ b/zh/option/partial/version.md @@ -1,5 +1,7 @@ {{ target: partial-version }} - +{{ if: ${deprecated} }} +> 从 `v${version}` 开始不推荐使用(deprecated)。${deprecated} +{{ else }} > 从 `v${version}` 开始支持 - +{{ /if }} diff --git a/zh/option/series/funnel.md b/zh/option/series/funnel.md index fb2a0e3f3..f7262bc67 100644 --- a/zh/option/series/funnel.md +++ b/zh/option/series/funnel.md @@ -189,7 +189,7 @@ option = { ) }} {{ use: partial-rect-layout-width-height( - componentName = "漏斗图", + hostName = "漏斗图系列(funnel series)", defaultLeft = 80, defaultTop = 60, defaultRight = 80, diff --git a/zh/option/series/graph.md b/zh/option/series/graph.md index 11af225c5..f7ebb50b5 100644 --- a/zh/option/series/graph.md +++ b/zh/option/series/graph.md @@ -604,6 +604,7 @@ links: [{ ) }} {{ use: partial-rect-layout-width-height( + hostName = "关系图系列(graph series)", defaultLeft = "'center'", defaultTop = "'middle'", defaultWidth = '自适应', diff --git a/zh/option/series/pie.md b/zh/option/series/pie.md index aff226e2e..d3291174a 100644 --- a/zh/option/series/pie.md +++ b/zh/option/series/pie.md @@ -147,7 +147,7 @@ const option = { {{ use: partial-cursor() }} {{ use: partial-rect-layout-width-height( - componentName = "pie chart", + hostName = "饼图系列(pie series)", defaultLeft = 0, defaultTop = 0, defaultRight = 0, diff --git a/zh/option/series/sankey.md b/zh/option/series/sankey.md index 240dc3246..4caf5be7a 100644 --- a/zh/option/series/sankey.md +++ b/zh/option/series/sankey.md @@ -36,7 +36,7 @@ const option = {"tooltip":{"trigger":"item","triggerOn":"mousemove"},"series":[{ {{ use: partial-series-name() }} {{ use: partial-rect-layout-width-height( - componentName = 'sankey', + hostName = '桑基图系列(sankey series)', defaultLeft = '5%', defaultRight = '20%', defaultTop = '5%', diff --git a/zh/option/series/themeRiver.md b/zh/option/series/themeRiver.md index 48573a34f..7a8c2d5d3 100644 --- a/zh/option/series/themeRiver.md +++ b/zh/option/series/themeRiver.md @@ -105,7 +105,7 @@ const option = { ) }} {{ use: partial-rect-layout-width-height( - componentName = 'thmemRiver', + hostName = '主题河流图系列(themeRiver series)', defaultLeft = '5%', defaultRight = '5%', defaultTop = '5%', diff --git a/zh/option/series/tree.md b/zh/option/series/tree.md index fd3f3fb19..250522471 100644 --- a/zh/option/series/tree.md +++ b/zh/option/series/tree.md @@ -69,7 +69,7 @@ const option = { {{ use: partial-series-name() }} {{ use: partial-rect-layout-width-height( - componentName = 'tree', + hostName = '树图系列(tree series)', defaultLeft = '12%', defaultRight = '12%', defaultTop = '12%', diff --git a/zh/option/series/treemap.md b/zh/option/series/treemap.md index b3978271a..1339b292c 100644 --- a/zh/option/series/treemap.md +++ b/zh/option/series/treemap.md @@ -203,7 +203,7 @@ const option = { {{ use: partial-series-name() }} {{ use: partial-rect-layout-width-height( - componentName = 'treemap ', + hostName = '矩形树图系列(treemap series)', defaultLeft = 'center', defaultRight = null, defaultTop = 'middle', @@ -290,7 +290,7 @@ const option = { 是否显示面包屑。 {{ use: partial-rect-layout( - componentName = "面包屑", + hostName = "面包屑(breadcrumb)", prefix = "##", noZ = true, defaultLeft = "'center'",