ooxml-excel-editor 1.1.0

package/dist/core/formula/engine.d.ts

@@ -0,0 +1,27 @@
+import { CellModel, WorkbookModel } from '../model/types';
+import { CellValue } from '../model/data-access';
+/** 一个被引擎判定为"值变了"的格(含算出的新值)。sheet = 0-based 工作表索引。 */
+export interface DirtyCell {
+    sheet: number;
+    row: number;
+    col: number;
+    value: CellValue;
+}
+export interface FormulaEngine {
+    /** 用整个工作簿(全表,供跨表引用)初始化引擎。 */
+    setSheets(wb: WorkbookModel): void;
+    /** 设一个格的内容(公式串 '=...' 或字面值或 null),返回所有受影响格(含依赖级联)。 */
+    setCell(sheet: number, row: number, col: number, content: string | number | boolean | null): DirtyCell[];
+    /** 读一个格的当前计算值。 */
+    getValue(sheet: number, row: number, col: number): CellValue;
+    /** 释放引擎资源。 */
+    destroy(): void;
+}
+/** 引擎工厂:异步(默认适配器懒 import hyperformula);用方可注入。 */
+export type FormulaEngineFactory = () => Promise<FormulaEngine>;
+/**
+ * 取一个格喂给引擎的内容:公式格 → 公式文本(A1 串);值格 → 字面值;空/日期 → 见下。
+ * 日期暂以 null 入引擎(v1 不支持公式引用日期格运算,避免类型不匹配;后续可换 Excel 序列号)。
+ */
+export declare function cellContentForEngine(cell: CellModel | null): string | number | boolean | null;
+export type { CellValue };

package/dist/core/formula/hyperformula-adapter.d.ts

@@ -0,0 +1,3 @@
+import { FormulaEngineFactory } from './engine';
+/** 默认引擎工厂:动态 import hyperformula(不进 core 产物)。装了才用,没装则 import 抛错由调用方兜底。 */
+export declare const defaultFormulaEngineFactory: FormulaEngineFactory;

package/dist/core/formula/recalc.d.ts

@@ -0,0 +1,9 @@
+import { WorkbookModel } from '../model/types';
+import { DirtyCell, FormulaEngine } from './engine';
+import { CellPos } from '../edit/commands';
+/** 把 editedCells 同步进引擎,收集所有受影响格(含跨表依赖),**不写模型**。 */
+export declare function collectDirty(engine: FormulaEngine, wb: WorkbookModel, activeSheet: number, editedCells: CellPos[]): DirtyCell[];
+/** 把脏格的计算值写回各自模型表(只改 raw)。 */
+export declare function writeDirty(wb: WorkbookModel, dirty: DirtyCell[]): void;
+/** 活动表上、由级联产生(非直接编辑)的脏格 —— 供逐格发 cell-change。 */
+export declare function dependentsOnSheet(dirty: DirtyCell[], activeSheet: number, editedCells: CellPos[]): CellPos[];

package/dist/core/formula/refs.d.ts

@@ -0,0 +1,21 @@
+import { WorkbookModel } from '../model/types';
+import { StructOp } from '../model/structure';
+export type ShiftAxis = 'row' | 'col';
+export interface ShiftSpec {
+    axis: ShiftAxis;
+    /** 0-based 模型索引:插入/删除发生的位置 */
+    at: number;
+    count: number;
+    mode: 'insert' | 'delete';
+    /** 结构操作发生在哪张表(名);仅指向它的引用才重写 */
+    targetSheet: string;
+    /** 该公式所在表(名);无 `Sheet!` 限定的引用归属它 */
+    formulaSheet: string;
+}
+/** 重写一条公式串里所有指向 targetSheet 的引用以适配增删行列。前导 `=` 原样保留。 */
+export declare function shiftFormulaRefs(formula: string, spec: ShiftSpec): string;
+/**
+ * 增删行列后,重写**全簿**所有公式格里指向 targetSheet 的引用(含跨表 `Sheet!A1`)。
+ * 就地改 cell.formula;撤销由结构命令的整簿快照负责。
+ */
+export declare function rewriteWorkbookFormulas(wb: WorkbookModel, targetSheetIdx: number, op: StructOp, at: number, count: number): void;

