diff --git a/README.md b/README.md index 675f75c41..cc9d9e8d1 100644 --- a/README.md +++ b/README.md @@ -246,10 +246,10 @@ 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 `}}`. +The template syntax and expressions are enclosed by delimiters `{{` and `}}`. For example, {{ if: condition_expression }} xxx {{ /if }} -The expressoin within `{{` and `}}` can be considered a (restricted) JS expression. +The expression within `{{` and `}}` can be considered a (restricted) JS expression. For example, {{ if: ${someVar1} + 'abc' === '123abc' }} ... {{ /if }} {{ if: !${someVar2} }} ... {{ /if }} diff --git a/en/api/echarts-instance.md b/en/api/echarts-instance.md index c9ac20b90..02accb766 100644 --- a/en/api/echarts-instance.md +++ b/en/api/echarts-instance.md @@ -630,7 +630,7 @@ The format of the input `coord` and return type are defined by each coordinate s + [only yAxis](option.html#xAxis) or [only yAxis](option.html#yAxis): - For example, convert a axis coord to pixel value: + For example, convert an axis coord to pixel value: ```ts // In the xAxis with id 'x0' (type: number), // convert coord 3000 to the horizontal pixel coordinate: diff --git a/en/option/component/axis-common.md b/en/option/component/axis-common.md index 66acda8e2..a7b41ad68 100644 --- a/en/option/component/axis-common.md +++ b/en/option/component/axis-common.md @@ -7,21 +7,39 @@ Set this to `true`, to prevent interaction with the axis. #${prefix} triggerEvent(boolean) = false -Set this to `true` to enable triggering events. +{{ use: partial-trigger-event-common-content() }} Parameters of the event include: ```ts { - // Component type: xAxis, yAxis, radiusAxis, angleAxis - // Each of which has an attribute for index, e.g., xAxisIndex for xAxis - componentType: string, - // Value on axis before being formatted. - // Click on value label to trigger event. - value: '', - // Name of axis. - // Click on label name to trigger event. - name: '' + // Component type, e.g., + // 'xAxis', 'yAxis', 'radiusAxis', 'angleAxis', + // 'singleAxis', 'parallelAxis', 'radar', etc. + componentType: string; + componentIndex: number; + // The same as `componentIndex`. + [componentType]Index?: number; + + // The emitter of this event. + targetType: 'axisLabel' | 'axisName'; + + // A label string formatted by a built-in formatter; + // User-provided `axisLabel.formatter` does not affect this value. + // Present when `targetType: 'axisLabel'`. + value?: string; + + // Present only if this is an axis label for "axis break". + break?: { + // Parsed break start. + start?: number; + // Parsed break start. + end?: number; + }; + + // `axis.name`. + // Present when `targetType: 'axisName'`. + name?: string; } ``` @@ -790,7 +808,7 @@ Option: Time axis, suitable for continuous time series data. As compared to value axis, it has a better formatting for time and a different tick calculation method. For example, it decides to use month, week, day or hour for tick based on the range of span. + `'log'` - Log axis, suitable for log data. Stacked bar or line series with `type: 'log'` axes may lead to significant visual errors and may have unintended effects in certain circumstances. Their use should be avoided. + Logarithmic axis. It is useful when the data spans a very large range of values or when the important pattern is about multiplicative change rather than additive change. {{ target: axis-common }} @@ -1223,6 +1241,8 @@ Example: formatter: '{value} kg' // Use callback. formatter: function (value, index, extra?) { + // Notice: when using `customValues`, parameter `index` is + // provided since `v6.1.0`. return value + 'kg'; } ``` @@ -1237,7 +1257,7 @@ formatter: function (value, index, extra?) { The break info can be obtained from the `extra` param: ```ts type AxisLabelFormatterExtraBreakPart = { - // If this label is a axis break start or end. + // If this label is an axis break start or end. break?: { type: 'start' | 'end'; // The parsed `start`/`end`, always be numbers, and has been diff --git a/en/option/component/data-zoom-inside.md b/en/option/component/data-zoom-inside.md index 1c9c460be..162843c15 100644 --- a/en/option/component/data-zoom-inside.md +++ b/en/option/component/data-zoom-inside.md @@ -77,3 +77,20 @@ How to trigger data window move. Optional values: Whether to prevent default behavior of mouse move event. + +{{ use: partial-cursor( + prefix = "#", + version = "6.1.0", + defaultValue = "grab", + prop = "cursorGrab", + targetDesc = "when mouse hovers over the grabbable area" +) }} + +{{ use: partial-cursor( + prefix = "#", + version = "6.1.0", + defaultValue = "grabbing", + prop = "cursorGrabbing", + targetDesc = "when grabbing" +) }} + diff --git a/en/option/component/legend.md b/en/option/component/legend.md index 209d2697a..be315027c 100644 --- a/en/option/component/legend.md +++ b/en/option/component/legend.md @@ -7,7 +7,9 @@ Legend component. Legend component shows symbol, color and name of different series. You can click legends to toggle displaying series in the chart. -In ECharts 3, a single echarts instance may contain multiple legend components, which makes it easier for the layout of multiple legend components. +See [legend.data](~legend.data) for the matching rules between legend items and series or series data items. + +A single echarts instance may contain multiple legend components, which makes it easier for the layout of multiple legend components. (since `v3.0.0`) If there have to be too many legend items, [vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1) or [horizontally scrollable legend](${galleryEditorPath}radar2&edit=1&reset=1) are options to paginate them. Check [legend.type](~legend.type) please. @@ -192,11 +194,107 @@ Icon of the legend items. ## data(Array) -Data array of legend. An array item is usually a `name` representing string. (If it is a [pie chart](~series-pie), it could also be the `name` of a single data in the pie chart) of a series. Legend component would automatically calculate the color and icon according to series. Special string `''` (null string) or `'\n'` (new line string) can be used for a new line. +
+ +**Explicitly Specify `legend.data`:** + +`legend.data` is an array. An array item can be a string (representing `name`) or an object (containing a `name` field). + +If the `name` of an array item is a special string `''` or `'\n'`, this array item is only used to create a line break. +```js +legend: { + data: ['a', 'b', '\n', 'c', 'd'] + // The final displayed items are (line wrapped): + // 'a' 'b' + // 'c' 'd' +} +``` + +If the `name` of an array item dose not match any `LEGEND_TARGET`, this legend item is ignored. (See also the description of `LEGEND_TARGET` below.) + +
-If `data` is not specified, it will be auto collected from series. For most of series, it will be collected from [series.name](~series.name) or the dimension name specified by `seriesName` of [series.encode](~series.encode). For some types of series like [pie](~series-pie) and [funnel](~series-funnel), it will be collected from the name field of `series.data`. +**Automatically Collect `legend.data`:** + +If `legend.data` is not explicitly specified, it is automatically collected from `series` or `dataset`. +- It is basically collected from [series.name](~series.name). +- It can also collect from `dataset` according to the dimension specified in `seriesName` field in [series.encode](~series.encode). +- Some series supports `LEGEND_CONTROL_SERIES_DATA_ITEM` (see details below). It is collected from the `name` field (if present) of each `series.data` item. For a single series, if these `name`s from `series.data` are collected, series name is no longer collected. + +Some examples: +```ts +option = { + legend: {/* No `legend.data` field is specified. */}, + xAxis: {}, + yAxis: {}, + series: [{ + type: 'line', name: 'lineA', data: [11, 22] + }, { + type: 'line', name: 'lineB', data: [111, 222] + }, { + type: 'pie', name: 'pieC', + data: [ + {name: 'pieItemA', value: 9}, + {name: 'pieItemB', value: 8}, + {name: 'pieItemC', value: 7}, + ] + }], +} +// The final displayed legend items are: +// 'lineA' 'lineB' 'pieItemA' 'pieItemB' 'pieItemC' +``` +```ts +option = { + legend: {/* No `legend.data` field is specified. */}, + dataset: { + source: [ + [null, 'nameH', 'nameI', 'nameJ', 'nameK'], + ['2012-01', 32, 65, 71, 31], + ['2012-02', 41, 67, 89, 23], + ['2012-03', 58, 61, 97, 12], + ['2012-04', 67, 73, 105, 9], + ['2012-05', 72, 67, 122, 18], + ] + }, + xAxis: {type: 'category'}, + yAxis: {}, + series: [{ + type: 'bar', + // Retrieve `seriesName` from dataset column with index 1; get 'nameH'. + encode: {x: 0, y: 1, seriesName: 1} + }, { + type: 'bar', + // Retrieve `seriesName` from dataset column with index 3; get 'nameJ'. + encode: { x: 0, y: 3, seriesName: 3 } + }, { + type: 'bar', + // Retrieve `seriesName` from dataset column with index 3; get 'nameI'. + encode: { x: 0, y: 2, seriesName: 2 } + }] +}; +// The final displayed legend items are: +// 'nameH' 'nameJ' 'nameI' +``` -If you need to set the style for a single item, you may also set the configuration of it. In this case, `name` attribute is used to represent name of `series`. +
+ +**LEGEND_TARGET and LEGEND_MATCHING_RULES:** + +A legend item can control the visibility of a entire series or a series data item (see `LEGEND_CONTROL_SERIES_DATA_ITEM` below). They can be called as `LEGEND_TARGET`. A `LEGEND_TARGET` is under control if and only if the `name` from `legend.data` (either explicitly specified or automatically collected) matches the name from `LEGEND_TARGET`, i.e., matches series names or series data item names. + +This mapping is allowed to be many-to-many. For example, if multiple series share the same series name, they can be controlled by a single legend item. + +
+ +**LEGEND_CONTROL_SERIES_DATA_ITEM:** + +These series support that legend items control each series data items: [pie](~series-pie), [funnel](~series-funnel), [chord](~series-chord), [graph](~series-graph), [radar](~series-radar) and [themeRiver](~series-themeRiver). They are matched according to `name` fields of legend items and series data items. + +
+ +**Legend Item Styles:** + +If you need to set the style for a single item, you may also set the configuration of it. Example: ``` @@ -498,11 +596,28 @@ The gap between selector button and legend component. ## triggerEvent(boolean) = false -{{ use: partial-version( +{{ use: partial-trigger-event-common-content( version = "6.0.0" ) }} -Set this to `true` to enable triggering events. +Parameters of the event include: + +```ts +{ + componentType: 'legend'; + // legend component index. (based on echarts option) + componentIndex: number; + // The `name` of this legend item, which controls the + // visibility of LEGEND_TARGET. + // See `legend.data` for more details. + value: string; + // The index of the triggering legend item. + dataIndex: number; + // The index of the first series that matches + // this legend item. (based on echarts option) + seriesIndex: number; +} +``` {{ target: partial-legend-style }} diff --git a/en/option/component/matrix.md b/en/option/component/matrix.md index 1a2babc35..be2499a89 100644 --- a/en/option/component/matrix.md +++ b/en/option/component/matrix.md @@ -121,3 +121,30 @@ matrix: { // ... } ``` + +## triggerEvent(boolean) = false + +{{ use: partial-trigger-event-common-content( + version = "6.1.0" +) }} + +Parameters of the event include: + +```ts +{ + componentType: 'matrix'; + // legend component index. (based on echarts option) + componentIndex: number; + // The same as `componentIndex`. + matrixIndex: number; + + targetType: 'x' | 'y' | 'body' | 'corner'; + + // Displayed cell text. + name: string; + // Cell value (provided by echarts option). + value: textValue; + // Cell coord. That is `MatrixXYLocator[]`. + coord: number; +} +``` diff --git a/en/option/component/title.md b/en/option/component/title.md index ff23218eb..502bcb414 100644 --- a/en/option/component/title.md +++ b/en/option/component/title.md @@ -106,7 +106,17 @@ Optional values: `'auto'`, `'top'`, `'bottom'`, `'middle'`. ## triggerEvent(boolean) = false -Set this to `true` to enable triggering events +{{ use: partial-trigger-event-common-content() }} + +The parameters of the event: + +```ts +{ + componentType: 'title'; + // The index of the title component (base on echarts option) + componentIndex: number; +} +``` ## padding(number|Array) = 5 diff --git a/en/option/partial/cursor.md b/en/option/partial/cursor.md index 41aee8dd8..6db9dfb03 100644 --- a/en/option/partial/cursor.md +++ b/en/option/partial/cursor.md @@ -1,9 +1,9 @@ {{ target: partial-cursor }} -#${prefix|default('#')} cursor(string) = 'pointer' +#${prefix|default('#')} ${prop|default("cursor")}(string) = ${defaultValue|default("pointer")} - + {{ if: ${version} }} {{ use: partial-version( @@ -11,5 +11,5 @@ ) }} {{ /if }} -The mouse style when mouse hovers on an element, the same as `cursor` property in `CSS`. +The mouse style ${targetDesc|default("when mouse hovers over an element")}, the same as `cursor` property in `CSS`. diff --git a/en/option/partial/item-style.md b/en/option/partial/item-style.md index 329085bb4..204b09894 100644 --- a/en/option/partial/item-style.md +++ b/en/option/partial/item-style.md @@ -23,6 +23,8 @@ Supports callback functions, in the form of: Input parameters are `seriesIndex`, `dataIndex`, `data`, `value`, and etc. of data item. {{ /if }} +${colorExtraInfo} + #${prefix} borderColor(Color) = ${defaultBorderColor|default("'#000'")} diff --git a/en/option/partial/matrix-header.md b/en/option/partial/matrix-header.md index cc1aeed29..f97f2bbfc 100644 --- a/en/option/partial/matrix-header.md +++ b/en/option/partial/matrix-header.md @@ -44,9 +44,9 @@ data: [{ }] ``` -If [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is not provided, it will be collected from `series.data` or `dataset.soruce`. +If [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is not provided, and [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) is provided, a [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is automatically composed according to [matrix.${matrixDim}.length](~matrix.${matrixDim}.length). -See [matrix data collection example](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1). +Otherwise, if either of them are provided, [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) will be automatically collected from `series.data` or `dataset.source`. See [matrix data collection example](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1). And in this case [series.encode](~series-scatter.encode) can be used to specify the dimension from which value is collected. For example, ```js @@ -81,6 +81,15 @@ See [matrix.${matrixDim}.data](~matrix.${matrixDim}.data). {{ use: partial-matrix-dimension-size-desc }} +### length(number) + +{{ use: partial-version(version = "6.1.0") }} + +Users can omit [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) but only provide a [matrix.${matrixDim}.length](~matrix.${matrixDim}.length), which defines the {{ if: ${matrixDim} === 'x' }}column{{ else }}row{{ /if }} number. This is useful for headless matrix (i.e., [matrix.${matrixDim}.show](~matrix.${matrixDim}.show) is `false`), where only column and row number need to be specified. + +Note: [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) is ignored if [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is specified. + + {{ use: partial-matrix-cell-style-option( prefix='##', name=${name} diff --git a/en/option/partial/silent.md b/en/option/partial/silent.md index 3f4c5da9b..cdf2287d7 100644 --- a/en/option/partial/silent.md +++ b/en/option/partial/silent.md @@ -11,5 +11,48 @@ ) }} {{ /if }} -Whether to ignore mouse events. Default value is false, for triggering and responding to mouse events. +Whether to ignore user interactions (typically, mouse or touch events). +- `true`: Elements do not respond to mouse and touch interactions. As a result: + - Interactive features are disabled, such as `tooltip`, hover state changing (i.e., `emphasis`), hover linking, etc. + - Mouse/touch events are not dispatched to user-registered listeners (i.e., `chart.on('xxx', listener)`). +- `false`: + - Interactive features are not disabled by this option, but they still depend on other relevant options to be enabled. + - Mouse/touch events are not prevented by this option, but they still depend on other relevent options (typically, `triggerEvent`, if supported). + +{{ /target }} + + + +{{ target: partial-trigger-event-common-content }} + + + +{{ use: partial-trigger-event-common-content-1( + version = ${version} +) }} +{{ use: partial-trigger-event-common-content-2() }} + +{{ /target }} + + + +{{ target: partial-trigger-event-common-content-1 }} + +{{ if: ${version} }} +{{ use: partial-version(version = ${version}) }} +{{ /if }} + +Whether to enable to dispatch mouse/touch events to user-registered listeners (i.e., `chart.on('xxx', function (event) {})`). + +Supported mouse/touch events are `'click'`, `'dblclick'`, `'mouseover'`, `'mouseout'`, `'mousemove'`, `'mousedown'`, `'mouseup'`, `'globalout'`, `'contextmenu'`. Note, both mouse and touch events are unified to the event type `'mouse{xxx}'`. + +{{ /target }} + + + +{{ target: partial-trigger-event-common-content-2 }} +Values: +- `true`: Enable to trigger events. But dispatching also requires option `silent` to be falsy. +- `false`: Disable to trigger mouse/touch events, even if option `silent` is falsy. +{{ /target }} diff --git a/en/option/partial/tooltip-common.md b/en/option/partial/tooltip-common.md index 33b0856f7..f53d24a5d 100644 --- a/en/option/partial/tooltip-common.md +++ b/en/option/partial/tooltip-common.md @@ -396,9 +396,13 @@ Interface: ``` {{ use: partial-version( - feature = '`dataIndex` is provided', + feature = '`dataIndex` is provided; but not reasonable when `dataZoom` exists, since it is the index after dataZoom filtering.', version = '5.5.0' ) }} +{{ use: partial-version( + feature = '`dataIndex` is corrected to the index before `dataZoom` filtering.', + version = '6.1.0' +) }} Example: ```ts diff --git a/en/option/partial/version.md b/en/option/partial/version.md index 044301567..29c2868ee 100644 --- a/en/option/partial/version.md +++ b/en/option/partial/version.md @@ -5,7 +5,7 @@ {{ if: ${deprecated} }} Deprecated since `v${version}`. ${deprecated} {{ elif: ${feature} }} -${feature} since `v${version}` +Since `v${version}` ${feature} {{ else }} Since `v${version}` {{ /if }} diff --git a/en/option/series/bar.md b/en/option/series/bar.md index 5f6327f8a..915b9e88c 100644 --- a/en/option/series/bar.md +++ b/en/option/series/bar.md @@ -5,7 +5,7 @@ **bar chart** -Bar chart shows different data through the height of a bar, which is used in [rectangular coordinate](~grid) with at least 1 category axis. +Bar chart shows different data through the height of a bar. Currently it can only be used in [Cartesian coordinate system (i.e., grid component)](~grid) or [polar coordinate system](~polar). ## type(string) = 'bar' diff --git a/en/option/series/candlestick.md b/en/option/series/candlestick.md index 82243b056..4eddea3a6 100644 --- a/en/option/series/candlestick.md +++ b/en/option/series/candlestick.md @@ -311,6 +311,10 @@ Select state of single data. {{ use: partial-tooltip-in-series() }} +{{ use: partial-cursor( + prefix = "#", + version = "6.1.0" +) }} {{ target: partial-candlestick-item-style-detail }} diff --git a/en/option/series/gauge.md b/en/option/series/gauge.md index 101236420..9b4ffa9dd 100644 --- a/en/option/series/gauge.md +++ b/en/option/series/gauge.md @@ -195,7 +195,9 @@ Whether to clip overflow. The style of progress. {{ use: partial-item-style( - prefix = "###" + prefix = "###", + defaultColor = "'auto'", + colorExtraInfo = "Notice: value 'auto' is supported since `v6.1.0`" ) }} ## splitLine(Object) diff --git a/en/option/series/line.md b/en/option/series/line.md index 115d2c0b4..967171dbc 100644 --- a/en/option/series/line.md +++ b/en/option/series/line.md @@ -74,13 +74,49 @@ Whether to connect the line across null points. seriesType = "line" ) }} + +## triggerEvent(boolean|string) = false + + + +{{ use: partial-trigger-event-common-content-1( + version = "6.1.0" +) }} +{{ use: partial-trigger-event-common-content-2() }} +- `'line'`: Only the line is the emitter. +- `'area'`: Only the area (present when using `areaStyle`), is the emitter. + +The parameters of the event include: +```ts +{ + componentType: 'series'; + componentSubType: 'line'; + seriesType: 'line'; + // The index with respect to the declaration in echarts option. + componentIndex: number; + // The same as `componentIndex`. + seriesIndex: number; + // The declared `series.name`. + seriesName: string; + // For determining this event is triggered by area or line + selfType: 'area' | 'line'; +} +``` + + ## triggerLineEvent(boolean) = false {{ use: partial-version( version = "5.2.2" ) }} -Whether `line` and `area` can trigger the event. +{{ use: partial-version( + deprecated = "Use `triggerEvent` instead.", + version = "6.1.0" +) }} + +Whether the line and the area can trigger the event. + ## step(string|boolean) = false diff --git a/en/option/series/pictorialBar.md b/en/option/series/pictorialBar.md index e46712771..319db1dc6 100644 --- a/en/option/series/pictorialBar.md +++ b/en/option/series/pictorialBar.md @@ -7,7 +7,7 @@ Pictorial bar chart is a type of bar chart that customized glyph (like images, [SVG PathData](http://www.w3.org/TR/SVG/paths.html#PathData)) can be used instead of rectangular bar. This kind of chart is usually used in infographic. -Pictorial bar chart can only be used in [rectangular coordinate](~grid) with at least 1 category axis. +Pictorial bar chart can only be used in [Cartesian coordinate system (i.e., grid component)](~grid). **Example:** diff --git a/src/components/DocContentItemCard.vue b/src/components/DocContentItemCard.vue index d539a9b45..b3aff6d23 100644 --- a/src/components/DocContentItemCard.vue +++ b/src/components/DocContentItemCard.vue @@ -26,7 +26,7 @@ - = {{nodeData.default}} + = {{nodeData.default}} + +**显式指定 `legend.data`：** + +`legend.data` 是一个数组。每个数组项可以是一个字符串（表示 `name`）或者一个对象（含有 `name` 属性）。 + +如果数组项的 `name` 是特殊字符串 `''` 或 `'\n'`，这项表示换行。 +```js +legend: { + data: ['a', 'b', '\n', 'c', 'd'] + // 最终显示的项为（被换行）： + // 'a' 'b' + // 'c' 'd' +} +``` + +如果数组项的 `name` 不匹配任何的 `LEGEND_TARGET`，这项会被忽略。（`LEGEND_TARGET` 的定义见下文）。 + +
+ +**自动收集 `legend.data`：** + +如果 `legend.data` 没有被给定，会自动从 `series` 或 `dataset` 中收集得来. +- 一般会收集 [series.name](~series.name)。 +- 如果 [series.encode](~series.encode) 的 `seriesName` 字段被指定，也会根据它从 `dataset` 中的对应的维度进行收集。 +- 一些系列支持 `LEGEND_CONTROL_SERIES_DATA_ITEM` （使用图例控制系列数据项，详见下文）。如果 `series.data` 的数据项中存在 `name` 属性，它们也会被收集。对于任一系列，如果从 `series.data` 中收集 `name`，那么不再从收集系列名。 + +一些示例： +```ts +option = { + legend: {/* `legend.data` 没有被指定。 */}, + xAxis: {}, + yAxis: {}, + series: [{ + type: 'line', name: 'lineA', data: [11, 22] + }, { + type: 'line', name: 'lineB', data: [111, 222] + }, { + type: 'pie', name: 'pieC', + data: [ + {name: 'pieItemA', value: 9}, + {name: 'pieItemB', value: 8}, + {name: 'pieItemC', value: 7}, + ] + }], +} +// 最终显示的图例项为： +// 'lineA' 'lineB' 'pieItemA' 'pieItemB' 'pieItemC' +``` +```ts +option = { + legend: {/* `legend.data` 没有被指定。 */}, + dataset: { + source: [ + [null, 'nameH', 'nameI', 'nameJ', 'nameK'], + ['2012-01', 32, 65, 71, 31], + ['2012-02', 41, 67, 89, 23], + ['2012-03', 58, 61, 97, 12], + ['2012-04', 67, 73, 105, 9], + ['2012-05', 72, 67, 122, 18], + ] + }, + xAxis: {type: 'category'}, + yAxis: {}, + series: [{ + type: 'bar', + // 从 dataset 的 index 为 1 的列中收集 `seriesName`，得到 'nameH'. + encode: {x: 0, y: 1, seriesName: 1} + }, { + type: 'bar', + // 从 dataset 的 index 为 3 的列中收集 `seriesName`，得到 'nameJ'. + encode: { x: 0, y: 3, seriesName: 3 } + }, { + type: 'bar', + // 从 dataset 的 index 为 2 的列中收集 `seriesName`，得到 'nameI'. + encode: { x: 0, y: 2, seriesName: 2 } + }] +}; +// 最终显示的图例项为： +// 'nameH' 'nameJ' 'nameI' +``` + +
+ +**图例控制的内容（LEGEND_TARGET）和图例匹配规则（LEGEND_MATCHING_RULES）：** + +一个图例项可控制整个系列或者系列中的某个数据项（详见 `LEGEND_CONTROL_SERIES_DATA_ITEM`）的显示。这些被控制的内容可称为 `LEGEND_TARGET`。一个 `LEGEND_TARGET` 被图例项控制当且仅当它的 `name`（即系列名或 `series.data` 每项的 `name`）和图例项的 `name` 匹配（无论 `name` 来自直接给出的 `legend.data` 还是自动收集的）。 + +这种映射可以是“多对多”的。例如，如果多个系列共享一个系列名，那么这些系列可以同时被一个图例项控制。 + +
+ +**图例控制系列数据项（LEGEND_CONTROL_SERIES_DATA_ITEM）：** + +这列系列支持“图例控制系列中具体的每一个数据项”：[pie](~series-pie)、[funnel](~series-funnel)、[chord](~series-chord)、[graph](~series-graph)、[radar](~series-radar) 和 [themeRiver](~series-themeRiver)。通过图例项和数据项的 `name` 字段来进行匹配。 + +
+ +**图例项的样式：** + +如果要设置单独一项的样式，也可以把该项写成配置项对象，例如： ``` data: [{ name: '系列1', @@ -592,11 +693,27 @@ selector: ['all', 'inverse'] ## triggerEvent(boolean) = false -{{ use: partial-version( +{{ use: partial-trigger-event-common-content( version = "6.0.0" ) }} -是否触发事件。 +事件对象的内容为： + +```ts +{ + componentType: 'legend'; + // 图例组件的 index（基于 echarts option）。 + componentIndex: number; + // 这个图例项的 `name`。它控制了 LEGEND_TARGET 是否显示。 + // 参见 `legend.data`。 + value: string; + // 图例项的 index 。 + dataIndex: number; + // 匹配这个图例项的第一个系列的 index（基于 echarts option）。 + seriesIndex: number; +} +``` + {{ target: partial-legend-style }} diff --git a/zh/option/component/matrix.md b/zh/option/component/matrix.md index ff9d05fe3..a16e5e233 100644 --- a/zh/option/component/matrix.md +++ b/zh/option/component/matrix.md @@ -122,3 +122,30 @@ matrix: { // ... } ``` + +## triggerEvent(boolean) = false + +{{ use: partial-trigger-event-common-content( + version = "6.1.0" +) }} + +事件对象的内容为： + +```ts +{ + componentType: 'matrix'; + // 图例组件的 index（基于 echarts option）。 + componentIndex: number; + // 同 `componentIndex`。 + matrixIndex: number; + + targetType: 'x' | 'y' | 'body' | 'corner'; + + // 单元格（cell）的内容字符串。 + name: string; + // 单元格（cell）的值（来自 echarts option）。 + value: textValue; + // 单元格（cell）坐标。它实际是 `MatrixXYLocator[]`。 + coord: number; +} +``` diff --git a/zh/option/component/title.md b/zh/option/component/title.md index fe2c1490d..9fa74f1c1 100644 --- a/zh/option/component/title.md +++ b/zh/option/component/title.md @@ -123,7 +123,16 @@ const option = { ## triggerEvent(boolean) = false -是否触发事件。 +{{ use: partial-trigger-event-common-content() }} + +事件对象的内容为： +```ts +{ + componentType: 'title'; + // title 组件的 index（基于 echarts option）。 + componentIndex: number; +} +``` ## padding(number|Array) = 5 diff --git a/zh/option/partial/cursor.md b/zh/option/partial/cursor.md index 96bbfc1b6..23f3fe9a4 100644 --- a/zh/option/partial/cursor.md +++ b/zh/option/partial/cursor.md @@ -1,9 +1,9 @@ {{ target: partial-cursor }} -#${prefix|default('#')} cursor(string) = 'pointer' +#${prefix|default('#')} ${prop|default("cursor")}(string) = ${defaultValue|default("pointer")} - + {{ if: ${version} }} {{ use: partial-version( @@ -11,5 +11,4 @@ ) }} {{ /if }} -鼠标悬浮时在图形元素上时鼠标的样式是什么。同 CSS 的 `cursor`。 - +${targetDesc|default("鼠标悬浮时在图形元素上时")}鼠标的样式是什么。同 CSS 的 `cursor`。 diff --git a/zh/option/partial/item-style.md b/zh/option/partial/item-style.md index be4c54326..a974995d5 100644 --- a/zh/option/partial/item-style.md +++ b/zh/option/partial/item-style.md @@ -23,6 +23,8 @@ ${name}图形的颜色。{{ if: ${useColorPalatte} }} 默认从全局调色盘 [ 传入的是数据项 `seriesIndex`, `dataIndex`, `data`, `value` 等各个参数。 {{ /if }} +${colorExtraInfo} + #${prefix} borderColor(Color) = ${defaultBorderColor|default("'#000'")} diff --git a/zh/option/partial/matrix-header.md b/zh/option/partial/matrix-header.md index 16cf09f96..fcc4867e3 100644 --- a/zh/option/partial/matrix-header.md +++ b/zh/option/partial/matrix-header.md @@ -44,9 +44,9 @@ data: [{ }] ``` -如果 [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) 没有提供，它会从 `series.data` 或者 `dataset.source` 中自动收集。 +如果 [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) 没有提供，且 [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) 提供了，[matrix.${matrixDim}.data](~matrix.${matrixDim}.data) 会自动基于 [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) 构造出来。 -参见 [示例](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1)。 +否则，如果它们都没有提供，则 [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) 会从 `series.data` 或者 `dataset.source` 中自动收集出来。参见 [示例](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1)。 在这种情况下，[series.encode](~series-scatter.encode) 可指定从哪个维度收集数据。例如： ```js @@ -84,6 +84,14 @@ var option = { {{ use: partial-matrix-dimension-size-desc }} +### length(number) + +{{ use: partial-version(version = "6.1.0") }} + +[matrix.${matrixDim}.data](~matrix.${matrixDim}.data) 可不提供，而只提供 [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) 来决定{{ if: ${matrixDim} === 'x' }}列{{ else }}行{{ /if }}数。这种方式方便了无头矩阵（即 [matrix.${matrixDim}.show](~matrix.${matrixDim}.show) 为 `false` 时）的创建，这种情况下只有行列数需要提供。 + +注：如果提供了 [matrix.${matrixDim}.data](~matrix.${matrixDim}.data)，则 [matrix.${matrixDim}.length](~matrix.${matrixDim}.length)会被忽略。 + {{ use: partial-matrix-cell-style-option( prefix='##', diff --git a/zh/option/partial/silent.md b/zh/option/partial/silent.md index c50109ba3..d6c291c20 100644 --- a/zh/option/partial/silent.md +++ b/zh/option/partial/silent.md @@ -11,5 +11,48 @@ ) }} {{ /if }} -图形是否不响应和触发鼠标事件，默认为 false，即响应和触发鼠标事件。 +图形是否不响应和用户交互（鼠标和触摸事件）。 +- `true`: 图形不响应用户交互。这导致： + - 用户交互功能被禁止，例如 `tooltip`、鼠标悬浮时的状态变化（`emphasis`），鼠标悬浮时的联动等。 + - 对外的鼠标和触摸事件不再发送给开发者注册的监听器（`chart.on('xxx', listener)`）。 +- `false`: + - 用户交互功能不被此配置项禁止，但是是否可交互仍取决于其他相关配置项的设置。 + - 对外的鼠标和触摸事件不被此配置项禁止，但是是否发送仍取决于其他配置项，一般是 `triggerEvent`（如果支持此配置项的话）。 + +{{ /target }} + + + +{{ target: partial-trigger-event-common-content }} + + + +{{ use: partial-trigger-event-common-content-1( + version = ${version} +) }} +{{ use: partial-trigger-event-common-content-2() }} + +{{ /target }} + + + +{{ target: partial-trigger-event-common-content-1 }} + +{{ if: ${version} }} +{{ use: partial-version(version = ${version}) }} +{{ /if }} + +鼠标和触摸事件是否发送给开发者注册的监听器（`chart.on('xxx', function (event) {})`）。 + +支持的鼠标和触摸事件为 `'click'`、`'dblclick'`、`'mouseover'`、`'mouseout'`、`'mousemove'`、`'mousedown'`、`'mouseup'`、`'globalout'`、`'contextmenu'`。注意，鼠标和触摸事件都统一使用名字 `'mouse{xxx}'`。 + +{{ /target }} + + + +{{ target: partial-trigger-event-common-content-2 }} +可取值： +- `true`: 允许对外发送事件。但是它也需要 `silent` 配置项为 `false` 才能真正发送事件。 +- `false`: 禁止对外发送事件，哪怕 `silent` 配置项为 `false`。 +{{ /target }} diff --git a/zh/option/partial/tooltip-common.md b/zh/option/partial/tooltip-common.md index 0bd352ed2..cade2c005 100644 --- a/zh/option/partial/tooltip-common.md +++ b/zh/option/partial/tooltip-common.md @@ -401,8 +401,12 @@ tooltip 中数值显示部分的格式化回调函数。 ``` {{ use: partial-version( - feature = '`dataIndex` 参数', - version = '5.3.0' + feature = '`dataIndex` 参数。但是其值当 `dataZoom` 存在时不合理，因为所取的值是数据被 `dataZoom` 过滤后的 index。', + version = '5.5.0' +) }} +{{ use: partial-version( + feature = '`dataIndex` 参数修正 `dataZoom` 过滤前的 index', + version = '6.1.0' ) }} 示例： diff --git a/zh/option/partial/version.md b/zh/option/partial/version.md index ddd5265a9..1365bd06b 100644 --- a/zh/option/partial/version.md +++ b/zh/option/partial/version.md @@ -5,7 +5,7 @@ {{ if: ${deprecated} }} 从 `v${version}` 开始不推荐使用（deprecated）。${deprecated} {{ elif: ${feature} }} -${feature} 从 `v${version}` 开始支持 +从 `v${version}` 开始支持${feature} {{ else }} 从 `v${version}` 开始支持 {{ /if }} diff --git a/zh/option/series/bar.md b/zh/option/series/bar.md index eb18e1a41..95e9b8426 100644 --- a/zh/option/series/bar.md +++ b/zh/option/series/bar.md @@ -7,6 +7,8 @@ 柱状图（或称条形图）是一种通过柱形的高度（横向的情况下则是宽度）来表现数据大小的一种常用图表类型。 +当前只支持用在 [直角坐标系（即 grid 组件）](~grid) 或 [极坐标](~polar) 上。 + const option = { diff --git a/zh/option/series/candlestick.md b/zh/option/series/candlestick.md index 30264e9aa..738771218 100644 --- a/zh/option/series/candlestick.md +++ b/zh/option/series/candlestick.md @@ -500,6 +500,10 @@ series: [{ {{ use: partial-tooltip-in-series() }} +{{ use: partial-cursor( + prefix = "#", + version = "6.1.0" +) }} {{ target: partial-candlestick-item-style-detail }} diff --git a/zh/option/series/gauge.md b/zh/option/series/gauge.md index d235567c4..5d8a11ad8 100644 --- a/zh/option/series/gauge.md +++ b/zh/option/series/gauge.md @@ -208,7 +208,9 @@ color: [ 进度条样式。 {{ use: partial-item-style( - prefix = "###" + prefix = "###", + defaultColor = "'auto'", + colorExtraInfo = "自 `v6.1.0` 起 'auto' 才被支持。" ) }} ## splitLine(Object) diff --git a/zh/option/series/line.md b/zh/option/series/line.md index 46235da58..67fa2623e 100644 --- a/zh/option/series/line.md +++ b/zh/option/series/line.md @@ -103,13 +103,49 @@ const option = { seriesType = "line" ) }} + +## triggerEvent(boolean|string) = false + + + +{{ use: partial-trigger-event-common-content-1( + version = "6.1.0" +) }} +{{ use: partial-trigger-event-common-content-2() }} +- `'line'`: 只有在线条上交互时派发事件。 Only the line is the interactive element. +- `'area'`: 只有在区域（当使用 `areaStyle` 时候存在）上交互时派发事件。 + +事件的参数包括： +```ts +{ + componentType: 'series'; + componentSubType: 'line'; + seriesType: 'line'; + // 序数（从 0 起），基于 echarts options 的声明。 + componentIndex: number; + // 同 `componentIndex`。 + seriesIndex: number; + // 声明的 `series.name`。 + seriesName: seriesModel.name; + // 为了区分事件触发于 area 还是 line。 + selfType: 'area' | 'line'; +} +``` + + ## triggerLineEvent(boolean) = false {{ use: partial-version( version = "5.2.2" ) }} -线条和区域面积是否触发事件 +{{ use: partial-version( + deprecated = "Use `triggerEvent` instead.", + version = "6.1.0" +) }} + +线条和区域面积是否触发事件。 + ## step(string|boolean) = false diff --git a/zh/option/series/pictorialBar.md b/zh/option/series/pictorialBar.md index e042a4b51..7c5fd0c62 100644 --- a/zh/option/series/pictorialBar.md +++ b/zh/option/series/pictorialBar.md @@ -5,7 +5,7 @@ **象形柱图** -象形柱图是可以设置各种具象图形元素（如图片、[SVG PathData](http://www.w3.org/TR/SVG/paths.html#PathData) 等）的柱状图。往往用在信息图中。用于有至少一个类目轴或时间轴的[直角坐标系](~grid)上。 +象形柱图是可以设置各种具象图形元素（如图片、[SVG PathData](http://www.w3.org/TR/SVG/paths.html#PathData) 等）的柱状图。往往用在信息图中。目前只支持用于 [直角坐标系（即grid 组件）](~grid) 上。 **示例：** ~[800x400](${galleryViewPath}pictorialBar-hill&reset=1&edit=1)