ooxml-excel-editor 1.1.0

package/dist/core/render/canvas-renderer.d.ts

@@ -0,0 +1,225 @@
+import { CellStyle, CellStyleFn, MergeRange, SheetModel, WorkbookModel } from '../model/types';
+import { ViewerTheme } from './theme';
+import { GridMetrics } from '../layout/grid-metrics';
+import { FreezeGeometry } from '../layout/freeze';
+export interface RendererOptions {
+    theme?: Partial<ViewerTheme>;
+    cellStyle?: CellStyleFn;
+}
+/** 导出为离屏 canvas 的选项 */
+export interface ExportToCanvasOptions {
+    /** 0-based 闭区间;缺省 = 整个已用范围 */
+    range?: MergeRange;
+    /** 设备像素缩放(越大越清晰),默认 2;受 maxPixels 限制可能被下调 */
+    scale?: number;
+    /** 是否含行号/列字母表头,默认 false(同 Excel 打印默认) */
+    includeHeaders?: boolean;
+    /** 覆盖网格线显隐(缺省跟随 sheet.showGridLines) */
+    gridlines?: boolean;
+    /** 背景色,默认白 */
+    background?: string;
+    /** 单维度设备像素安全上限,默认 16384(超大表自动降 scale) */
+    maxPixels?: number;
+}
+/** exportToCanvas 的产物 + 合成叠加层(图片/图表/形状)所需的坐标信息 */
+export interface ExportToCanvasResult {
+    canvas: HTMLCanvasElement;
+    /** 实际用的设备像素缩放(可能被 maxPixels 下调) */
+    scale: number;
+    /** 解析出的导出范围 */
+    range: MergeRange;
+    /** 正文宽高(css px,不含表头,zoom=1) */
+    bodyW: number;
+    bodyH: number;
+    /** 导出空间几何(zoom=1),供合成叠加层定位 */
+    metrics: GridMetrics;
+    /** 画布内"范围左上角格子"所在的 css 像素偏移(含表头时为表头宽高,否则 0) */
+    originX: number;
+    originY: number;
+    /** 范围左上角在网格坐标系的像素(zoom=1);合成时: deviceX = (originX + gridLeft - gridOriginX) * scale */
+    gridOriginX: number;
+    gridOriginY: number;
+}
+export interface ViewState {
+    scrollX: number;
+    scrollY: number;
+    width: number;
+    height: number;
+    zoom: number;
+}
+/** 矢量导出: 一个单元格解析后的绘制信息 */
+export interface CellDrawInfo {
+    style: CellStyle;
+    text: string;
+    /** 有效字色(已并入条件格式/数字格式/超链接色) */
+    color: string;
+    bold: boolean;
+    /** 条件格式可矢量化的效果(背景色/数据条/图标);无则省略 */
+    effect?: {
+        fillColor?: string;
+        dataBar?: {
+            ratio: number;
+            color: string;
+            gradient: boolean;
+        };
+        icon?: {
+            setName: string;
+            level: number;
+            count: number;
+        };
+    };
+    /** 矢量层仍画不动的效果(迷你图/旋转/富文本)→ 调用方栅格兜底 */
+    complex: boolean;
+}
+export declare class CanvasRenderer {
+    private canvas;
+    private sheet;
+    private workbook;
+    metrics: GridMetrics;
+    private merges;
+    private freeze;
+    private cond;
+    private ctx;
+    private dpr;
+    private sparklineIndex;
+    private theme;
+    private cellStyleHook?;
+    constructor(canvas: HTMLCanvasElement, sheet: SheetModel, workbook: WorkbookModel, zoom?: number, opts?: RendererOptions);
+    /** 改变缩放: 重建几何(列宽行高表头按 zoom 缩放)。合并/条件格式无需重建。 */
+    setZoom(zoom: number): void;
+    /** 内容总尺寸(含表头)，给外层滚动容器用 */
+    get contentWidth(): number;
+    get contentHeight(): number;
+    get freezeGeometry(): FreezeGeometry;
+    /** 默认行高(已含缩放),供翻页步长估算 */
+    get defaultRowPx(): number;
+    /** 把行列号映射到当前视图的屏幕矩形(供叠加层定位) */
+    screenRectOfCell(view: ViewState, row: number, col: number): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    private selection;
+    setSelection(sel: MergeRange | null): void;
+    private findHits;
+    private findCurrent;
+    /** 扫描非空单元格,返回命中的格(按阅读顺序: 先行后列) */
+    searchCells(query: string, opts?: {
+        matchCase?: boolean;
+        wholeCell?: boolean;
+    }): {
+        row: number;
+        col: number;
+    }[];
+    /** 设置高亮命中集 + 当前项(供 drawFind 绘制) */
+    setFind(hits: {
+        row: number;
+        col: number;
+    }[], current: number): void;
+    private filteredCols;
+    /** 标记哪些列处于筛选态(下拉按钮画成蓝色漏斗) */
+    setFilteredCols(cols: Set<number>): void;
+    /** 单元格的当前屏幕矩形(冻结感知: 冻结行/列不随滚动) */
+    cellScreenRect(view: ViewState, row: number, col: number): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** 屏幕坐标是否落在某个自动筛选表头的下拉按钮上;是则返回列号 */
+    filterButtonAt(view: ViewState, px: number, py: number): number | null;
+    /** 屏幕坐标 → 单元格(0-based)。落在表头或越界返回 null。 */
+    cellAtScreen(view: ViewState, x: number, y: number): {
+        row: number;
+        col: number;
+    } | null;
+    /** 屏幕 y → 行(用于点行号选整行);落在列表头返回 -1 */
+    rowAtScreen(view: ViewState, y: number): number;
+    /** 屏幕 x → 列(用于点列标选整列);落在行表头返回 -1 */
+    colAtScreen(view: ViewState, x: number): number;
+    /** 该 cell 所属的合并区(用于选区/复制时按整块处理) */
+    mergeAt(row: number, col: number): MergeRange | null;
+    /** 双击列边界: 把列宽自适应到该列内容最宽处 */
+    autoFitColumn(col: number): void;
+    /** 双击行边界: 行高自适应到该行内容最高处 */
+    autoFitRow(row: number): void;
+    /** 拖拽改列宽(传入屏幕像素,内部换算为非缩放存储) */
+    setColWidthPx(col: number, px: number): void;
+    /** 拖拽改行高 */
+    setRowHeightPx(row: number, px: number): void;
+    /** 复制带格式用: 单元格的内联 CSS(粗体/斜体/色/底色/对齐) */
+    cellInlineStyle(row: number, col: number): string;
+    /** 列宽/行高变化后重建几何 */
+    rebuildMetrics(): void;
+    /** 选区统计: 遍历非空 cell(O(非空数),不随选区大小爆炸) */
+    selectionStats(range: MergeRange): {
+        count: number;
+        numCount: number;
+        sum: number;
+        avg: number;
+        min: number;
+        max: number;
+    };
+    /**
+     * 矢量导出用: 解析一个单元格的绘制信息(样式 + 显示文本 + 有效字色/粗体 + 是否"复杂")。
+     * complex = 含条件格式背景/数据条/图标、迷你图、旋转、富文本 —— 矢量层画不动,调用方应栅格兜底。
+     * 返回 null 表示该格无任何可绘制内容(无填充/边框/文本)。
+     */
+    exportCellDraw(row: number, col: number): CellDrawInfo | null;
+    /** 单元格的显示文本(套数字格式后);空返回 '' */
+    cellText(row: number, col: number): string;
+    /** 单元格的公式文本(无则 null),供公式栏显示 */
+    cellFormula(row: number, col: number): string | null;
+    /** 单元格原始数值(供状态栏统计);非数字返回 null */
+    cellNumber(row: number, col: number): number | null;
+    cellHyperlink(row: number, col: number): string | null;
+    /** 单元格批注(无则 null) */
+    commentAt(row: number, col: number): string | null;
+    private inDataValidation;
+    /** 若该 cell 文本被裁切(非换行、宽度不足、且溢出也放不下),返回完整文本供 tooltip;否则 null */
+    overflowTextAt(row: number, col: number): string | null;
+    render(view: ViewState): void;
+    /**
+     * 绘制核心: 被实时 render() 与导出 exportToCanvas() 共用。
+     * 用 this.{canvas,ctx,metrics,freeze,selection,dpr} 当前值,flags 控制 UI 装饰是否绘制。
+     */
+    private paint;
+    /** 查找高亮: 所有命中淡黄,当前项橙色描边 */
+    private drawFind;
+    /**
+     * 把整表(或指定区域)渲染到一张离屏 canvas: 无选区高亮/分页线/冻结分区,scale 可控。
+     * 复用全部单元格绘制逻辑(填充/边框/条件格式/迷你图/文本)。图片/图表/形状是 DOM 叠加层,
+     * 不在此绘制 —— 由调用方拿到 result.metrics/scale/origin 后合成到底图上。
+     */
+    exportToCanvas(opts?: ExportToCanvasOptions): ExportToCanvasResult;
+    /** 手动分页符: 蓝色虚线(在正文区内,随内容滚动) */
+    private drawPageBreaks;
+    /** 选区高亮: 半透明填充 + 蓝色边框，裁到表头以下的正文区。 */
+    private drawSelection;
+    private drawPane;
+    /** 取某格指定边的边框样式(供相邻共享边取较重者);越界/无格返回 undefined */
+    private borderEdgeOf;
+    /** 画单个 cell(或合并区)的: 填充 → 条件背景 → 数据条 → 边框 → 内容 → 图标 → 筛选按钮 */
+    private paintCellBox;
+    private drawCellContent;
+    /**
+     * 文本溢出可用的裁剪范围: 从本格向对齐方向延伸，吞掉相邻"空白"格(无值且无填充)。
+     * 返回扩展后的 clip x/w(对齐锚点仍用原格，只是裁剪放宽)。
+     */
+    private spillClip;
+    private drawRichText;
+    private drawRotatedText;
+    private drawVerticalText;
+    private drawTextDecoration;
+    private drawHeaders;
+    private drawColHeaderRange;
+    private drawRowHeaderRange;
+    private drawFreezeLines;
+    private styleOf;
+}
+/**
+ * [start,end] 减去 gaps(合并区内部区间,可重叠/乱序)的补集 → 要画的实线段。
+ * 纯函数,便于单测。合并区内部的网格线靠此被"挖空"。
+ */
+export declare function gridSegments(start: number, end: number, gaps: Array<[number, number]>): Array<[number, number]>;

