feat(matrix): add new option `triggerEvent` to support triggering event on matrix cells by natsuokawai · Pull Request #21390 · apache/echarts

natsuokawai · 2025-11-26T08:48:30Z

Brief Information

This pull request is in the type of:

bug fixing
new feature
others

What does this PR do?

Fixes an issue where click events were not triggered on matrix component cells.

Fixed issues

Fix [Bug] Matrix component click event is not triggered even when silent is false #21389

Details

Before: What was the problem?

Even when matrix.body.silent was set to false (and the cell was made hit-testable, e.g., by setting itemStyle.color to 'transparent'), click events on matrix cells were not being emitted by the ECharts instance. This was because the underlying graphic elements (rects and texts) created in MatrixView lacked the necessary eventData (ECData) to identify them as part of the matrix component.

After: How does it behave after the fixing?

Click events are now correctly triggered when clicking on matrix cells. The event parameters include componentType: 'matrix', componentIndex, and the cell's name.

This is achieved by:

Importing getECData in src/component/matrix/MatrixView.ts.
Attaching eventData to the cell's text elements during creation in createMatrixCell.

events-on-matrix-cell-text.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 apache/echarts-doc#xxx

Misc

Security Checking

This PR uses security-sensitive Web APIs.

ZRender Changes

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

Related test cases or examples to use the new APIs

Added a new test case in test/ut/spec/component/matrix/event.test.ts to verify the fix.

Merging options

Please squash the commits into a single one when merging.

Other information

echarts-bot · 2025-11-26T08:48:38Z

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.

Please DO NOT commit the files in dist, i18n, and ssr/client/dist folders in a non-release pull request. These folders are for release use only.

Ovilia

Matrix is a layout so its text in the header or body should not trigger 'click' event by default. If you need this information, you need to add a new option matrix.triggerEvent (default false) like https://echarts.apache.org/en/option.html#yAxis.triggerEvent.

natsuokawai · 2025-11-30T05:14:20Z

@Ovilia
Thank you for your review and the helpful feedback!

I've updated the implementation to add the triggerEvent option (default: false) following the same pattern as yAxis.triggerEvent.

I would appreciate it if you could take another look.

Ovilia

Please also add test cases in test/matrix.html.

Ovilia · 2025-12-03T08:21:53Z

+            name: textValue != null ? textValue + '' : null,
+            coord: xyLocator.slice()
+        };
+        getECData(cellRect).eventData = eventData;


It seems that events only trigger when there is text, correct me if I'm wrong. So what's the meaning of setting eventData of cellRect here?

@Ovilia
Sorry, you're right. I've removed the eventData from cellRect. Fixed in 1a12a50

Copilot

Pull request overview

This PR fixes a bug where click events were not being triggered on matrix component cells. It adds a triggerEvent option to the matrix component (defaulting to false) and implements the necessary eventData attachment to enable click event propagation when enabled.

Key Changes:

Adds triggerEvent boolean option to MatrixOption interface with a default value of false
Updates createMatrixCell function to attach eventData to cell text elements when triggerEvent is enabled
Adjusts silent property logic to account for both triggerEvent and tooltip interactions

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
src/coord/matrix/MatrixModel.ts	Adds `triggerEvent` option to MatrixOption interface and sets default to false
src/component/matrix/MatrixView.ts	Imports getECData, adds targetType parameter to createMatrixCell, attaches eventData to cellText when triggerEvent is enabled, and updates silent property logic
test/ut/spec/component/matrix/event.test.ts	Adds comprehensive unit tests for verifying click events work when triggerEvent is true and eventData is not attached when false
test/matrix.html	Adds interactive demo showing click events on matrix cells with visual feedback

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-10T06:39:08Z

+    if (triggerEvent && cellText) {
+        const eventData = {
+            componentType: 'matrix' as const,
+            componentIndex: matrixModel.componentIndex,
+            matrixIndex: matrixModel.componentIndex,
+            targetType: targetType,
+            name: textValue != null ? textValue + '' : null,
+            coord: xyLocator.slice()
+        };
+        getECData(cellText).eventData = eventData;
+    }


The eventData is only attached to cellText, which means cells without text values (where textValue is null/undefined) won't trigger click events even when triggerEvent is true. Consider whether eventData should also be attached to cellRect for cells without text to ensure consistent event handling across all matrix cells.

I also have this doubt. @natsuokawai Do you think it be useful to cells without text to trigger events?

