src/component/dataZoom/AxisProxy.ts - master - githubmirror/echarts

src/component/dataZoom/AxisProxy.ts
502 строки21 KB
100pah
test: fix UT.
11 апр 2026, 16:50
11 апр 2026, 16:50e548306
/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements.  See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership.  The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License.  You may obtain a copy of the License at
*
*   http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied.  See the License for the
* specific language governing permissions and limitations
* under the License.
*/

import {clone, defaults, each, map} from 'zrender/src/core/util';
import {
    asc, getAcceptableTickPrecision, linearMap, mathAbs, mathCeil, mathFloor, mathMax, mathMin, round
} from '../../util/number';
import sliderMove from '../helper/sliderMove';
import GlobalModel from '../../model/Global';
import SeriesModel from '../../model/Series';
import ExtensionAPI from '../../core/ExtensionAPI';
import { Dictionary, NullUndefined } from '../../util/types';
// TODO Polar?
import DataZoomModel from './DataZoomModel';
import { AxisBaseModel } from '../../coord/AxisBaseModel';
import { getAxisMainType, isCoordSupported, DataZoomAxisDimension } from './helper';
import { ensureExtentAscSimply, SINGLE_REFERRING } from '../../util/model';
import { isOrdinalScale, isTimeScale } from '../../scale/helper';
import {
    AXIS_EXTENT_INFO_BUILD_FROM_DATA_ZOOM, scaleRawExtentInfoCreate,
    ScaleRawExtentResultForZoom,
} from '../../coord/scaleRawExtentInfo';


interface MinMaxSpan {
    minSpan: number
    maxSpan: number
    minValueSpan: number
    maxValueSpan: number
}

export interface AxisProxyWindow {
    // NOTE: May include non-effective portion.
    value: ScaleRawExtentResultForZoom;
    percent: number[];
    // Percent invert from "value window", which may be slightly different from "percent window" due to some
    // handling such as rounding. The difference may be magnified in cases like "alignTicks", so we use
    // `percentInverted` in these cases.
    // But we retain the original input percent in `percent` whenever possible, since they have been used in views.
    percentInverted: number[];
    valuePrecision: number;
}

/**
 * Operate single axis.
 * One axis can only operated by one axis operator.
 * Different dataZoomModels may be defined to operate the same axis.
 * (i.e. 'inside' data zoom and 'slider' data zoom components)
 * So dataZoomModels share one axisProxy in that case.
 */
class AxisProxy {

    ecModel: GlobalModel;

    // NOTICE: The lifetime of `AxisProxy` instance is different from `Axis` instance.
    // It is recreated in each run of "ec prepare".

    private _dimName: DataZoomAxisDimension;
    private _axisIndex: number;

    private _window: AxisProxyWindow;

    private _extent: ScaleRawExtentResultForZoom;

    private _minMaxSpan: MinMaxSpan;

    /**
     * The host `dataZoom` model. An axis may be controlled by multiple `dataZoom`s,
     * but only the first declared `dataZoom` is the host.
     */
    private _dataZoomModel: DataZoomModel;

    constructor(
        dimName: DataZoomAxisDimension,
        axisIndex: number,
        dataZoomModel: DataZoomModel,
        ecModel: GlobalModel
    ) {
        this._dimName = dimName;

        this._axisIndex = axisIndex;

        this.ecModel = ecModel;

        this._dataZoomModel = dataZoomModel;

        // /**
        //  * @readOnly
        //  * @private
        //  */
        // this.hasSeriesStacked;
    }

    /**
     * Whether the axisProxy is hosted by dataZoomModel.
     */
    hostedBy(dataZoomModel: DataZoomModel): boolean {
        return this._dataZoomModel === dataZoomModel;
    }

    /**
     * @return `getWindow().value` can only have NaN or finite value.
     */
    getWindow(): AxisProxyWindow {
        return clone(this._window);
    }