package/dist/core/index.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 框架无关 core 入口(供 'ooxml-excel-editor/core' 及 Vue / React 壳复用)。
+ * 这里只暴露引擎 + 解析 + 数据 + 类型,零框架依赖 —— Vue/React 各自的壳在上层包。
+ */
+export { parseWorkbook } from './parser';
+export { loadArrayBuffer } from './loader';
+export type { ExcelSource } from './loader';
+export { detectFormat, finalizeImages, friendlyError, revokeImages } from './finalize';
+export type { ParseProgress } from './progress';
+export { cellDisplayText, getCell, getCellValue, getCellStyle, getCellText, getSheetData, getRangeData, sheetToJSON, getWorkbookJSON, } from './model/data-access';
+export type { CellValue, ReadOptions, SheetToJSONOptions } from './model/data-access';
+export { cellKey } from './model/types';
+export type { WorkbookModel, SheetModel, CellModel, CellStyle, MergeRange, ConditionalRule, ChartSpec, ImageAnchor, ShapeSpec, Sparkline, CssColor, TransformModelFn, CellStyleFn, CellStyleOverride, } from './model/types';
+export { CanvasRenderer } from './render/canvas-renderer';
+export type { ViewState, RendererOptions } from './render/canvas-renderer';
+export { ViewerController } from './viewer/controller';
+export type { Cell, TooltipState, FindState, FilterPopupState, ViewerControllerEls, ViewerControllerHooks, } from './viewer/controller';
+export { OverlayManager } from './viewer/overlay-manager';
+export type { OverlayQuads } from './viewer/overlay-manager';
+export { PluginOverlayHost } from './viewer/plugin-overlay';
+export { resolveEditable } from './edit/permissions';
+export type { EditConfig, EditPermission } from './edit/types';
+export { EditController } from './edit/edit-controller';
+export type { EditControllerHost, EditEventName, EditSource, CellChangePayload, DimChangePayload, DirtyChangePayload, ImageChangePayload, StructChangePayload, } from './edit/edit-controller';
+export { isDimCommand, isImageCommand, isStructCommand } from './edit/commands';
+export type { EditCommand, CellPos, DimAxis } from './edit/commands';
+export { insertRows, deleteRows, insertCols, deleteCols, captureStructure, restoreStructure, deleteIntersectsMerge, } from './model/structure';
+export type { StructOp, StructSnapshot } from './model/structure';
+export { toCsv, toWorkbookJson } from './export/data-export';
+export { workbookToXlsxBlob } from './export/xlsx-writer';
+export type { XlsxExportOptions } from './export/xlsx-writer';
+export { buildCellSnapshot, cloneCell } from './model/snapshot';
+export type { CellSnapshot } from './model/snapshot';
+export { setCellValue, clearCell, setRangeValues, restoreCell, internStyle, setColumnWidth, setRowHeight, restoreDimension, applyStyleOverride, mergeStyleOverride, addImage, removeImage, setImageRect, cloneImageAnchor, } from './model/mutations';
+export { cloneWorkbook, restoreWorkbookInto } from './model/clone';
+export { cellContentForEngine } from './formula/engine';
+export type { FormulaEngine, FormulaEngineFactory, DirtyCell } from './formula/engine';
+export { defaultFormulaEngineFactory } from './formula/hyperformula-adapter';
+export { shiftFormulaRefs, rewriteWorkbookFormulas } from './formula/refs';
+export type { ShiftSpec, ShiftAxis } from './formula/refs';
+export { CellEditorHost } from './edit/editor-host';
+export type { CellEditorContext, CellEditorFactory, EditorResolver, EditorCommitValue } from './edit/editor-context';
+export { definePlugin } from './plugin';
+export type { ExcelPlugin, ExcelPluginContext, OverlayContext, OverlayNode, PluginEvent, Rect, ToolbarItem, ViewerApi, } from './plugin';
+export { GridMetrics, colIndexToLetters } from './layout/grid-metrics';
+export { formatValue } from './format/number-format';
+export { DEFAULT_THEME, mergeTheme } from './render/theme';
+export type { ViewerTheme } from './render/theme';
+export { WorkbookExporter } from './export/exporter';
+export type { ExporterHost } from './export/exporter';
+export { canvasToBlob, canvasToDataURL, downloadBlob } from './export/raster';
+export type { ExportTarget, RenderExportOptions, ImageExportOptions, PdfExportOptions, PrintOptions, PageSetup, PageFormat, Orientation, Margins, PdfPageContext, BeforeRenderPage, } from './export/types';