@Ovilia
I figured that cells without text (so, no actual data) probably don't need to trigger events.
The way I see it, ECharts events are mainly for when you want to do something with the data shown at a particular point.

Copilot · 2025-12-10T06:39:09Z

+    it('should trigger click event on matrix cell when triggerEvent is true', function () {
+        const option = {
+            matrix: {
+                triggerEvent: true,
+                x: {
+                    data: ['A', 'B']
+                },
+                y: {
+                    data: ['Y']
+                },
+                body: {
+                    data: [
+                        { coord: [0, 0], value: 'Cell A' }
+                    ]
+                }
+            }
+        };
+
+        chart.setOption(option);
+
+        let clickedParams: any = null;
+
+        chart.on('click', function (params) {
+            clickedParams = params;
+        });
+
+        // Find the matrix cell element
+        const zr = chart.getZr();
+        const displayList = zr.storage.getDisplayList();
+
+        let targetEl;
+        for (let i = 0; i < displayList.length; i++) {
+            const el = displayList[i];
+            const ecData = getECData(el);
+            if (ecData && ecData.eventData && ecData.eventData.name === 'Cell A') {
+                // Find the cell with the specific name
+                targetEl = el;
+                break;
+            }
+        }
+
+        expect(targetEl).toBeDefined();
+
+        // Trigger click
+        zr.trigger('click', {
+            target: targetEl,
+            offsetX: 10, // Dummy
+            offsetY: 10  // Dummy
+        });
+
+        expect(clickedParams).not.toBeNull();
+        expect(clickedParams.componentType).toEqual('matrix');
+        expect(clickedParams.matrixIndex).toEqual(0);
+        expect(clickedParams.targetType).toEqual('body');
+        expect(clickedParams.name).toEqual('Cell A');
+        expect(clickedParams.coord).toEqual([0, 0]);
+    });


Consider adding test coverage for cells without text values to verify whether click events should (or should not) be triggered on cells that only have background styling but no text content. This would help clarify the intended API behavior.

Fixed in 5530423

…List

natsuokawai · 2025-12-22T01:27:22Z

@Ovilia
Just checking in on this. Let me know if you need any more time or if there's anything else I can do.

Ovilia · 2026-01-07T11:27:25Z

Sorry for the late reply. I will have @100pah for a closer look. Thanks!

github-actions · 2026-01-07T11:33:38Z

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

