ooxml-excel-editor 1.1.0

package/dist/core/edit/edit-controller.d.ts

@@ -0,0 +1,137 @@
+import { CellStyleOverride, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel, WorkbookModel } from '../model/types';
+import { CellValue } from '../model/data-access';
+import { CellSnapshot } from '../model/snapshot';
+import { CellPos, DimAxis } from './commands';
+import { StructOp } from '../model/structure';
+import { FormulaEngineFactory } from '../formula/engine';
+export type EditEventName = 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change';
+export type EditSource = 'api' | 'ui' | 'undo' | 'redo';
+/** 结构变更事件载荷(增删行列;restore = 撤销/重做的整体还原) */
+export interface StructChangePayload {
+    op: StructOp | 'restore';
+    at?: number;
+    count?: number;
+    source: EditSource;
+}
+/** 图片变更事件载荷(before/after = ImageAnchor 克隆;add → before=null;remove → after=null) */
+export interface ImageChangePayload {
+    index: number;
+    before: ImageAnchor | null;
+    after: ImageAnchor | null;
+    source: EditSource;
+}
+export interface CellChangePayload {
+    before: CellSnapshot;
+    after: CellSnapshot;
+    source: EditSource;
+}
+/** 列宽/行高变更事件载荷(before/after = px 尺寸,含默认值回落) */
+export interface DimChangePayload {
+    axis: DimAxis;
+    index: number;
+    before: number;
+    after: number;
+    source: EditSource;
+}
+/** 脏状态变更事件载荷 */
+export interface DirtyChangePayload {
+    dirty: boolean;
+}
+/** EditController 与 ViewerController 的桥(host-callback,框架无关) */
+export interface EditControllerHost {
+    getSheet(): SheetModel | null;
+    getWorkbook(): WorkbookModel | null;
+    getDate1904(): boolean;
+    /** 该格是否可编辑(综合 editable + readOnlyRanges + cellReadOnly) */
+    isEditable(row: number, col: number): boolean;
+    /** 编辑模式是否开启(决定是否懒捕获 baseline / 记账脏状态) */
+    isEditingEnabled(): boolean;
+    /** 当前活动表索引(0-based;重算把级联事件/写回锚到它) */
+    getActiveSheetIndex(): number;
+    /** 是否开启公式重算(EditConfig.recalc) */
+    isRecalcEnabled(): boolean;
+    /** 公式引擎工厂(EditConfig.formulaEngine,或默认 HyperFormula;未开重算 → null) */
+    getEngineFactory(): FormulaEngineFactory | null;
+    /** 模型变更后回调:重建几何 + 重绘 */
+    onModelChange(): void;
+    /** 图片结构变化(增删)→ 重建叠加层(重绘不够,要新建/移除 DOM)。移动只需 onModelChange 重定位。 */
+    rebuildOverlays(): void;
+    /** 发编辑事件(壳转 emit + 插件派发) */
+    emit(event: EditEventName, payload: unknown): void;
+}
+export declare class EditController {
+    private host;
+    private undoStack;
+    private redoStack;
+    private editing;
+    private readonly limit;
+    private dirty;
+    private baseline;
+    private baselineFor;
+    private engine;
+    private engineFor;
+    private warming;
+    constructor(host: EditControllerHost);
+    /** 异步懒初始化引擎(开重算 + 有工厂 + 尚未为当前簿建好)。返回的 Promise 供测试 await;生产 fire-and-forget。 */
+    warmEngine(): Promise<void>;
+    /** 释放引擎(切簿/关重算/dispose)。 */
+    disposeEngine(): void;
+    /** 配置变化(recalc/factory)或换新簿:重置引擎并按需重新点火。 */
+    refreshEngine(): void;
+    private engineReady;
+    /** 公式引擎是否已就绪(异步 warm 完成且对应当前簿);未开重算恒 false。 */
+    isRecalcReady(): boolean;
+    getEditingCell(): CellPos | null;
+    setEditing(cell: CellPos | null): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** 查询任意格的完整快照(要求 5:事件之外也有查询 API) */
+    getCellSnapshot(row: number, col: number): CellSnapshot | null;
+    /** 切表/换簿时清空(交互态 + 命令栈作废) */
+    reset(): void;
+    /** 编辑单格;只读则不动,返回是否生效 */
+    editCell(row: number, col: number, value: CellValue): boolean;
+    /** 区域批量设值(2D,左上对齐 range.top/left);跳过只读格,返回是否有改动 */
+    editRange(range: MergeRange, values: CellValue[][]): boolean;
+    /** 清空区域(跳过只读) */
+    clearRange(range: MergeRange): boolean;
+    /** 给区域套样式覆盖(E5;跳过只读格)。返回是否有改动。前后 style 不同 → 发 cell-change。 */
+    setStyle(range: MergeRange, patch: CellStyleOverride): boolean;
+    insertRows(at: number, count?: number): boolean;
+    deleteRows(at: number, count?: number): boolean;
+    insertCols(at: number, count?: number): boolean;
+    deleteCols(at: number, count?: number): boolean;
+    private structEdit;
+    /** 读当前表全部图片锚点(克隆,防外部改)。 */
+    getImages(): ImageAnchor[];
+    /** 加一张图,返回插入索引(失败 -1)。 */
+    addImage(anchor: ImageAnchor): number;
+    /** 删一张图。 */
+    removeImage(index: number): boolean;
+    /**
+     * 补登一次图片移动/缩放(拖拽/programmatic:模型已被 setImageRect 改完,这里只补 undo + 发 image-change)。
+     * baseline 须在变更前由调用方 ensureBaseline() 捕获。
+     */
+    recordImageEdit(index: number, before: ImageAnchor, after: ImageAnchor): void;
+    /** 程序化设列宽/行高(API 路径:apply-via-command)。返回是否生效。 */
+    setDimension(axis: DimAxis, index: number, size: number): boolean;
+    /**
+     * 补登一次维度变更(拖拽/autofit 路径:模型已被 renderer 改完,这里只补 undo 项 + 发事件)。
+     * baseline 须在变更前(拖拽起始/autofit 前)由调用方 ensureBaseline() 捕获。
+     */
+    recordDimEdit(axis: DimAxis, index: number, beforeInfo: ColumnInfo | RowInfo | null, before: number, after: number): void;
+    /** editable 时懒捕获 baseline(首次编辑/resize 前调,模型仍原始);幂等。 */
+    ensureBaseline(): void;
+    isDirty(): boolean;
+    private markDirty;
+    /** 换新工作簿(非切表)时:作废 baseline + 清脏(切表保留,见 controller 判定)。 */
+    resetDirtyBaseline(): void;
+    /** 放弃全部修改,还原到刚加载的原件。返回是否还原(无 baseline → false)。 */
+    resetToOriginal(): boolean;
+    undo(): void;
+    redo(): void;
+    private collectEditable;
+    private pushUndo;
+    /** 应用一条命令:建前快照 → apply → 重绘 → 发事件(cell 族 cell-change / dim 族 dim-change)。返回逆命令。 */
+    private exec;
+}