package/dist/core/layout/autofit.d.ts

@@ -0,0 +1,2 @@
+import { SheetModel, WorkbookModel } from '../model/types';
+export declare function autoFitRowHeights(sheet: SheetModel, workbook: WorkbookModel, ctx?: CanvasRenderingContext2D): void;

package/dist/core/layout/freeze.d.ts

@@ -0,0 +1,11 @@
+import { SheetModel } from '../model/types';
+import { GridMetrics } from './grid-metrics';
+export interface FreezeGeometry {
+    frozenRows: number;
+    frozenCols: number;
+    /** 冻结列总宽 px(网格坐标) */
+    frozenWidth: number;
+    /** 冻结行总高 px */
+    frozenHeight: number;
+}
+export declare function computeFreeze(sheet: SheetModel, metrics: GridMetrics): FreezeGeometry;

package/dist/core/layout/grid-metrics.d.ts

@@ -0,0 +1,37 @@
+import { SheetModel } from '../model/types';
+export declare class GridMetrics {
+    private sheet;
+    readonly cols: number;
+    readonly rows: number;
+    /** 行表头(显示行号)宽度 px */
+    readonly rowHeaderWidth: number;
+    /** 列表头(显示列字母)高度 px */
+    readonly colHeaderHeight: number;
+    private colLefts;
+    private rowTops;
+    private colWidths;
+    private rowHeights;
+    /** 当前缩放比例(几何与字体同步按它缩放，保证缩放后排版一致) */
+    readonly zoom: number;
+    constructor(sheet: SheetModel, zoom?: number);
+    colWidth(c: number): number;
+    rowHeight(r: number): number;
+    private get dcw();
+    private get drh();
+    /** 第 c 列左边缘(网格坐标，不含表头)。超出数据范围按默认列宽外推(模拟 Excel 无限网格)。 */
+    colLeft(c: number): number;
+    rowTop(r: number): number;
+    get totalWidth(): number;
+    get totalHeight(): number;
+    /** 给定网格 x 坐标，返回所在列。超出数据范围按默认列宽外推。 */
+    colAt(x: number): number;
+    rowAt(y: number): number;
+    /** 数据单元格的可视区列区间(end 限制在数据范围内，避免画空 cell) */
+    visibleColRange(scrollX: number, viewW: number): [number, number];
+    visibleRowRange(scrollY: number, viewH: number): [number, number];
+    /** 网格线/表头的可视区列区间(可超出数据范围，铺满视口，模拟 Excel) */
+    gridColRange(scrollX: number, viewW: number): [number, number];
+    gridRowRange(scrollY: number, viewH: number): [number, number];
+}
+/** 0-based 列号 → Excel 列字母(A, B, ..., Z, AA, ...) */
+export declare function colIndexToLetters(index: number): string;

package/dist/core/layout/merges.d.ts

@@ -0,0 +1,14 @@
+import { MergeRange, SheetModel } from '../model/types';
+export declare class MergeIndex {
+    /** key `${row}:${col}` → 该 cell 所属的合并区(任意成员都能查到) */
+    private map;
+    /** 锚点(左上角) key 集合 */
+    private anchors;
+    constructor(sheet: SheetModel);
+    /** 该 cell 所在的合并区(没有返回 undefined) */
+    rangeOf(row: number, col: number): MergeRange | undefined;
+    /** 是否合并区锚点(左上角，渲染内容的那个) */
+    isAnchor(row: number, col: number): boolean;
+    /** 是否被合并覆盖但不是锚点(渲染时跳过内容) */
+    isCovered(row: number, col: number): boolean;
+}

