ooxml-excel-editor 1.1.0

package/dist/core/model/types.d.ts

@@ -0,0 +1,289 @@
+/**
+ * 中间数据模型 —— 渲染层只认这套类型，与 ExcelJS / 原始 XML 形状完全解耦。
+ * 将来要换解析库或换 DOM 渲染，只要保证产出/消费这套模型即可。
+ */
+/** RGB(A) 颜色，统一成 css 可用字符串(如 "#RRGGBB" / "rgba(...)")。 */
+export type CssColor = string;
+/** 水平对齐 */
+export type HAlign = 'left' | 'center' | 'right' | 'fill' | 'justify' | 'general';
+/** 垂直对齐 */
+export type VAlign = 'top' | 'middle' | 'bottom';
+/** 单个边框边的样式 */
+export interface BorderEdge {
+    style: BorderStyle;
+    color: CssColor;
+}
+export type BorderStyle = 'none' | 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'mediumDashDot' | 'dashDotDot' | 'mediumDashDotDot' | 'slantDashDot';
+export interface Borders {
+    top?: BorderEdge;
+    bottom?: BorderEdge;
+    left?: BorderEdge;
+    right?: BorderEdge;
+    /** 对角线边框样式(up/down 共用此线型与颜色) */
+    diagonal?: BorderEdge;
+    /** ↗ 左下→右上 对角线 */
+    diagonalUp?: boolean;
+    /** ↘ 左上→右下 对角线 */
+    diagonalDown?: boolean;
+}
+export interface Font {
+    name: string;
+    size: number;
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    strike: boolean;
+    color: CssColor;
+}
+export type FillType = 'none' | 'solid' | 'pattern' | 'gradient';
+export interface Fill {
+    type: FillType;
+    /** solid / pattern 前景色；gradient 时为第一个 stop */
+    fgColor?: CssColor;
+    bgColor?: CssColor;
+    pattern?: string;
+    /** 渐变色标(可选，简化版) */
+    gradientStops?: {
+        position: number;
+        color: CssColor;
+    }[];
+    gradientAngle?: number;
+}
+export interface CellStyle {
+    font: Font;
+    fill: Fill;
+    borders: Borders;
+    hAlign: HAlign;
+    vAlign: VAlign;
+    wrapText: boolean;
+    shrinkToFit: boolean;
+    /** 文本旋转角度(度)，Excel 范围 -90..90，255 表示竖排 */
+    textRotation: number;
+    indent: number;
+    /** 数字格式代码字符串(已从 numFmtId 解析为 code) */
+    numFmt: string;
+}
+/** 单元格的逻辑值类型 */
+export type CellValueType = 'empty' | 'number' | 'string' | 'boolean' | 'date' | 'error' | 'hyperlink' | 'richtext' | 'formula';
+export interface RichTextRun {
+    text: string;
+    font?: Partial<Font>;
+}
+export interface CellModel {
+    row: number;
+    col: number;
+    type: CellValueType;
+    /** 原始值: number / string / boolean / Date / error 字符串 */
+    raw: number | string | boolean | Date | null;
+    /** 富文本分段(type === 'richtext' 时有) */
+    rich?: RichTextRun[];
+    /** 公式文本(type === 'formula' 时有；显示用 raw 缓存值) */
+    formula?: string;
+    /** 超链接目标 */
+    hyperlink?: string;
+    /** 单元格批注(纯文本) */
+    comment?: string;
+    /** 样式索引，指向 SheetModel.styles */
+    styleId: number;
+}
+/** 合并区域(0-based，闭区间) */
+export interface MergeRange {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+}
+export interface ColumnInfo {
+    /** 列宽，单位 = px(已从字符数换算) */
+    width: number;
+    hidden: boolean;
+}
+export interface RowInfo {
+    /** 行高，单位 = px(已从 pt 换算) */
+    height: number;
+    hidden: boolean;
+}
+/** 冻结窗格: 冻结前 frozenRows 行 / frozenCols 列 */
+export interface FreezeInfo {
+    frozenRows: number;
+    frozenCols: number;
+}
+/** 条件格式规则(简化版，覆盖常见 4 类) */
+export interface ConditionalRule {
+    ranges: MergeRange[];
+    priority: number;
+    type: 'cellIs' | 'colorScale' | 'dataBar' | 'iconSet' | 'expression' | 'top10' | 'unsupported';
+    /** cellIs */
+    operator?: string;
+    formulae?: string[];
+    /** 命中时套用的样式(cellIs / expression) */
+    style?: Partial<CellStyle>;
+    /** colorScale: 2~3 个色标 */
+    colorScale?: {
+        min: CssColor;
+        mid?: CssColor;
+        max: CssColor;
+    };
+    /** dataBar */
+    dataBar?: {
+        color: CssColor;
+        gradient: boolean;
+    };
+    /** iconSet */
+    iconSet?: {
+        name: string;
+    };
+}
+/** 图片锚定(像素矩形由 layout 阶段最终算出，这里给逻辑锚点) */
+export interface ImageAnchor {
+    /** blob url(由主线程从 bytes 生成；解析阶段为空) */
+    src: string;
+    /** 原始图片字节 + mime(解析层产出，可跨 Worker 传输) */
+    bytes?: Uint8Array;
+    mime?: string;
+    /** twoCellAnchor: from/to 单元格 + 单元格内偏移(EMU) */
+    from: AnchorCell;
+    to?: AnchorCell;
+    /** oneCellAnchor / absolute 的尺寸(EMU) */
+    extWidthEmu?: number;
+    extHeightEmu?: number;
+    editAs?: string;
+}
+export interface AnchorCell {
+    col: number;
+    colOffEmu: number;
+    row: number;
+    rowOffEmu: number;
+}
+/** 图表规格(从 chartN.xml 抽出，交给 ECharts 映射) */
+export interface ChartSpec {
+    type: 'bar' | 'line' | 'pie' | 'area' | 'scatter' | 'doughnut' | 'radar' | 'unsupported';
+    title?: string;
+    showLegend: boolean;
+    barDirection?: 'col' | 'bar';
+    categories: (string | number)[];
+    series: ChartSeries[];
+    anchor: ImageAnchor;
+}
+export interface ChartSeries {
+    name?: string;
+    values: (number | null)[];
+    color?: CssColor;
+}
+export interface SheetModel {
+    name: string;
+    index: number;
+    state: 'visible' | 'hidden' | 'veryHidden';
+    /** 实际数据范围 */
+    dimension: {
+        rows: number;
+        cols: number;
+    };
+    /** 稀疏存储: key = `${row}:${col}` */
+    cells: Map<string, CellModel>;
+    /** 样式表，CellModel.styleId 索引 */
+    styles: CellStyle[];
+    merges: MergeRange[];
+    columns: Map<number, ColumnInfo>;
+    rows: Map<number, RowInfo>;
+    defaultColWidth: number;
+    defaultRowHeight: number;
+    freeze: FreezeInfo;
+    conditional: ConditionalRule[];
+    /** 自动筛选区域(画下拉按钮用) */
+    autoFilterRange?: MergeRange;
+    /** 含"列表"型数据验证的区域(选中时画下拉箭头) */
+    dataValidations: MergeRange[];
+    images: ImageAnchor[];
+    charts: ChartSpec[];
+    /** 形状 / 文本框(DrawingML sp) */
+    shapes: ShapeSpec[];
+    /** 迷你图(单元格内嵌折线/柱/盈亏图) */
+    sparklines: Sparkline[];
+    /** 手动分页符(0-based 边界索引): 在这些行上方/列左侧画分页虚线 */
+    pageBreaks?: {
+        rows: number[];
+        cols: number[];
+    };
+    /** 原生页面设置(打印/导出默认值来源);缺省走 export 模块默认 */
+    pageSetup?: PageSetupModel;
+    showGridLines: boolean;
+}
+/** OOXML 原生页面设置(pageSetup + pageMargins + 打印区域/标题),用作导出默认值 */
+export interface PageSetupModel {
+    orientation?: 'portrait' | 'landscape';
+    /** 纸张: 由 paperSize 代码映射;无法识别时省略(走默认 a4) */
+    paperFormat?: 'a4' | 'a3' | 'letter' | [number, number];
+    /** 缩放百分比(如 80 = 80%);fitToPage 时无意义 */
+    scale?: number;
+    /** 适应页面(fitToPage): 优先于 scale */
+    fitToPage?: boolean;
+    fitToWidth?: number;
+    fitToHeight?: number;
+    /** 页边距 mm(从 inch 换算) */
+    margins?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        header: number;
+        footer: number;
+    };
+    /** 打印区域(0-based 闭区间;多区域取第一段) */
+    printArea?: MergeRange;
+    /** 打印标题行 [r0,r1] 0-based(每页顶部重复) */
+    printTitleRows?: [number, number];
+    /** 打印标题列 [c0,c1] 0-based(横向分页时左侧重复;当前竖向分页管线不应用) */
+    printTitleCols?: [number, number];
+}
+/** 形状 / 文本框: 用锚点定位,带填充/边框/文字 */
+export interface ShapeSpec {
+    anchor: ImageAnchor;
+    /** 形状类型(prstGeom): rect / roundRect / ellipse / 其它(按 rect 处理) */
+    geom: 'rect' | 'roundRect' | 'ellipse' | 'other';
+    text?: string;
+    fillColor?: CssColor;
+    lineColor?: CssColor;
+    textColor?: CssColor;
+    bold?: boolean;
+    /** 文本水平对齐 */
+    align?: 'left' | 'center' | 'right';
+}
+/** 迷你图: 锚在某个单元格，数据来自一段区域的数值 */
+export interface Sparkline {
+    row: number;
+    col: number;
+    type: 'line' | 'column' | 'winloss';
+    values: (number | null)[];
+    /** 主色(可选，缺省用默认蓝) */
+    color?: CssColor;
+    negativeColor?: CssColor;
+}
+export interface WorkbookModel {
+    sheets: SheetModel[];
+    activeSheet: number;
+    /** 主题色调色板(theme1.xml 解析所得，索引同 ECMA dk1/lt1/dk2/lt2/accent1..6/hlink/folHlink) */
+    themeColors: CssColor[];
+    date1904: boolean;
+}
+export declare const cellKey: (row: number, col: number) => string;
+/** 数据钩子: 解析后、渲染前改模型(返回新模型或就地改) */
+export type TransformModelFn = (workbook: WorkbookModel) => WorkbookModel | void;
+/** 单元格样式覆盖(各字段可选;font/fill/borders 允许部分,与解析样式浅合并) */
+export interface CellStyleOverride {
+    font?: Partial<Font>;
+    fill?: Partial<Fill>;
+    borders?: Partial<Borders>;
+    hAlign?: HAlign;
+    vAlign?: VAlign;
+    wrapText?: boolean;
+    shrinkToFit?: boolean;
+    textRotation?: number;
+    indent?: number;
+    numFmt?: string;
+}
+/** 渲染钩子: 按单元格覆盖样式(返回部分样式,与解析样式合并) */
+export type CellStyleFn = (cell: CellModel, pos: {
+    row: number;
+    col: number;
+}) => CellStyleOverride | void;

