Skip to content

Commit 09904ec

Browse files
committed
doc(custom): fix doc description
1 parent 2d81ca1 commit 09904ec

5 files changed

Lines changed: 82 additions & 15 deletions

File tree

en/api/echarts.md

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -237,15 +237,50 @@ Registers a theme, should be specified when [initialize the chart instance](~ech
237237

238238
{{ use: partial-version(version: '6.0.0') }}
239239

240-
Register a custom series. After registration, it can be used as [series-custom.type](option.html#series-custom.type) in [setOption](~api.html#echartsInstance.setOption).
241-
242240
```ts
243-
(type: string, renderItem: Function) => void
241+
(type: string, renderItem: Function)
244242
```
245243

246-
+ `type` is the type of the chart to be registered, that is, the `series.type` written later in `setOption`.
244+
Register a custom series. After registration, it can be used in [setOption](~api.html#echartsInstance.setOption).
245+
246+
+ `type` is the type of the chart to be registered, that is, the `series.renderItem` written later in `setOption`.
247247
+ `renderItem` is the graphic rendering logic of the custom series. For details, see [series-custom.renderItem](option.html#series-custom.renderItem).
248248

249+
Example:
250+
251+
```ts
252+
const renderItem = (params, api) => {
253+
return {
254+
type: 'circle',
255+
shape: {
256+
cx: api.coord([api.value(0), api.value(1)])[0],
257+
cy: api.coord([api.value(0), api.value(1)])[1],
258+
r: api.value(2) * (params.itemPayload.scale || 1)
259+
},
260+
style: {
261+
fill: api.visual('color'),
262+
opacity: params.itemPayload.opacity() || 1,
263+
}
264+
}
265+
};
266+
echarts.registerCustomSeries('bubble', renderItem);
267+
268+
const option = {
269+
xAxis: {},
270+
yAxis: {},
271+
series: {
272+
type: 'custom',
273+
renderItem: 'bubble',
274+
itemPayload: {
275+
scale: 2,
276+
opacity: () => Math.random() * 0.5 + 0.5
277+
},
278+
data: [[11, 22, 20], [33, 44, 40], [18, 24, 10]]
279+
}
280+
};
281+
chart.setOption(option);
282+
```
283+
249284
## registerLocale(Function)
250285

251286
> Since `5.0.0`

en/option/series/custom.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ chart.on('click', {element: 'aaa'}, function (params) {
113113
none = true
114114
) }}
115115

116-
## renderItem(Function)
116+
## renderItem(Function|string)
117117

118118
{{ use: partial-custom-renderItem-common() }}
119119

@@ -493,7 +493,7 @@ Value of data item.
493493

494494
{{ target: partial-custom-renderItem-common }}
495495

496-
`custom series` requires developers to write a render logic by themselves. This render logic is called [renderItem](~series-custom.renderItem).
496+
`custom series` requires developers to write a rendering logic by themselves in the form of `Function`, or use a registered rendering logic in the form of `string` (since `v6.0.0`; See [echarts.registerCustomSeries](api.html#echarts.registerCustomSeries) for more information). This render logic is called [renderItem](~series-custom.renderItem).
497497

498498
For example:
499499

zh/api/echarts.md

Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -234,18 +234,50 @@ echarts.registerMap('USA', usaJson, {
234234
{{ use: partial-version(version: '6.0.0') }}
235235

236236
```ts
237-
(type: string, renderItem: Function) => void
237+
(type: string, renderItem: Function)
238238
```
239239

240-
注册自定义系列。注册后可以通过 [setOption](~api.html#echartsInstance.setOption) 中使用:
240+
注册自定义系列。注册后可以通过 [setOption](~api.html#echartsInstance.setOption) 中使用。
241+
242+
+ `type` 注册的图表类型,也就是之后在 `setOption` 中写的 `series.renderItem`
243+
+ `renderItem` 自定义系列的图形渲染逻辑,详见 [series-custom.renderItem](option.html#series-custom.renderItem)。
244+
245+
示例:
241246

242247
```ts
243-
(type: string, renderItem: Function) => void
248+
const renderItem = (params, api) => {
249+
return {
250+
type: 'circle',
251+
shape: {
252+
cx: api.coord([api.value(0), api.value(1)])[0],
253+
cy: api.coord([api.value(0), api.value(1)])[1],
254+
r: api.value(2) * (params.itemPayload.scale || 1)
255+
},
256+
style: {
257+
fill: api.visual('color'),
258+
opacity: params.itemPayload.opacity() || 1,
259+
}
260+
}
261+
};
262+
echarts.registerCustomSeries('bubble', renderItem);
263+
264+
const option = {
265+
xAxis: {},
266+
yAxis: {},
267+
series: {
268+
type: 'custom',
269+
renderItem: 'bubble',
270+
itemPayload: {
271+
scale: 2,
272+
opacity: () => Math.random() * 0.5 + 0.5
273+
},
274+
data: [[11, 22, 20], [33, 44, 40], [18, 24, 10]]
275+
}
276+
};
277+
chart.setOption(option);
244278
```
245279

246-
+ `type` 注册的图表类型,也就是之后在 `setOption` 中写的 `series.type`
247-
+ `renderItem` 自定义系列的图形渲染逻辑,详见 [series-custom.renderItem](option.html#series-custom.renderItem)。
248-
280+
[apache/echarts-custom-series](https://github.com/apache/echarts-custom-series) 项目提供了多种可以直接使用的自定义系列。
249281

250282
## registerLocale(Function)
251283

zh/option/partial/zr-graphic.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -989,7 +989,7 @@ font: 'bolder 2em "Microsoft YaHei", sans-serif'
989989

990990
{{ use: partial-version(version: '6.0.0') }}
991991

992-
The union of multiple elements.
992+
多个图形元素并集组成的复合元素。
993993

994994
{{ use: partial-graphic-cpt-common-props(
995995
type = 'compoundPath',

zh/option/series/custom.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ chart.on('click', {element: 'aaa'}, function (params) {
102102
none = true
103103
) }}
104104

105-
## renderItem(Function)
105+
## renderItem(Function|string)
106106

107107
{{ use: partial-custom-renderItem-common() }}
108108

@@ -480,7 +480,7 @@ renderItem 函数的第二个参数。
480480

481481
{{ target: partial-custom-renderItem-common }}
482482

483-
custom 系列需要开发者自己提供图形渲染的逻辑。这个渲染逻辑一般命名为 [renderItem](~series-custom.renderItem)。例如:
483+
custom 系列需要开发者以 `Function` 形式提供图形渲染的逻辑或者以 `string` 形式使用预先注册的图形渲染逻辑(从 `v6.0.0` 开始支持,详见 [echarts.registerCustomSeries](api.html#echarts.registerCustomSeries)。这个渲染逻辑一般命名为 [renderItem](~series-custom.renderItem)。例如:
484484

485485
```ts
486486
var option = {

0 commit comments

Comments
 (0)