ooxml-excel-editor 1.1.0 → 1.3.0

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

@@ -3,8 +3,10 @@ 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 { CellInspection } from '../model/inspect';
+import { MenuItem } from '../edit/context-menu';
 import { EditorCommitValue, EditorResolver } from '../edit/editor-context';
-import { CanvasRenderer, RendererOptions, ViewState } from '../render/canvas-renderer';
+import { CanvasRenderer, CellImageFit, RendererOptions, ViewState } from '../render/canvas-renderer';
 import { OverlayQuads } from './overlay-manager';
 import { ImageExportOptions, PdfExportOptions, PrintOptions } from '../export/types';
 import { XlsxExportOptions } from '../export/xlsx-writer';
@@ -70,6 +72,33 @@ export interface ViewerControllerHooks {
     onFilterChange: () => void;
     /** 编辑事件(cell-change/edit-start/edit-commit;壳转 emit + 插件派发) */
     onEditEvent: (event: EditEventName, payload: unknown) => void;
+    /** 右键菜单触发前(Plan C):用户可调 `preventDefault()` 阻止内置菜单弹出(然后自渲染) */
+    onContextMenuBefore?: (payload: ContextMenuBeforePayload) => void;
+    /** 右键菜单"展示"通知(Plan C):无论内置是否弹都触发,供壳自渲染或事件流串到业务 */
+    onContextMenuShow?: (payload: ContextMenuShowPayload) => void;
+}
+/** 右键菜单上下文(单格/选区 + 活动格 + 当前表/簿 + editable 闸门态) */
+export interface ContextMenuCtx {
+    range: MergeRange;
+    single: boolean;
+    activeCell: Cell;
+    sheet: SheetModel;
+    workbook: WorkbookModel;
+    editable: boolean;
+}
+/** 用户 transform:在内置 items 上做加 / 减 / 重排;返新数组生效,返 undefined 用原样 */
+export type ContextMenuTransform = (ctx: ContextMenuCtx, items: MenuItem[]) => MenuItem[] | undefined | void;
+export interface ContextMenuBeforePayload {
+    event: MouseEvent;
+    ctx: ContextMenuCtx;
+    items: MenuItem[];
+    preventDefault: () => void;
+}
+export interface ContextMenuShowPayload {
+    x: number;
+    y: number;
+    ctx: ContextMenuCtx;
+    items: MenuItem[];
 }
 export declare class ViewerController {
     private els;
@@ -83,11 +112,20 @@ export declare class ViewerController {
     private rafId;
     private contentW;
     private contentH;
+    /** 虚拟外推行/列数(滚动出空行/空列;只增不减,封顶 Excel 上限)。不动 dimension/文件。 */
+    private virtualRows;
+    private virtualCols;
     private workbook;
     private activeIndex;
     private rendererOpts;
     /** 下载默认文件名(壳可随 props 更新) */
     fileName: string | undefined;
+    /** 右键上下文菜单宿主(G3;body 级 DOM,框架无关) */
+    private menuHost;
+    private lightbox;
+    private lightboxEnabled;
+    /** 用户的右键菜单 transform 回调(Plan C):`(ctx, items) => MenuItem[] | undefined` */
+    private ctxMenuTransform;
     /** 原始 .xlsx 字节(壳加载时注入;供高保真 overlay 导出重载原件) */
     private sourceBuffer;
     /** 壳在加载后注入原始字节(供 exportXlsx({fidelity:'overlay'}) 重载原件叠加编辑) */
@@ -107,6 +145,7 @@ export declare class ViewerController {
     private resizeStartInfo;
     private resizeStartModelSize;
     private dragMoved;
+    private dragStartXY;
     private findQuery;
     private findMatchCase;
     private findWholeCell;
@@ -145,10 +184,30 @@ export declare class ViewerController {
     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;
+    /**
+     * 程序化设列宽 (px, 模型单位/非缩放). Phase B 2026-06-08:
+     * target 接 `number | number[] | {from,to}` (DimTarget). 多 index 时聚合成单次 undo.
+     * editable 时走命令栈;strictDimensions=true 时该列至少 1 格在白名单内才生效.
+     * 返回**成功条数** (0 = 全部 skip / editable=false).
+     */
+    setColumnWidth(target: import('../edit/types').DimTarget, width: number): number;
+    /** 程序化设行高 (px, 模型单位/非缩放). 同 setColumnWidth, 维度 = 'row'. */
+    setRowHeight(target: import('../edit/types').DimTarget, height: number): number;
+    /**
+     * 批量 autoFit 列宽 (Phase B 2026-06-08). target 不传 = 整表; 传 DimTarget = 选定列.
+     * 单 index 走 autoFitColumn (含 resize-record); 多 index 单次 restore-wb undo + 循环 autofit.
+     * 返回成功条数.
+     */
+    autoFitColumns(target?: import('../edit/types').DimTarget): number;
+    /** 批量 autoFit 行高 (Phase B 2026-06-08). 同 autoFitColumns, 维度 = 'row'. */
+    autoFitRows(target?: import('../edit/types').DimTarget): number;
+    /**
+     * 重置列宽到默认 (Phase B 2026-06-08) — 移除 sheet.columns Map 条目, 回落到 defaultColWidth.
+     * 多 index 单次 undo. 返回成功条数.
+     */
+    resetColumnWidth(target: import('../edit/types').DimTarget): number;
+    /** 重置行高到默认. 同 resetColumnWidth, 维度 = 'row'. */
+    resetRowHeight(target: import('../edit/types').DimTarget): number;
     /** 公式引擎是否已就绪(recalc 开启 + 异步 warm 完成);未开重算恒 false。 */
     isRecalcReady(): boolean;
     /** 当前是否有未保存修改(自加载/还原以来发生过编辑或 resize)。 */
@@ -172,10 +231,34 @@ export declare class ViewerController {
     dispose(): void;
     /** 内容总尺寸变化 → 量 + 直接撑 spacer(滚动范围由它决定) */
     refreshContentSize(): void;
+    /**
+     * 据当前滚动+视口算"虚拟范围"(滚到数据下方仍有空行/空列可滚动/选中/编辑)。
+     * 只增不减(防 spacer 抖动)、封顶 Excel 上限。**不动 dimension/文件**;编辑虚拟格才靠 growDimension 变实。
+     * 仅当范围真变化时重建 GridMetrics + 刷 spacer。
+     */
+    recomputeVirtualExtent(): void;
+    /** 当前虚拟范围(含 dimension 兜底);供调试/e2e。 */
+    getVirtualExtent(): {
+        rows: number;
+        cols: number;
+    };
     /** 当前选区(随 mode 解析为单元格/整行/整列范围,含合并单元格扩展) */
     getSelection(): MergeRange | null;
     /** 活动单元格(选区的"焦点"角) */
     getActiveCell(): Cell | null;
+    /**
+     * 活动格(或指定格)在公式栏里**可编辑的字符串**:
+     * 公式 → `=...`;数值 → 原始数字串(非格式化,避免编辑货币/千分位被当文本);布尔 → TRUE/FALSE;
+     * 日期/字符串/富文本 → 显示文本。空格返 ''。供公式栏 / 命令式取活动格编辑值。
+     */
+    getCellEditString(row?: number, col?: number): string;
+    /** 活动格此刻是否可经公式栏/命令式编辑(editable 开 + 该格非只读) */
+    canEditActiveCell(): boolean;
+    /**
+     * 经公式栏提交活动格的值(value 同 editCell 的输入语义:`=`→公式、数字串→数字…)。
+     * 仅在 editable + 该格可编辑时生效;move='down' 时提交后活动格下移(像 Excel 回车)。返回是否提交。
+     */
+    commitActiveCellValue(value: string, move?: 'down'): boolean;
     /** 清空选区 */
     clearSelection(): void;
     /** 全选 */
@@ -201,12 +284,59 @@ export declare class ViewerController {
     /** 拖拽结束:模型已被 renderer 改完,补登一条 undo 项 + 发 dim-change。 */
     private endResizeRecord;
     onMouseLeave(): void;
+    /** 右键上下文菜单(G3;仅 editable;只读用浏览器默认菜单)。壳把 contextmenu 事件转给它。 */
+    /**
+     * 右键事件入口(Plan C 全面开放):
+     *  1. 算 ctx(选区 + 单/多格 + 活动格);右键不在当前选区 → 先选中(仿 Excel)
+     *  2. 算内置 items(`buildBuiltinContextMenuItems`,editable 时才有,否则空)
+     *  3. 跑用户 `setContextMenuTransform` 回调(可加/减/重排)
+     *  4. 触发 `onContextMenuBefore` 钩子(可 preventDefault)
+     *  5. 没被 prevent + items 非空 → 弹内置浮层;无论是否弹,都触发 `onContextMenuShow`(让用户也能自渲染)
+     */
+    onContextMenu(e: MouseEvent): void;
+    /** 算右键 ctx:命中格 + 选区调整;非内容区 / 无 renderer 返 null */
+    private buildContextMenuCtx;
+    /** 编辑模式下的内置菜单项(独立提取,便于 transform 回调拿到再二次加工) */
+    buildBuiltinContextMenuItems(ctx: ContextMenuCtx): MenuItem[];
+    /** 设置用户 transform 回调(`(ctx, items) => MenuItem[] | undefined`);壳侧调用 */
+    setContextMenuTransform(fn: ContextMenuTransform | null | undefined): void;
+    /** 程序化打开菜单(键盘 Shift+F10 / 自定义触发);items 不给则按当前选区算内置 */
+    openContextMenu(x: number, y: number, items?: MenuItem[]): void;
+    /** 关闭当前菜单(无打开则 no-op) */
+    closeContextMenu(): void;
     private updateHover;
     onDblClick(e: MouseEvent): void;
     private pageRows;
     onKeyDown(e: KeyboardEvent): void;
     private scrollActiveIntoView;
     copySelection(): Promise<void>;
+    /**
+     * 从系统剪贴板粘贴。优先 `clipboard.read()` 拿 **text/html**(Excel/WPS 复制 → 富粘贴:值+字体+颜色+
+     * 填充+边框+合并),否则单张图片 → 落格,再否则回退 **text/plain** TSV(`pasteText`)。需读权限/安全上下文,
+     * 受限时回退 readText;都失败返 false。
+     */
+    pasteFromClipboard(): Promise<boolean>;
+    /**
+     * 解析 Excel/WPS 复制的剪贴板 HTML(text/html)→ 富粘贴:值 + 字体/颜色/填充/边框/对齐 + 合并 + data-uri 图,
+     * **整体单次撤销**。无 `<table>` 返 false(调用方回退 TSV)。at 缺省用活动格。
+     */
+    pasteRichHtml(html: string, at?: {
+        row: number;
+        col: number;
+    }): boolean;
+    /** 把一张图片 blob 落到活动格(转内嵌图);剪贴板单图粘贴 / 拖文件进网格用。 */
+    pasteImageBlob(blob: Blob, at?: {
+        row: number;
+        col: number;
+    }): Promise<boolean>;
+    /**
+     * 把 TSV(Excel/表格复制的制表符分隔文本)粘到选区左上角(无 at 时用活动格)。
+     * 值类型自动推断(纯数字串→数字、`=`→公式)、跳过只读格;入命令栈可撤销。返回是否有改动。
+     */
+    pasteText(text: string, at?: {
+        row: number;
+        col: number;
+    }): boolean;
     /** 查找状态快照(壳渲染 FindBar) */
     getFindState(): FindState;
     setFindQuery(q: string): void;
@@ -260,13 +390,39 @@ export declare class ViewerController {
     sortColumn(col: number, dir: 'asc' | 'desc'): void;
     /** 设置编辑配置(默认只读;壳在挂载 + props 变化时调) */
     setEditConfig(cfg: EditConfig): void;
-    /** 该格当前是否可编辑(综合 editable + readOnlyRanges + cellReadOnly) */
+    /** 该格当前是否可编辑(综合 editable + editableTargets 白名单 + readOnlyRanges + cellReadOnly) */
     isCellEditable(row: number, col: number): boolean;
+    /**
+     * **运行时**改可编辑白名单(2026-06-08 新增) —— 不动 `:editableTargets` prop,
+     * 直接覆盖 `editCfg.editableTargets`. 立即重绘以反映只读光标变化.
+     * 传 `undefined` = 关闭白名单(默认全可编辑);`[]` = 全只读;单值或数组 = 白名单.
+     */
+    setEditableTargets(targets: EditConfig['editableTargets']): void;
+    /** 当前生效的可编辑白名单(运行时 setEditableTargets 或初始 prop). 用 `undefined` 表示未启用白名单 */
+    getEditableTargets(): EditConfig['editableTargets'];
     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;
+    /** 活动格当前背景填充色(#RRGGBB);无填充/非纯色 → 默认白 #FFFFFF。 */
+    getActiveFillColor(): string;
+    /** 活动格当前字体色(#RRGGBB);缺省黑 #000000。 */
+    getActiveFontColor(): string;
+    /** 给当前选区设背景填充色(null = 清除填充);editable 时入命令栈。 */
+    setSelectionFill(color: string | null): boolean;
+    /** 给当前选区设字体色;editable 时入命令栈。 */
+    setSelectionFontColor(color: string): boolean;
+    /** 当前选区里 wrapText 的整体态:'all' 全开 / 'none' 全关 / 'mixed' 混合。空选区→'none'。 */
+    getSelectionWrapState(): 'all' | 'none' | 'mixed';
+    /** 切换当前选区的"自动换行"(WPS 风格):全 wrap → 全关;否则 → 全开。
+     *  失效行高缓存让 autofit 按新 wrap 重撑(只扩不缩);editable 时入命令栈(单次撤销 style)。
+     *  注:undo 回滚 style 但不回滚行高,与现有 setStyle/autofit "只扩不缩"语义一致。 */
+    toggleWrapTextOnSelection(): boolean;
+    /** 合并区域(G1;清空被覆盖格,只留左上锚点);editable 时入命令栈 */
+    mergeCells(range: MergeRange): boolean;
+    /** 拆分区域内的合并(G1);editable 时入命令栈 */
+    unmergeCells(range: MergeRange): boolean;
     /** 读当前表全部图片锚点(克隆)。 */
     getImages(): ImageAnchor[];
     /** 加一张图(无 src 但有 bytes+mime 时自动生成 blob url);返回插入索引(失败 -1)。 */
@@ -277,6 +433,50 @@ export declare class ViewerController {
     moveImage(index: number, dxPx: number, dyPx: number): boolean;
     /** 缩放图片(目标屏幕像素宽高);editable 时入命令栈 + 发 image-change。 */
     resizeImage(index: number, widthPx: number, heightPx: number): boolean;
+    /** 改 WPS 单元格内嵌图贴合方式(fill/contain/cover);即时重绘。 */
+    setCellImageFit(fit: CellImageFit): void;
+    /** 读 WPS 单元格内嵌图登记表(克隆,id→{id,src,mime});无则空数组。 */
+    getCellImages(): {
+        id: string;
+        src: string;
+        mime?: string;
+    }[];
+    /** 某格是否内嵌图(DISPIMG)→ 返 {id,src,mime},否则 null(供点击放大判定)。 */
+    getCellImageAt(row: number, col: number): {
+        id: string;
+        src: string;
+        mime?: string;
+    } | null;
+    /** 开/关图片点击放大灯箱(默认开;只读模式单击图、编辑模式右键菜单触发)。 */
+    setLightboxEnabled(b: boolean): void;
+    /** 打开图片放大灯箱(命令式;src = blob/data/http url)。 */
+    openImageLightbox(src: string, fileName?: string, mime?: string): void;
+    /** 一张浮动图视觉中心落在哪个单元格(用几何反推;无渲染器时回落锚点 from 格)。 */
+    imageCellOf(index: number): {
+        row: number;
+        col: number;
+    } | null;
+    /** 浮动图 → 单元格内嵌图(显式指定目标格);失败返 false。 */
+    convertImageToCell(imageIndex: number, row: number, col: number): boolean;
+    /** 选区批量:把"中心格落在 range 内"的所有浮动图就近嵌入,聚合成单次 undo;返回成功嵌入张数。 */
+    convertImagesInRangeToCell(range: MergeRange): number;
+    /** 选区批量:把 range 内所有 DISPIMG 格拎成浮动图;聚合成单次 undo;返回成功转换张数。 */
+    convertCellImagesInRangeToFloat(range: MergeRange, size?: {
+        width: number;
+        height: number;
+    }): number;
+    /** 浮动图 → 内嵌图(**就近**:图在哪格就嵌哪格,目标由几何反推);失败返 false。 */
+    convertImageToCellAuto(imageIndex: number): boolean;
+    /**
+     * 批量把浮动图按"所在单元格"就近嵌入(整表 / 整列)。`col` 给定则只嵌中心落在该列的图。
+     * 一次进撤销栈(单次 Ctrl+Z 全撤)。返回成功嵌入的张数。
+     */
+    convertAllImagesToCells(col?: number): number;
+    /** 单元格内嵌图 → 浮动图(把 row,col 的 DISPIMG 拎成浮动图);非内嵌图格返 false。 */
+    convertCellImageToFloat(row: number, col: number, size?: {
+        width: number;
+        height: number;
+    }): boolean;
     /** 在 at 处插入 count 行(原 at 行及之后下移)。 */
     insertRows(at: number, count?: number): boolean;
     /** 删除 [at, at+count) 行(与合并相交则警告,相交合并被移除)。 */
@@ -296,6 +496,9 @@ export declare class ViewerController {
         col: number;
     } | null;
     getCellSnapshot(row: number, col: number): CellSnapshot | null;
+    /** 单元格"全息体检":snapshot + 合并区 + 浮动图覆盖 + WPS 内嵌图 + 数据验证 + 条件格式命中 + 链接/批注。
+     *  无 workbook / sheet / 越界返 null。详见 [src/core/model/inspect.ts](src/core/model/inspect.ts)。 */
+    inspectCell(row: number, col: number): CellInspection | null;
     /** 壳注入合并后的编辑器解析器(plugin.editor + prop.editor) */
     setEditorResolver(fn?: EditorResolver): void;
     /**

package/dist/core/viewer/lightbox-host.d.ts

@@ -0,0 +1,16 @@
+export interface LightboxImage {
+    /** 图片地址(blob url / data url / http);直接喂 <img src> */
+    src: string;
+    /** 下载时的文件名(缺省按 mime 推扩展名) */
+    fileName?: string;
+    mime?: string;
+}
+export declare class LightboxHost {
+    private el;
+    private cleanup;
+    isOpen(): boolean;
+    show(img: LightboxImage): void;
+    private download;
+    close(): void;
+    dispose(): void;
+}

package/dist/core.js

@@ -1,4 +1,4 @@
-import { C as r, w as t, D as l, E as n, G as i, O as m, P as d, V as g, W as c, x as u, y as C, z as k, i as b, j as y, A as f, B as v, k as S, m as E, F as I, H as T, I as p, J as R, h, K as W, L as w, M as x, N as D, d as F, n as O, f as V, o as B, a as H, q as M, t as A, c as J, e as L, g as N, b as P, u as U, Q as z, R as G, S as K, T as X, U as _, X as j, l as q, Y as Q, v as Y, p as Z, Z as $, _ as ee, $ as ae, a0 as se, a1 as oe, a2 as re, r as te, a3 as le, a4 as ne, a5 as ie, a6 as me, a7 as de, a8 as ge, s as ce, a9 as ue, aa as Ce, ab as ke, ac as be } from "./chunks/plugin-overlay-Cfnn9EOi.js";
+import { C as r, w as t, D as l, E as n, G as i, O as m, P as d, V as g, W as c, x as u, y as C, z as k, j as b, k as y, A as f, B as v, m as S, i as E, F as I, H as T, I as p, J as R, h, K as W, L as w, M as x, N as D, d as F, n as O, f as V, o as B, a as H, q as M, t as A, c as J, e as L, g as N, b as P, u as U, Q as z, R as G, S as K, T as X, U as _, X as j, l as q, Y as Q, v as Y, p as Z, Z as $, _ as ee, $ as ae, a0 as se, a1 as oe, a2 as re, r as te, a3 as le, a4 as ne, a5 as ie, a6 as me, a7 as de, a8 as ge, s as ce, a9 as ue, aa as Ce, ab as ke, ac as be } from "./chunks/plugin-overlay-DLb6sRhU.js";
 function a(e) {
   return e;
 }