    getTargetSeriesModels() {
        const seriesModels: SeriesModel[] = [];

        this.ecModel.eachSeries(function (seriesModel) {
            if (isCoordSupported(seriesModel)) {
                const axisMainType = getAxisMainType(this._dimName);
                const axisModel = seriesModel.getReferringComponents(axisMainType, SINGLE_REFERRING).models[0];
                if (axisModel && this._axisIndex === axisModel.componentIndex) {
                    seriesModels.push(seriesModel);
                }
            }
        }, this);

        return seriesModels;
    }

    getAxisModel(): AxisBaseModel {
        return this.ecModel.getComponent(this._dimName + 'Axis', this._axisIndex) as AxisBaseModel;
    }

    getMinMaxSpan() {
        return clone(this._minMaxSpan);
    }

    /**
     * [CAVEAT] Keep this method pure, so that it can be called multiple times.
     */
    calculateDataWindow(
        opt: {
            start?: number // percent, 0 ~ 100
            end?: number // percent, 0 ~ 100
            startValue?: number | string | Date
            endValue?: number | string | Date
        }
    ): AxisProxyWindow {
        const dataExtent = this._extent;
        const axis = this.getAxisModel().axis;
        const scale = axis.scale;
        const dataZoomModel = this._dataZoomModel;
        const rangePropMode = dataZoomModel.getRangePropMode();
        const percentExtent = [0, 100];
        const percentWindow = [] as unknown as [number, number];
        const valueWindow = [] as unknown as [number, number];
        let hasPropModeValue;
        const needRound = [false, false];

        // NOTE:
        //  The current percentage base calculation strategy:
        //    - If the window boundary is NOT at 0% or 100%, boundary values are derived from the raw extent
        //      (series data + axis.min/max; see `ScaleRawExtentInfo['makeForZoom']`). Any subsequent "nice"
        //      expansion are excluded.
        //    - If the window boundary is at 0% or 100%, the "nice"-expanded portion is included.
        //  Pros:
        //    - The effect may be preferable when users intend to quickly narrow down to data details,
        //      especially when "nice strategy" excessively expands the extent.
        //    - It simplifies the logic, otherwise, "nice strategy" would need to be applied twice (full window
        //      + current window).
        //  Cons:
        //    - This strategy causes jitter when switching dataZoom to/from 0%/100% (though generally acceptable).

        each(['start', 'end'] as const, function (prop, idx) {
            let boundPercent = opt[prop];
            let boundValue = opt[prop + 'Value' as 'startValue' | 'endValue'];

            // NOTE: dataZoom is based either on `percentProp` ('start', 'end') or
            // on `valueProp` ('startValue', 'endValue').
            // The former one is suitable for cases that a dataZoom component controls multiple
            // axes with different unit or extent, and the latter one is suitable for accurate
            // zoom by pixel (e.g., in dataZoomSelect).
            // we use `getRangePropMode()` to mark which prop is used. `rangePropMode` is updated
            // only when setOption or dispatchAction, otherwise it remains its original value.
            // (Why not only record `percentProp` and always map to `valueProp`? Because
            // the map `valueProp` -> `percentProp` -> `valueProp` probably not the original
            // `valueProp`. consider two axes constrolled by one dataZoom. They have different
            // data extent. All of values that are overflow the `dataExtent` will be calculated
            // to percent '100%').

            if (rangePropMode[idx] === 'percent') {
                boundPercent == null && (boundPercent = percentExtent[idx]);
                boundValue = linearMap(boundPercent, percentExtent, dataExtent);
                needRound[idx] = true;
            }
            else {
                hasPropModeValue = true;
                // NOTE: `scale.parse` can also round input for 'time' or 'ordinal' scale.
                if (boundValue == null) {
                    boundValue = dataExtent[idx];
                }
                else {
                    // Need to parse user inputs from ec option or action param.
                    boundValue = scale.parse(boundValue);
                    if (scale.sanitize) {
                        boundValue = scale.sanitize(boundValue, dataExtent);
                    }
                }
                // Calculating `percent` from `value` may be not accurate, because
                // This calculation can not be inverted, because all of values that
                // are overflow the `dataExtent` will be calculated to percent '100%'
                boundPercent = linearMap(boundValue, dataExtent, percentExtent);
            }

            // fallback to extent start/end when parsed value or percent is invalid
            valueWindow[idx] = boundValue == null || isNaN(boundValue)
                ? dataExtent[idx]
                : boundValue;
            percentWindow[idx] = boundPercent == null || isNaN(boundPercent)
                ? percentExtent[idx]
                : boundPercent;
        });

        // Historical behavior - enable switching.
        asc(valueWindow);
        asc(percentWindow);

        // The windows specified from `dispatchAction` or `setOption` may:
        //  (1) be out of the extent, or
        //  (2) do not comply with `minSpan/maxSpan`, `minValueSpan/maxValueSpan`.
        // So we clamp them here.
        // But we don't restrict window by `zoomLock` here, because we see `zoomLock` just as a
        // interaction constraint, where API is able to initialize/modify the window size even
        // though `zoomLock` specified.
        // PENDING: For historical reason, the option design is partially incompatible:
        //  If `option.start` and `option.endValue` are specified, and when we choose whether
        //  `min/maxValueSpan` or `minSpan/maxSpan` is applied, neither one is intuitive.
        //  (Currently using `minValueSpan/maxValueSpan`.)
        const spans = this._minMaxSpan;
        hasPropModeValue
            ? restrictSet(valueWindow, percentWindow, dataExtent, percentExtent, false)
            : restrictSet(percentWindow, valueWindow, percentExtent, dataExtent, true);

        function restrictSet(
            fromWindow: number[],
            toWindow: number[],
            fromExtent: number[],
            toExtent: number[],
            toValue: boolean
        ) {
            const suffix = toValue ? 'Span' : 'ValueSpan';
            sliderMove(
                0, fromWindow, fromExtent, 'all',
                spans['min' + suffix as 'minSpan' | 'minValueSpan'],
                spans['max' + suffix as 'maxSpan' | 'maxValueSpan']
            );
            for (let i = 0; i < 2; i++) {
                toWindow[i] = linearMap(fromWindow[i], fromExtent, toExtent, true);
                if (toValue) {
                    toWindow[i] = toWindow[i];
                    needRound[i] = true;
                }
            }
            ensureExtentAscSimply(toWindow);
        }

        // - In 'time' and 'ordinal' scale, rounding by 0 is required.
        // - In 'interval' and 'log' scale, we round values for acceptable display with acceptable accuracy loose.
        //  "Values" can be rounded only if they are generated from `percent`, since user-specified "value"
        //  should be respected, and `DataZoomSelect` already performs its own rounding.
        // - Currently we only round "value" but not "percent", since there is no need so far.
        // - MEMO: See also #3228 and commit a89fd0d7f1833ecf08a4a5b7ecf651b4a0d8da41
        // - PENDING: The rounding result may slightly overflow the restriction from `min/maxSpan`,
        //  but it is acceptable so far.
        const isScaleOrdinalOrTime = isOrdinalScale(scale) || isTimeScale(scale);
        // Typically pxExtent has been ready in coordSys create. (See `create` of `Grid.ts`)
        const pxExtent = axis.getExtent();
        // NOTICE: this pxSpan may be not accurate yet due to "outerBounds" logic, but acceptable.
        const pxSpan = mathAbs(pxExtent[1] - pxExtent[0]);
        const precision = isScaleOrdinalOrTime
            ? 0
            // NOTICE: We deliberately do not allow specifying this precision by users, until real requirements
            // occur. Otherwise, unnecessary complexity and bad case may be introduced. A small precision may
            // cause the rounded ends overflow the expected min/max significantly. And this precision effectively
            // determines the size of a roaming step, and a big step would likely constantly cut through series
            // shapes in an unexpected place and cause visual artifacts (e.g., for bar series). Although
            // theroetically that defect can be resolved by introducing extra spaces between axis min/max tick
            // and axis boundary (see `SCALE_EXTENT_KIND_MAPPING`), it's complicated and unnecessary.
            : getAcceptableTickPrecision(valueWindow, pxSpan, 0.5);
        each([[0, mathCeil], [1, mathFloor]] as const, function ([idx, ceilOrFloor]) {
            if (!needRound[idx] || !isFinite(precision)) {
                return;
            }
            valueWindow[idx] = round(valueWindow[idx], precision);
            valueWindow[idx] = mathMin(dataExtent[1], mathMax(dataExtent[0], valueWindow[idx])); // Clamp.
            if (percentWindow[idx] === percentExtent[idx]) {
                // When `percent` is 0 or 100, `value` must be `dataExtent[0]` or `dataExtent[1]`
                // regardless of the calculated precision.
                // NOTE: `percentWindow` is never over [0, 100] at this moment.
                valueWindow[idx] = dataExtent[idx];
                if (isScaleOrdinalOrTime) {
                    // In case that dataExtent[idx] is not an integer (may occur since it comes from user input)
                    valueWindow[idx] = ceilOrFloor(valueWindow[idx]);
                }
            }
        });
        ensureExtentAscSimply(valueWindow);

        const percentInvertedWindow = [
            linearMap(valueWindow[0], dataExtent, percentExtent, true),
            linearMap(valueWindow[1], dataExtent, percentExtent, true),
        ] as [number, number];
        ensureExtentAscSimply(percentInvertedWindow);

        return {
            value: valueWindow,
            percent: percentWindow,
            percentInverted: percentInvertedWindow,
            valuePrecision: precision,
        };
    }