package/dist/core/render/conditional.d.ts

@@ -0,0 +1,25 @@
+import { SheetModel } from '../model/types';
+export interface CellEffect {
+    fillColor?: string;
+    fontColor?: string;
+    bold?: boolean;
+    dataBar?: {
+        ratio: number;
+        color: string;
+        gradient: boolean;
+    };
+    icon?: {
+        setName: string;
+        level: number;
+        count: number;
+    };
+}
+export declare class ConditionalEngine {
+    private sheet;
+    private prepared;
+    constructor(sheet: SheetModel);
+    hasRules(): boolean;
+    private numericValuesIn;
+    private prepare;
+    effectsFor(row: number, col: number, value: number | string | boolean | Date | null): CellEffect | null;
+}

package/dist/core/render/fills.d.ts

@@ -0,0 +1,2 @@
+import { Fill } from '../model/types';
+export declare function paintFill(ctx: CanvasRenderingContext2D, fill: Fill, x: number, y: number, w: number, h: number): void;

package/dist/core/render/text.d.ts

@@ -0,0 +1,20 @@
+import { CellStyle, Font, HAlign } from '../model/types';
+/** 行高系数(字号 → 行盒高度)。渲染与自动行高测量共用，保证算高=占高。 */
+export declare const LINE_HEIGHT_FACTOR = 1.18;
+/** 单元格文本左右/上下内边距(px @ zoom=1) */
+export declare const CELL_PADDING = 3;
+export declare function fontToCss(font: Font, zoom?: number): string;
+export declare function measureWidth(ctx: CanvasRenderingContext2D, text: string, fontCss: string): number;
+/** 默认对齐: 文本左对齐、数字右对齐(general 语义) */
+export declare function resolveHAlign(align: HAlign, isNumber: boolean): Exclude<HAlign, 'general'>;
+/** 按可用宽度把文本拆成多行(wrapText) */
+export declare function wrapLines(ctx: CanvasRenderingContext2D, text: string, fontCss: string, maxWidth: number): string[];
+/** shrink-to-fit: 计算能塞进 maxWidth 的缩放比例(只缩不放) */
+export declare function shrinkScale(ctx: CanvasRenderingContext2D, text: string, fontCss: string, maxWidth: number): number;
+export interface TextAppearance {
+    fontCss: string;
+    color: string;
+    underline: boolean;
+    strike: boolean;
+}
+export declare function appearanceOf(style: CellStyle, zoom: number, overrideColor?: string): TextAppearance;