package/dist/core/edit/editor-context.d.ts

@@ -0,0 +1,40 @@
+import { SheetModel, WorkbookModel, CellModel, CellStyleOverride } from '../model/types';
+import { CellValue } from '../model/data-access';
+import { CellSnapshot } from '../model/snapshot';
+import { EditPermission } from './types';
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** commit 既可只给值,也可同时给样式(样式 E5 起生效) */
+export type EditorCommitValue = CellValue | {
+    value: CellValue;
+    style?: CellStyleOverride;
+};
+export interface CellEditorContext {
+    /** 进入编辑时的完整前态快照 */
+    snapshot: CellSnapshot;
+    /** 单元格当前屏幕矩形(render-area 相对) */
+    rect: Rect;
+    sheet: SheetModel;
+    workbook: WorkbookModel;
+    permission: EditPermission;
+    /** 进入编辑的初始文本(打字进入时为该字符;否则 undefined → editor 用 snapshot.text) */
+    initialText?: string;
+    /** 提交编辑(走命令栈 + 事件);move 指示提交后活动格移动方向 */
+    commit(value: EditorCommitValue, move?: 'down' | 'right'): void;
+    /** 取消编辑(不改模型) */
+    cancel(): void;
+}
+/** 编辑器工厂:返回 DOM 元素,或 { el, destroy }(destroy 在卸载时清理) */
+export type CellEditorFactory = (ctx: CellEditorContext) => HTMLElement | {
+    el: HTMLElement;
+    destroy?: () => void;
+};
+/** 编辑器解析器:按格决定用哪个工厂(无 → 该格无自定义编辑器) */
+export type EditorResolver = (cell: CellModel | null, pos: {
+    row: number;
+    col: number;
+}) => CellEditorFactory | void;

