ooxml-excel-editor 1.1.0 → 1.2.0

package/dist/react/ExcelViewer.d.ts

@@ -1,8 +1,12 @@
 import { CSSProperties } from 'react';
 import { CellModel, CellStyleFn, CellStyleOverride, ImageAnchor, MergeRange, TransformModelFn, WorkbookModel } from '../core/model/types';
+import { EditableTarget } from '../core/edit/types';
 import { FormulaEngineFactory } from '../core/formula/engine';
 import { CellChangePayload, DimChangePayload, DirtyChangePayload, ImageChangePayload, StructChangePayload } from '../core/edit/edit-controller';
 import { CellSnapshot } from '../core/model/snapshot';
+import { CellInspection } from '../core/model/inspect';
+import { JsonInput, JsonLoadOptions } from '../core/loader-json';
+import { ExportProgress } from '../core/progress';
 import { CellValue, getCellValue, getSheetData, getRangeData, sheetToJSON, ReadOptions, SheetToJSONOptions } from '../core/model/data-access';
 import { EditorResolver } from '../core/edit/editor-context';
 import { ViewerTheme } from '../core/render/theme';
@@ -10,15 +14,60 @@ import { ExcelSource } from '../core/loader';
 import { ImageExportOptions, PdfExportOptions, PrintOptions } from '../core/export';
 import { XlsxExportOptions } from '../core/export/xlsx-writer';
 import { Cell } from '../core/viewer/controller';
-import { ExcelPlugin } from '../core/plugin';
+import { ContextMenuBeforePayload, ContextMenuShowPayload, ContextMenuTransform, ExcelPlugin, MenuItem, PermissionDeniedPayload } from '../core/plugin';
 export interface ExcelViewerProps {
     src?: ExcelSource;
+    /**
+     * 直接喂 WorkbookModel 或 JsonInput(P3):绕过 parser。优先级 workbook > src。
+     * WorkbookModel 直用;JsonInput(二维数组 / 对象数组 / `{sheets:[...]}`)走 jsonToWorkbook。
+     */
+    workbook?: WorkbookModel | JsonInput;
+    /** JSON 直渲选项(workbook = JsonInput 时生效) */
+    jsonOptions?: JsonLoadOptions;
+    /**
+     * 渲染模板(P3 重设计 2026-06-08):一份 .xlsx 当**样式捐赠者** —— 模板的 styling
+     * (styles / merges / 列宽 / 行高 / freeze / theme)套到无格式数据源上,模板的 raw 文字 / 占位符 /
+     * 图 / 图表 / 条件格式 全部丢弃。
+     *
+     * ⚠️ **只在数据源是 `workbook`(JSON / 模型)时生效**;`src`(.xlsx)数据源自带格式,
+     * 给 `templateFile` 会被忽略并 console.warn.
+     */
+    templateFile?: ExcelSource;
+    /** 模板显示名(标题栏 `· 模板: xxx` 后缀);不给则取运行时 File.name */
+    templateName?: string;
+    /**
+     * 内置导出进度遮罩(P1.5):默认 `true` —— 调 `viewer.downloadPdf/exportImage/...` /
+     * 选区图片批量转换 时,壳自动建 AbortController + 接 onProgress → 显示居中模态 + 取消。
+     * `false` 关闭(走纯回调);`renderExportProgress` 自渲染(覆盖内置 UI)。
+     */
+    exportProgress?: boolean;
+    /** 完全自渲染遮罩:返回任意 ReactNode 替代内置 UI。`exportProgress=false` 时此项也不渲染。 */
+    renderExportProgress?: (ctx: {
+        state: ExportProgress | null;
+        busy: boolean;
+        cancel: () => void;
+    }) => React.ReactNode;
+    /**
+     * 右键菜单(Plan C):
+     * - `false` → 不弹内置菜单(`onBeforeContextMenu` / `onContextMenuShow` 仍触发,壳可自渲染)
+     * - 函数 `(ctx, items) => MenuItem[] | undefined` → 在内置 items 上加 / 减 / 重排;返 undefined 不动
+     * - 不传(默认)→ editable 时显示内置菜单,非 editable 走浏览器默认
+     */
+    contextMenu?: boolean | ContextMenuTransform;
+    /** 右键菜单触发前:`payload.preventDefault()` 阻止内置菜单(自渲染替代) */
+    onBeforeContextMenu?: (payload: ContextMenuBeforePayload) => void;
+    /** 右键菜单展示通知:无论内置是否弹都触发,供自渲染或事件流串到业务 */
+    onContextMenuShow?: (payload: ContextMenuShowPayload) => void;
     fileName?: string;
     theme?: Partial<ViewerTheme>;
     /** 单击超链接是否自动打开(默认 true) */
     openLinks?: boolean;
     transformModel?: TransformModelFn;
     cellStyle?: CellStyleFn;
+    /** WPS 单元格内嵌图(DISPIMG)贴合方式:contain 等比(默认,与 WPS 渲染一致)/ fill 拉伸铺满 / cover 等比裁剪 */
+    cellImageFit?: 'fill' | 'contain' | 'cover';
+    /** 图片点击放大灯箱(默认 true):只读模式单击图放大、编辑模式右键「查看大图」;false 关闭 */
+    imageLightbox?: boolean;
     /** 插件(与 Vue 通用):theme/transformModel/cellStyle/events/overlay/setup 全跨框架可用 */
     plugins?: ExcelPlugin[];
     /** 编辑总开关:默认 false = 只读(行为不变)。开启后才能进入编辑(E0:闸门) */
@@ -30,6 +79,23 @@ export interface ExcelViewerProps {
     }) => boolean | void;
     /** 只读区域(0-based 闭区间);命中即只读 */
     readOnlyRanges?: MergeRange[];