…` may trigger events, depending on both `matrix.triggerEvent`, `matrix.xxx.silent` and `matrix.xxx.label.silent` settings. By default (`matrix.triggerEvent:true`, `matrix.xxx.silent` and `matrix.xxx.label.silent` is undefined) cell text and non-transparent cell bg trigger event. (2) Modify event param: `name` is the final rendered text, `value` is the original input cell value in option. (3) Add visual test cases for `matrix.html`.

100pah · 2026-01-07T17:37:23Z

@natsuokawai @Ovilia

I made a commit and modified:

Both cellRect (typically non-transparent) and cellText may trigger events, depending on both matrix.triggerEvent, matrix.xxx.silent and matrix.xxx.label.silent settings.
- If set matrix.triggerEvent:true, matrix.xxx.silent and matrix.xxx.label.silent is not specified or null/undefined, cell text and non-transparent cell background trigger events.
- If intending to disable cell background triggering, set matrix.xxx.silent: true in the above case.
- [NOTE]: matrix.xxx.silent and matrix.xxx.label.silent (missing in doc) have been used to control the interactive of cellRect and cellText separately since v6.0.0. Therefore I think the new triggerEvent can follow this pattern, as long as it is not inappropriate.
Modify event param:
- name is the final rendered text
- value is the original input cell value in option.
Add visual test cases for matrix.html.

And I've changed the merge target to "release" for the upcoming v6.1.0.

v6.1.0 is in testing, so I modify the code directly; sorry for that.
If any of the change is inappropriate, we can discuss them further.

echarts-bot · 2026-01-08T05:39:10Z

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

pull-request-size Bot added the size/S label Nov 26, 2025

echarts-bot Bot added PR: awaiting review PR: doc unchanged labels Nov 26, 2025

Ovilia requested changes Nov 28, 2025

View reviewed changes

echarts-bot Bot added PR: revision needed and removed PR: awaiting review labels Nov 28, 2025

pull-request-size Bot added size/M and removed size/S labels Nov 30, 2025

echarts-bot Bot added PR: awaiting review and removed PR: revision needed labels Nov 30, 2025

natsuokawai requested a review from Ovilia November 30, 2025 05:14

Ovilia reviewed Dec 3, 2025

View reviewed changes

natsuokawai requested a review from Ovilia December 7, 2025 06:53

Ovilia requested a review from Copilot December 10, 2025 06:35

Copilot started reviewing on behalf of Ovilia December 10, 2025 06:35 View session

Copilot AI reviewed Dec 10, 2025

View reviewed changes

natsuokawai and others added 7 commits December 15, 2025 16:45

fix(matrix): trigger click event on matrix cells

e9267e2

fix(matrix): Trigger event only when matrix.triggerEvent is true

78ed359

fix(matrix): Add eventData items

f43776a

fix(matrix): Trigger click event only on text, not on background

a7228a0

test(matrix): Add a test case for matrix text events

5bdc7b0

test(matrix): Make some cells empty

e800931

test(matrix): Retrieve eventData from text content instead of display…

6609e32

…List

natsuokawai force-pushed the fix/matrix-click-event branch from 5530423 to 6609e32 Compare December 15, 2025 08:05

100pah changed the base branch from master to release January 7, 2026 17:20

100pah approved these changes Jan 7, 2026

View reviewed changes

echarts-bot Bot removed the PR: awaiting review label Jan 7, 2026

Ovilia approved these changes Jan 8, 2026

View reviewed changes

100pah merged commit e770604 into apache:release Jan 8, 2026

plainheart changed the title ~~fix(matrix): trigger click event on matrix cells~~ Jan 10, 2026

plainheart changed the title ~~fix(matrix): fix matrix cells do not trigger event~~ Jan 10, 2026

plainheart added this to the 6.1.0 milestone Jan 10, 2026

Navigation Menu

Uh oh!

feat(matrix): add new option `triggerEvent` to support triggering event on matrix cells - #21390

feat(matrix): add new option `triggerEvent` to support triggering event on matrix cells#21390
100pah merged 8 commits into
apache:releasefrom
natsuokawai:fix/matrix-click-event

natsuokawai commented Nov 26, 2025 •

edited by plainheart

Loading

echarts-bot Bot commented Nov 26, 2025

Ovilia left a comment

natsuokawai commented Nov 30, 2025

Ovilia left a comment

Ovilia Dec 3, 2025

natsuokawai Dec 7, 2025 •

edited

Loading

Copilot AI left a comment

Copilot AI Dec 10, 2025

Ovilia Dec 10, 2025

natsuokawai Dec 12, 2025

Copilot AI Dec 10, 2025

natsuokawai Dec 13, 2025

natsuokawai commented Dec 22, 2025

Ovilia commented Jan 7, 2026

github-actions Bot commented Jan 7, 2026

100pah commented Jan 7, 2026 •

edited

Loading

echarts-bot Bot commented Jan 8, 2026

Labels

5 participants

Uh oh!

Conversation

natsuokawai commented Nov 26, 2025 • edited by plainheart Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Brief Information

What does this PR do?

Fixed issues

Details

Before: What was the problem?

After: How does it behave after the fixing?

Document Info

Misc

Security Checking

ZRender Changes

Related test cases or examples to use the new APIs

Merging options

Other information

echarts-bot Bot commented Nov 26, 2025

Ovilia left a comment

Choose a reason for hiding this comment

natsuokawai commented Nov 30, 2025

Ovilia left a comment

Choose a reason for hiding this comment

Ovilia Dec 3, 2025

Choose a reason for hiding this comment

natsuokawai Dec 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

Ovilia Dec 10, 2025

Choose a reason for hiding this comment

natsuokawai Dec 12, 2025

Choose a reason for hiding this comment

Copilot AI Dec 10, 2025

Choose a reason for hiding this comment

natsuokawai Dec 13, 2025

Choose a reason for hiding this comment

natsuokawai commented Dec 22, 2025

Ovilia commented Jan 7, 2026

github-actions Bot commented Jan 7, 2026

100pah commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

echarts-bot Bot commented Jan 8, 2026

Labels

5 participants

natsuokawai commented Nov 26, 2025 •

edited by plainheart

Loading

natsuokawai Dec 7, 2025 •

edited

Loading

100pah commented Jan 7, 2026 •

edited

Loading