antvis
diff --git a/‎packages/s2-core/src/common/interface/interaction.ts‎
Lines changed: 25 additions & 0 deletions b/‎packages/s2-core/src/common/interface/interaction.ts‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎packages/s2-core/src/index.ts‎
Lines changed: 1 addition & 0 deletions b/‎packages/s2-core/src/index.ts‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎packages/s2-core/src/sheet-type/spread-sheet.ts‎
Lines changed: 42 additions & 0 deletions b/‎packages/s2-core/src/sheet-type/spread-sheet.ts‎
Lines changed: 42 additions & 0 deletions
@@ -330,6 +330,31 @@ export interface InteractionOptions {
    * @see https://s2.antv.antgroup.com/manual/advanced/interaction/custom
    */
   customInteractions?: CustomInteraction[];
+
+  /**
+   * 开启 window 级别表头吸顶, 当表格高度超出页面可视区域时, 表头会自动吸附在视口顶部
+   * @default false
+   */
+  stickyHeader?: boolean | StickyHeaderOptions;
+}
+
+export interface StickyHeaderOptions {
+  /**
+   * 吸顶时的 top 偏移量 (应对外部业务带有固定 Header 的情况, 如导航栏)
+   * @default 0
+   */
+  offsetTop?: number | (() => number);
+
+  /**
+   * 绑定的外部滚动容器 (默认 window)
+   */
+  scrollContainer?: HTMLElement | Window;
+
+  /**
+   * 是否启用吸顶表头的交互能力 (排序/resize/展开折叠等)
+   * @default false
+   */
+  enableInteraction?: boolean;
 }
 
 export interface InteractionCellHighlightOptions {
 
@@ -13,5 +13,6 @@ export * from './sheet-type';
 export * from './styles';
 export * from './theme';
 export * from './ui/scrollbar';
+export * from './ui/sticky-header';
 export * from './ui/tooltip';
 export * from './utils';
@@ -64,6 +64,7 @@ import type { Node } from '../facet/layout/node';
 import { RootInteraction } from '../interaction/root';
 import { getTheme } from '../theme';
 import { HdAdapter } from '../ui/hd-adapter';
+import { StickyHeaderController } from '../ui/sticky-header';
 import { BaseTooltip } from '../ui/tooltip';
 import { getOffscreenCanvas, removeOffscreenCanvas } from '../utils/canvas';
 import { clearValueRangeState } from '../utils/condition/state-controller';
@@ -98,6 +99,8 @@ export abstract class SpreadSheet extends EE {
 
   public hdAdapter: HdAdapter;
 
+  public stickyHeaderController: StickyHeaderController | null = null;
+
   /**
    * 表格是否已销毁
    */
@@ -152,6 +155,7 @@ export abstract class SpreadSheet extends EE {
     this.registerIcons();
     this.setOverscrollBehavior();
     this.mountSheetInstance();
+    this.initStickyHeader();
   }
 
   protected setupDataConfig(dataCfg: S2DataConfig) {
@@ -244,6 +248,24 @@ export abstract class SpreadSheet extends EE {
     }
   }
 
+  /**
+   * 初始化表头吸顶控制器 (延迟到首次渲染完成后)
+   */
+  private initStickyHeader() {
+    if (!this.options.interaction?.stickyHeader) {
+      return;
+    }
+
+    // 吸顶控制器依赖 facet.cornerBBox, 需要在首次渲染完成后才能初始化
+    const onFirstRender = () => {
+      this.off(S2Event.LAYOUT_AFTER_RENDER, onFirstRender);
+      this.stickyHeaderController?.destroy();
+      this.stickyHeaderController = new StickyHeaderController(this);
+    };
+
+    this.on(S2Event.LAYOUT_AFTER_RENDER, onFirstRender);
+  }
+
   protected initInteraction() {
     this.interaction?.destroy?.();
     this.interaction = new RootInteraction(this);
@@ -410,6 +432,24 @@ export abstract class SpreadSheet extends EE {
 
     this.resetHiddenColumnsDetailInfoIfNeeded();
     this.registerIcons();
+    this.syncStickyHeader();
+  }
+
+  /**
+   * 同步吸顶控制器状态：options 更新后如果 stickyHeader 配置变更则销毁/重建
+   */
+  private syncStickyHeader() {
+    const enabled = !!this.options.interaction?.stickyHeader;
+
+    // 先销毁旧控制器（无论是关闭还是选项内容变更都需要重建）
+    if (this.stickyHeaderController) {
+      this.stickyHeaderController.destroy();
+      this.stickyHeaderController = null;
+    }
+
+    if (enabled) {
+      this.initStickyHeader();
+    }
   }
 
   /**
@@ -528,6 +568,8 @@ export abstract class SpreadSheet extends EE {
     this.destroyed = true;
     this.restoreOverscrollBehavior();
     this.emit(S2Event.LAYOUT_DESTROY);
+    this.stickyHeaderController?.destroy();
+    this.stickyHeaderController = null;
     this.facet?.destroy();
     this.hdAdapter?.destroy();
     this.interaction?.destroy();