package/dist/core/overlay/anchor.d.ts

@@ -0,0 +1,9 @@
+import { ImageAnchor } from '../model/types';
+import { GridMetrics } from '../layout/grid-metrics';
+export interface ContentRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export declare function anchorRect(metrics: GridMetrics, anchor: ImageAnchor): ContentRect;

package/dist/core/overlay/chart-mapper.d.ts

@@ -0,0 +1,3 @@
+import { ChartSpec } from '../model/types';
+import { EChartsOption } from 'echarts';
+export declare function chartToOption(spec: ChartSpec): EChartsOption;

package/dist/core/overlay/echarts-loader.d.ts

@@ -0,0 +1,3 @@
+/** echarts 按需加载(可选 peer 依赖)。共享给 OverlayManager 与导出图表栅格化。 */
+import type * as EChartsNS from 'echarts';
+export declare function loadECharts(): Promise<typeof EChartsNS>;

package/dist/core/parse.worker.d.ts

@@ -0,0 +1,14 @@
+import { WorkbookModel } from './model/types';
+import { ParseProgress } from './progress';
+export type WorkerMsg = {
+    type: 'progress';
+    progress: ParseProgress;
+} | {
+    type: 'done';
+    ok: true;
+    model: WorkbookModel;
+} | {
+    type: 'done';
+    ok: false;
+    error: string;
+};