package/dist/core/layout/units.d.ts

@@ -0,0 +1,20 @@
+/** OOXML 单位换算常量与函数。 */
+/** 默认字体(Calibri 11)的最大数字宽度，单位 px。Excel 列宽换算的基准。 */
+export declare const DEFAULT_MDW = 7;
+/** 屏幕 DPI / 印刷 DPI */
+export declare const PX_PER_POINT: number;
+/** 1 px = 9525 EMU (914400 EMU/inch ÷ 96 px/inch) */
+export declare const EMU_PER_PX = 9525;
+export declare const DEFAULT_COL_WIDTH_CHARS = 8.43;
+export declare const DEFAULT_ROW_HEIGHT_PT = 15;
+/**
+ * Excel 列宽(字符数) → 像素。
+ * px = Truncate(width * MDW + 0.5) + 5
+ * 末尾 +5 是单元格内边距(左右各 2px + 1px 网格线)。这是 Excel 实际渲染宽度,
+ * 早期只用 Truncate(width*MDW) 会每列偏窄 5px(默认 8.43 → 64px 才对)。
+ */
+export declare function colWidthToPx(chars: number, mdw?: number): number;
+/** 行高(pt) → 像素 */
+export declare function rowHeightToPx(pt: number): number;
+export declare function emuToPx(emu: number): number;
+export declare function pxToEmu(px: number): number;

package/dist/core/layout/viewport.d.ts

@@ -0,0 +1,29 @@
+import { GridMetrics } from './grid-metrics';
+import { FreezeGeometry } from './freeze';
+export interface Pane {
+    /** 屏幕坐标裁剪区(含表头偏移之后) */
+    clipX: number;
+    clipY: number;
+    clipW: number;
+    clipH: number;
+    /** 该 pane 绘制内容时减去的滚动量(冻结区为 0) */
+    offsetX: number;
+    offsetY: number;
+    /** 行列区间 [startCol,endCol] / [startRow,endRow] */
+    colStart: number;
+    colEnd: number;
+    rowStart: number;
+    rowEnd: number;
+}
+export interface ViewportLayout {
+    panes: Pane[];
+    rowHeaderWidth: number;
+    colHeaderHeight: number;
+}
+/**
+ * @param scrollX 可滚动区横向滚动量
+ * @param scrollY 可滚动区纵向滚动量
+ * @param viewW   画布 css 宽
+ * @param viewH   画布 css 高
+ */
+export declare function computeViewport(metrics: GridMetrics, freeze: FreezeGeometry, scrollX: number, scrollY: number, viewW: number, viewH: number): ViewportLayout;

package/dist/core/loader.d.ts

@@ -0,0 +1,5 @@
+/** 把多种输入归一化成 ArrayBuffer,供解析层使用。可选 onProgress 报字节读取进度。 */
+export type ExcelSource = File | Blob | ArrayBuffer | Uint8Array | string;
+/** 读取进度回调: loaded/total 字节(total 为 0 表示未知) */
+export type ReadProgressFn = (loaded: number, total: number) => void;
+export declare function loadArrayBuffer(src: ExcelSource, onProgress?: ReadProgressFn): Promise<ArrayBuffer>;

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

@@ -0,0 +1,9 @@
+import { WorkbookModel } from './types';
+/** 深克隆整个工作簿(供 editable 时懒捕获 baseline)。 */
+export declare function cloneWorkbook(wb: WorkbookModel): WorkbookModel;
+/**
+ * 把 baseline(snap)的内容就地还原进 live(不换 live / live.sheets / 各 sheet 的对象身份)。
+ * 每次都对 snap 取一份新克隆,故 baseline 自身保持原始、可重复还原。
+ * 约定:editing 期间不增删 sheet,故按 index 对齐;多出的 live sheet 不动。
+ */
+export declare function restoreWorkbookInto(live: WorkbookModel, snap: WorkbookModel): void;

package/dist/core/model/data-access.d.ts