package/dist/core/render/theme.d.ts

@@ -0,0 +1,19 @@
+/** 预览器外观主题(可由 :theme prop 覆盖)。 */
+export interface ViewerTheme {
+    /** 行/列表头背景 */
+    headerBg: string;
+    /** 选中行/列时表头高亮背景(预留) */
+    headerActiveBg: string;
+    /** 表头文字色 */
+    headerText: string;
+    /** 表头边线色 */
+    headerLine: string;
+    /** 网格线色 */
+    gridLine: string;
+    /** 选区边框色 */
+    selBorder: string;
+    /** 多格选区填充色(含透明) */
+    selFill: string;
+}
+export declare const DEFAULT_THEME: ViewerTheme;
+export declare function mergeTheme(partial?: Partial<ViewerTheme>): ViewerTheme;

package/dist/core/viewer/controller.d.ts

@@ -0,0 +1,339 @@
+import { CellModel, CellStyleOverride, ImageAnchor, MergeRange, SheetModel, WorkbookModel } from '../model/types';
+import { EditConfig } from '../edit/types';
+import { EditController, EditEventName } from '../edit/edit-controller';
+import { CellValue, SheetToJSONOptions } from '../model/data-access';
+import { CellSnapshot } from '../model/snapshot';
+import { EditorCommitValue, EditorResolver } from '../edit/editor-context';
+import { CanvasRenderer, RendererOptions, ViewState } from '../render/canvas-renderer';
+import { OverlayQuads } from './overlay-manager';
+import { ImageExportOptions, PdfExportOptions, PrintOptions } from '../export/types';
+import { XlsxExportOptions } from '../export/xlsx-writer';
+export type Cell = {
+    row: number;
+    col: number;
+};
+export interface TooltipState {
+    text: string;
+    x: number;
+    y: number;
+    kind: 'overflow' | 'comment';
+}
+/** 查找状态快照(供壳渲染 FindBar) */
+export interface FindState {
+    query: string;
+    matchCase: boolean;
+    wholeCell: boolean;
+    count: number;
+    index: number;
+}
+/** 自动筛选下拉浮层(列去重值 + 已选 + 屏幕位置) */
+export interface FilterPopupState {
+    col: number;
+    values: string[];
+    selected: string[];
+    x: number;
+    y: number;
+    /** 该列当前排序方向(用于浮层高亮 ↑/↓);null = 未按此列排序 */
+    sortDir: 'asc' | 'desc' | null;
+}
+export interface ViewerControllerEls {
+    canvas: HTMLCanvasElement;
+    /** 量可视区尺寸用 */
+    renderArea: HTMLElement;
+    /** 原生滚动容器 */
+    scroller: HTMLElement;
+    /** 撑开滚动范围的占位元素(控制器直接设其宽高) */
+    spacer: HTMLElement;
+    /** 叠加层四象限 */
+    overlays: OverlayQuads;
+    /** 单元格编辑器挂载层(在格 + overlay 之上;E2) */
+    editorSlot: HTMLElement;
+}
+export interface ViewerControllerHooks {
+    /** renderer 重建时回调,壳据此镜像到响应式(保持现有 renderer.value 读法 + chrome 响应) */
+    onRenderer: (renderer: CanvasRenderer | null) => void;
+    /** 每次绘制后回调,壳据此 +1 让 overlay slot 重算位置 */
+    onRenderTick: () => void;
+    /** 选区模型变化(壳据此 +1 让 selection/activeCell/stats 等计算属性重算) */
+    onSelectionChange: () => void;
+    /** 单击单元格(壳 emit 'cell-click' + 派发插件) */
+    onCellClick: (row: number, col: number, text: string) => void;
+    /** 双击单元格(壳 emit 'cell-dblclick') */
+    onCellDblClick: (row: number, col: number, text: string) => void;
+    /** 单击超链接(壳 emit 'hyperlink-click' + 按 openLinks 决定是否 window.open) */
+    onHyperlink: (url: string, cell: Cell) => void;
+    /** 悬停提示变化(壳渲染 tooltip DOM) */
+    onTooltip: (tip: TooltipState | null) => void;
+    /** 查找状态变化(壳据此 +1 让 FindBar / 工具栏重算) */
+    onFindChange: () => void;
+    /** 筛选状态/浮层变化(壳据此 +1 让 FilterPopup / 工具栏重算) */
+    onFilterChange: () => void;
+    /** 编辑事件(cell-change/edit-start/edit-commit;壳转 emit + 插件派发) */
+    onEditEvent: (event: EditEventName, payload: unknown) => void;
+}
+export declare class ViewerController {
+    private els;
+    private hooks;
+    /** 当前渲染器(壳通过 onRenderer 镜像) */
+    renderer: CanvasRenderer | null;
+    /** 视图状态(滚动/缩放/尺寸);壳与控制器共享同一对象 */
+    readonly view: ViewState;
+    private overlays;
+    private sheet;
+    private rafId;
+    private contentW;
+    private contentH;
+    private workbook;
+    private activeIndex;
+    private rendererOpts;
+    /** 下载默认文件名(壳可随 props 更新) */
+    fileName: string | undefined;
+    /** 原始 .xlsx 字节(壳加载时注入;供高保真 overlay 导出重载原件) */
+    private sourceBuffer;
+    /** 壳在加载后注入原始字节(供 exportXlsx({fidelity:'overlay'}) 重载原件叠加编辑) */
+    setSourceBuffer(buf: ArrayBuffer | null): void;
+    private exporter;
+    private selAnchor;
+    private selActive;
+    private selMode;
+    private dragMode;
+    private resizeTarget;
+    private imageDragIdx;
+    private imageDragStartRect;
+    private imageDragStartMouse;
+    private imageDragBefore;
+    private resizeStartPos;
+    private resizeStartSize;
+    private resizeStartInfo;
+    private resizeStartModelSize;
+    private dragMoved;
+    private findQuery;
+    private findMatchCase;
+    private findWholeCell;
+    private findHits;
+    private findIndex;
+    private filterState;
+    private filterOrigHidden;
+    private filterPopup;
+    private sortCol;
+    private sortDir;
+    private editCfg;
+    /** 编辑底座(命令栈/快照/事件;E1) */
+    readonly edit: EditController;
+    /** 单元格编辑器宿主(E2) */
+    private editorHost;
+    /** 按格解析编辑器(壳合并 plugin.editor + prop.editor 后注入;E2) */
+    private editorResolver?;
+    constructor(els: ViewerControllerEls, hooks: ViewerControllerHooks);
+    /** 切表/换簿/主题变化: 清状态,重建渲染器,重置滚动,量尺寸,建叠加层,绘制,按需重跑查找 */
+    rebuild(sheet: SheetModel, workbook: WorkbookModel, zoom: number, opts: RendererOptions): void;
+    /** 立即绘制(取消挂起的 rAF)。绘制 + 定位叠加层 + 通知 tick。 */
+    render(): void;
+    /** 合并到下一帧绘制(滚动/拖选高频时,每帧最多一次) */
+    scheduleRender(): void;
+    /** 量可视区尺寸 */
+    measure(): void;
+    /** 同步滚动量(壳的 scroll 事件里调) */
+    setScroll(scrollX: number, scrollY: number): void;
+    /** 缩放: 保持视口中心相对内容的比例,避免跳到左上角 */
+    setZoom(zoom: number): void;
+    /** 拖拽改列宽(px) */
+    setColWidthPx(col: number, px: number): void;
+    /** 拖拽改行高(px) */
+    setRowHeightPx(row: number, px: number): void;
+    /** 双击列边界: 自适应列宽(editable 时入命令栈/发事件/记脏) */
+    autoFitColumn(col: number): void;
+    /** 双击行边界: 自适应行高(editable 时入命令栈/发事件/记脏) */
+    autoFitRow(row: number): void;
+    /** 程序化设列宽(px,模型单位/非缩放);editable 时走命令栈(可撤销+发 dim-change+记脏)。 */
+    setColumnWidth(col: number, width: number): boolean;
+    /** 程序化设行高(px,模型单位/非缩放);editable 时走命令栈。 */
+    setRowHeight(row: number, height: number): boolean;
+    /** 公式引擎是否已就绪(recalc 开启 + 异步 warm 完成);未开重算恒 false。 */
+    isRecalcReady(): boolean;
+    /** 当前是否有未保存修改(自加载/还原以来发生过编辑或 resize)。 */
+    isDirty(): boolean;
+    /** 放弃全部修改,还原到刚加载的原件;返回是否还原(无 baseline → false)。 */
+    resetToOriginal(): boolean;
+    /** 单元格当前屏幕矩形(render-area 相对) */
+    rectOf(row: number, col: number): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** 区域当前屏幕矩形(左上到右下并集) */
+    rectOfRange(range: MergeRange): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    dispose(): void;
+    /** 内容总尺寸变化 → 量 + 直接撑 spacer(滚动范围由它决定) */
+    refreshContentSize(): void;
+    /** 当前选区(随 mode 解析为单元格/整行/整列范围,含合并单元格扩展) */
+    getSelection(): MergeRange | null;
+    /** 活动单元格(选区的"焦点"角) */
+    getActiveCell(): Cell | null;
+    /** 清空选区 */
+    clearSelection(): void;
+    /** 全选 */
+    selectAll(): void;
+    /** 选中单个单元格并滚动到视图(查找定位用);range 模式,anchor=active */
+    selectCell(row: number, col: number): void;
+    /** 命令式设选区(anchor=左上, active=右下) */
+    setSelectionRange(range: MergeRange): void;
+    private setCell;
+    private setRows;
+    private setCols;
+    private localXY;
+    private hitRegion;
+    private nearColBorder;
+    private nearRowBorder;
+    onMouseDown(e: MouseEvent): void;
+    onMouseMove(e: MouseEvent): void;
+    onMouseUp(e: MouseEvent): void;
+    /** 命中最上层浮动图(editable;p 为 render-area 坐标含表头);返回 index 或 -1。 */
+    private imageHitAt;
+    /** 拖拽起始:editable 时捕获 baseline + 起始维度信息(供 undo / dim-change)。 */
+    private beginResizeRecord;
+    /** 拖拽结束:模型已被 renderer 改完,补登一条 undo 项 + 发 dim-change。 */
+    private endResizeRecord;
+    onMouseLeave(): void;
+    private updateHover;
+    onDblClick(e: MouseEvent): void;
+    private pageRows;
+    onKeyDown(e: KeyboardEvent): void;
+    private scrollActiveIntoView;
+    copySelection(): Promise<void>;
+    /** 查找状态快照(壳渲染 FindBar) */
+    getFindState(): FindState;
+    setFindQuery(q: string): void;
+    setFindMatchCase(b: boolean): void;
+    setFindWholeCell(b: boolean): void;
+    /** 重算命中并应用(query/选项变化时) */
+    private recomputeFind;
+    /** 把当前命中应用到渲染器 + 移动选区/滚动到视图 */
+    private applyFind;
+    findNext(): void;
+    findPrev(): void;
+    /** 关闭查找: 清 query + 命中(保留 matchCase/wholeCell 选项),清除高亮 */
+    clearFind(): void;
+    /** 当前是否有列处于筛选中(工具栏「清除筛选」启用判断) */
+    hasFilters(): boolean;
+    /** 当前筛选浮层(壳渲染 FilterPopup) */
+    getFilterPopup(): FilterPopupState | null;
+    /** 筛选数据区底行: 正常用 af.bottom;若 af 只含表头(bottom===top)则延伸到数据末行 */
+    private filterDataBottom;
+    /** 某列(自动筛选数据区)的去重值,数值/中文自然排序 */
+    private distinctColumnValues;
+    /** 重算筛选导致的隐藏行并应用到模型(行隐藏机制 → 几何归零) */
+    private applyFilters;
+    /** 点中下拉按钮 / 命令式: 打开某列筛选浮层(算去重值 + 已选 + 屏幕位置) */
+    openFilterPopup(col: number): void;
+    closeFilterPopup(): void;
+    /** 浮层「确定」: 勾选值落筛选态(全选=取消该列;子集=保留;空集=全隐藏)。 */
+    applyFilterSelection(checked: string[]): void;
+    /** 浮层「清除」: 取消该列筛选 */
+    clearFilterColumn(): void;
+    /** 清除当前表全部筛选 */
+    clearAllFilters(): void;
+    /**
+     * 离开某表 / 取消自动筛选: 恢复被筛选隐藏的行,清空筛选态。
+     * 传入要恢复的 sheet(切表时是"旧表",取消筛选时是当前表)。
+     */
+    resetFilter(sheet: SheetModel | null | undefined): void;
+    /** 换工作簿: 仅清筛选态(旧 sheet 已废,不需恢复行) */
+    clearFilterState(): void;
+    /** 工具栏「筛选」: 切换自动筛选。无则按选区(或整张已用区)新建,使下拉按钮出现。 */
+    toggleAutoFilter(): void;
+    /** 当前排序状态(壳可读以显示指示) */
+    getSortState(): {
+        col: number;
+        dir: 'asc' | 'desc' | null;
+    };
+    /**
+     * 按某列对自动筛选数据区排序(只读视图重排:移动行内容 + 行高,不改文件)。
+     * 合并区与数据区相交则拒绝(与 Excel 一致)。排序前会清除该表筛选,避免行索引快照错位。
+     */
+    sortColumn(col: number, dir: 'asc' | 'desc'): void;
+    /** 设置编辑配置(默认只读;壳在挂载 + props 变化时调) */
+    setEditConfig(cfg: EditConfig): void;
+    /** 该格当前是否可编辑(综合 editable + readOnlyRanges + cellReadOnly) */
+    isCellEditable(row: number, col: number): boolean;
+    editCell(row: number, col: number, value: CellValue): boolean;
+    editRange(range: MergeRange, values: CellValue[][]): boolean;
+    clearRange(range: MergeRange): boolean;
+    /** 给区域套样式覆盖(E5;粗体/对齐/填充等);editable 时走命令栈(可撤销 + 发 cell-change + 记脏) */
+    setStyle(range: MergeRange, patch: CellStyleOverride): boolean;
+    /** 读当前表全部图片锚点(克隆)。 */
+    getImages(): ImageAnchor[];
+    /** 加一张图(无 src 但有 bytes+mime 时自动生成 blob url);返回插入索引(失败 -1)。 */
+    addImage(anchor: ImageAnchor): number;
+    /** 删一张图。 */
+    removeImage(index: number): boolean;
+    /** 移动图片(屏幕像素增量);editable 时入命令栈 + 发 image-change。 */
+    moveImage(index: number, dxPx: number, dyPx: number): boolean;
+    /** 缩放图片(目标屏幕像素宽高);editable 时入命令栈 + 发 image-change。 */
+    resizeImage(index: number, widthPx: number, heightPx: number): boolean;
+    /** 在 at 处插入 count 行(原 at 行及之后下移)。 */
+    insertRows(at: number, count?: number): boolean;
+    /** 删除 [at, at+count) 行(与合并相交则警告,相交合并被移除)。 */
+    deleteRows(at: number, count?: number): boolean;
+    /** 在 at 处插入 count 列。 */
+    insertCols(at: number, count?: number): boolean;
+    /** 删除 [at, at+count) 列(与合并相交则警告)。 */
+    deleteCols(at: number, count?: number): boolean;
+    /** 移动/缩放公共路径:算当前矩形 → 变换 → setImageRect → 重定位 → 补登命令。 */
+    private editImageRect;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    getEditingCell(): {
+        row: number;
+        col: number;
+    } | null;
+    getCellSnapshot(row: number, col: number): CellSnapshot | null;
+    /** 壳注入合并后的编辑器解析器(plugin.editor + prop.editor) */
+    setEditorResolver(fn?: EditorResolver): void;
+    /**
+     * 进入编辑:解析编辑器工厂(无自定义则用内置文本编辑器)→ 挂载。只读则不进入。
+     * initialText 为打字进入时的起始字符。返回是否进入。
+     */
+    beginEdit(row: number, col: number, initialText?: string): boolean;
+    /**
+     * 提交当前编辑(取值 → 命令栈 → 卸编辑器)。value 可为裸值或 {value,style}(样式 E5 起生效)。
+     * move 指示提交后活动格移动(Enter→down / Tab→right)。
+     */
+    commitEdit(value: EditorCommitValue, move?: 'down' | 'right'): void;
+    /** 取消当前编辑(不改模型) */
+    cancelEdit(): void;
+    /** 当前是否有活动编辑器 */
+    isEditing(): boolean;
+    exportImage(opts?: ImageExportOptions): Promise<Blob>;
+    downloadImage(opts?: ImageExportOptions): Promise<void>;
+    exportPdf(opts?: PdfExportOptions): Promise<Blob>;
+    downloadPdf(opts?: PdfExportOptions): Promise<void>;
+    print(opts?: PrintOptions): Promise<void>;
+    exportXlsx(opts?: XlsxExportOptions): Promise<Blob>;
+    downloadXlsx(opts?: XlsxExportOptions): Promise<void>;
+    exportJson(opts?: SheetToJSONOptions): string;
+    downloadJson(opts?: SheetToJSONOptions): void;
+    exportCsv(opts?: {
+        target?: number;
+        format?: boolean;
+    }): string;
+    downloadCsv(opts?: {
+        target?: number;
+        format?: boolean;
+    }): void;
+}
+/** 排序用:空值判定(null / 空串 / undefined) */
+export declare function isBlankValue(v: CellModel['raw']): boolean;
+/**
+ * 排序用:非空值比较(升序基准,返回 -1/0/1)。
+ * 类型序:数字/日期 < 文本 < 布尔;同类型内数值比大小、文本按自然顺序(中文/数字混排)。
+ */
+export declare function compareCellValues(a: CellModel['raw'], b: CellModel['raw']): number;