package/dist/core/parser/chart-parser.d.ts

@@ -0,0 +1,3 @@
+import { RawPackage } from './raw-xml';
+import { ChartSpec } from '../model/types';
+export declare function parseChart(pkg: RawPackage, chartPath: string): Omit<ChartSpec, 'anchor'> | undefined;

package/dist/core/parser/drawing-parser.d.ts

@@ -0,0 +1,3 @@
+import { RawPackage } from './raw-xml';
+import { SheetModel } from '../model/types';
+export declare function attachDrawings(pkg: RawPackage, sheets: SheetModel[]): void;

package/dist/core/parser/exceljs-adapter.d.ts

@@ -0,0 +1,8 @@
+import { default as ExcelJS } from 'exceljs';
+import { MergeRange, PageSetupModel, SheetModel, CssColor } from '../model/types';
+import { ProgressFn } from '../progress';
+export declare function buildSheets(wb: ExcelJS.Workbook, themeColors: CssColor[], onProgress?: ProgressFn): SheetModel[];
+/** 从 ExcelJS worksheet.pageSetup 抽出原生页面设置;失败返回 undefined。(导出供单测) */
+export declare function parsePageSetup(ws: ExcelJS.Worksheet): PageSetupModel | undefined;
+export declare function colLettersToIndex(letters: string): number;
+export declare function parseA1Range(range: string): MergeRange | null;