@@ -0,0 +1,30 @@
+import { CellModel, CellStyle, MergeRange, SheetModel, WorkbookModel } from './types';
+export type CellValue = number | string | boolean | Date | null;
+export interface ReadOptions {
+    /** true(默认)=格式化显示文本;false=原始值 */
+    format?: boolean;
+    /** 1904 日期系统(组件 ref 方法会自动带上;独立调用时从 workbook.date1904 取) */
+    date1904?: boolean;
+}
+/** 单元格显示文本(套数字/日期格式;富文本拼接)。纯函数,渲染器与数据 API 共用。 */
+export declare function cellDisplayText(cell: CellModel | undefined, style: CellStyle | undefined, date1904: boolean): string;
+/** 取单元格模型(Map 之上的便捷封装) */
+export declare function getCell(sheet: SheetModel, row: number, col: number): CellModel | undefined;
+/** 取单元格原始值(number/boolean/Date/string/null) */
+export declare function getCellValue(sheet: SheetModel, row: number, col: number): CellValue;
+/** 取单元格解析后的样式(经 styleId);无则 undefined */
+export declare function getCellStyle(sheet: SheetModel, row: number, col: number): CellStyle | undefined;
+/** 取单元格格式化显示文本 */
+export declare function getCellText(sheet: SheetModel, row: number, col: number, date1904?: boolean): string;
+/** 整表 → 稠密二维数组(dimension.rows × dimension.cols)。空格为 ''(文本)/ null(值)。 */
+export declare function getSheetData(sheet: SheetModel, opts?: ReadOptions): CellValue[][];
+/** 区域 → 二维数组(行×列,0-based 闭区间) */
+export declare function getRangeData(sheet: SheetModel, range: MergeRange, opts?: ReadOptions): CellValue[][];
+export interface SheetToJSONOptions extends ReadOptions {
+    /** 表头所在行(0-based,默认 0);数据从其下一行起 */
+    headerRow?: number;
+}
+/** 整表 → 对象数组(首行作 key)。空表头回退列字母;整行皆空则跳过。 */
+export declare function sheetToJSON(sheet: SheetModel, opts?: SheetToJSONOptions): Record<string, CellValue>[];
+/** 全簿 → { 表名: 对象数组 }(可见表;自动用 workbook.date1904) */
+export declare function getWorkbookJSON(workbook: WorkbookModel, opts?: SheetToJSONOptions): Record<string, Record<string, CellValue>[]>;

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

@@ -0,0 +1,46 @@
+import { CellModel, CellStyle, CellStyleOverride, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel } from './types';
+import { CellValue } from './data-access';
+/** 设单元格值。返回旧 CellModel(克隆,供 undo);新值为空则删除该格。 */
+export declare function setCellValue(sheet: SheetModel, row: number, col: number, value: CellValue): void;
+/** 清空单元格(删除该格,保留 dimension)。 */
+export declare function clearCell(sheet: SheetModel, row: number, col: number): void;
+/** 区域批量设值(2D,左上对齐 range.top/left)。 */
+export declare function setRangeValues(sheet: SheetModel, range: MergeRange, values: CellValue[][]): void;
+/**
+ * 写回公式引擎算出的结果(只改 raw,保留 formula/type/styleId/rich)。
+ * 公式格:raw = 计算值(显示用 raw);被公式引用的值格:不变(raw 已是其值)。空格跳过。
+ */
+export declare function setCellComputed(sheet: SheetModel, row: number, col: number, value: CellValue): void;
+/** 直接写回/删除一个格的底层 CellModel(命令逆向用:精确还原前态)。 */
+export declare function restoreCell(sheet: SheetModel, row: number, col: number, cell: CellModel | null): void;
+/** 设列宽(px,非缩放存储);保留 hidden。 */
+export declare function setColumnWidth(sheet: SheetModel, col: number, width: number): void;
+/** 设行高(px,非缩放存储);保留 hidden。 */
+export declare function setRowHeight(sheet: SheetModel, row: number, height: number): void;
+/** 浅克隆 ImageAnchor(共享不可变的 bytes/src,省内存;命令逆向 / 拖拽起始态用)。 */
+export declare function cloneImageAnchor(a: ImageAnchor): ImageAnchor;
+/** 加一张图(index 缺省追加到末尾),返回插入位置。 */
+export declare function addImage(sheet: SheetModel, anchor: ImageAnchor, index?: number): number;
+/** 删一张图(调用方负责为 undo 捕获前态)。 */
+export declare function removeImage(sheet: SheetModel, index: number): void;
+/**
+ * 设图片的内容矩形(zoom 后像素,content 坐标)→ 规整为原点相对 oneCellAnchor。
+ * 像素↔EMU:left_px = emuToPx(colOffEmu)*zoom ⇒ colOffEmu = pxToEmu(left/zoom)。不依赖列/行几何。
+ */
+export declare function setImageRect(sheet: SheetModel, index: number, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, zoom: number): void;
+/** 直接写回/删除一个列/行的维度信息(命令逆向用:精确还原前态;null=删 Map 项回落默认宽高)。 */
+export declare function restoreDimension(sheet: SheetModel, axis: 'col' | 'row', index: number, info: ColumnInfo | RowInfo | null): void;
+/** 样式去重入表,返回 styleId(E5 样式编辑用;深比较已存在则复用)。 */
+export declare function internStyle(sheet: SheetModel, style: CellStyle): number;
+/** 合并样式覆盖到完整样式: font/fill/borders 浅合并,其余字段覆盖(单一真相源,渲染与编辑共用)。 */
+export declare function mergeStyleOverride(base: CellStyle, over: CellStyleOverride): CellStyle;
+/**
+ * 给一个格套样式覆盖(E5):取基样式 → 合并 → intern → 改 styleId。
+ * 空格(不在 Map)→ 以默认样式为基,新建一个 type='empty' 的格承载 styleId(像 Excel 给空格上色)。
+ */
+export declare function applyStyleOverride(sheet: SheetModel, row: number, col: number, patch: CellStyleOverride): void;

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

