ooxml-excel-editor 1.3.2 → 1.7.0

package/dist/chunks/{toolbar-icons-fOm95ASq.js → toolbar-icons-CD7G5Aof.js}

@@ -1,30 +1,16 @@
 var S = Object.defineProperty;
-var T = Object.getOwnPropertySymbols;
+var z = Object.getOwnPropertySymbols;
 var E = Object.prototype.hasOwnProperty, H = Object.prototype.propertyIsEnumerable;
-var j = (e, r, t) => r in e ? S(e, r, { enumerable: !0, configurable: !0, writable: !0, value: t }) : e[r] = t, f = (e, r) => {
+var j = (e, r, t) => r in e ? S(e, r, { enumerable: !0, configurable: !0, writable: !0, value: t }) : e[r] = t, w = (e, r) => {
   for (var t in r || (r = {}))
     E.call(r, t) && j(e, t, r[t]);
-  if (T)
-    for (var t of T(r))
+  if (z)
+    for (var t of z(r))
       H.call(r, t) && j(e, t, r[t]);
   return e;
 };
-import { i as R, p as G } from "./plugin-overlay-BUrPrpT2.js";
-const N = Array(17).fill("#000000");
-function F() {
-  return {
-    font: { name: "Calibri", size: 11, bold: !1, italic: !1, underline: !1, strike: !1, color: "#000000" },
-    fill: { type: "none" },
-    borders: {},
-    hAlign: "general",
-    vAlign: "bottom",
-    wrapText: !1,
-    shrinkToFit: !1,
-    textRotation: 0,
-    indent: 0,
-    numFmt: "General"
-  };
-}
+import { m as N, i as k, p as G } from "./plugin-overlay-C_qauTcv.js";
+const O = Array(17).fill("#000000");
 function V(e, r) {
   return {
     name: e,
@@ -32,7 +18,7 @@ function V(e, r) {
     state: "visible",
     dimension: { rows: 0, cols: 0 },
     cells: /* @__PURE__ */ new Map(),
-    styles: [F()],
+    styles: [N()],
     merges: [],
     columns: /* @__PURE__ */ new Map(),
     rows: /* @__PURE__ */ new Map(),
@@ -45,10 +31,11 @@ function V(e, r) {
     charts: [],
     shapes: [],
     sparklines: [],
+    pivotTables: [],
     showGridLines: !0
   };
 }
-function O(e, r) {
+function $(e, r) {
   if (e == null || e === "") return { raw: null, type: "empty" };
   if (typeof e == "number") return { raw: e, type: "number" };
   if (typeof e == "boolean") return { raw: e, type: "boolean" };
@@ -67,54 +54,54 @@ function O(e, r) {
   }
   return { raw: e, type: "string" };
 }
-function $(e, r) {
+function D(e, r) {
   return r.map((t) => e[t]);
 }
 function L(e, r, t = {}) {
-  var A, x, p, w, C, M;
-  const s = (A = t.startRow) != null ? A : 0, c = (x = t.startCol) != null ? x : 0, y = (p = t.autoInfer) != null ? p : !0;
-  let n = 0, h = 0, d = !1;
+  var I, x, p, f, M, C;
+  const s = (I = t.startRow) != null ? I : 0, c = (x = t.startCol) != null ? x : 0, y = (p = t.autoInfer) != null ? p : !0;
+  let l = 0, h = 0, m = !1;
   if (!r.length) return { lastRow: 0, lastCol: 0, wrote: !1 };
-  const m = r[0], o = m !== null && typeof m == "object" && !Array.isArray(m), a = o ? (w = t.columns) != null ? w : Object.keys(m) : [];
+  const d = r[0], o = d !== null && typeof d == "object" && !Array.isArray(d), a = o ? (f = t.columns) != null ? f : Object.keys(d) : [];
   let g = s;
-  if (o && ((C = t.headerRow) == null || C)) {
-    for (let l = 0; l < a.length; l++) {
-      const i = g, u = c + l;
-      e.cells.set(R(i, u), { row: i, col: u, type: "string", raw: a[l], styleId: 0 }), n = Math.max(n, i), h = Math.max(h, u), d = !0;
+  if (o && ((M = t.headerRow) == null || M)) {
+    for (let n = 0; n < a.length; n++) {
+      const i = g, u = c + n;
+      e.cells.set(k(i, u), { row: i, col: u, type: "string", raw: a[n], styleId: 0 }), l = Math.max(l, i), h = Math.max(h, u), m = !0;
     }
     g++;
   }
-  for (let l = 0; l < r.length; l++) {
-    const i = r[l], u = Array.isArray(i) ? i : $(i, a);
-    for (let k = 0; k < u.length; k++) {
-      const I = g + l - (o && ((M = t.headerRow) == null || M), 0), b = c + k, z = O(u[k], y);
-      z.type !== "empty" && (e.cells.set(R(I, b), { row: I, col: b, type: z.type, raw: z.raw, styleId: 0 }), n = Math.max(n, I), h = Math.max(h, b), d = !0);
+  for (let n = 0; n < r.length; n++) {
+    const i = r[n], u = Array.isArray(i) ? i : D(i, a);
+    for (let R = 0; R < u.length; R++) {
+      const b = g + n - (o && ((C = t.headerRow) == null || C), 0), A = c + R, T = $(u[R], y);
+      T.type !== "empty" && (e.cells.set(k(b, A), { row: b, col: A, type: T.type, raw: T.raw, styleId: 0 }), l = Math.max(l, b), h = Math.max(h, A), m = !0);
     }
   }
-  return { lastRow: n, lastCol: h, wrote: d };
+  return { lastRow: l, lastCol: h, wrote: m };
 }
-function B(e, r = {}) {
+function v(e, r = {}) {
   var o, a;
-  const t = r.themeColors && r.themeColors.length === 17 ? r.themeColors : N, s = (o = r.autoInfer) != null ? o : !0, c = (a = r.headerRow) != null ? a : !0;
+  const t = r.themeColors && r.themeColors.length === 17 ? r.themeColors : O, s = (o = r.autoInfer) != null ? o : !0, c = (a = r.headerRow) != null ? a : !0;
   if (e && typeof e == "object" && !Array.isArray(e) && Array.isArray(e.sheets))
     return { sheets: e.sheets.map((x, p) => {
       var i;
-      const w = V(x.name || `Sheet${p + 1}`, p), { lastRow: C, lastCol: M, wrote: l } = L(w, (i = x.rows) != null ? i : [], { headerRow: c, autoInfer: s });
-      return w.dimension = l ? { rows: C + 1, cols: M + 1 } : { rows: 0, cols: 0 }, w;
+      const f = V(x.name || `Sheet${p + 1}`, p), { lastRow: M, lastCol: C, wrote: n } = L(f, (i = x.rows) != null ? i : [], { headerRow: c, autoInfer: s });
+      return f.dimension = n ? { rows: M + 1, cols: C + 1 } : { rows: 0, cols: 0 }, f;
     }), activeSheet: 0, themeColors: t, date1904: !1 };
-  const y = V(r.sheetName || "Sheet1", 0), n = e != null ? e : [], { lastRow: h, lastCol: d, wrote: m } = L(y, n, { headerRow: c, autoInfer: s });
-  return y.dimension = m ? { rows: h + 1, cols: d + 1 } : { rows: 0, cols: 0 }, { sheets: [y], activeSheet: 0, themeColors: t, date1904: !1 };
+  const y = V(r.sheetName || "Sheet1", 0), l = e != null ? e : [], { lastRow: h, lastCol: m, wrote: d } = L(y, l, { headerRow: c, autoInfer: s });
+  return y.dimension = d ? { rows: h + 1, cols: m + 1 } : { rows: 0, cols: 0 }, { sheets: [y], activeSheet: 0, themeColors: t, date1904: !1 };
 }
-function _(e) {
+function B(e) {
   return !!e && typeof e == "object" && Array.isArray(e.sheets) && typeof e.activeSheet == "number" && Array.isArray(e.themeColors);
 }
-function K(e, r) {
-  var m;
+function _(e, r) {
+  var d;
   const t = r.sheets[0], s = e.sheets[0];
   if (!t) return e;
   if (!s)
     return {
-      sheets: [D(t, t.name)],
+      sheets: [F(t, t.name)],
       activeSheet: 0,
       themeColors: r.themeColors,
       date1904: e.date1904,
@@ -126,13 +113,13 @@ function K(e, r) {
     state: "visible",
     dimension: { rows: 0, cols: 0 },
     cells: /* @__PURE__ */ new Map(),
-    styles: t.styles.map((o) => f({}, o)),
-    merges: t.merges.map((o) => f({}, o)),
+    styles: t.styles.map((o) => w({}, o)),
+    merges: t.merges.map((o) => w({}, o)),
     columns: new Map(t.columns),
     rows: new Map(t.rows),
     defaultColWidth: t.defaultColWidth,
     defaultRowHeight: t.defaultRowHeight,
-    freeze: f({}, t.freeze),
+    freeze: w({}, t.freeze),
     // 条件格式 / 数据验证 不带过来 —— 数据可能不在模板的目标列上, 套规则会误命中
     conditional: [],
     dataValidations: [],
@@ -141,12 +128,13 @@ function K(e, r) {
     charts: [],
     shapes: [],
     sparklines: [],
+    pivotTables: [],
     showGridLines: t.showGridLines
   };
-  let y = 0, n = 0;
+  let y = 0, l = 0;
   for (const o of s.cells.values()) {
-    const a = t.cells.get(R(o.row, o.col));
-    c.cells.set(R(o.row, o.col), {
+    const a = t.cells.get(k(o.row, o.col));
+    c.cells.set(k(o.row, o.col), {
       row: o.row,
       col: o.col,
       type: o.type,
@@ -155,14 +143,14 @@ function K(e, r) {
       formula: o.formula,
       hyperlink: o.hyperlink,
       comment: o.comment,
-      styleId: (m = a == null ? void 0 : a.styleId) != null ? m : 0,
+      styleId: (d = a == null ? void 0 : a.styleId) != null ? d : 0,
       dispImgId: o.dispImgId
-    }), o.row > y && (y = o.row), o.col > n && (n = o.col);
+    }), o.row > y && (y = o.row), o.col > l && (l = o.col);
   }
-  const h = t.columns.size ? Math.max(...t.columns.keys()) + 1 : 0, d = t.rows.size ? Math.max(...t.rows.keys()) + 1 : 0;
+  const h = t.columns.size ? Math.max(...t.columns.keys()) + 1 : 0, m = t.rows.size ? Math.max(...t.rows.keys()) + 1 : 0;
   return c.dimension = {
-    rows: Math.max(s.dimension.rows, y + 1, d),
-    cols: Math.max(s.dimension.cols, n + 1, h)
+    rows: Math.max(s.dimension.rows, y + 1, m),
+    cols: Math.max(s.dimension.cols, l + 1, h)
   }, {
     sheets: [c],
     activeSheet: 0,
@@ -171,33 +159,34 @@ function K(e, r) {
     cellImages: e.cellImages
   };
 }
-function D(e, r) {
+function F(e, r) {
   return {
     name: r,
     index: 0,
     state: "visible",
     dimension: { rows: 0, cols: 0 },
     cells: /* @__PURE__ */ new Map(),
-    styles: e.styles.map((t) => f({}, t)),
-    merges: e.merges.map((t) => f({}, t)),
+    styles: e.styles.map((t) => w({}, t)),
+    merges: e.merges.map((t) => w({}, t)),
     columns: new Map(e.columns),
     rows: new Map(e.rows),
     defaultColWidth: e.defaultColWidth,
     defaultRowHeight: e.defaultRowHeight,
-    freeze: f({}, e.freeze),
+    freeze: w({}, e.freeze),
     conditional: [],
     dataValidations: [],
     images: [],
     charts: [],
     shapes: [],
     sparklines: [],
+    pivotTables: [],
     showGridLines: e.showGridLines
   };
 }
-function Z(e, r) {
+function K(e, r) {
   return G(e, r);
 }
-const q = {
+const Z = {
   // 放大镜
   find: '<circle cx="11" cy="11" r="7"/><line x1="21" y1="21" x2="16.65" y2="16.65"/>',
   // 漏斗
@@ -206,6 +195,8 @@ const q = {
   "clear-filter": '<path d="M3 5h18l-7 8.5V20l-4-2.2V13.5z"/><line x1="3" y1="3" x2="21" y2="21"/>',
   // 上下箭头(排序)
   sort: '<path d="M7 16l3 3 3-3"/><line x1="10" y1="19" x2="10" y2="5"/><path d="M17 8l-3-3-3 3"/><line x1="14" y1="5" x2="14" y2="19"/>',
+  // 透视表: 小表格 + 汇总箭头
+  "pivot-table": '<rect x="3" y="4" width="13" height="13" rx="1.5"/><line x1="3" y1="8" x2="16" y2="8"/><line x1="7" y1="4" x2="7" y2="17"/><path d="M14 14h7"/><path d="M18 11l3 3-3 3"/>',
   // 下载(导出)
   export: '<line x1="12" y1="3" x2="12" y2="15"/><path d="M8 11l4 4 4-4"/><path d="M4 19h16"/>',
   // 放大镜带 +
@@ -225,14 +216,14 @@ const q = {
   // 下拉小箭头
   caret: '<path d="M6 9l6 6 6-6"/>'
 };
-function J(e) {
+function q(e) {
   return '<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' + e + "</svg>";
 }
 export {
-  q as T,
-  K as a,
-  _ as i,
-  B as j,
-  Z as p,
-  J as s
+  Z as T,
+  _ as a,
+  B as i,
+  v as j,
+  K as p,
+  q as s
 };

package/dist/components/ExcelViewer.vue.d.ts

@@ -7,6 +7,7 @@ import { ReadOptions } from '../core/model/data-access';
 import { ViewerTheme } from '../core/render/theme';
 import { ContextMenuBeforePayload, ContextMenuShowPayload, ContextMenuTransform } from '../core/viewer/controller';
 import { EditableTarget } from '../core/edit/types';
+import { PasteBehavior } from '../core/edit/paste-behavior';
 import { FormulaEngineFactory } from '../core/formula/engine';
 import { CellChangePayload, DimChangePayload, DirtyChangePayload, ImageChangePayload, StructChangePayload } from '../core/edit/edit-controller';
 import { EditorResolver } from '../core/edit/editor-context';
@@ -58,6 +59,12 @@ type __VLS_Props = {
     toolbar?: boolean | Array<string | ToolbarItem>;
     /** 编辑总开关:默认 false = 只读(行为不变)。开启后才能进入编辑(E0:闸门) */
     editable?: boolean;
+    /**
+     * 透视表功能开关:默认 false = 关闭。开启后(还需 `editable`)工具栏 `pivot-table` 入口可见、
+     * `createPivotTable`/`openPivotTableDialog` 等 API 生效、导出 .xlsx 回注真实 OOXML 透视表零件
+     * (overlay 模式同时保留原文件透视表)。
+     */
+    pivotTable?: boolean;
     /** 按格只读判定:返回 true = 只读(cell 为空格时传 null) */
     cellReadOnly?: (cell: CellModel | null, pos: {
         row: number;
@@ -95,6 +102,13 @@ type __VLS_Props = {
     recalc?: boolean;
     /** 自定义/自研公式引擎工厂(可换引擎);不给则用默认 HyperFormula(需 npm i hyperformula) */
     formulaEngine?: FormulaEngineFactory;
+    /**
+     * 粘贴行为(默认 = 覆盖式 1:1)。控制 Ctrl+V / 右键粘贴时源各方面如何落目标(覆盖/合并/仅值)。
+     * 不传 = 默认;也可 `viewer.setPasteBehavior(cfg)` 运行时改、右键「选择性粘贴」逐次选预设。
+     */
+    pasteBehavior?: Partial<PasteBehavior>;
+    /** 粘贴撞只读格的内置提醒:'dialog'(默认,弹窗列出哪些格只读)/ 'toast'(气泡)/ 'none'(只发事件) */
+    readOnlyPrompt?: 'dialog' | 'toast' | 'none';
     /**
      * 内置导出进度遮罩(P1.5):默认 `true` —— 调 `viewer.downloadPdf` / `downloadImage` / `downloadXlsx` /
      * `print` / 选区图片批量转换 时,壳自动建 `AbortController` + 接 `onProgress` →
@@ -206,12 +220,23 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {
     setActiveSheet(index: number): void;
     getSelection(): MergeRange | null;
     setSelection(range: MergeRange): void;
+    scrollToCell(row: number, col: number, opts?: {
+        select?: boolean;
+    }): boolean;
     rectOf(row: number, col: number): import('../core/plugin').Rect | null;
     rectOfRange(range: MergeRange): import('../core/plugin').Rect | null;
     redraw(): void;
     isCellEditable(row: number, col: number): boolean;
     setEditableTargets(targets: EditableTarget | EditableTarget[] | undefined): void;
     getEditableTargets(): EditableTarget | EditableTarget[] | undefined;
+    sortActiveColumn(dir: "asc" | "desc"): boolean;
+    createPivotTable(opts: import('../core/plugin').CreatePivotTableOptions): boolean;
+    createPivotTableFromSelection(opts?: {
+        rowFieldIndex?: number;
+        valueFieldIndex?: number;
+        output?: import('../core/plugin').PivotOutput;
+    }): boolean;
+    openPivotTableDialog(): boolean;
     exportImage(opts?: ImageExportOptions): Promise<Blob>;
     downloadImage(opts?: ImageExportOptions): Promise<void>;
     exportPdf(opts?: PdfExportOptions): Promise<Blob>;
@@ -266,7 +291,10 @@ declare const __VLS_component: import('vue').DefineComponent<__VLS_Props, {
     pasteRichHtml(html: string, at?: {
         row: number;
         col: number;
-    }): boolean;
+    }, behaviorOverride?: Partial<PasteBehavior> | null): boolean;
+    getPasteBehavior(): PasteBehavior;
+    setPasteBehavior(cfg: Partial<PasteBehavior> | null): void;
+    openPasteConfigDialog(): boolean;
     pasteImageBlob(blob: Blob, at?: {
         row: number;
         col: number;

package/dist/core/edit/clipboard-html.d.ts

@@ -17,7 +17,19 @@ export interface ParsedClipboard {
         col: number;
         dataUrl: string;
     }[];
+    /** 列宽(相对列 index → px;来自 <col width>);稀疏 */
+    colWidths: number[];
+    /** 行高(相对行 index → px;来自 <tr height>);稀疏 */
+    rowHeights: number[];
 }
+/** mso-number-format 的值是 CSS 转义的 Excel 格式码(\0022→" \#→# \;→; \\(→\( …),解回真实格式码。 */
+export declare function unescapeMsoNumFmt(v: string): string;
+/**
+ * 从合并 CSS 串里解析 mso-number-format → Excel 格式码(值可能含转义的 \; ,故按引号串/到分号匹配)。
+ * **取最后一条**:合并串是 `td默认;类;内联`,按 CSS 层叠后写的覆盖——裸 `td` 默认常带 `mso-number-format:General`,
+ * 若取第一条会被它的 General 顶掉、丢掉后面类里的真实日期/货币格式码。
+ */
+export declare function parseMsoNumberFormat(css: string): string | undefined;
 /**
  * 解析剪贴板 HTML → {values, styles, merges, images}。非浏览器环境 / 无 <table> 返 null(调用方回退 TSV)。
  */

package/dist/core/edit/clipboard-snapshot.d.ts

@@ -0,0 +1,76 @@
+import { AnchorCell, CellModel, CellStyle, CellValueType, MergeRange, RichTextRun, SheetModel, WorkbookModel } from '../model/types';
+/** raw 是 Date 时序列化为 {__d: epochMs},反序列化还原。其余原样 JSON。 */
+type ClipRaw = number | string | boolean | null | {
+    __d: number;
+};
+export interface ClipCell {
+    r: number;
+    c: number;
+    type: CellValueType;
+    raw: ClipRaw;
+    formula?: string;
+    hyperlink?: string;
+    comment?: string;
+    rich?: RichTextRun[];
+    dispImgId?: string;
+    style: CellStyle;
+}
+export interface ClipImage {
+    from: AnchorCell;
+    to?: AnchorCell;
+    extWidthEmu?: number;
+    extHeightEmu?: number;
+    editAs?: string;
+    mime: string;
+    b64: string;
+}
+export interface ClipCellImage {
+    id: string;
+    mime: string;
+    b64: string;
+}
+export interface ClipDim {
+    i: number;
+    height?: number;
+    width?: number;
+    hidden?: boolean;
+    custom?: boolean;
+}
+export interface ClipSnapshot {
+    v: 1;
+    rows: number;
+    cols: number;
+    cells: ClipCell[];
+    merges: MergeRange[];
+    images: ClipImage[];
+    cellImages: ClipCellImage[];
+    rowHeights: ClipDim[];
+    colWidths: ClipDim[];
+}
+/** 图片字节预算(原始字节):复制区图片总字节超此值 → 降级为"无图 1:1 复制",避免剪贴板超限/卡顿。 */
+export declare const CLIP_IMAGE_BUDGET_BYTES: number;
+/**
+ * 抓一段区域的完整模型快照(相对坐标)。
+ * `withImageBytes=false`:图片只记引用(id / 浮动序号),b64 留空 —— 给"图片字节走可见 `<img>`、
+ * 快照只引用"的瘦身传输用(避免图片被双重 base64),粘贴时由 parseSnapshotHtml 从 `<img>` 回填字节。
+ */
+export declare function serializeSnapshot(sheet: SheetModel, wb: WorkbookModel, range: MergeRange, opts?: {
+    withImageBytes?: boolean;
+}): ClipSnapshot;
+/** ClipRaw → 运行时 raw(还原 Date)。 */
+export declare function reviveClipRaw(raw: ClipRaw): CellModel['raw'];
+export declare function encodeSnapshot(snap: ClipSnapshot): string;
+export declare function decodeSnapshot(s: string | null | undefined): ClipSnapshot | null;
+/**
+ * 把图片字节从可见 `<img data-clip-img="key">` 回填进瘦身快照(传输优化:图片只在 `<img>` 存一份)。
+ * key 约定:DISPIMG 单元格图 = `c:${id}`,浮动图 = `f:${序号}`(序号同 serializeSnapshot 的 images 顺序)。
+ * 已带 b64(完整快照路径)则原样保留。
+ */
+export declare function reattachImages(snap: ClipSnapshot | null, imgB64: Map<string, string>): ClipSnapshot | null;
+/** 降级:去掉所有图片(超字节预算时用)。DISPIMG 格中性化为空格(保样式),避免粘出引用不到的破图。 */
+export declare function withoutImages(snap: ClipSnapshot): ClipSnapshot;
+/** 从剪贴板 HTML 抽出本组件的 1:1 快照(`<table data-ooxml-clip="...">` + 回填 `<img>` 字节);非本组件复制返 null。 */
+export declare function parseSnapshotHtml(html: string): ClipSnapshot | null;
+export declare function bytesToB64(bytes: Uint8Array): string;
+export declare function b64ToBytes(b64: string): Uint8Array;
+export {};

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

@@ -1,6 +1,7 @@
 /**
  * 右键上下文菜单宿主(框架无关 DOM)—— 挂到 document.body 的 fixed 菜单,点项执行 action + 关闭,
- * 点外部 / Esc 关闭,贴边自动翻转。Vue / React 壳只把 contextmenu 事件转给 controller,菜单逻辑全在这。
+ * 点外部 / Esc 关闭,贴边自动翻转。支持一级子菜单(`children`,悬停展开右侧 flyout)。
+ * Vue / React 壳只把 contextmenu 事件转给 controller,菜单逻辑全在这。
  */
 export interface MenuItem {
     label?: string;
@@ -8,12 +9,24 @@ export interface MenuItem {
     disabled?: boolean;
     /** true = 分隔线 */
     separator?: boolean;
+    /** 子菜单项(有则该行不执行 action,悬停展开右侧 flyout) */
+    children?: MenuItem[];
 }
 export declare class ContextMenuHost {
     private el;
+    private submenus;
+    private openSubRow;
+    private subCloseTimer;
     private cleanup;
     isOpen(): boolean;
     show(x: number, y: number, items: MenuItem[]): void;
+    /** 建一级菜单 DOM(不挂载、不定位);子菜单悬停时再建 flyout。 */
+    private buildMenu;
+    /** 在 row 右侧展开子菜单 flyout(贴边翻转到左侧);悬停 flyout 取消关闭,离开 flyout 延时关。 */
+    private openSubmenu;
+    private scheduleSubClose;
+    private cancelSubClose;
+    private closeAllSubmenus;
     close(): void;
     dispose(): void;
 }

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

@@ -1,7 +1,9 @@
 import { CellStyleOverride, ColumnInfo, ImageAnchor, MergeRange, RowInfo, SheetModel, WorkbookModel } from '../model/types';
 import { CellValue } from '../model/data-access';
 import { CellSnapshot } from '../model/snapshot';
+import { PasteBehavior } from './paste-behavior';
 import { ParsedClipboard } from './clipboard-html';
+import { ClipSnapshot } from './clipboard-snapshot';
 import { CellPos, DimAxis, EditCommand } from './commands';
 import { StructOp } from '../model/structure';
 import { FormulaEngineFactory } from '../formula/engine';
@@ -72,7 +74,12 @@ export declare class EditController {
     private engine;
     private engineFor;
     private warming;
+    private pasteBehavior;
     constructor(host: EditControllerHost);
+    /** 读当前粘贴行为(完整配置)。 */
+    getPasteBehavior(): PasteBehavior;
+    /** 设粘贴行为默认(缺项回落默认);影响 Ctrl+V / 右键「粘贴」。 */
+    setPasteBehavior(cfg: Partial<PasteBehavior> | null): void;
     /** 异步懒初始化引擎(开重算 + 有工厂 + 尚未为当前簿建好)。返回的 Promise 供测试 await;生产 fire-and-forget。 */
     warmEngine(): Promise<void>;
     /** 释放引擎(切簿/关重算/dispose)。 */
@@ -94,14 +101,28 @@ export declare class EditController {
     editCell(row: number, col: number, value: CellValue): boolean;
     /** 区域批量设值(2D,左上对齐 range.top/left);跳过只读格,返回是否有改动 */
     editRange(range: MergeRange, values: CellValue[][]): boolean;
+    /** 合并区 m 是否与矩形 [top,left]-[bottom,right] 有交叠(用于清粘贴区内的目标原有合并)。 */
+    private _mergeOverlaps;
     /**
      * 富粘贴(Excel/WPS 复制的 HTML 解析后):值 + 样式 + 合并 + 图片,**整体单次撤销**。
      * start = 落点左上角。跳过只读格。一次 cloneWorkbook 快照 → 应用全部 → 压一条 restore-wb 逆。
+     * behaviorOverride = 右键「选择性粘贴」逐次预设(覆盖 this.pasteBehavior;缺省走默认配置)。
      */
     pasteRich(start: {
         row: number;
         col: number;
-    }, parsed: ParsedClipboard): boolean;
+    }, parsed: ParsedClipboard, behaviorOverride?: Partial<PasteBehavior> | null): boolean;
+    /** 去重后发一次 paste 的 permission-denied(没只读格则不发)。 */
+    private _emitPasteDenied;
+    /**
+     * 1:1 保真粘贴:用复制时序列化进剪贴板的完整模型快照(本组件自己复制的,跨实例 Vue3/Vue2/React 通用)
+     * 覆盖式落到目标区 —— 完整还原 值/原始类型/数字格式/全部样式(含边框)/合并/图片(浮动 + DISPIMG)/行高列宽。
+     * 跟 pasteRich(外部 HTML 近似)同走命令栈(整体单次撤销)+ 前后快照 cell-change + 只读 permission-denied。
+     */
+    pasteSnapshot(start: {
+        row: number;
+        col: number;
+    }, snap: ClipSnapshot, behaviorOverride?: Partial<PasteBehavior> | null): boolean;
     /** 清空区域(跳过只读) */
     clearRange(range: MergeRange): boolean;
     /** 给区域套样式覆盖(E5;跳过只读格)。返回是否有改动。前后 style 不同 → 发 cell-change。 */

package/dist/core/edit/paste-behavior.d.ts

@@ -0,0 +1,33 @@
+import { CellStyle, CellStyleOverride } from '../model/types';
+export interface PasteBehavior {
+    /** 字体/对齐/换行/边框/数字格式: 'overwrite' 覆盖式(只留源) | 'merge' 合并式(源没写的留目标) | 'skip' 不动 */
+    cellStyle: 'overwrite' | 'merge' | 'skip';
+    /** 填充底色: 'overwrite' 覆盖式(源没写→无填充) | 'merge' 合并式(源没写→留目标底色) | 'skip' 不动 */
+    fill: 'overwrite' | 'merge' | 'skip';
+    /** 行高: 'source' 搬源行高 | 'keep' 不动 */
+    rowHeight: 'source' | 'keep';
+    /** 列宽: 'source' 总搬源 | 'keep' 不动 | 'firstRowOnly' 仅粘到首行(start.row===0)搬源 */
+    colWidth: 'source' | 'keep' | 'firstRowOnly';
+    /** 源自带的合并区: 'apply' 应用 | 'skip' 不应用 */
+    sourceMerges: 'apply' | 'skip';
+    /** 目标原有、落在粘贴区内的合并: 'clear' 清掉(否则旧合并会吞列致数据错位) | 'keep' 保留 */
+    targetMerges: 'clear' | 'keep';
+    /** 图片(内嵌/浮动): 'apply' 落格 | 'skip' 不粘 */
+    images: 'apply' | 'skip';
+}
+/** 默认粘贴行为 = 覆盖式 1:1(贴近源)。不配置即此。 */
+export declare const DEFAULT_PASTE_BEHAVIOR: PasteBehavior;
+/** 右键预设:保留原来的(仅值)—— 只落值,样式/底色/行高列宽/合并/图片全不动,目标结构完全保留。 */
+export declare const PASTE_PRESET_VALUES_ONLY: PasteBehavior;
+/** 补全部分配置为完整 PasteBehavior(缺项回落默认)。 */
+export declare function resolvePasteBehavior(partial?: Partial<PasteBehavior> | null): PasteBehavior;
+/** 列宽该不该搬:source 总搬;firstRowOnly 仅 start.row===0 搬;keep 不搬。 */
+export declare function shouldApplyColWidth(b: PasteBehavior, startRow: number): boolean;
+/**
+ * 按 cellStyle / fill 两档模式,从「目标现有样式 target + 源 patch」算出粘贴后该格的完整 CellStyle。
+ * 返回 null = 两档都 skip,样式整个不动(调用方跳过)。neutral = 表的中性默认(styles[0])。
+ *
+ * 非填充部分(font/对齐/换行/边框/数字格式):overwrite 以 neutral 为基套源(只留源);merge 以 target 为基套源
+ *   (源没写的留目标);skip 保留 target。填充部分(fill):overwrite 源没写→无填充;merge 源没写→留目标;skip 留目标。
+ */
+export declare function resolvePastedCellStyle(target: CellStyle, neutral: CellStyle, patch: CellStyleOverride, styleMode: PasteBehavior['cellStyle'], fillMode: PasteBehavior['fill']): CellStyle | null;

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

@@ -1,5 +1,6 @@
 import { CellModel, MergeRange } from '../model/types';
 import { FormulaEngineFactory } from '../formula/engine';
+import { PasteBehavior } from './paste-behavior';
 /**
  * 行/列维度目标 (Phase B, 2026-06-08) —— 用于尺寸 API (setColumnWidth / setRowHeight /
  * autoFitColumns / resetColumnWidth ...) 的参数. 3 种形状自动识别:
@@ -44,6 +45,12 @@ export type EditableTarget = {
 export interface EditConfig {
     /** 总开关:默认 false = 只读(行为与历史完全一致) */
     editable?: boolean;
+    /**
+     * 透视表功能开关(默认 false = 关闭)。开启后(还需 `editable`):工具栏 `pivot-table` 入口可见、
+     * `createPivotTable` / `openPivotTableDialog` 等 API 生效、导出 .xlsx 回注真实 OOXML 透视表零件
+     * (含 overlay 模式保留原文件透视表)。关闭时上述行为全部不生效,与历史版本一致。
+     */
+    pivotTable?: boolean;
     /** 按格只读判定:返回 true = 该格只读。cell 为空格时传 null。pos 为 0-based 行列。 */
     cellReadOnly?: (cell: CellModel | null, pos: {
         row: number;
@@ -80,6 +87,19 @@ export interface EditConfig {
     recalc?: boolean;
     /** 自定义/自研公式引擎工厂(可换引擎);不给则用默认 HyperFormula 适配器。 */
     formulaEngine?: FormulaEngineFactory;
+    /**
+     * 粘贴行为配置(默认 = 覆盖式 1:1,见 {@link PasteBehavior})。控制 Ctrl+V / 右键粘贴时
+     * 源内容各方面如何落到目标(覆盖 / 合并 / 仅值)。不传 = 默认。也可运行时 `viewer.setPasteBehavior(cfg)`,
+     * 或右键「选择性粘贴」逐次选预设。缺项回落默认。
+     */
+    pasteBehavior?: Partial<PasteBehavior>;
+    /**
+     * 粘贴撞只读格时的**内置提醒**方式(逐格精确,即便编辑模式下也可能有只读格):
+     *  - `'dialog'`(默认):弹窗列出**具体哪些格**只读,让用户明确知道哪部分没粘上;
+     *  - `'toast'`:顶部气泡简短提示 + 自动消失;
+     *  - `'none'`:不弹内置 UI(仍发 `permission-denied` 事件,消费方自处理)。
+     */
+    readOnlyPrompt?: 'dialog' | 'toast' | 'none';
 }
 /** 单元格编辑权限 */
 export type EditPermission = 'editable' | 'readonly';

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

@@ -16,6 +16,8 @@ export interface ExporterHost {
     getFileName(): string | undefined;
     /** 原始 .xlsx 字节(高保真 overlay 导出重载原件用;无则返回 null,overlay 回退 rebuild) */
     getSourceBuffer?(): ArrayBuffer | null;
+    /** 透视表功能是否开启(EditConfig.pivotTable;决定 xlsx 导出是否回注/保留 pivot 零件) */
+    isPivotEnabled?(): boolean;
 }
 export declare class WorkbookExporter {
     private host;

package/dist/core/export/pivot-tables.d.ts

@@ -0,0 +1,17 @@
+import { WorkbookModel } from '../model/types';
+/**
+ * 把 App 内创建的透视表回注进 ExcelJS 写出的 zip 字节,返回新 zip 字节。
+ * 无可回注透视表 → 原样返回(零开销)。单个透视表失败不影响其余(整体 try/catch 由调用方兜底)。
+ */
+export declare function injectPivotTablesIntoZip(zipBytes: Uint8Array, workbook: WorkbookModel): Uint8Array;
+/**
+ * overlay 导出:把**原文件**的透视表零件原样搬运进 ExcelJS 写出的 zip(ExcelJS 不建模 pivot,
+ * load→write 会整套丢掉)。与 `injectPivotTablesIntoZip`(重建 App 内新建的)互补,先搬运后重建,
+ * 重建侧的零件编号/cacheId 扫描会自动避开搬运进来的。
+ *
+ * 搬运内容:xl/pivotCache/** + xl/pivotTables/**(零件 + _rels 整目录)、workbook `<pivotCaches>`
+ * 注册(cacheId 不变,r:id 在新 rels 里重新分配)、所在 worksheet 的隐式关系(按表名匹配新旧
+ * worksheet)、`[Content_Types].xml` Override。源数据被编辑过时,打开后由宿主刷新重算(透视表
+ * 自身带 cacheSource 范围)。原件无透视表 → 原样返回(零开销)。
+ */
+export declare function restoreOriginalPivotPartsIntoZip(zipBytes: Uint8Array, sourceBytes: Uint8Array): Uint8Array;

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

@@ -15,6 +15,12 @@ export interface XlsxExportOptions {
     fidelity?: 'rebuild' | 'overlay';
     /** 原始 .xlsx 字节(overlay 模式用;由 exporter 从 host 注入,用方一般不直接传) */
     sourceBuffer?: ArrayBuffer;
+    /**
+     * 透视表零件回注开关(默认 false,经 viewer 导出时随 `EditConfig.pivotTable` 自动注入)。
+     * 开启时:① App 内创建的透视表重建成真实 OOXML 零件(pivot-tables.ts);② overlay 模式
+     * 从 `sourceBuffer` 原样搬运原文件的透视表零件(ExcelJS 不建模 pivot,不搬运就丢)。
+     */
+    pivotTables?: boolean;
     /** 长任务进度回调(zip 写出前/后 emit `{stage:'zip'}`;exceljs writeBuffer 黑盒) */
     onProgress?: ExportProgressFn;
     /** 取消信号(zip 阶段前后检查) */