ooxml-excel-editor 1.3.3 → 1.7.0

package/dist/core/index.d.ts

@@ -10,7 +10,7 @@ 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 type { WorkbookModel, SheetModel, CellModel, CellStyle, MergeRange, ConditionalRule, ChartSpec, ImageAnchor, ShapeSpec, Sparkline, PivotTableModel, PivotButton, PivotTableLayout, PivotFilterRule, PivotValueRule, PivotSummary, PivotFilterMode, 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';
@@ -20,6 +20,8 @@ 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 type { PasteBehavior } from './edit/paste-behavior';
+export { DEFAULT_PASTE_BEHAVIOR, PASTE_PRESET_VALUES_ONLY, resolvePasteBehavior } from './edit/paste-behavior';
 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';
@@ -41,7 +43,7 @@ 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 type { ExcelPlugin, ExcelPluginContext, OverlayContext, OverlayNode, PluginEvent, Rect, ToolbarItem, ViewerApi, CreatePivotTableOptions, PivotOutput, } from './plugin';
 export { GridMetrics, colIndexToLetters } from './layout/grid-metrics';
 export { formatValue } from './format/number-format';
 export { DEFAULT_THEME, mergeTheme } from './render/theme';

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

@@ -23,6 +23,8 @@ export declare function cloneImageAnchor(a: ImageAnchor): ImageAnchor;
 export declare function addImage(sheet: SheetModel, anchor: ImageAnchor, index?: number): number;
 /** 删一张图(调用方负责为 undo 捕获前态)。 */
 export declare function removeImage(sheet: SheetModel, index: number): void;
+/** 整个 CellModel 落格(承载公式/超链/批注/富文本/dispImgId 等 setCellValue 推不出的字段)+ 撑维度。 */
+export declare function setCellModel(sheet: SheetModel, cell: CellModel): void;
 /**
  * 浮动图 → WPS 单元格内嵌图(DISPIMG)。
  * 取 sheet.images[imageIndex] 的字节登记到 wb.cellImages(新 id),目标格设 =DISPIMG 公式 + dispImgId,

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

@@ -219,12 +219,19 @@ export interface SheetModel {
     autoFilterRange?: MergeRange;
     /** 含"列表"型数据验证的区域(选中时画下拉箭头) */
     dataValidations: MergeRange[];
+    /** 列表型数据验证的可选值(点下拉箭头弹选;range 内任一格命中即用 options)。可选 —— 老数据/无选项时缺省 */
+    dataValidationLists?: {
+        range: MergeRange;
+        options: string[];
+    }[];
     images: ImageAnchor[];
     charts: ChartSpec[];
     /** 形状 / 文本框(DrawingML sp) */
     shapes: ShapeSpec[];
     /** 迷你图(单元格内嵌折线/柱/盈亏图) */
     sparklines: Sparkline[];
+    /** 透视表只读 UI 元数据:用于叠加字段按钮/下拉箭头;数据仍按普通单元格显示 */
+    pivotTables: PivotTableModel[];
     /** 手动分页符(0-based 边界索引): 在这些行上方/列左侧画分页虚线 */
     pageBreaks?: {
         rows: number[];
@@ -284,6 +291,53 @@ export interface Sparkline {
     color?: CssColor;
     negativeColor?: CssColor;
 }
+/** 透视表字段按钮(只读 UI):按钮锚在对应标题/筛选单元格上。 */
+export interface PivotButton {
+    row: number;
+    col: number;
+    label: string;
+    kind: 'row' | 'col' | 'page' | 'data' | 'field';
+}
+/** 透视表模型(只读):范围来自 pivotTableDefinition/location,字段来自 cacheFields + axis/dataFields。 */
+export interface PivotTableModel {
+    name: string;
+    range: MergeRange;
+    fields: string[];
+    buttons: PivotButton[];
+    /** 静态透视表来源:当前模型内的源表 index + 源数据区域。用于运行时重建/后续导出。 */
+    source?: {
+        sheetIndex: number;
+        range: MergeRange;
+    };
+    /** 运行时透视布局元数据:字段 index 均为源数据区域内的绝对列 index。 */
+    layout?: PivotTableLayout;
+    /** 已折叠的外层行分组 key(行字段 ≥2 时,外层分组可折叠隐藏明细;空/缺省 = 全展开)。 */
+    collapsed?: string[];
+    /** 运行时:可折叠的分组表头所在输出行(绝对行号)+ 外层 key;每次重算刷新,供渲染折叠按钮 + 命中测试。 */
+    rowGroups?: {
+        row: number;
+        key: string;
+    }[];
+}
+export type PivotSummary = 'sum' | 'count' | 'avg' | 'max' | 'min';
+/** all=全部 / non-empty=非空 / equals=单值等于 / include=多选包含(values 列出保留值,空=不约束)。 */
+export type PivotFilterMode = 'all' | 'non-empty' | 'equals' | 'include';
+export interface PivotFilterRule {
+    field: number;
+    mode: PivotFilterMode;
+    value?: string;
+    values?: string[];
+}
+export interface PivotValueRule {
+    field: number;
+    summary: PivotSummary;
+}
+export interface PivotTableLayout {
+    filters: PivotFilterRule[];
+    columns: number[];
+    rows: number[];
+    values: PivotValueRule[];
+}
 export interface WorkbookModel {
     sheets: SheetModel[];
     activeSheet: number;
@@ -297,6 +351,13 @@ export interface WorkbookModel {
     cellImages?: Map<string, CellImage>;
 }
 export declare const cellKey: (row: number, col: number) => string;
+/**
+ * 规范的"空白默认样式"——所有 SheetModel.styles[0] 必须是它(中性、无填充、无边框)。
+ * 空格 / 新建格 / setCellValue 落的格 / applyStyleOverride 的兜底基样式都回落到 styleId 0,
+ * 因此 index 0 绝不能是"恰好第一个被解析到的单元格样式"(否则那个格的底色/边框会冒到所有默认格,
+ * 见 parser 把首格 A1 绿底当默认导致粘贴/编辑串色的 bug)。loader-json / parser / clipboard-snapshot 共用此工厂。
+ */
+export declare function makeDefaultStyle(): CellStyle;
 /** 数据钩子: 解析后、渲染前改模型(返回新模型或就地改) */
 export type TransformModelFn = (workbook: WorkbookModel) => WorkbookModel | void;
 /** 单元格样式覆盖(各字段可选;font/fill/borders 允许部分,与解析样式浅合并) */

package/dist/core/parser/pivot-parser.d.ts

@@ -0,0 +1,3 @@
+import { RawPackage } from './raw-xml';
+import { SheetModel } from '../model/types';
+export declare function attachPivotTables(pkg: RawPackage, sheets: SheetModel[]): void;

package/dist/core/plugin.d.ts

@@ -1,10 +1,11 @@
-import { CellStyleFn, CellStyleOverride, ImageAnchor, MergeRange, TransformModelFn, WorkbookModel } from './model/types';
+import { CellStyleFn, CellStyleOverride, ImageAnchor, MergeRange, PivotTableLayout, TransformModelFn, WorkbookModel } from './model/types';
 import { CellValue, ReadOptions, SheetToJSONOptions } from './model/data-access';
 import { CellSnapshot } from './model/snapshot';
 import { CellInspection } from './model/inspect';
 import { MenuItem } from './edit/context-menu';
 import { EditorResolver } from './edit/editor-context';
 import { EditableTarget } from './edit/types';
+import { PasteBehavior } from './edit/paste-behavior';
 import { ViewerTheme } from './render/theme';
 import { ExcelSource } from './loader';
 import { ImageExportOptions, PdfExportOptions, PrintOptions } from './export/types';
@@ -15,6 +16,24 @@ export interface Rect {
     w: number;
     h: number;
 }
+export type PivotOutput = {
+    kind: 'current-sheet';
+    cell: string;
+} | {
+    kind: 'new-sheet';
+};
+export interface CreatePivotTableOptions {
+    /** 源数据区域,第一行作为字段名。缺省时使用当前选区。 */
+    sourceRange?: MergeRange;
+    /** 源数据所在 sheet index。缺省为当前活动表。 */
+    sourceSheetIndex?: number;
+    /** 输出位置。缺省为当前表源区域右侧空两列。 */
+    output?: PivotOutput;
+    /** 透视表布局。缺省:第一个文本字段为行字段,第一个数值字段为值字段。 */
+    layout?: Partial<PivotTableLayout>;
+    /** 是否打开右侧字段面板。缺省 false;工具栏入口会打开。 */
+    showPanel?: boolean;
+}
 export type PluginEvent = 'cell-click' | 'cell-dblclick' | 'selection-change' | 'sheet-change' | 'hyperlink-click' | 'cell-change' | 'edit-start' | 'edit-commit' | 'dim-change' | 'dirty-change' | 'image-change' | 'struct-change' | 'permission-denied';
 /**
  * 权限拒绝事件 payload (Phase A, 2026-06-08):mutation 因 editable / editableTargets /
@@ -24,8 +43,8 @@ export type PluginEvent = 'cell-click' | 'cell-dblclick' | 'selection-change' |
  * 一次操作只 emit 一次 (避免 N 张图 spam N 次).
  */
 export interface PermissionDeniedPayload {
-    /** 触发的操作类型 */
-    reason: 'paste' | 'merge' | 'unmerge' | 'image-place' | 'image-convert' | 'dimension' | 'other';
+    /** 触发的操作类型('copy' = 复制图片超字节预算,已降级为无图复制,非真正"拒绝") */
+    reason: 'paste' | 'merge' | 'unmerge' | 'image-place' | 'image-convert' | 'dimension' | 'copy' | 'other';
     /** 被拒的目标格 (粘贴 / 合并 / 图片转换 等场景下的具体位置;'dimension' 时可空) */
     cells: Array<{
         row: number;
@@ -47,6 +66,10 @@ export interface ViewerApi {
     setActiveSheet(index: number): void;
     getSelection(): MergeRange | null;
     setSelection(range: MergeRange): void;
+    /** 滚动到指定单元格;select=true 时同步选中目标格。 */
+    scrollToCell(row: number, col: number, opts?: {
+        select?: boolean;
+    }): boolean;
     rectOf(row: number, col: number): Rect | null;
     rectOfRange(range: MergeRange): Rect | null;
     redraw(): void;
@@ -61,6 +84,18 @@ export interface ViewerApi {
     setEditableTargets(targets: EditableTarget | EditableTarget[] | undefined): void;
     /** 当前生效的可编辑白名单. `undefined` 表示未启用白名单. */
     getEditableTargets(): EditableTarget | EditableTarget[] | undefined;
+    /** 按活动单元格所在列排序;未开启自动筛选时会先按选区/已用区建立筛选范围。 */
+    sortActiveColumn(dir: 'asc' | 'desc'): boolean;
+    /** 通过 API 直接创建静态透视表,不依赖当前页面选区或对话框。需开启 `pivotTable` + `editable` 配置(默认均关)。 */
+    createPivotTable(opts: CreatePivotTableOptions): boolean;
+    /** 基于当前选区创建静态透视汇总表;未传 opts 时使用默认布局并输出到右侧。需 `pivotTable` + `editable`。 */
+    createPivotTableFromSelection(opts?: {
+        rowFieldIndex?: number;
+        valueFieldIndex?: number;
+        output?: PivotOutput;
+    }): boolean;
+    /** 打开透视表字段选择对话框,再从当前选区创建静态透视汇总表。需 `pivotTable` + `editable`。 */
+    openPivotTableDialog(): boolean;
     /** 导出当前/指定表为图片 Blob(默认 png) */
     exportImage(opts?: ImageExportOptions): Promise<Blob>;
     /** 导出为图片并触发下载 */
@@ -147,11 +182,18 @@ export interface ViewerApi {
         row: number;
         col: number;
     }): boolean;
-    /** 解析 Excel/WPS 复制的剪贴板 HTML → 富粘贴(值+字体/颜色/填充/边框/对齐+合并+data-uri图),整体单次撤销 */
+    /** 解析 Excel/WPS 复制的剪贴板 HTML → 富粘贴(值+字体/颜色/填充/边框/对齐+合并+data-uri图),整体单次撤销。
+     *  behaviorOverride = 逐次粘贴行为预设(右键「选择性粘贴」用;缺省走 setPasteBehavior 设的默认) */
     pasteRichHtml(html: string, at?: {
         row: number;
         col: number;
-    }): boolean;
+    }, behaviorOverride?: Partial<PasteBehavior> | null): boolean;
+    /** 读当前粘贴行为配置(完整) */
+    getPasteBehavior(): PasteBehavior;
+    /** 设粘贴行为默认(缺项回落默认);影响 Ctrl+V / 右键「粘贴」 */
+    setPasteBehavior(cfg: Partial<PasteBehavior> | null): void;
+    /** 打开「粘贴行为配置」面板(框架无关 DOM,三壳共用);需 editable。返回是否打开 */
+    openPasteConfigDialog(): boolean;
     /** 把一张图片 blob 落到活动格(转内嵌图);剪贴板单图 / 拖文件进网格用 */
     pasteImageBlob(blob: Blob, at?: {
         row: number;

package/dist/core/render/canvas-renderer.d.ts

@@ -174,6 +174,11 @@ export declare class CanvasRenderer {
     };
     /** 屏幕坐标是否落在某个自动筛选表头的下拉按钮上;是则返回列号 */
     filterButtonAt(view: ViewState, px: number, py: number): number | null;
+    /** 点击是否落在"活动格的数据验证下拉箭头"上(箭头只画在选区左上的列表验证格);是则返回该格。 */
+    dataValidationButtonAt(view: ViewState, px: number, py: number): {
+        row: number;
+        col: number;
+    } | null;
     /** 屏幕坐标 → 单元格(0-based)。落在表头或越界返回 null。 */
     cellAtScreen(view: ViewState, x: number, y: number): {
         row: number;
@@ -230,6 +235,13 @@ export declare class CanvasRenderer {
      * 用 this.{canvas,ctx,metrics,freeze,selection,dpr} 当前值,flags 控制 UI 装饰是否绘制。
      */
     private paint;
+    /** 画各透视表的行分组折叠/展开按钮(贴在分组表头格最左)。 */
+    private drawPivotToggles;
+    /** 屏幕坐标是否落在某透视表的折叠按钮上;是则返回 { tableIdx, key }。 */
+    pivotToggleAt(view: ViewState, px: number, py: number): {
+        tableIdx: number;
+        key: string;
+    } | null;
     /** 查找高亮: 所有命中淡黄,当前项橙色描边 */
     private drawFind;
     /**

package/dist/core/render/pivot-toggle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 透视表行分组折叠/展开按钮(canvas 绘制 + 控制器命中测试),与 autofilter 下拉按钮同款套路:
+ * 画在分组表头行最左格内,点击由 ViewerController.onMouseDown 经 CanvasRenderer.pivotToggleAt 命中。
+ * 只在多行字段(外层分组可折叠)时出现,导出时不画(导出件靠真 OOXML 透视表自身的展开)。
+ */
+/** 折叠按钮方框:左对齐贴在分组表头格内、垂直居中;格太窄(<8px)返回 null 不画。 */
+export declare function pivotToggleBox(cellX: number, cellY: number, cellW: number, cellH: number): {
+    x: number;
+    y: number;
+    size: number;
+} | null;
+/** 画一个折叠按钮:方框 + 横杠(展开态显示 −)/ 横竖杠(折叠态显示 +)。 */
+export declare function drawPivotToggle(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, collapsed: boolean): void;

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

@@ -5,11 +5,14 @@ import { CellValue, SheetToJSONOptions } from '../model/data-access';
 import { CellSnapshot } from '../model/snapshot';
 import { CellInspection } from '../model/inspect';
 import { MenuItem } from '../edit/context-menu';
+import { PivotOutputChoice } from './pivot-dialog-host';
+import { PasteBehavior } from '../edit/paste-behavior';
 import { EditorCommitValue, EditorResolver } from '../edit/editor-context';
 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';
+import { CreatePivotTableOptions } from '../plugin';
 export type Cell = {
     row: number;
     col: number;
@@ -70,6 +73,8 @@ export interface ViewerControllerHooks {
     onFindChange: () => void;
     /** 筛选状态/浮层变化(壳据此 +1 让 FilterPopup / 工具栏重算) */
     onFilterChange: () => void;
+    /** core 里新增/切换工作表时通知壳同步 activeSheet。 */
+    onActiveSheetChange?: (index: number) => void;
     /** 编辑事件(cell-change/edit-start/edit-commit;壳转 emit + 插件派发) */
     onEditEvent: (event: EditEventName, payload: unknown) => void;
     /** 右键菜单触发前(Plan C):用户可调 `preventDefault()` 阻止内置菜单弹出(然后自渲染) */
@@ -123,6 +128,12 @@ export declare class ViewerController {
     /** 右键上下文菜单宿主(G3;body 级 DOM,框架无关) */
     private menuHost;
     private lightbox;
+    private pivotDialog;
+    private pivotPanel;
+    private pasteConfigDialog;
+    private readonlyPrompt;
+    /** 透视表"活刷新"重入兜底:recompute 内部 setCellValue 不再触发 onModelChange,此旗保险。 */
+    private pivotRefreshing;
     private lightboxEnabled;
     /** 用户的右键菜单 transform 回调(Plan C):`(ctx, items) => MenuItem[] | undefined` */
     private ctxMenuTransform;
@@ -163,6 +174,8 @@ export declare class ViewerController {
     private editorHost;
     /** 按格解析编辑器(壳合并 plugin.editor + prop.editor 后注入;E2) */
     private editorResolver?;
+    /** paste 事件处理器(绑在 scroller 上;Ctrl+V 走它拿**原始**剪贴板 HTML,避开 clipboard.read() 的净化) */
+    private readonly onPasteHandler;
     constructor(els: ViewerControllerEls, hooks: ViewerControllerHooks);
     /** 切表/换簿/主题变化: 清状态,重建渲染器,重置滚动,量尺寸,建叠加层,绘制,按需重跑查找 */
     rebuild(sheet: SheetModel, workbook: WorkbookModel, zoom: number, opts: RendererOptions): void;
@@ -265,6 +278,10 @@ export declare class ViewerController {
     selectAll(): void;
     /** 选中单个单元格并滚动到视图(查找定位用);range 模式,anchor=active */
     selectCell(row: number, col: number): void;
+    /** 滚动到指定单元格;select=true 时同步选中目标格。 */
+    scrollToCell(row: number, col: number, opts?: {
+        select?: boolean;
+    }): boolean;
     /** 命令式设选区(anchor=左上, active=右下) */
     setSelectionRange(range: MergeRange): void;
     private setCell;
@@ -296,7 +313,8 @@ export declare class ViewerController {
     onContextMenu(e: MouseEvent): void;
     /** 算右键 ctx:命中格 + 选区调整;非内容区 / 无 renderer 返 null */
     private buildContextMenuCtx;
-    /** 编辑模式下的内置菜单项(独立提取,便于 transform 回调拿到再二次加工) */
+    /** 内置右键菜单项(独立提取,便于 transform 回调拿到再二次加工)。
+     *  只读模式:只返回**不改数据**的项(复制) —— 复制不修改数据源,只读也该能用;编辑模式给全套。 */
     buildBuiltinContextMenuItems(ctx: ContextMenuCtx): MenuItem[];
     /** 设置用户 transform 回调(`(ctx, items) => MenuItem[] | undefined`);壳侧调用 */
     setContextMenuTransform(fn: ContextMenuTransform | null | undefined): void;
@@ -309,13 +327,26 @@ export declare class ViewerController {
     private pageRows;
     onKeyDown(e: KeyboardEvent): void;
     private scrollActiveIntoView;
+    private scrollCellIntoView;
     copySelection(): Promise<void>;
     /**
-     * 从系统剪贴板粘贴。优先 `clipboard.read()` 拿 **text/html**(Excel/WPS 复制 → 富粘贴:值+字体+颜色+
-     * 填充+边框+合并),否则单张图片 → 落格,再否则回退 **text/plain** TSV(`pasteText`)。需读权限/安全上下文,
-     * 受限时回退 readText;都失败返 false。
+     * paste 事件粘贴(Ctrl+V 主路径,绑在 scroller 上)。`e.clipboardData` 给的是**原始未净化** HTML/图片/文本 ——
+     * 关键:`navigator.clipboard.read()`(pasteFromClipboard 用)会净化 HTML、删掉 `<style>` 块和注释,而 WPS/Excel
+     * 的格式(CSS 类)、数字格式(mso-number-format)、内嵌图(VML o:gfxdata)全在那里面 → 走 read 必丢。paste 事件不净化。
+     * 我们自己复制的快照(data-ooxml-clip)也一并原样拿到,1:1 不受影响。
+     */
+    /**
+     * 统一出口(核心层唯一只读反馈点):**任何**改数据的操作撞只读 → EditController/控制器都经 `host.emit` 走到这里,
+     * 按 `readOnlyPrompt` 配置(dialog/toast/none)弹一次内置提醒,再转壳事件。新增输入方式只要照常走 EditController
+     * 的 API(其内 `isEditable` 中央闸门已逐格拦截 + emit permission-denied),无需各自重写只读检查/提醒。
      */
-    pasteFromClipboard(): Promise<boolean>;
+    private emitEditEvent;
+    onPaste(e: ClipboardEvent): void;
+    /**
+     * 从系统剪贴板粘贴(右键菜单"粘贴"等无 paste 事件的入口用)。`clipboard.read()` 拿 text/html —— 注意它会**净化**
+     * HTML(删 `<style>`/注释),所以从 WPS/Excel 粘的格式不如 Ctrl+V(走 onPaste 的原始 HTML)全。否则单图 / TSV 兜底。
+     */
+    pasteFromClipboard(behaviorOverride?: Partial<PasteBehavior> | null): Promise<boolean>;
     /**
      * 解析 Excel/WPS 复制的剪贴板 HTML(text/html)→ 富粘贴:值 + 字体/颜色/填充/边框/对齐 + 合并 + data-uri 图,
      * **整体单次撤销**。无 `<table>` 返 false(调用方回退 TSV)。at 缺省用活动格。
@@ -323,7 +354,13 @@ export declare class ViewerController {
     pasteRichHtml(html: string, at?: {
         row: number;
         col: number;
-    }): boolean;
+    }, behaviorOverride?: Partial<PasteBehavior> | null): boolean;
+    /** 读当前粘贴行为配置(完整)。 */
+    getPasteBehavior(): PasteBehavior;
+    /** 设粘贴行为默认(缺项回落默认);影响 Ctrl+V / 右键「粘贴」。右键「选择性粘贴」逐次预设走 pasteRichHtml 的第 3 参。 */
+    setPasteBehavior(cfg: Partial<PasteBehavior> | null): void;
+    /** 打开「粘贴行为配置」面板(框架无关 DOM,三壳共用);应用即 setPasteBehavior。需 editable。 */
+    openPasteConfigDialog(): boolean;
     /** 把一张图片 blob 落到活动格(转内嵌图);剪贴板单图粘贴 / 拖文件进网格用。 */
     pasteImageBlob(blob: Blob, at?: {
         row: number;
@@ -361,6 +398,8 @@ export declare class ViewerController {
     /** 重算筛选导致的隐藏行并应用到模型(行隐藏机制 → 几何归零) */
     private applyFilters;
     /** 点中下拉按钮 / 命令式: 打开某列筛选浮层(算去重值 + 已选 + 屏幕位置) */
+    /** 列表型数据验证下拉:在箭头处弹可选值菜单(复用右键菜单宿主),点选 → editCell(undo 可回退)。 */
+    private openDataValidationPicker;
     openFilterPopup(col: number): void;
     closeFilterPopup(): void;
     /** 浮层「确定」: 勾选值落筛选态(全选=取消该列;子集=保留;空集=全隐藏)。 */
@@ -383,6 +422,43 @@ export declare class ViewerController {
         col: number;
         dir: 'asc' | 'desc' | null;
     };
+    /** 按活动单元格所在列排序;若当前表未开启自动筛选,先按选区/已用区建立筛选范围。 */
+    sortActiveColumn(dir: 'asc' | 'desc'): boolean;
+    /** 打开 WPS 式透视表入口:确认选区字段后生成静态透视汇总表。需 `pivotTable` + `editable` 配置。 */
+    openPivotTableDialog(): boolean;
+    /** 兼容旧 API:基于当前选区创建静态透视汇总表。 */
+    createPivotTableFromSelection(opts?: {
+        rowFieldIndex?: number;
+        valueFieldIndex?: number;
+        output?: PivotOutputChoice;
+    }): boolean;
+    /** 通过 API 直接创建静态透视表,不依赖页面选区或对话框。需 `pivotTable` + `editable` 配置。 */
+    createPivotTable(opts: CreatePivotTableOptions): boolean;
+    private showPivotPanel;
+    /**
+     * 透视表的唯一重算入口:读 pivot.source/layout/collapsed → 重建静态结果 → 清旧区写新区 →
+     * 刷新 range/buttons/rowGroups。被面板改布局、源数据"活刷新"、折叠/展开三处共用,避免逻辑分叉。
+     */
+    private recomputePivot;
+    /**
+     * 源数据"活刷新":任何模型变更(编辑/粘贴/撤销/重做都经 onModelChange)后,把所有透视表按其源区域重算,
+     * 让结果跟着源数据走(WPS 透视表的"活"语义)。重算用 setCellValue 直接改模型(不经命令栈,不再触发
+     * onModelChange),pivotRefreshing 兜底防重入。功能开关关闭或无透视表时零开销。
+     */
+    private refreshPivotsAfterEdit;
+    /** 折叠/展开某个外层行分组(行字段 ≥2 时由折叠按钮触发),重算并重绘。 */
+    private togglePivotGroup;
+    /**
+     * 重建透视结果为二维单元格数组(框架无关纯计算)。
+     * 行字段第 1 个为外层分组,其余为内层明细 → 多行字段时产出可折叠的"大纲"(外层分组行带小计 +
+     * 内层缩进明细);单行字段退化为扁平(每个值一行,无折叠)。列字段横向展开,值字段可多个。
+     * groups 列出可折叠的分组表头行(相对 top 的偏移 + 外层 key),供渲染折叠按钮 + 命中测试。
+     */
+    private buildPivotRows;
+    private failPivot;
+    private pivotFieldOptions;
+    private pivotFieldOptionsForSheet;
+    private pivotCellText;
     /**
      * 按某列对自动筛选数据区排序(只读视图重排:移动行内容 + 行高,不改文件)。
      * 合并区与数据区相交则拒绝(与 Excel 一致)。排序前会清除该表筛选,避免行索引快照错位。

package/dist/core/viewer/overlay-manager.d.ts

@@ -13,6 +13,7 @@ export declare class OverlayManager {
     private imageEls;
     private chartPlaceholders;
     private shapeEls;
+    private pivotButtonEls;
     /** 防止异步加载 echarts 期间已切表/重建: build 自增,await 后 token 变了就放弃 */
     private buildToken;
     constructor(quads: OverlayQuads);

package/dist/core/viewer/paste-config-host.d.ts

@@ -0,0 +1,12 @@
+import { PasteBehavior } from '../edit/paste-behavior';
+export interface PasteConfigDialogOptions {
+    current: PasteBehavior;
+    onSubmit: (cfg: PasteBehavior) => void;
+}
+export declare class PasteConfigDialogHost {
+    private el;
+    private cleanup;
+    show(opts: PasteConfigDialogOptions): void;
+    close(): void;
+    dispose(): void;
+}

package/dist/core/viewer/pivot-dialog-host.d.ts

@@ -0,0 +1,48 @@
+import { PivotTableLayout as PivotPanelLayout } from '../model/types';
+export interface PivotFieldOption {
+    index: number;
+    label: string;
+    numeric: boolean;
+}
+export interface PivotDialogOptions {
+    rangeLabel: string;
+    defaultOutputCell: string;
+    onSubmit: (output: PivotOutputChoice) => void;
+}
+export type PivotOutputChoice = {
+    kind: 'current-sheet';
+    cell: string;
+} | {
+    kind: 'new-sheet';
+};
+export interface PivotPanelOptions {
+    fields: PivotFieldOption[];
+    filterValues: Record<number, string[]>;
+    layout: PivotPanelLayout;
+    onChange: (layout: PivotPanelLayout) => void;
+}
+export declare class PivotDialogHost {
+    private el;
+    private cleanup;
+    show(opts: PivotDialogOptions): void;
+    close(): void;
+    dispose(): void;
+}
+export declare class PivotFieldPanelHost {
+    private el;
+    private opts;
+    /** 当前正在编辑筛选值的字段 index(null = 未展开筛选明细面板) */
+    private activeFilterField;
+    show(opts: PivotPanelOptions): void;
+    close(): void;
+    dispose(): void;
+    private render;
+    private fieldRow;
+    private area;
+    private updateLayout;
+    /** 筛选 chip 上的小按钮:显示当前筛选状态(全部/非空/N 项),点开底部明细面板编辑。 */
+    private filterSummaryBtn;
+    /** 底部筛选明细面板:全部/非空/多选 三模式 + 多选时的值复选框列表(WPS 风格勾选筛选)。 */
+    private filterDetail;
+    private summarySelect;
+}

package/dist/core/viewer/readonly-prompt-host.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 只读提醒 UI(框架无关 DOM,三壳共用)。粘贴撞只读格时,按配置:
+ *  - 'dialog'(默认):弹窗列出**具体哪些格**只读(A1 引用),让用户明确知道哪部分没粘上;
+ *  - 'toast':顶部气泡,简短提示 + 自动消失;
+ *  - 'none':不弹内置 UI(只走 permission-denied 事件,消费方自处理)。
+ * 逐格精确:cells 是被跳过的只读格列表。
+ */
+export type ReadOnlyPromptMode = 'dialog' | 'toast' | 'none';
+export declare class ReadOnlyPromptHost {
+    private el;
+    private toastEl;
+    private toastTimer;
+    private cleanup;
+    show(mode: ReadOnlyPromptMode, message: string, cells: Array<{
+        row: number;
+        col: number;
+    }>): void;
+    private showToast;
+    private closeToast;
+    private showDialog;
+    close(): void;
+    dispose(): void;
+}