+    /**
+     * **可编辑白名单**(2026-06-08 新增):设了就是白名单语义,只命中**任一** target 的格才可编辑.
+     * 4 种 target 形状自动识别:`{row,col}` 单格 / `{row}` 整行 / `{col}` 整列 / `MergeRange` 矩形.
+     * 单值或数组都支持;允许**不相邻**多 target. `undefined`=默认全可编辑(老行为),`[]`=全只读.
+     */
+    editableTargets?: EditableTarget | EditableTarget[];
+    /**
+     * **严格尺寸闸门**(Phase B, 2026-06-08) —— 默认 `false`: 尺寸 API 仅受全局 editable 控制. 设 `true` +
+     * editableTargets 启用了 → 该列/行至少有 1 格在白名单内才能改尺寸.
+     */
+    strictDimensions?: boolean;
+    /**
+     * **只读单元格视觉钩子** (Phase C, 2026-06-08):
+     * `false`(默认) 无视觉差异;`true` 内置浅灰底 `#f5f7fa`;`CellStyleOverride` 固定样式;`CellStyleFn` 按格自定义.
+     * 跟 editableTargets 配合 → 白名单外的格自动套此视觉.
+     */
+    readOnlyCellStyle?: boolean | CellStyleOverride | CellStyleFn;
     /** 自定义单元格编辑器(按格返回工厂;覆盖插件 editor)。需 editable 开启 */
     editor?: EditorResolver;
     /** 公式重算(E4):默认 false 沿用缓存值。开启后编辑公式/被引用格 → 依赖格自动重算。需 editable */
