This is an automated email from the ASF dual-hosted git repository. 100pah pushed a commit to branch v6.1.0 in repository https://gitbox.apache.org/repos/asf/echarts-doc.git
commit f01a4e83260d6e1835e9a0b60a7d20b90487483a Author: 100pah <[email protected]> AuthorDate: Sun May 24 02:28:51 2026 +0800 dox: (1) Supplement legend tutorial. (2) Add and supplement `triggerEvent`. (3) Add doc for dataZoom.inside cursor styles and candlestick cursor styles. --- README.md | 4 +- en/api/echarts-instance.md | 2 +- en/option/component/axis-common.md | 40 +++++++--- en/option/component/data-zoom-inside.md | 17 +++++ en/option/component/legend.md | 127 ++++++++++++++++++++++++++++++-- en/option/component/matrix.md | 27 +++++++ en/option/component/title.md | 12 ++- en/option/partial/cursor.md | 6 +- en/option/partial/silent.md | 45 ++++++++++- en/option/series/candlestick.md | 4 + en/option/series/line.md | 38 +++++++++- zh/option/component/axis-common.md | 36 +++++++-- zh/option/component/data-zoom-inside.md | 17 +++++ zh/option/component/legend.md | 127 ++++++++++++++++++++++++++++++-- zh/option/component/matrix.md | 27 +++++++ zh/option/component/title.md | 11 ++- zh/option/partial/cursor.md | 7 +- zh/option/partial/silent.md | 45 ++++++++++- zh/option/series/candlestick.md | 4 + zh/option/series/line.md | 38 +++++++++- 20 files changed, 588 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 675f75c4..cc9d9e8d 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 c9ac20b9..02accb76 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 66acda8e..84c1a82e 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; } ``` @@ -1237,7 +1255,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 1c9c460b..162843c1 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 209d2697..be315027 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. +<br> + +**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.) + +<br> -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`. +<br> + +**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. + +<br> + +**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. + +<br> + +**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 1a2babc3..be2499a8 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 ff23218e..502bcb41 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 41aee8dd..6db9dfb0 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")} -<ExampleUIControlEnum options="auto,pointer,move" default="pointer" /> +<ExampleUIControlEnum options="auto,pointer,move,grab,grabbing" 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/silent.md b/en/option/partial/silent.md index 3f4c5da9..cdf2287d 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 }} + +<ExampleUIControlBoolean default="${defaultValue|default('false')}" /> + +{{ 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/series/candlestick.md b/en/option/series/candlestick.md index 82243b05..4eddea3a 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/line.md b/en/option/series/line.md index 115d2c0b..967171db 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 + +<ExampleUIControlEnum options="false,true,line,area" default="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/zh/option/component/axis-common.md b/zh/option/component/axis-common.md index 0b452248..75500cd8 100644 --- a/zh/option/component/axis-common.md +++ b/zh/option/component/axis-common.md @@ -7,19 +7,39 @@ #${prefix} triggerEvent(boolean) = false -坐标轴的标签是否响应和触发鼠标事件，默认不响应。 +{{ use: partial-trigger-event-common-content() }} 事件参数如下： ```ts { - // 组件类型，xAxis, yAxis, radiusAxis, angleAxis - // 对应组件类型都会有一个属性表示组件的 index，例如 xAxis 就是 xAxisIndex - componentType: string, - // 未格式化过的刻度值, 点击刻度标签有效 - value: '', - // 坐标轴名称, 点击坐标轴名称有效 - name: '' + // Component type. 例如： + // 'xAxis'、'yAxis'、'radiusAxis'、'angleAxis'、 + // 'singleAxis'、'parallelAxis'、'radar' 等。 + componentType: string; + componentIndex: number; + // 和 `componentIndex` 相同。 + [componentType]Index?: number; + + // 事件的触发者。 + targetType: 'axisLabel' | 'axisName'; + + // 被内置的 formatter 格式化过的标签字符串。 + // 但是用户提供的 `axisLabel.formatter` 并不影响这个值。 + // 仅当 `targetType: 'axisLabel'` 时存在。 + value?: string; + + // 仅当此标签为断轴（"axis break"）标签时存在。 + break?: { + // 断轴起始值。 + start?: number; + // 断轴终止值。 + end?: number; + }; + + // 即 `axis.name`。 + // 仅当 `targetType: 'axisName'` 时存在。 + name?: string; } ``` diff --git a/zh/option/component/data-zoom-inside.md b/zh/option/component/data-zoom-inside.md index de04102a..6777bc01 100644 --- a/zh/option/component/data-zoom-inside.md +++ b/zh/option/component/data-zoom-inside.md @@ -108,3 +108,20 @@ const option = { 是否阻止 mousemove 事件的默认行为。 + +{{ use: partial-cursor( + prefix = "#", + version = "6.1.0", + defaultValue = "grab", + prop = "cursorGrab", + targetDesc = "鼠标悬浮时在可拖拽的区域上时" +) }} + +{{ use: partial-cursor( + prefix = "#", + version = "6.1.0", + defaultValue = "grabbing", + prop = "cursorGrabbing", + targetDesc = "鼠标拖拽时" +) }} + diff --git a/zh/option/component/legend.md b/zh/option/component/legend.md index 85e2c64e..59cec1ac 100644 --- a/zh/option/component/legend.md +++ b/zh/option/component/legend.md @@ -7,7 +7,9 @@ 图例组件展现了不同系列的标记(symbol)，颜色和名字。可以通过点击图例控制哪些系列不显示。 -ECharts 3 中单个 echarts 实例中可以存在多个图例组件，会方便多个图例的布局。 +图例项和系列或系列数据项的对应规则，详见 [legend.data](~legend.data)。 + +单个 echarts 实例中可以存在多个图例组件，会方便多个图例的布局。（从 `v3.0.0` 开始支持）。 当图例数量过多时，可以使用 [滚动图例（垂直）](${galleryEditorPath}pie-legend&edit=1&reset=1) 或 [滚动图例（水平）](${galleryEditorPath}radar2&edit=1&reset=1)，参见：[legend.type](~legend.type) @@ -290,9 +292,108 @@ legend: { 如果 `data` 没有被指定，会自动从当前系列中获取。多数系列会取自 [series.name](~series.name) 或者 [series.encode](~series.encode) 的 `seriesName` 所指定的维度。如 [饼图](~series-pie) and [漏斗图](~series-funnel) 等会取自 series.data 中的 name。 -如果要设置单独一项的样式，也可以把该项写成配置项对象。此时必须使用 `name` 属性对应表示系列的 `name`。 -示例 +<br> + +**显式指定 `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` 的定义见下文）。 + +<br> + +**自动收集 `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' +``` + +<br> + +**图例控制的内容（LEGEND_TARGET）和图例匹配规则（LEGEND_MATCHING_RULES）：** + +一个图例项可控制整个系列或者系列中的某个数据项（详见 `LEGEND_CONTROL_SERIES_DATA_ITEM`）的显示。这些被控制的内容可称为 `LEGEND_TARGET`。一个 `LEGEND_TARGET` 被图例项控制当且仅当它的 `name`（即系列名或 `series.data` 每项的 `name`）和图例项的 `name` 匹配（无论 `name` 来自直接给出的 `legend.data` 还是自动收集的）。 + +这种映射可以是“多对多”的。例如，如果多个系列共享一个系列名，那么这些系列可以同时被一个图例项控制。 + +<br> + +**图例控制系列数据项（LEGEND_CONTROL_SERIES_DATA_ITEM）：** + +这列系列支持“图例控制系列中具体的每一个数据项”：[pie](~series-pie)、[funnel](~series-funnel)、[chord](~series-chord)、[graph](~series-graph)、[radar](~series-radar) 和 [themeRiver](~series-themeRiver)。通过图例项和数据项的 `name` 字段来进行匹配。 + +<br> + +**图例项的样式：** + +如果要设置单独一项的样式，也可以把该项写成配置项对象，例如： ``` 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 ff9d05fe..a16e5e23 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 fe2c1490..9fa74f1c 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 96bbfc1b..23f3fe9a 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")} -<ExampleUIControlEnum options="auto,pointer,move" default="pointer" /> +<ExampleUIControlEnum options="auto,pointer,move,grab,grabbing" default="pointer" /> {{ if: ${version} }} {{ use: partial-version( @@ -11,5 +11,4 @@ ) }} {{ /if }} -鼠标悬浮时在图形元素上时鼠标的样式是什么。同 CSS 的 `cursor`。 - +${targetDesc|default("鼠标悬浮时在图形元素上时")}鼠标的样式是什么。同 CSS 的 `cursor`。 diff --git a/zh/option/partial/silent.md b/zh/option/partial/silent.md index c50109ba..d6c291c2 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 }} + +<ExampleUIControlBoolean default="${defaultValue|default('false')}" /> + +{{ 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/series/candlestick.md b/zh/option/series/candlestick.md index 30264e9a..73877121 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/line.md b/zh/option/series/line.md index 46235da5..67fa2623 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 + +<ExampleUIControlEnum options="false,true,line,area" default="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 --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