@@ -0,0 +1,14 @@
+import { CellModel, CellStyle, SheetModel } from './types';
+import { CellValue } from './data-access';
+export interface CellSnapshot {
+    row: number;
+    col: number;
+    cell: CellModel | null;
+    style: CellStyle | undefined;
+    raw: CellValue;
+    computed: CellValue;
+    text: string;
+}
+/** 深克隆 CellModel(raw 的 Date / rich 数组都拷,避免前后快照共享引用) */
+export declare function cloneCell(c: CellModel): CellModel;
+export declare function buildCellSnapshot(sheet: SheetModel, row: number, col: number, date1904: boolean): CellSnapshot;

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

@@ -0,0 +1,26 @@
+import { CellModel, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel } from './types';
+export type StructOp = 'insert-rows' | 'delete-rows' | 'insert-cols' | 'delete-cols';
+/** 整张表结构状态快照(供撤销整体还原) */
+export interface StructSnapshot {
+    cells: Map<string, CellModel>;
+    merges: MergeRange[];
+    rows: Map<number, RowInfo>;
+    columns: Map<number, ColumnInfo>;
+    images: ImageAnchor[];
+    dimension: {
+        rows: number;
+        cols: number;
+    };
+}
+/** 拍快照(深克隆;images 浅克隆共享 bytes)。 */
+export declare function captureStructure(sheet: SheetModel): StructSnapshot;
+/** 把快照就地还原进 sheet(替换其集合引用,保 sheet 对象身份;再克隆一份保快照可重复用)。 */
+export declare function restoreStructure(sheet: SheetModel, snap: StructSnapshot): void;
+export declare function insertRows(sheet: SheetModel, at: number, count: number): void;
+export declare function deleteRows(sheet: SheetModel, at: number, count: number): void;
+export declare function insertCols(sheet: SheetModel, at: number, count: number): void;
+export declare function deleteCols(sheet: SheetModel, at: number, count: number): void;
+/** 应用一个结构操作(分发)。 */
+export declare function applyStructOp(sheet: SheetModel, op: StructOp, at: number, count: number): void;
+/** 删除段是否与任一合并区相交(controller 据此给"会丢合并"警告,仿 sortColumn 守卫)。 */
+export declare function deleteIntersectsMerge(sheet: SheetModel, op: 'delete-rows' | 'delete-cols', at: number, count: number): boolean;