Feat/brush api & interactive api

common/changes/@visactor/vchart/feat-brush-api_2026-01-04-12-02.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vchart",
+      "comment": "feat: add brush api before change",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vchart"
+}

common/changes/@visactor/vchart/feat-brush-api_2026-01-05-09-41.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vchart",
+      "comment": "git commit -m 'feat: add interactive api",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vchart"
+}

common/changes/@visactor/vchart/feat-brush-api_2026-01-07-03-54.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vchart",
+      "comment": "feat: add brush clear api and disable dimension hover config. close#4400",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vchart"
+}

common/changes/@visactor/vchart/pre-release-2.0.13-alpha.9_2026-01-19-07-28.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@visactor/vchart",
+      "comment": "feat: interactive params add event. feat #4421",
+      "type": "none"
+    }
+  ],
+  "packageName": "@visactor/vchart"
+}

packages/vchart/src/compile/compiler.ts

@@ -71,6 +71,9 @@ export class Compiler implements ICompiler {
 
   protected _container: IRenderContainer;
   protected _option: IRenderOption;
+  getOption() {
+    return this._option;
+  }
   // 已释放标记
   private _released: boolean = false;
 
@@ -498,8 +501,8 @@ export class Compiler implements ICompiler {
     const animationState = markAnimationStates.every(state => state === AnimationStateEnum.appear)
       ? AnimationStateEnum.appear
       : markAnimationStates.every(state => state === AnimationStateEnum.disappear)
-      ? AnimationStateEnum.disappear
-      : AnimationStateEnum.none;
+        ? AnimationStateEnum.disappear
+        : AnimationStateEnum.none;
     if (!this._stage.context) {
       this._stage.context = {};
     }

packages/vchart/src/compile/interface/compilable-item.ts

@@ -6,7 +6,7 @@ import type { IMorphConfig } from '../../animation/spec';
 import type { IBoundsLike } from '@visactor/vutils';
 import type { EventSourceType, EventType } from '../../event/interface';
 import type { IMark, IMarkGraphic } from '../../mark/interface';
-import type { LayoutState } from '../interface/compiler';
+import type { IRenderOption, LayoutState } from '../interface/compiler';
 import type { MarkAnimationSpec } from '../../animation/interface';
 
 export type CompilerListenerParameters = {
@@ -34,6 +34,7 @@ export interface IGrammarItemMap<T extends IGrammarItem> {
 export type ICompilerModel = Record<GrammarType, IProductMap<IGrammarItem>>;
 
 export interface ICompiler {
+  getOption: () => IRenderOption;
   isInited?: boolean;
   readonly stateAnimationConfig?: MarkAnimationSpec;
   getCanvas: () => HTMLCanvasElement | undefined;

packages/vchart/src/component/brush/brush.ts

@@ -8,7 +8,7 @@ import { Brush as BrushComponent, IOperateType as BrushEvent } from '@visactor/v
 import type { IBounds, IPointLike, Maybe } from '@visactor/vutils';
 // eslint-disable-next-line no-duplicate-imports
 import { array, polygonIntersectPolygon, isValid, last } from '@visactor/vutils';
-import type { IModelRenderOption, IModelSpecInfo } from '../../model/interface';
+import type { IModelSpecInfo } from '../../model/interface';
 import type { IRegion } from '../../region/interface';
 import type { IGraphic, IGroup, INode, IPolygon } from '@visactor/vrender-core';
 import { transformToGraphic } from '../../util/style';
@@ -24,6 +24,7 @@ import { getSpecInfo } from '../util';
 import { brush } from '../../theme/builtin/common/component/brush';
 import { isReverse, statePointToData } from '../data-zoom/util';
 import type { CartesianAxis } from '../axis/cartesian';
+import type { IRenderOption } from '../../compile/interface';
 
 const IN_BRUSH_STATE = 'inBrush';
 const OUT_BRUSH_STATE = 'outOfBrush';
@@ -47,6 +48,8 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
   protected _relativeRegions!: IRegion[];
   protected _linkedSeries: ISeries[] = [];
 
+  protected _operateMask: IPolygon;
+
   private _itemMap: { [regionId: string | number]: IMark[] } = {};
   private _linkedItemMap: { [seriesId: string | number]: IMark[] } = {};
 
@@ -249,6 +252,10 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
     brushComponent.children[0].removeAllChild();
   }
 
+  protected _shouldEnableInteractive() {
+    return (this.getOption().getCompiler().getOption() as IRenderOption).interactive !== false;
+  }
+
   protected _createBrushComponent(region: IRegion, componentIndex: number) {
     const interactiveAttr = this._getBrushInteractiveAttr(region);
     const brush = new BrushComponent({
@@ -265,38 +272,50 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
 
     brush.addEventListener(BrushEvent.brushActive, (e: any) => {
       this._initMarkBrushState(componentIndex, OUT_BRUSH_STATE);
-      this._emitEvent(ChartEvent.brushActive, region);
+      this._emitEvent(ChartEvent.brushActive, region, e);
     });
 
     brush.addEventListener(BrushEvent.drawStart, (e: any) => {
+      if (this._spec.disableDimensionHoverWhenBrushing) {
+        this._option.globalInstance.disableDimensionHoverEvent(true);
+      }
       this._setRegionMarkPickable(region, true);
-      this._emitEvent(ChartEvent.brushStart, region);
+      this._emitEvent(ChartEvent.brushStart, region, e);
     });
 
     brush.addEventListener(BrushEvent.moveStart, (e: any) => {
+      if (this._spec.disableDimensionHoverWhenBrushing) {
+        this._option.globalInstance.disableDimensionHoverEvent(true);
+      }
       this._setRegionMarkPickable(region, true);
-      this._emitEvent(ChartEvent.brushStart, region);
+      this._emitEvent(ChartEvent.brushStart, region, e);
     });
 
     brush.addEventListener(BrushEvent.drawing, (e: any) => {
       this._setRegionMarkPickable(region, false);
       this._handleBrushChange(region, e);
-      this._emitEvent(ChartEvent.brushChange, region);
+      this._emitEvent(ChartEvent.brushChange, region, e);
     });
 
     brush.addEventListener(BrushEvent.moving, (e: any) => {
       this._setRegionMarkPickable(region, false);
       this._handleBrushChange(region, e);
-      this._emitEvent(ChartEvent.brushChange, region);
+      this._emitEvent(ChartEvent.brushChange, region, e);
     });
 
     brush.addEventListener(BrushEvent.brushClear, (e: any) => {
+      if (this._spec.disableDimensionHoverWhenBrushing) {
+        this._option.globalInstance.disableDimensionHoverEvent(false);
+      }
       this._setRegionMarkPickable(region, true);
       this._initMarkBrushState(componentIndex, '');
-      this._emitEvent(ChartEvent.brushClear, region);
+      this._emitEvent(ChartEvent.brushClear, region, e);
     });
 
     brush.addEventListener(BrushEvent.drawEnd, (e: any) => {
+      if (this._spec.disableDimensionHoverWhenBrushing) {
+        this._option.globalInstance.disableDimensionHoverEvent(false);
+      }
       this._setRegionMarkPickable(region, true);
       const { operateMask } = e.detail as any;
       const { updateElementsState = true } = this._spec;
@@ -305,29 +324,32 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
         if (this._spec.onBrushEnd(e) === true) {
           this.clearGraphic();
           this._initMarkBrushState(componentIndex, '');
-          this._emitEvent(ChartEvent.brushClear, region);
+          this._emitEvent(ChartEvent.brushClear, region, e);
         } else {
           this._spec.onBrushEnd(e);
-          this._emitEvent(ChartEvent.brushEnd, region);
+          this._emitEvent(ChartEvent.brushEnd, region, e);
         }
       } else {
         const inBrushData = this._extendDataInBrush(this._inBrushElementsMap);
         if ((!this._spec.zoomWhenEmpty && inBrushData.length > 0) || !updateElementsState) {
           this._setAxisAndDataZoom(operateMask, region);
         }
-        this._emitEvent(ChartEvent.brushEnd, region);
+        this._emitEvent(ChartEvent.brushEnd, region, e);
       }
     });
 
     brush.addEventListener(BrushEvent.moveEnd, (e: any) => {
+      if (this._spec.disableDimensionHoverWhenBrushing) {
+        this._option.globalInstance.disableDimensionHoverEvent(false);
+      }
       this._setRegionMarkPickable(region, true);
       const { operateMask } = e.detail as any;
       const { updateElementsState = true } = this._spec;
       const inBrushData = this._extendDataInBrush(this._inBrushElementsMap);
       if ((!this._spec.zoomWhenEmpty && inBrushData.length > 0) || updateElementsState) {
         this._setAxisAndDataZoom(operateMask, region);
       }
-      this._emitEvent(ChartEvent.brushEnd, region);
+      this._emitEvent(ChartEvent.brushEnd, region, e);
     });
   }
 
@@ -346,7 +368,8 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
         maxX: seriesRegionEndX
       },
       xRange: [seriesRegionStartX, seriesRegionEndX],
-      yRange: [seriesRegionStartY, seriesRegionEndY]
+      yRange: [seriesRegionStartY, seriesRegionEndY],
+      interactive: this._shouldEnableInteractive()
     } as BrushInteractiveRangeAttr;
   }
 
@@ -374,6 +397,7 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
   /*** start: event dispatch ***/
   private _handleBrushChange(region: IRegion, e: any) {
     const { operateMask } = e.detail as any;
+    this._operateMask = operateMask;
     const { updateElementsState = true } = this._spec;
     if (updateElementsState) {
       this._reconfigItem(operateMask, region);
@@ -403,7 +427,7 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
     return data;
   }
 
-  private _emitEvent(eventType: string, region: IRegion) {
+  private _emitEvent(eventType: string, region: IRegion, e: any) {
     this.event.emit(eventType, {
       model: this,
       value: {
@@ -430,7 +454,8 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
         // 缩放记录
         zoomRecord: this._zoomRecord
       },
-      vchart: this._option?.globalInstance
+      vchart: this._option?.globalInstance,
+      event: e
     });
   }
   /*** end: event dispatch ***/
@@ -767,6 +792,12 @@ export class Brush<T extends IBrushSpec = IBrushSpec> extends BaseComponent<T> i
       this._brushComponents = null;
     }
   }
+  clearBrushStateAndMask() {
+    this._relativeRegions.forEach((region: IRegion, componentIndex: number) => {
+      this._initMarkBrushState(componentIndex, '');
+      this._brushComponents[componentIndex].children[0].removeAllChild();
+    });
+  }
 }
 
 export const registerBrush = () => {

packages/vchart/src/component/brush/interface.ts

@@ -1,4 +1,4 @@
-import type { SymbolType } from '@visactor/vrender-core';
+import type { FederatedPointerEvent, SymbolType } from '@visactor/vrender-core';
 import type { IPolygonMarkSpec } from '../../typings';
 import type { IComponent } from '../interface';
 import type { IDelayType } from '../../typings/event';
@@ -65,6 +65,16 @@ interface IBrushDataBindSpec {
    * 2) 散点图按照散点中心定位, 如果严格按照中心范围更新，会出现散点超出画布的现象
    */
   axisRangeExpand?: number;
+  /**
+   * 框选前触发事件
+   * 返回false, 则阻止后续逻辑
+   */
+  beforeBrushChange?: (e: FederatedPointerEvent) => void | boolean;
+  /**
+   * 是否在框选时禁用维度 hover 事件
+   * @default false
+   */
+  disableDimensionHoverWhenBrushing?: boolean;
 }
 
 export interface IBrushTheme {

packages/vchart/src/component/crosshair/interface/spec.ts

@@ -5,6 +5,7 @@ import type { IComponentSpec } from '../../base/interface';
 import type { IComponent } from '../../interface';
 
 export interface ICrossHair extends IComponent {
+  enable: boolean;
   clearAxisValue: () => void;
   setAxisValue: (v: StringOrNumber, axis: IAxis) => void;
   layoutByValue: (enableRemain?: boolean) => void;

packages/vchart/src/component/tooltip/interface/common.ts

@@ -49,4 +49,5 @@ export interface ITooltip extends IComponent {
   tooltipHandler?: ITooltipHandler;
   getVisible: () => boolean;
   showTooltip: (datum: Datum, options: IShowTooltipOption) => void;
+  enable?: boolean;
 }

packages/vchart/src/component/tooltip/processor/base.ts

@@ -151,6 +151,9 @@ export abstract class BaseTooltipProcessor {
 
   /** 判断是否应该触发 tooltip */
   shouldHandleTooltip(params: BaseEventParams, info: TooltipInfo): boolean {
+    if (!this.component.enable) {
+      return false;
+    }
     if (isNil(info)) {
       return false;
     }

packages/vchart/src/component/tooltip/tooltip.ts

@@ -68,9 +68,10 @@ export class Tooltip extends BaseComponent<any> implements ITooltip {
    * 是否正在浏览tooltip内容
    */
   private _isEnterTooltip: boolean;
-  protected declare _spec: ITooltipSpec;
+  declare protected _spec: ITooltipSpec;
 
   tooltipHandler?: ITooltipHandler;
+  enable?: boolean = true;
 
   processor: ITooltipActiveTypeAsKeys<
     ITooltipProcessor<MarkTooltipInfo>,

packages/vchart/src/core/interface.ts

@@ -15,7 +15,7 @@ import type {
 } from '../typings';
 import type { IMorphConfig } from '../animation/spec';
 import type { IBoundsLike } from '@visactor/vutils';
-import type { EventCallback, EventQuery, EventType, ExtendEventParam } from '../event/interface';
+import type { EventCallback, EventParamsDefinition, EventQuery, EventType, ExtendEventParam } from '../event/interface';
 import type { IMark, IMarkDataTransform } from '../mark/interface';
 import type { ISeries } from '../series/interface/series';
 import type { ITheme } from '../theme/interface';
@@ -451,6 +451,22 @@ export interface IVChart {
    */
   setDimensionIndex: (value: StringOrNumber, options?: DimensionIndexOption) => void;
 
+  /**
+   * 如果传入参数, 则禁用/开启 dimension 交互事件
+   * 如果不传入参数, 获取当前是否禁用 dimension 交互事件
+   */
+  disableDimensionHoverEvent: (disabled?: boolean) => void;
+
+  /**
+   * 禁用/开启 crosshair
+   */
+  disableCrossHair: (disabled: boolean) => void;
+
+  /**
+   * 禁用/开启 tooltip
+   */
+  disableTooltip: (disabled: boolean) => void;
+
   // 数据转换相关的 api
   /**
    * Convert the data to coordinate position
@@ -592,7 +608,10 @@ export interface VRenderComponentOptions {
 }
 
 export interface IStageEventPlugin<T> {
-  new (taget: IEventTarget, cfg?: T): {
+  new (
+    taget: IEventTarget,
+    cfg?: T
+  ): {
     release: () => void;
   };
 }
@@ -603,3 +622,9 @@ export interface GrammarTransformOption {
   transform: IMarkDataTransform;
   runType?: 'beforeJoin' | 'afterEncode';
 }
+
+export interface UserEvent {
+  eType: EventType;
+  query: EventQuery | EventCallback<EventParamsDefinition[EventType]>;
+  handler?: EventCallback<EventParamsDefinition[EventType]>;
+}