feat(custom): reusable custom series

[Ovilia]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

Custom series provide a powerful way to let developers define their own charts. But for now, it's hard to reuse the renderItem for other projects or other developers. This PR provides a way to register custom series so that developer A can make a custom series and publish it (probably by npm) and developer B can use it by simply setting renderItem to the related name.

Fixed issues

Details

Before: What was the problem?

Custom series is hard to be reused.

After: How does it behave after the fixing?

Making a reusable custom series:

const renderItem = (params, api) => {
    return {
        type: 'circle',
        shape: {
            cx: api.coord([api.value(0), api.value(1)])[0],
            cy: api.coord([api.value(0), api.value(1)])[1],
            r: api.value(2) * (params.itemPayload.scale || 1)
        },
        style: {
            fill: api.visual('color'),
            opacity: params.itemPayload.opacity() || 1,
        }
    }
};
echarts.registerCustomSeries('bubble', renderItem);

Using the above custom series:

const option = {
    xAxis: {},
    yAxis: {},
    series: {
        type: 'custom',
        renderItem: 'bubble',
        itemPayload: {
            scale: 2,
            opacity: () => Math.random() * 0.5 + 0.5
        },
        data: [[11, 22, 20], [33, 44, 40], [18, 24, 10]]
    }
};

Document Info

One of the following should be checked.

• This PR doesn't relate to document changes
• The document should be updated later
• The document changes have been made in apache/echarts-doc#xxx

Misc

ZRender Changes

• This PR depends on ZRender changes (ecomfe/zrender#xxx).

Related test cases or examples to use the new APIs

N.A.

Others

Merging options

• Please squash the commits into a single one when merging.

Other information

[echarts-bot]

Thanks for your contribution!
The community will review it ASAP. In the meanwhile, please checkout the coding standard and Wiki about How to make a pull request.

The pull request is marked to be PR: author is committer because you are a committer of this project.

Document changes are required in this PR. Please also make a PR to apache/echarts-doc for document changes and update the issue id in the PR description. When the doc PR is merged, the maintainers will remove the PR: awaiting doc label.

[github-actions]

The changes brought by this PR can be previewed at: https://echarts.apache.org/examples/editor?version=PR-20226@78c072c

[100pah]

Do we need to enable it to pass the additional user params to renderItem, as discussed earlier?

Custom rendering logic provider:

function myRenderItem(params) {
    console.log(  params.renderItemArgs );
    // params.renderItemArgs is required in the following rendering logic.
}
echarts.registerCustomSeries('perfectRenderItem', myRenderItem);

Custom rendering logic user:

option = {
  series: {
    type: 'custom', 
    renderItem: 'perfectRenderItem',
    renderItemArgs: {abc: 123, def: 'haha'}
  }
}

[100pah]

LGTM

[pissang]

Use import type explictly to ensure the CustomSeries is not in the depedencies of core/echarts

import type { CustomSeriesRenderItem } ...

[echarts-bot]

Congratulations! Your PR has been merged. Thanks for your contribution! 👍