feat(line): add triggerEvent option for more control over mouse event

[sjcobb]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

Add triggerEvent: 'line' option to line series that can be used to ensure the mouse event only fires when actually hovering on the line, not the shaded area under curve (when areaStyle set). Also support triggerEvent: 'area' and preserve existing behavior of triggerLineEvent boolean using triggerEvent boolean.

Fixed issues

• [Feature] More control over when line events trigger #21000

Details

Before: What was the problem?

Mouse event fires when hovering on shaded region, not just on the actual line. That behavior makes sense in many cases, but when there are many series overlapping, it can be useful to only fire when actually hovering directly on the line (or else it might not actually be the series closest to your cursor)

ex_area_hover.mov

Bold series in tooltip does not stay in sync with the correct line being hovered over:

test_tooltip_bold_series_ex_02.mov

After: How does it behave after the fixing?

When triggerEvent: 'line', only hovering on the line triggers the mouse event

after_trigger_area_option.mov

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 doc: add triggerLineOnlyEvent apache/echarts#21001 echarts-doc#447

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.

[Ovilia]

I think this should be a useful feature to have. Considering compatibility, we shouldn't change the behavior of triggerLineEvent. Name the new event to be something like triggerLineOnlyEvent or suggest a better name.

[sjcobb]

I think this should be a useful feature to have. Considering compatibility, we shouldn't change the behavior of triggerLineEvent. Name the new event to be something like triggerLineOnlyEvent or suggest a better name.

Agreed that's a much better approach, I just made the change to triggerLineOnlyEvent and opened a docs PR in apache/echarts-doc#447

[plainheart]

To be honest, triggerLineOnlyEvent is more confusing. I know what it means until I see this comment. If we want to refine the triggerEvent behavior to split it into the line event and area event, I would suggest introducing a new option triggerEvent - the triggerEvent ‌option is used repeatedly. For instance, title.triggerEvent, xAxis.triggerEvent, etc.

So I think we can merge both options into a single option triggerEvent with the boolean type and constant string 'line'/'area' allowed.

For backward compatibility, the new option triggerEvent should work with both line and area unless it is explicitly specified to a single target.

The changes look like this,

src/chart/line/LineSeries.ts

export interface LineSeriesOption extends SeriesOption<LineStateOption<CallbackDataParams>, LineStateOptionMixin & {
    // ...

    /**
     * @deprecated Use `triggerEvent: 'line'` for only line event or `triggerEvent: true` for both line and area event. 
     */
    triggerLineEvent?: boolean

   /**
    * Whether to trigger event when hovering on the line or the area
    * @since v6.0.0
    */
    triggerEvent?: boolean | 'line' | 'area'
}

class LineSeriesModel extends SeriesModel<LineSeriesOption> {
    // ...

    /**
     * @deprecated
     */
    triggerLineEvent: false,

    triggerEvent: false
};

src/chart/line/LineView.ts

Note that triggerLineEvent has higher priority than triggerEvent for compatibility.

const triggerEvent = seriesModel.get('triggerEvent');
const triggerLineEvent = seriesModel.get('triggerLineEvent');

const shouldTriggerLineEvent = triggerLineEvent === true || triggerEvent === true || triggerEvent === 'line';
const shouldTriggerAreaEvent = triggerLineEvent === true || triggerEvent === true || triggerEvent === 'area';

shouldTriggerLineEvent && this.packEventData(seriesModel, polyline);
shouldTriggerAreaEvent && polygon && this.packEventData(seriesModel, polygon);

But triggerEvent does not control whether to trigger the symbol event, which is triggered by default. This may be a confusing point, so it's better to add some explanation. I would like to hear what you think about this.

[Ovilia]

I agree that triggerEvent is a better idea than triggerLineOnlyEvent. It would also be nice to have a feature that developers can decide whether to blur other series when hovering on the line or the line area. Would this triggerEvent also be helpful if we decide to implement such a feature in the future?

[plainheart]

It would also be nice to have a feature that developers can decide whether to blur other series when hovering on the line or the line area.

It sounds like emphasis.disabled can do that.

[sjcobb]

This makes sense, I made the change to support triggerEvent and deprecate triggerLineEvent. As far as more control over symbol event, for my use case it's not required. When symbols are visible, we always want the event to fire (and the showSymbol, showAllSymbol options give enough flexibility already).

Also not a strong opinion since it would be a breaking change but given that v6.0 is about to release, would it make sense for triggerEvent: 'line' or triggerEvent: true to be the default instead of triggerEvent: false?