    /**
     * Notice: reset should not be called before series.restoreData() is called,
     * so it is recommended to be called in "process stage" but not "model init
     * stage".
     */
    reset(dataZoomModel: DataZoomModel, alignToPercentInverted: number[] | NullUndefined) {
        if (!this.hostedBy(dataZoomModel)) {
            return;
        }

        // It is important to get "consistent" extent when more then one axes is
        // controlled by a `dataZoom`, otherwise those axes will not be synchronized
        // when zooming. But it is difficult to know what is "consistent", considering
        // axes have different type or even different meanings (For example, two
        // time axes are used to compare data of the same date in different years).
        // So basically dataZoom just obtains extent by series.data (in category axis
        // extent can be obtained from axis.data).
        // Nevertheless, user can set min/max/scale on axes to make extent of axes
        // consistent.
        const axis = this.getAxisModel().axis;
        scaleRawExtentInfoCreate(axis, AXIS_EXTENT_INFO_BUILD_FROM_DATA_ZOOM);

        const rawExtentInfo = axis.scale.rawExtentInfo;
        this._extent = rawExtentInfo.makeNoZoom();

        // `calculateDataWindow` uses min/maxSpan.
        this._updateMinMaxSpan();

        let opt = dataZoomModel.settledOption;
        if (alignToPercentInverted) {
            opt = defaults({
                start: alignToPercentInverted[0],
                end: alignToPercentInverted[1],
            }, opt);
        }
        const {percent, value} = this._window = this.calculateDataWindow(opt);

        if (percent[0] !== 0) {
            rawExtentInfo.setZoomMM(0, value[0]);
        }
        if (percent[1] !== 100) {
            rawExtentInfo.setZoomMM(1, value[1]);
        }
    }