package/dist/core/edit/editor-host.d.ts

@@ -0,0 +1,22 @@
+import { CellEditorContext, CellEditorFactory, Rect } from './editor-context';
+export declare class CellEditorHost {
+    private container;
+    private rectOf;
+    private active;
+    constructor(container: HTMLElement, rectOf: (row: number, col: number) => Rect | null);
+    isActive(): boolean;
+    activeCell(): {
+        row: number;
+        col: number;
+    } | null;
+    /**
+     * 挂载一个编辑器(先卸旧)。返回是否成功(工厂产出有效 DOM)。
+     * rectOverride 给定时用它定位(合并单元格 → 整片合并区),否则按单格 rectOf。
+     */
+    mount(row: number, col: number, factory: CellEditorFactory, ctx: CellEditorContext, rectOverride?: () => Rect | null): boolean;
+    /** 按当前 rectOf 重定位活动编辑器(滚动/缩放后跟随) */
+    position(): void;
+    /** 卸载活动编辑器 */
+    unmount(): void;
+    dispose(): void;
+}

package/dist/core/edit/permissions.d.ts

@@ -0,0 +1,3 @@
+import { SheetModel } from '../model/types';
+import { EditConfig } from './types';
+export declare function resolveEditable(sheet: SheetModel, row: number, col: number, cfg: EditConfig): boolean;

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

@@ -0,0 +1,23 @@
+import { CellModel, MergeRange } from '../model/types';
+import { FormulaEngineFactory } from '../formula/engine';
+export interface EditConfig {
+    /** 总开关:默认 false = 只读(行为与历史完全一致) */
+    editable?: boolean;
+    /** 按格只读判定:返回 true = 该格只读。cell 为空格时传 null。pos 为 0-based 行列。 */
+    cellReadOnly?: (cell: CellModel | null, pos: {
+        row: number;
+        col: number;
+    }) => boolean | void;
+    /** 只读区域(0-based 闭区间);命中即只读 */
+    readOnlyRanges?: MergeRange[];
+    /**
+     * 公式重算(E4):默认 false = 沿用 Excel 缓存值(只读/无公式路径零成本)。
+     * 开启后,编辑公式格或被公式引用的格 → 依赖格自动重算并逐个发 cell-change。
+     * 默认引擎 HyperFormula(GPL-3.0/商业双授权,可选 peer);需 `npm i hyperformula`。
+     */
+    recalc?: boolean;
+    /** 自定义/自研公式引擎工厂(可换引擎);不给则用默认 HyperFormula 适配器。 */
+    formulaEngine?: FormulaEngineFactory;
+}
+/** 单元格编辑权限 */
+export type EditPermission = 'editable' | 'readonly';

package/dist/core/export/composite.d.ts

@@ -0,0 +1,18 @@
+import { ExportToCanvasResult } from '../render/canvas-renderer';
+import { ImageAnchor, ShapeSpec } from '../model/types';
+export interface ExportDecorations {
+    /** 已加载的图片源(HTMLImageElement / 离屏 canvas 等) + 其锚点 */
+    images?: {
+        source: CanvasImageSource;
+        anchor: ImageAnchor;
+    }[];
+    /** 已栅格化的图表源(如 echarts getDataURL 加载成的 Image) + 锚点 */
+    charts?: {
+        source: CanvasImageSource;
+        anchor: ImageAnchor;
+    }[];
+    /** 形状/文本框(按 ShapeSpec 直接画) */
+    shapes?: ShapeSpec[];
+}
+/** 把装饰合成到 base.canvas(原地修改)。 */
+export declare function compositeOverlays(base: ExportToCanvasResult, deco?: ExportDecorations): void;

package/dist/core/export/data-export.d.ts