package/dist/core/parser/index.d.ts

@@ -0,0 +1,3 @@
+import { WorkbookModel } from '../model/types';
+import { ProgressFn } from '../progress';
+export declare function parseWorkbook(buffer: ArrayBuffer, onProgress?: ProgressFn): Promise<WorkbookModel>;

package/dist/core/parser/page-break-parser.d.ts

@@ -0,0 +1,3 @@
+import { RawPackage } from './raw-xml';
+import { SheetModel } from '../model/types';
+export declare function attachPageBreaks(pkg: RawPackage, sheets: SheetModel[]): void;

package/dist/core/parser/raw-xml.d.ts

@@ -0,0 +1,15 @@
+export interface RawPackage {
+    files: Record<string, Uint8Array>;
+    parse(path: string): any | undefined;
+    text(path: string): string | undefined;
+    bytes(path: string): Uint8Array | undefined;
+    list(prefix: string): string[];
+}
+export declare function openPackage(buffer: ArrayBuffer): RawPackage;
+/** 解析 part 的 .rels，返回 r:id → target(相对该 part 目录解析后的绝对包内路径) */
+export declare function parseRels(pkg: RawPackage, partPath: string): Record<string, string>;
+export declare function basename(p: string): string;
+/** 相对 baseDir 解析 target(支持 ../) → 包内绝对路径(无前导 /) */
+export declare function resolvePath(baseDir: string, target: string): string;
+/** fast-xml-parser 对单元素/多元素返回 object/array 不一致，统一成数组 */
+export declare function toArray<T = any>(v: T | T[] | undefined | null): T[];

package/dist/core/parser/sparkline-parser.d.ts

@@ -0,0 +1,3 @@
+import { RawPackage } from './raw-xml';
+import { SheetModel } from '../model/types';
+export declare function attachSparklines(pkg: RawPackage, sheets: SheetModel[]): void;

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