    filterData(dataZoomModel: DataZoomModel, api: ExtensionAPI) {
        if (!this.hostedBy(dataZoomModel)) {
            return;
        }

        const axisDim = this._dimName;
        const seriesModels = this.getTargetSeriesModels();
        const filterMode = dataZoomModel.get('filterMode');
        const valueWindow = this._window.value;

        if (filterMode === 'none') {
            return;
        }

        // FIXME
        // Toolbox may has dataZoom injected. And if there are stacked bar chart
        // with NaN data, NaN will be filtered and stack will be wrong.
        // So we need to force the mode to be set empty.
        // In fact, it is not a big deal that do not support filterMode-'filter'
        // when using toolbox#dataZoom, util tooltip#dataZoom support "single axis
        // selection" some day, which might need "adapt to data extent on the
        // otherAxis", which is disabled by filterMode-'empty'.
        // But currently, stack has been fixed to based on value but not index,
        // so this is not an issue any more.
        // let otherAxisModel = this.getOtherAxisModel();
        // if (dataZoomModel.get('$fromToolbox')
        //     && otherAxisModel
        //     && otherAxisModel.hasSeriesStacked
        // ) {
        //     filterMode = 'empty';
        // }

        // TODO
        // filterMode 'weakFilter' and 'empty' is not optimized for huge data yet.

        each(seriesModels, function (seriesModel) {
            let seriesData = seriesModel.getData();
            const dataDims = seriesData.mapDimensionsAll(axisDim);

            if (!dataDims.length) {
                return;
            }

            if (filterMode === 'weakFilter') {
                const store = seriesData.getStore();
                const dataDimIndices = map(dataDims, dim => seriesData.getDimensionIndex(dim), seriesData);
                seriesData.filterSelf(function (dataIndex) {
                    let leftOut;
                    let rightOut;
                    let hasValue;
                    for (let i = 0; i < dataDims.length; i++) {
                        const value = store.get(dataDimIndices[i], dataIndex) as number;
                        const thisHasValue = !isNaN(value);
                        const thisLeftOut = value < valueWindow[0];
                        const thisRightOut = value > valueWindow[1];
                        if (thisHasValue && !thisLeftOut && !thisRightOut) {
                            return true;
                        }
                        thisHasValue && (hasValue = true);
                        thisLeftOut && (leftOut = true);
                        thisRightOut && (rightOut = true);
                    }
                    // If both left out and right out, do not filter.
                    return hasValue && leftOut && rightOut;
                });
            }
            else {
                each(dataDims, function (dim) {
                    if (filterMode === 'empty') {
                        seriesModel.setData(
                            seriesData = seriesData.map(dim, function (value: number) {
                                return !isInWindow(value) ? NaN : value;
                            })
                        );
                    }
                    else {
                        const range: Dictionary<[number, number]> = {};
                        range[dim] = valueWindow as [number, number];

                        // console.time('AxisProxy_selectRange');
                        seriesData.selectRange(range);
                        // console.timeEnd('AxisProxy_selectRange');
                    }
                });
            }

            each(dataDims, function (dim) {
                seriesData.setApproximateExtent(valueWindow as [number, number], dim);
            });
        });

        function isInWindow(value: number) {
            return value >= valueWindow[0] && value <= valueWindow[1];
        }
    }