package/dist/core/viewer/overlay-manager.d.ts

@@ -0,0 +1,27 @@
+import { SheetModel } from '../model/types';
+import { CanvasRenderer, ViewState } from '../render/canvas-renderer';
+/** 冻结四象限容器: 主区 / 冻结行 / 冻结列 / 冻结角 */
+export interface OverlayQuads {
+    main: HTMLElement;
+    frow: HTMLElement;
+    fcol: HTMLElement;
+    corner: HTMLElement;
+}
+export declare class OverlayManager {
+    private quads;
+    private chartInstances;
+    private imageEls;
+    private chartPlaceholders;
+    private shapeEls;
+    /** 防止异步加载 echarts 期间已切表/重建: build 自增,await 后 token 变了就放弃 */
+    private buildToken;
+    constructor(quads: OverlayQuads);
+    private container;
+    /** 锚点落在哪个象限(冻结行/列内的钉住,其余随滚动) */
+    private quadrantOf;
+    dispose(): void;
+    /** 重建该表全部叠加层(先销毁再挂载),末尾定位一次 */
+    build(sheet: SheetModel, renderer: CanvasRenderer, view: ViewState): Promise<void>;
+    /** 按当前视图(滚动/缩放)重新定位四象限容器与各叠加层 */
+    position(sheet: SheetModel, renderer: CanvasRenderer, view: ViewState): void;
+}

package/dist/core/viewer/plugin-overlay.d.ts

@@ -0,0 +1,8 @@
+import { ExcelPlugin, OverlayContext } from '../plugin';
+export declare class PluginOverlayHost {
+    private container;
+    constructor(container: HTMLElement);
+    /** 重渲所有插件的 overlay:依次调 overlay(ctx),把返回的 DOM 节点替换进容器。 */
+    render(plugins: readonly ExcelPlugin[], ctx: OverlayContext): void;
+    dispose(): void;
+}

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+export * from './core/index'
+export {}