@@ -0,0 +1,9 @@
+import { SheetModel, WorkbookModel } from '../model/types';
+import { SheetToJSONOptions } from '../model/data-access';
+/** 一张表 → CSV 文本(默认格式化显示值,与渲染一致;行用 CRLF)。 */
+export declare function toCsv(sheet: SheetModel, opts?: {
+    format?: boolean;
+    date1904?: boolean;
+}): string;
+/** 整簿 → JSON(各表首行作 key 的对象数组);复用 getWorkbookJSON。默认 raw 类型值(非显示串)。 */
+export declare function toWorkbookJson(workbook: WorkbookModel, opts?: SheetToJSONOptions): string;

package/dist/core/export/exporter.d.ts

@@ -0,0 +1,64 @@
+import { WorkbookModel } from '../model/types';
+import { CanvasRenderer, RendererOptions } from '../render/canvas-renderer';
+import { XlsxExportOptions } from './xlsx-writer';
+import { SheetToJSONOptions } from '../model/data-access';
+import { ImageExportOptions, PdfExportOptions, PrintOptions } from './types';
+/** 导出取数器: 壳提供当前工作簿 / 活动表 / 复用渲染器 / 渲染配置 / 文件名 */
+export interface ExporterHost {
+    getWorkbook(): WorkbookModel | null;
+    /** 活动表索引(决定 'active' 目标 + 哪张表能复用 live renderer) */
+    getActiveIndex(): number;
+    /** 当前活动表的在用 renderer(复用以省一次离屏构建);非活动表传 null 即可 */
+    getLiveRenderer(): CanvasRenderer | null;
+    /** 离屏渲染其它表时用的渲染配置(主题/cellStyle),须与 live 一致 */
+    getRendererOpts(): RendererOptions;
+    /** 文件名(下载默认名;缺省回退表名 / 'workbook') */
+    getFileName(): string | undefined;
+    /** 原始 .xlsx 字节(高保真 overlay 导出重载原件用;无则返回 null,overlay 回退 rebuild) */
+    getSourceBuffer?(): ArrayBuffer | null;
+}
+export declare class WorkbookExporter {
+    private host;
+    constructor(host: ExporterHost);
+    /** target → 工作表索引列表 */
+    private resolveTargets;
+    /** 取某表的 renderer: 活动表复用 live,其它表离屏新建 */
+    private rendererFor;
+    private baseName;
+    /** 离屏渲染一个图表为 dataURL(供非当前表 / 统一合成);echarts 不可用返回 null */
+    private chartDataUrl;
+    /** 收集一个工作表的叠加层装饰(图片/图表/形状),供合成到导出底图 */
+    private collectDecorations;
+    /**
+     * 为一个工作表生成合成底图(格子 + 图片/图表/形状)。
+     * withTitles(PDF/打印): 应用 pageSetup 打印标题行(抽出标题条 + 正文剔除标题行)与缩放。
+     */
+    private buildSheetImage;
+    /** 为一个工作表生成矢量导出输入(逐格信息 + 兜底底图 + 图片图表 + 标题行) */
+    private buildVectorSheet;
+    /** 从工作表原生 pageSetup 推导导出默认值(纸张/方向/边距/是否适应页宽) */
+    private pageSetupDefaults;
+    /** 导出当前/指定表为图片 Blob(图片为单表;多表请用 PDF) */
+    exportImage(opts?: ImageExportOptions): Promise<Blob>;
+    downloadImage(opts?: ImageExportOptions): Promise<void>;
+    /** 导出为 PDF Blob(每个目标表分页;需可选依赖 jspdf)。未显式指定的页面参数取自工作表 pageSetup。 */
+    exportPdf(opts?: PdfExportOptions): Promise<Blob>;
+    downloadPdf(opts?: PdfExportOptions): Promise<void>;
+    /** 打开系统打印(可在对话框另存为 PDF)。页面参数同样默认取自 pageSetup。 */
+    print(opts?: PrintOptions): Promise<void>;
+    /** 整簿 → JSON 文本(各表首行作 key 的对象数组)。 */
+    exportJson(opts?: SheetToJSONOptions): string;
+    downloadJson(opts?: SheetToJSONOptions): void;
+    /** 一张表 → CSV 文本(默认活动表、格式化显示值)。 */
+    exportCsv(opts?: {
+        target?: number;
+        format?: boolean;
+    }): string;
+    downloadCsv(opts?: {
+        target?: number;
+        format?: boolean;
+    }): void;
+    /** 整簿 → .xlsx Blob(默认从模型重建;`fidelity:'overlay'` 重载原件叠加编辑,保真更高)。 */
+    exportXlsx(opts?: XlsxExportOptions): Promise<Blob>;
+    downloadXlsx(opts?: XlsxExportOptions): Promise<void>;
+}

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