    private _updateMinMaxSpan() {
        const minMaxSpan = this._minMaxSpan = {} as MinMaxSpan;
        const dataZoomModel = this._dataZoomModel;
        const dataExtent = this._extent;

        each(['min', 'max'], function (minMax) {
            let percentSpan = dataZoomModel.get(minMax + 'Span' as 'minSpan' | 'maxSpan');
            let valueSpan = dataZoomModel.get(minMax + 'ValueSpan' as 'minValueSpan' | 'maxValueSpan');
            valueSpan != null && (valueSpan = this.getAxisModel().axis.scale.parse(valueSpan));

            // minValueSpan and maxValueSpan has higher priority than minSpan and maxSpan
            if (valueSpan != null) {
                percentSpan = linearMap(
                    dataExtent[0] + valueSpan, dataExtent, [0, 100], true
                );
            }
            else if (percentSpan != null) {
                valueSpan = linearMap(
                    percentSpan, [0, 100], dataExtent, true
                ) - dataExtent[0];
            }

            minMaxSpan[minMax + 'Span' as 'minSpan' | 'maxSpan'] = percentSpan;
            minMaxSpan[minMax + 'ValueSpan' as 'minValueSpan' | 'maxValueSpan'] = valueSpan;
        }, this);
    }
}

export default AxisProxy;