@@ -74,6 +140,8 @@ export interface ExcelViewerProps {
     onImageChange?: (p: ImageChangePayload) => void;
     /** 行列结构变更(增删行列) */
     onStructChange?: (p: StructChangePayload) => void;
+    /** 权限拒绝(Phase A, 2026-06-08):粘贴/合并/图片落点等命中只读 → 默认 skip + 此事件通知 */
+    onPermissionDenied?: (p: PermissionDeniedPayload) => void;
 }
 /** 命令式句柄(与 Vue ref / ViewerApi 对齐) */
 export interface ExcelViewerHandle {
@@ -97,15 +165,69 @@ export interface ExcelViewerHandle {
     } | null;
     redraw: () => void;
     isCellEditable: (row: number, col: number) => boolean;
+    setEditableTargets: (targets: EditableTarget | EditableTarget[] | undefined) => void;
+    getEditableTargets: () => EditableTarget | EditableTarget[] | undefined;
     editCell: (row: number, col: number, value: CellValue) => boolean;
     editRange: (range: MergeRange, values: CellValue[][]) => boolean;
     clearRange: (range: MergeRange) => boolean;
     setStyle: (range: MergeRange, patch: CellStyleOverride) => boolean;
+    getActiveFillColor: () => string;
+    getActiveFontColor: () => string;
+    setSelectionFill: (color: string | null) => boolean;
+    setSelectionFontColor: (color: string) => boolean;
+    getSelectionWrapState: () => 'all' | 'none' | 'mixed';
+    toggleWrapTextOnSelection: () => boolean;
+    mergeCells: (range: MergeRange) => boolean;
+    unmergeCells: (range: MergeRange) => boolean;
+    pasteText: (text: string, at?: {
+        row: number;
+        col: number;
+    }) => boolean;
+    pasteRichHtml: (html: string, at?: {
+        row: number;
+        col: number;
+    }) => boolean;
+    pasteImageBlob: (blob: Blob, at?: {
+        row: number;
+        col: number;
+    }) => Promise<boolean>;
     getImages: () => ImageAnchor[];
     addImage: (anchor: ImageAnchor) => number;
     removeImage: (index: number) => boolean;
     moveImage: (index: number, dxPx: number, dyPx: number) => boolean;
     resizeImage: (index: number, widthPx: number, heightPx: number) => boolean;
+    getCellImages: () => {
+        id: string;
+        src: string;
+        mime?: string;
+    }[];
+    getCellImageAt: (row: number, col: number) => {
+        id: string;
+        src: string;
+        mime?: string;
+    } | null;
+    openImageLightbox: (src: string, fileName?: string, mime?: string) => void;
+    /** 活动格在公式栏里的可编辑字符串(公式→=…,数值→原始数字串) */
+    getCellEditString: () => string;
+    /** 活动格此刻是否可经公式栏编辑(editable + 非只读) */
+    canEditActiveCell: () => boolean;
+    /** 经公式栏提交活动格的值(move='down' 提交后下移) */
+    commitActiveCellValue: (value: string, move?: 'down') => boolean;
+    setCellImageFit: (fit: 'fill' | 'contain' | 'cover') => void;
+    convertImageToCell: (imageIndex: number, row: number, col: number) => boolean;
+    convertImageToCellAuto: (imageIndex: number) => boolean;
+    convertAllImagesToCells: (col?: number) => number;
+    convertImagesInRangeToCell: (range: MergeRange) => Promise<number>;
+    convertCellImagesInRangeToFloat: (range: MergeRange, size?: {
+        width: number;
+        height: number;
+    }) => Promise<number>;
+    openContextMenu: (x: number, y: number, items?: MenuItem[]) => void;
+    closeContextMenu: () => void;
+    convertCellImageToFloat: (row: number, col: number, size?: {
+        width: number;
+        height: number;
+    }) => boolean;
     insertRows: (at: number, count?: number) => boolean;
     deleteRows: (at: number, count?: number) => boolean;
     insertCols: (at: number, count?: number) => boolean;
@@ -119,12 +241,21 @@ export interface ExcelViewerHandle {
         col: number;
     } | null;
     getCellSnapshot: (row: number, col: number) => CellSnapshot | null;
+    inspectCell: (row: number, col: number) => CellInspection | null;
     beginEdit: (row: number, col: number) => boolean;
     cancelEdit: () => void;
     isEditing: () => boolean;
-    setColumnWidth: (col: number, width: number) => boolean;
-    setRowHeight: (row: number, height: number) => boolean;
+    setColumnWidth: (target: import('../core/edit/types').DimTarget, width: number) => number;
+    setRowHeight: (target: import('../core/edit/types').DimTarget, height: number) => number;
+    autoFitColumns: (target?: import('../core/edit/types').DimTarget) => number;
+    autoFitRows: (target?: import('../core/edit/types').DimTarget) => number;
+    resetColumnWidth: (target: import('../core/edit/types').DimTarget) => number;
+    resetRowHeight: (target: import('../core/edit/types').DimTarget) => number;
     isRecalcReady: () => boolean;
+    getVirtualExtent: () => {
+        rows: number;
+        cols: number;
+    };
     isDirty: () => boolean;
     resetToOriginal: () => boolean;
     exportImage: (opts?: ImageExportOptions) => Promise<Blob>;

package/dist/react/ExportProgressOverlay.d.ts

@@ -0,0 +1,6 @@
+import { ExportProgress } from '../core/progress';
+export declare function ExportProgressOverlay({ state, busy, onCancel, }: {
+    state: ExportProgress | null;
+    busy: boolean;
+    onCancel: () => void;
+}): import("react").JSX.Element | null;

package/dist/react/use-excel-document.d.ts

@@ -7,6 +7,8 @@ export interface ExcelDocument {
     workbook: WorkbookModel | null;
     progress: ParseProgress | null;
     load: (src: ExcelSource, transform?: TransformModelFn) => Promise<void>;
+    /** 直接喂模型(JSON 直渲 / 模板已应用),跳过 parser */
+    loadModel: (model: WorkbookModel, transform?: TransformModelFn) => void;
     /** 原始字节(高保真 overlay 导出用) */
     sourceBuffer: ArrayBuffer | null;
 }