@@ -0,0 +1,3 @@
+import { RawPackage } from './raw-xml';
+import { CssColor } from '../model/types';
+export declare function parseTheme(pkg: RawPackage): CssColor[];

package/dist/core/plugin.d.ts

@@ -0,0 +1,180 @@
+import { CellStyleFn, CellStyleOverride, ImageAnchor, MergeRange, TransformModelFn, WorkbookModel } from './model/types';
+import { CellValue, ReadOptions, SheetToJSONOptions } from './model/data-access';
+import { CellSnapshot } from './model/snapshot';
+import { EditorResolver } from './edit/editor-context';
+import { ViewerTheme } from './render/theme';
+import { ExcelSource } from './loader';
+import { ImageExportOptions, PdfExportOptions, PrintOptions } from './export/types';
+import { XlsxExportOptions } from './export/xlsx-writer';
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export type PluginEvent = 'cell-click' | 'cell-dblclick' | 'selection-change' | 'sheet-change' | 'hyperlink-click' | 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change';
+/** 命令式 API(组件 ref 与插件 ctx 共用) */
+export interface ViewerApi {
+    load(src: ExcelSource): void;
+    getWorkbook(): WorkbookModel | null;
+    getActiveSheet(): number;
+    setActiveSheet(index: number): void;
+    getSelection(): MergeRange | null;
+    setSelection(range: MergeRange): void;
+    rectOf(row: number, col: number): Rect | null;
+    rectOfRange(range: MergeRange): Rect | null;
+    redraw(): void;
+    /** 该格当前是否可编辑(综合 editable + readOnlyRanges + cellReadOnly) */
+    isCellEditable(row: number, col: number): boolean;
+    /** 导出当前/指定表为图片 Blob(默认 png) */
+    exportImage(opts?: ImageExportOptions): Promise<Blob>;
+    /** 导出为图片并触发下载 */
+    downloadImage(opts?: ImageExportOptions): Promise<void>;
+    /** 导出为 PDF Blob(需可选依赖 jspdf);beforeRenderPage 可画页眉/页脚/水印 */
+    exportPdf(opts?: PdfExportOptions): Promise<Blob>;
+    /** 导出 PDF 并触发下载 */
+    downloadPdf(opts?: PdfExportOptions): Promise<void>;
+    /** 打开系统打印(可在对话框另存为 PDF) */
+    print(opts?: PrintOptions): Promise<void>;
+    /** 整簿 → .xlsx Blob(从编辑后模型重建,所见即所得;需可选依赖 exceljs) */
+    exportXlsx(opts?: XlsxExportOptions): Promise<Blob>;
+    /** 导出 .xlsx 并触发下载 */
+    downloadXlsx(opts?: XlsxExportOptions): Promise<void>;
+    /** 整簿 → JSON 文本(各表首行作 key) */
+    exportJson(opts?: SheetToJSONOptions): string;
+    /** 导出 JSON 并触发下载 */
+    downloadJson(opts?: SheetToJSONOptions): void;
+    /** 一张表 → CSV 文本(默认活动表、格式化显示值) */
+    exportCsv(opts?: {
+        target?: number;
+        format?: boolean;
+    }): string;
+    /** 导出 CSV 并触发下载(带 UTF-8 BOM) */
+    downloadCsv(opts?: {
+        target?: number;
+        format?: boolean;
+    }): void;
+    /** 单元格原始值 */
+    getCellValue(row: number, col: number, sheetIndex?: number): CellValue;
+    /** 单元格格式化显示文本 */
+    getCellText(row: number, col: number, sheetIndex?: number): string;
+    /** 整表二维数组(format 默认 true=显示文本) */
+    getSheetData(opts?: ReadOptions, sheetIndex?: number): CellValue[][];
+    /** 整表对象数组(首行作表头) */
+    getSheetJSON(opts?: SheetToJSONOptions, sheetIndex?: number): Record<string, CellValue>[];
+    /** 区域二维数组 */
+    getRangeData(range: MergeRange, opts?: ReadOptions, sheetIndex?: number): CellValue[][];
+    /** 编辑单格;返回是否生效 */
+    editCell(row: number, col: number, value: CellValue): boolean;
+    /** 区域批量设值(2D,左上对齐 range.top/left);跳过只读格 */
+    editRange(range: MergeRange, values: CellValue[][]): boolean;
+    /** 清空区域(跳过只读) */
+    clearRange(range: MergeRange): boolean;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** 当前正在编辑的格(无则 null) */
+    getEditingCell(): {
+        row: number;
+        col: number;
+    } | null;
+    /** 查询任意格的完整快照(底层结构 + raw/computed/text/style) */
+    getCellSnapshot(row: number, col: number): CellSnapshot | null;
+    /** 进入编辑(需有 editor 工厂 + 可编辑);返回是否进入 */
+    beginEdit(row: number, col: number): boolean;
+    /** 取消当前编辑(不改模型) */
+    cancelEdit(): void;
+    /** 当前是否有活动编辑器 */
+    isEditing(): boolean;
+    /** 给区域套样式覆盖(E5;粗体/对齐/填充等);editable 时入命令栈(可撤销 + 发 cell-change + 记脏) */
+    setStyle(range: MergeRange, patch: CellStyleOverride): boolean;
+    /** 读当前表全部图片锚点(克隆;E6) */
+    getImages(): ImageAnchor[];
+    /** 加一张图(无 src 但有 bytes+mime 时自动生成 blob url);返回插入索引 */
+    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 行(E7);editable 时入命令栈 + 发 struct-change */
+    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;
+    /** 程序化设列宽(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;
+    /** 放弃全部修改,还原到刚加载的原件;返回是否还原 */
+    resetToOriginal(): boolean;
+}
+/** overlay 渲染上下文(随滚动/缩放,tick 变即重渲) */
+export interface OverlayContext {
+    rectOf(row: number, col: number): Rect | null;
+    rectOfRange(range: MergeRange): Rect | null;
+    tick: number;
+    workbook: WorkbookModel | null;
+}
+/** overlay 钩子返回值:框架无关的 DOM 节点(单个 / 多个 / 无)。Vue 与 React 壳都直接挂载。 */
+export type OverlayNode = HTMLElement | HTMLElement[] | null;
+export interface ExcelPluginContext {
+    viewer: ViewerApi;
+    /** 订阅交互事件 */
+    on(event: PluginEvent, handler: (payload: any) => void): void;
+    /** 主动重绘 */
+    redraw(): void;
+}
+/** 操作工具栏的一个按钮(插件贡献 / 组件 :toolbar 配置 / 命令式自定义共用) */
+export interface ToolbarItem {
+    /** 唯一 id(内置: 'find'|'filter'|'sort'|'export'|'zoom'|'copy'|'freeze'|'clear-filter';自定义任意) */
+    id: string;
+    /** 类型: 'button'(默认) | 'separator'(分隔线,其余字段忽略) */
+    type?: 'button' | 'separator';
+    /** 图标(emoji / 字形);跨平台一致建议用 iconSvg */
+    icon?: string;
+    /** 内联 SVG(优先于 icon);建议 24×24 viewBox、stroke=currentColor */
+    iconSvg?: string;
+    /** 文字 */
+    label?: string;
+    /** 悬停提示 */
+    title?: string;
+    /** 点击回调(拿到命令式 API);有 items 时点击改为展开下拉 */
+    onClick?: (viewer: ViewerApi) => void;
+    /** 是否高亮(激活态),如开关类按钮 */
+    active?: (viewer: ViewerApi) => boolean;
+    /** 是否禁用(置灰不可点) */
+    disabled?: (viewer: ViewerApi) => boolean;
+    /** 下拉子菜单项;有则本项为下拉按钮(点击展开) */
+    items?: ToolbarItem[];
+}
+export interface ExcelPlugin {
+    name: string;
+    /** 外观主题覆盖(多插件按数组顺序合并,组件 :theme 最后覆盖) */
+    theme?: Partial<ViewerTheme>;
+    /** 贡献操作工具栏按钮(opt-in: 插件加载即出现) */
+    toolbar?: ToolbarItem[];
+    /** 数据钩子: 解析后改模型(多插件 + 组件 prop 链式应用) */
+    transformModel?: TransformModelFn;
+    /** 渲染钩子: 按单元格覆盖样式(多插件 + 组件 prop 合并) */
+    cellStyle?: CellStyleFn;
+    /** 交互事件处理(简单写法;复杂用 setup 的 on) */
+    events?: Partial<Record<PluginEvent, (payload: any) => void>>;
+    /** 在网格上叠加 UI(返回 DOM 节点,框架无关);随 tick 重渲。用 ctx.rectOf 定位单元格。 */
+    overlay?: (ctx: OverlayContext) => OverlayNode;
+    /** 按格自定义编辑控件(返回工厂;多插件数组序首个非空胜,组件 editor prop 覆盖);需 editable 开启。 */
+    editor?: EditorResolver;
+    /** 高级: 拿命令式 API、订阅事件;返回可选清理函数 */
+    setup?: (ctx: ExcelPluginContext) => void | (() => void);
+}
+/** 定义插件(仅作类型推断,原样返回) */
+export declare function definePlugin(plugin: ExcelPlugin): ExcelPlugin;