@@ -0,0 +1,9 @@
+/** 导出/打印模块出口 */
+export type { ExportTarget, RenderExportOptions, ImageExportOptions, PageFormat, Orientation, Margins, PageSetup, PdfPageContext, BeforeRenderPage, PdfExportOptions, PrintOptions, } from './types';
+export { canvasToBlob, canvasToDataURL, downloadBlob, loadImage, resolvePageSize, resolveMargins, MM_PER_PX } from './raster';
+export { compositeOverlays, type ExportDecorations } from './composite';
+export { sliceToPages, type SlicedPage } from './paginate';
+export { exportToPdf, type ExportSheetImage } from './pdf';
+export { exportToVectorPdf, type VectorSheet } from './vector-pdf';
+export { printSheets } from './print';
+export { WorkbookExporter, type ExporterHost } from './exporter';

package/dist/core/export/paginate.d.ts

@@ -0,0 +1,36 @@
+export interface SlicedPage {
+    /** 该页的图像切片(设备像素) */
+    canvas: HTMLCanvasElement;
+    /** 贴到 PDF 页上的尺寸 mm */
+    widthMm: number;
+    heightMm: number;
+}
+export interface SliceOptions {
+    contentWmm: number;
+    contentHmm: number;
+    fitToWidth: boolean;
+    /** 非 fitToWidth 时的打印缩放(pageSetup.scale/100),默认 1 */
+    zoom?: number;
+    /** 打印标题行条(标题行 × 正文列),贴每页顶部 */
+    repeatTop?: {
+        canvas: HTMLCanvasElement;
+        heightCss: number;
+    };
+    /** 打印标题列条(标题列 × 正文行),贴每页左侧 */
+    repeatLeft?: {
+        canvas: HTMLCanvasElement;
+        widthCss: number;
+    };
+    /** 标题角(标题列 × 标题行),贴左上角 */
+    corner?: {
+        canvas: HTMLCanvasElement;
+    };
+}
+interface Band {
+    s: number;
+    len: number;
+}
+/** 把 total 像素按 bandSize 切成若干段(末段取余)。(导出供测) */
+export declare function makeBands(total: number, bandSize: number): Band[];
+export declare function sliceToPages(base: HTMLCanvasElement, bodyWcss: number, bodyHcss: number, page: SliceOptions): SlicedPage[];
+export {};

package/dist/core/export/pdf.d.ts

@@ -0,0 +1,28 @@
+import { PdfExportOptions } from './types';
+/** 一个待导出工作表的合成底图 */
+export interface ExportSheetImage {
+    /** 已合成(格子 + 图片/图表/形状)的底图,设备像素 */
+    canvas: HTMLCanvasElement;
+    /** 正文 css 宽高(zoom=1,不含表头) */
+    bodyWcss: number;
+    bodyHcss: number;
+    sheetName: string;
+    /** 打印标题: 每页顶部重复的标题行条(同 scale,等宽于 canvas) */
+    repeatTop?: {
+        canvas: HTMLCanvasElement;
+        heightCss: number;
+    };
+    /** 打印标题: 每页左侧重复的标题列条(同 scale,等高于 canvas) */
+    repeatLeft?: {
+        canvas: HTMLCanvasElement;
+        widthCss: number;
+    };
+    /** 标题角(标题列×标题行) */
+    corner?: {
+        canvas: HTMLCanvasElement;
+    };
+    /** 非 fitToWidth 时的打印缩放(pageSetup.scale/100) */
+    zoom?: number;
+}
+/** 生成 PDF,返回 Blob(不触发下载)。 */
+export declare function exportToPdf(sheets: ExportSheetImage[], opts?: PdfExportOptions): Promise<Blob>;

package/dist/core/export/print.d.ts

