feat(legend): legend supports triggerEvent option

[sz-p]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

add legend event legendmouseover legendmouseout

Fixed issues

#18144

Details

Before: What was the problem?

Stop data carousel when mouse hover on legend must customizing legend elements with HTML

see demo:

https://codepen.io/plainheart/pen/xxJRdam

After: How does it behave after the fixing?

Stop data carousel with legend event legendmouseover legendmouseout

see demo:

https://stackblitz.com/edit/js-q9vzb5?file=index.js

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 add doc for apache/echarts#18164 echarts-doc#442

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.

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.

[oom-]

Hello, could someone go forward on this ?

Edit: I succeed to "bypass" my issue by subscribing to "highlight" and "downplay" events (kind of hard to guess).

[sz-p]

Waiting for review

[Ovilia]

Sorry for the late review. I think this PR is generally good. Please merge from the master to resolve the conflict and I'll have a quick review again. Please also add a test case.

[Ovilia]

This is perhaps no longer needed. You make merge the current master code and have a double check.

[Ovilia]

You should update the LegendSelectMethodNames after merging from master.

[100pah]

From users' perspective, if we use this API style, a complete set of events is supposed to be exposed to users ('click', 'mouseover', 'mouseout', 'mousedown', 'mouseup', 'mousemove', ...).
If we only expose mouseover and mouseout for legend, it may not be a good API design.
Whenever users require additional mouse events, we would need to introduce event names like legendmousexxx1, legendmousexxx2, legendmousexxx2. Furthermore, considering other components, the number of events we need to expose would grow significantly due to the orthogonal composition.

At present we already have setting like title.triggerEvent: true, xAxis.triggerEvent: true, radar.triggerEvent, etc. I think this pattern (xxxcomponent.triggerEvent: boolean) is better to resolve this requirement and could be a standard way.

option = {
    title: {
        text: "xxxxx",
        tiggerEvent: true,
    }
}

const chart = echarts.create(...);
chart.on('mouseover', params => {
    if (params.componentType === 'title') {
        // do something.
    }
});

So I think we should implement legend.triggerEvent like component title did.
(Incidentally, the implementation is simpler than the current way)

option = {
    legend: {
        tiggerEvent: true,
        // ...
    }
}

const chart = echarts.create(...);
chart.on('mouseover', params => {
    if (params.componentType === 'legend') {
        // do something.
    }
});

Some relevant details:

• by default value should be false, for backward compatibility.
• The event param should follow the convention.
  • componentType: 'legend'
  • componentIndex: number
  • dataIndex: number can be provided in the event param to representing different legend items. (follow the style of axis label event)
  • value: string can be provided in the event param to indicate the legend item value. (follow the style of axis label event)

[sz-p]

Thank you for your comments and great suggestions.

I didn't consider the triggerEvent option, and event name need orthogonal composition.

It was my mistake.

I have modified the code, add legend.triggerEvent. please help me review it again.

[github-actions]

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

[echarts-bot]

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

[plainheart]

I suggest adding the if check before the each function to avoid unnecessary invocation if triggerEvent is not enabled.

[sz-p]

I will do this later

[sz-p]

@plainheart

It's in #20907

Please help me to review.

Thanks.