package/dist/core/progress.d.ts

@@ -0,0 +1,7 @@
+/** 解析进度(分阶段)。read/build 有真实 ratio;parse 是 exceljs 黑盒,ratio 缺省=不确定态。 */
+export interface ParseProgress {
+    stage: 'read' | 'parse' | 'build';
+    /** 0..1;parse 阶段为 undefined(不确定态,UI 走脉冲) */
+    ratio?: number;
+}
+export type ProgressFn = (p: ParseProgress) => void;

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

@@ -0,0 +1,14 @@
+import { MergeRange } from '../model/types';
+/** 判断某 cell 是否是自动筛选表头(范围首行) */
+export declare function isFilterHeader(range: MergeRange | undefined, row: number, col: number): boolean;
+/** 单元格右侧筛选下拉按钮的方形区域(像素);供命中检测与绘制共用 */
+export declare function filterButtonBox(cellX: number, cellY: number, cellW: number, cellH: number): {
+    x: number;
+    y: number;
+    size: number;
+} | null;
+/**
+ * 在单元格右侧画一个筛选下拉按钮。active=true 时画蓝色漏斗(已筛选)。
+ * 返回按钮占用的宽度(供文本避让)。
+ */
+export declare function drawFilterButton(ctx: CanvasRenderingContext2D, cellX: number, cellY: number, cellW: number, cellH: number, active?: boolean): number;

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

@@ -0,0 +1,13 @@
+import { BorderEdge } from '../model/types';
+/** 共享边取较重的一条(同重则取 a / 本单元格的)。任一为空按 none 计。 */
+export declare function heavierEdge(a: BorderEdge | undefined, b: BorderEdge | undefined): BorderEdge | undefined;
+/**
+ * 画一条边。(x1,y1)-(x2,y2) 为边的两端点(已是屏幕坐标)。
+ * 横边传 y1===y2，竖边传 x1===x2。
+ */
+export declare function drawEdge(ctx: CanvasRenderingContext2D, edge: BorderEdge | undefined, x1: number, y1: number, x2: number, y2: number): void;
+/**
+ * 画一条任意方向的对角线(单元格对角线边框 ↘ / ↗)。
+ * 用线型的宽度/虚线/颜色;double 退化为单线(对角双线极罕见,不值得歪斜偏移)。
+ */
+export declare function drawDiagonalEdge(ctx: CanvasRenderingContext2D, edge: BorderEdge | undefined, x1: number, y1: number, x2: number, y2: number): void;