@@ -0,0 +1,3 @@
+import { PrintOptions } from './types';
+import { ExportSheetImage } from './pdf';
+export declare function printSheets(sheets: ExportSheetImage[], opts?: PrintOptions): void;

package/dist/core/export/raster.d.ts

@@ -0,0 +1,13 @@
+import { Margins, Orientation, PageFormat } from './types';
+export declare function canvasToBlob(canvas: HTMLCanvasElement, type?: string, quality?: number): Promise<Blob>;
+export declare function canvasToDataURL(canvas: HTMLCanvasElement, type?: string, quality?: number): string;
+/** 触发浏览器下载一个 Blob */
+export declare function downloadBlob(blob: Blob, fileName: string): void;
+/** 从 URL / blobURL / dataURL 加载为 HTMLImageElement(用于合成到导出底图) */
+export declare function loadImage(src: string): Promise<HTMLImageElement>;
+/** 解析纸张为 [宽, 高] mm,应用方向 */
+export declare function resolvePageSize(format?: PageFormat, orientation?: Orientation): [number, number];
+/** 归一化页边距(数字 → 四边;部分 → 补默认 10) */
+export declare function resolveMargins(margin: number | Partial<Margins> | undefined): Margins;
+/** css px → mm(按 96dpi) */
+export declare const MM_PER_PX: number;

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

@@ -0,0 +1,92 @@
+import { MergeRange } from '../model/types';
+/** 选哪些工作表导出 */
+export type ExportTarget = 'active' | 'all' | number | number[];
+/** 公共渲染选项(决定底图怎么画) */
+export interface RenderExportOptions {
+    /** 仅当导出单个工作表时生效: 限定单元格区域(0-based 闭区间) */
+    range?: MergeRange;
+    /** 设备像素缩放,越大越清晰(默认 2) */
+    scale?: number;
+    /** 含行号/列字母表头(默认 false,同 Excel 打印) */
+    includeHeaders?: boolean;
+    /** 覆盖网格线显隐(缺省跟随工作表设置) */
+    gridlines?: boolean;
+    /** 背景色(默认白) */
+    background?: string;
+}
+/** 图片导出选项 */
+export interface ImageExportOptions extends RenderExportOptions {
+    target?: ExportTarget;
+    /** 图片格式(默认 png) */
+    type?: 'png' | 'jpeg' | 'webp';
+    /** jpeg/webp 质量 0~1(默认 0.92) */
+    quality?: number;
+    /** 下载文件名(省略则用 "<表名>.png") */
+    fileName?: string;
+}
+export type PageFormat = 'a4' | 'a3' | 'letter' | [number, number];
+export type Orientation = 'portrait' | 'landscape';
+export interface Margins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+export interface PageSetup {
+    /** 纸张(默认 a4) */
+    format?: PageFormat;
+    /** 方向(默认 portrait) */
+    orientation?: Orientation;
+    /** 页边距 mm(数字=四边相同;默认 10) */
+    margin?: number | Partial<Margins>;
+    /** 把内容缩放到页宽(默认 true);false 则按自然尺寸,超宽会横向分页 */
+    fitToWidth?: boolean;
+}
+/** PDF 单页绘制上下文 —— 传给 beforeRenderPage 钩子(在页内容已贴图后调用) */
+export interface PdfPageContext {
+    /** jsPDF 实例(可调 doc.text / doc.setFontSize / doc.line 等画页眉页脚水印) */
+    doc: any;
+    /** 全局页序(0-based) */
+    pageIndex: number;
+    /** 全局总页数 */
+    pageCount: number;
+    /** 本页所属工作表名 */
+    sheetName: string;
+    /** 本页所属工作表在导出集合中的序(0-based) */
+    sheetIndex: number;
+    /** 整页尺寸 mm */
+    pageWidth: number;
+    pageHeight: number;
+    /** 页边距 mm */
+    margin: Margins;
+}
+export type BeforeRenderPage = (ctx: PdfPageContext) => void;
+/** PDF 导出选项 */
+export interface PdfExportOptions extends RenderExportOptions, PageSetup {
+    target?: ExportTarget;
+    /** 下载文件名(省略则用 "<文件名|workbook>.pdf") */
+    fileName?: string;
+    /** 每页贴图后调用,用于画页眉/页脚/水印/页码等(扩展点) */
+    beforeRenderPage?: BeforeRenderPage;
+    /**
+     * 矢量 PDF: 逐格用 jsPDF 真文字/矢量绘制(可选可搜、清晰、文件小)。
+     * 默认 false = 位图 PDF(整表贴图)。
+     */
+    vector?: boolean;
+    /**
+     * 矢量模式扩展钩子: 建好 jsPDF doc 后调用一次,宿主可在此 addFont 注册中文等字体。
+     *   configureDoc: (doc) => { doc.addFileToVFS('f.ttf', b64); doc.addFont('f.ttf','CN','normal'); doc.setFont('CN') }
+     * 注册了自定义字体 → 全矢量;否则非拉丁文本(中文)的单元格自动栅格兜底(不丢内容)。
+     */
+    configureDoc?: (doc: any) => void;
+}
+/** 打印选项 */
+export interface PrintOptions extends RenderExportOptions, PageSetup {
+    target?: ExportTarget;
+    /** 打印窗口标题 */
+    title?: string;
+    /** 每页顶部 HTML 片段(如公司抬头);出现在每个打印页 */
+    headerHtml?: string;
+    /** 每页底部 HTML 片段 */
+    footerHtml?: string;
+}

