[Feature] saveAsImage.formatter

[jdgme]

What problem does this feature solve?

I have a use case where I need to add elements (text, banners, etc.) to charts when they are downloaded, but these additional elements should not be included in the display of the charts in the browser. I prefer to still have the ability to utilize toolbox's saveAsImage to trigger this enhanced chart downloading since the only alternative is to put an event listener on the DOM element and use event.stopPropagation() if the click is in the area of the Download icon in the toolbox on the chart, which I have to calculate dynamically based on browser conditions. Towards this end, I recommend creating a saveAsImage function parameter (similar to tooltip.formatter) which the developer can set to further manipulate the saveAsImage prior to it being sent to the browser for download.

"formatter" may not be the best name for this parameter as it might be misleading for those who think only of formatting text, but I leave that to the developers/community.

Implementation should be rather straight forward as it just requires passing the current saveAsImage result to saveAsImage.formatter and exporting the result of that formatter instead of the current saveAsImage if the formatter is defined.

Additionally, I recommend/request implementation of #18121 so saveAsImage can be triggered outside of the echart itself.

What does the proposed API look like?

Setting in Options

option = {
    toolbox: {
        feature: {
            saveAsImage: {
                formatter: function (params) {
                    return this.myChartFormatFunction(params);
                },
            },
        }
    }
};

Documentation

saveAsImage.formatter

Function
The optional formatter of the saveAsImage output which supports a callback function.

Callback function

(params: any) => HTMLCanvasElement

The first parameter params is the data that the formatter needs. Its format is shown as follows:

{
    // Canvas image generated by saveAsImage
    canvas: HTMLCanvasElement,
}