package/dist/core/export/vector-pdf.d.ts

@@ -0,0 +1,42 @@
+import { GridMetrics } from '../layout/grid-metrics';
+import { CellDrawInfo } from '../render/canvas-renderer';
+import { ImageAnchor, MergeRange } from '../model/types';
+import { PdfExportOptions } from './types';
+/** 一个待矢量导出的工作表 */
+export interface VectorSheet {
+    sheetName: string;
+    metrics: GridMetrics;
+    /** 正文列范围(0-based 闭区间,已剔除标题列) */
+    bodyLeft: number;
+    bodyRight: number;
+    /** 正文行范围(0-based 闭区间,已剔除标题行) */
+    bodyTop: number;
+    bodyBottom: number;
+    /** 打印标题行 [r0,r1](每页顶部重复) */
+    titleRows?: [number, number];
+    /** 打印标题列 [c0,c1](每页左侧重复) */
+    titleCols?: [number, number];
+    merges: MergeRange[];
+    gridlines: boolean;
+    /** 非 fitToWidth 时的打印缩放(pageSetup.scale/100) */
+    zoom?: number;
+    /** 取一个格的绘制信息 */
+    getCell: (row: number, col: number) => CellDrawInfo | null;
+    /** 栅格兜底底图: 覆盖 [rasterTop..bodyBottom] 行 × [rasterLeft..bodyRight] 列,设备像素 */
+    rasterCanvas: HTMLCanvasElement;
+    rasterScale: number;
+    rasterTop: number;
+    rasterLeft: number;
+    /** 图片/图表(已加载源 + 锚点),addImage 贴上 */
+    images: {
+        source: CanvasImageSource;
+        anchor: ImageAnchor;
+    }[];
+}
+/** 含非拉丁字符(粗略: 码点 > 0x250) → jsPDF 内置字体画不了,需栅格兜底。(导出供测) */
+export declare function hasNonLatin(s: string): boolean;
+/** "#RRGGBB" → [r,g,b];非法返回黑。(导出供测) */
+export declare function hexToRgb(hex: string): [number, number, number];
+export declare function exportToVectorPdf(sheets: VectorSheet[], opts?: PdfExportOptions): Promise<Blob>;
+/** 把一串索引按各自尺寸打包成多段(每段累计 ≤ maxMm;每段至少 1 个)。(导出供测) */
+export declare function packBands(indices: number[], sizeMm: (i: number) => number, maxMm: number): number[][];

package/dist/core/export/xlsx-writer.d.ts

@@ -0,0 +1,15 @@
+import { WorkbookModel } from '../model/types';
+export interface XlsxExportOptions {
+    /**
+     * 保真模式:
+     * - `'rebuild'`(默认):从编辑后模型完整重建(干净,但丢原件里我们不建模的部分:条件格式/数据验证/VBA…)。
+     * - `'overlay'`:重载原始 .xlsx,只把编辑后的 值/样式/合并/行高列宽/冻结 叠加上去,**保留** ExcelJS
+     *   能往返的其余部分(条件格式/数据验证/打印设置/定义名/图表等)。需 `sourceBuffer`(壳自动注入);
+     *   缺原件时自动回退 rebuild。注:overlay 不反映 结构增删行列 / 图片 编辑(那类用 rebuild)。
+     */
+    fidelity?: 'rebuild' | 'overlay';
+    /** 原始 .xlsx 字节(overlay 模式用;由 exporter 从 host 注入,用方一般不直接传) */
+    sourceBuffer?: ArrayBuffer;
+}
+/** WorkbookModel → .xlsx Blob(懒加载 exceljs)。overlay 模式重载原件叠加编辑,否则从模型重建。 */
+export declare function workbookToXlsxBlob(workbook: WorkbookModel, opts?: XlsxExportOptions): Promise<Blob>;

package/dist/core/finalize.d.ts

@@ -0,0 +1,10 @@
+import { WorkbookModel } from './model/types';
+/** 把解析层产出的图片字节转成 blob URL(只能在有 URL.createObjectURL 的主线程做) */
+export declare function finalizeImages(model: WorkbookModel): void;
+/** 释放之前 finalizeImages 生成的 blob URL,避免内存泄漏 */
+export declare function revokeImages(model: WorkbookModel): void;
+export type FormatKind = 'xlsx' | 'xls' | 'not-zip' | 'empty';
+/** 看文件头几个字节判断格式,在真正解析前就能给出友好提示 */
+export declare function detectFormat(buffer: ArrayBuffer): FormatKind;
+/** 把底层异常翻成用户能懂的话 */
+export declare function friendlyError(e: unknown): string;

package/dist/core/format/builtin-formats.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 内置数字格式 numFmtId → 格式代码字符串(ECMA-376 §18.8.30)。
+ * id 0-49 是保留内置格式；>=164 是自定义格式(从 styles.xml 的 numFmts 取)。
+ * 注: 14-22、45-47 等会随 locale 变，这里用通用形态。
+ */
+export declare const BUILTIN_FORMATS: Record<number, string>;
+export declare function builtinFormat(id: number): string | undefined;

package/dist/core/format/color.d.ts

@@ -0,0 +1,11 @@
+import { CssColor } from '../model/types';
+export declare function argbToCss(argb: string | undefined): CssColor | undefined;
+export declare function indexedToCss(idx: number): CssColor | undefined;
+/** 主题色 + tint → css。tint > 0 变亮，< 0 变暗(按 OOXML 规范的 HSL Luminance 调整)。 */
+export declare function themeToCss(themeColors: CssColor[], themeIdx: number, tint?: number): CssColor | undefined;
+export declare function applyTint(hexColor: CssColor, tint: number): CssColor;
+/**
+ * 统一入口: ExcelJS 风格的颜色对象 → css。
+ * 形如 { argb }, { theme, tint }, { indexed }。
+ */
+export declare function resolveColor(color: any, themeColors: CssColor[]): CssColor | undefined;

package/dist/core/format/date-serial.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Excel 日期序列号 ↔ JS Date。
+ *
+ * 1900 系统: 序列号 1 = 1900-01-01。但 Excel 误把 1900 当闰年(序列号 60 = 不存在的
+ * 1900-02-29)，这是为兼容 Lotus 1-2-3 故意保留的 bug。所以 >= 60 的序列号要减 1 天。
+ * 1904 系统(老 Mac): 序列号 0 = 1904-01-01，无闰年 bug。
+ */
+/** 序列号(可能带小数表示时间) → Date(UTC 基准，渲染按本地读字段) */
+export declare function serialToDate(serial: number, date1904?: boolean): Date;
+/** 取序列号的小数部分对应的一天内秒数(用于纯时间格式) */
+export declare function serialTimePart(serial: number): {
+    h: number;
+    m: number;
+    s: number;
+    frac: number;
+};

package/dist/core/format/number-format.d.ts

@@ -0,0 +1,5 @@
+export interface FormatResult {
+    text: string;
+    color?: string;
+}
+export declare function formatValue(value: number | string | boolean | Date | null, code: string | undefined, date1904?: boolean): FormatResult;