ooxml-excel-editor 1.3.3 → 1.11.0

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,18 @@ export type EditableTarget = {
 export interface EditConfig {
     /** 总开关:默认 false = 只读(行为与历史完全一致) */
     editable?: boolean;
+    /**
+     * 透视表功能开关(默认 false = 关闭)。开启后(还需 `editable`):工具栏 `pivot-table` 入口可见、
+     * `createPivotTable` / `openPivotTableDialog` 等 API 生效、导出 .xlsx 回注真实 OOXML 透视表零件
+     * (含 overlay 模式保留原文件透视表)。关闭时上述行为全部不生效,与历史版本一致。
+     */
+    pivotTable?: boolean;
+    /**
+     * 条件格式编辑开关(默认 false = 关闭,只读渲染)。开启后(还需 `editable`):工具栏 `conditional-format`
+     * 入口可见、`openConditionalFormatDialog` / `addConditionalRule` 等 API 生效、导出 .xlsx 回写条件格式
+     * (rebuild 按模型写全类型;overlay 保留原件未编辑规则原样,只增改用户改的)。关闭时与历史版本一致。
+     */
+    conditionalFormat?: boolean;
     /** 按格只读判定:返回 true = 该格只读。cell 为空格时传 null。pos 为 0-based 行列。 */
     cellReadOnly?: (cell: CellModel | null, pos: {
         row: number;
@@ -80,6 +93,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 阶段前后检查) */

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

@@ -4,6 +4,8 @@ import { CellValue } from './data-access';
 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;
+/** 设/清单元格批注(1.11.0):空批注清除;格不存在且有批注 → 建空格挂批注。 */
+export declare function setCellComment(sheet: SheetModel, row: number, col: number, comment: string): void;
 /** 区域批量设值(2D,左上对齐 range.top/left)。 */
 export declare function setRangeValues(sheet: SheetModel, range: MergeRange, values: CellValue[][]): void;
 /**
@@ -23,6 +25,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

@@ -122,14 +122,22 @@ export interface FreezeInfo {
 }
 /** 条件格式规则(简化版，覆盖常见 4 类) */
 export interface ConditionalRule {
+    /** 稳定 id(解析:`cf-p<n>`;用户新建:`cf-u<n>`)。编辑/删除/导出对账用。1.9.0 起;老数据缺省 */
+    id?: string;
+    /** 来源:'parsed' 从文件解析;'user' app 内新建。overlay 导出据此决定原样回写还是按模型写。缺省按 parsed */
+    origin?: 'parsed' | 'user';
+    /** app 内被编辑过(parsed 规则改过后置 true)。导出:parsed && !dirty → 原样回写 raw;否则按模型写 */
+    dirty?: boolean;
     ranges: MergeRange[];
     priority: number;
     type: 'cellIs' | 'colorScale' | 'dataBar' | 'iconSet' | 'expression' | 'top10' | 'unsupported';
     /** cellIs */
     operator?: string;
     formulae?: string[];
-    /** 命中时套用的样式(cellIs / expression) */
-    style?: Partial<CellStyle>;
+    /** 命中时套用的样式(cellIs / expression / top10)。dxf 各字段都可缺,故 font 也是 Partial */
+    style?: Omit<Partial<CellStyle>, 'font'> & {
+        font?: Partial<Font>;
+    };
     /** colorScale: 2~3 个色标 */
     colorScale?: {
         min: CssColor;
@@ -144,7 +152,20 @@ export interface ConditionalRule {
     /** iconSet */
     iconSet?: {
         name: string;
+        reverse?: boolean;
+    };
+    /** top10: rank 个 / percent 百分比 / bottom 底部 */
+    top10?: {
+        rank: number;
+        percent: boolean;
+        bottom: boolean;
     };
+    /**
+     * 导出专用:解析时原始 ExcelJS rule 对象(含 cfvo 阈值等我们不全建模的字段)。
+     * overlay 导出对"未编辑的 parsed 规则"原样回写保真;编辑色阶/数据条/图标集时尽量改这里的颜色/名称、留住阈值。
+     * 框架无关模型刻意只放它作不透明透传载体,渲染/编辑逻辑不读它。
+     */
+    raw?: unknown;
 }
 /** 图片锚定(像素矩形由 layout 阶段最终算出，这里给逻辑锚点) */
 export interface ImageAnchor {
@@ -195,6 +216,33 @@ export interface ChartSeries {
     values: (number | null)[];
     color?: CssColor;
 }
+/**
+ * 数据验证规则(完整版,1.8.0):承载校验语义 —— 编辑时拦截非法输入 + 输入/出错提示。
+ * 渲染层只用 list 型画下拉箭头(见 SheetModel.dataValidations / dataValidationLists,从这里派生)。
+ * formulae 已尽量解析成字面量:整数/小数/文本长度 → number;日期/时间 → number(序列值)或原始串;
+ * list → 选项数组在 options;custom → 公式串(暂不求值,放行)。
+ */
+export interface DataValidationRule {
+    range: MergeRange;
+    type: 'list' | 'whole' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom';
+    /** 比较运算符(whole/decimal/date/time/textLength 用;list/custom 不用) */
+    operator?: 'between' | 'notBetween' | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual';
+    /** 约束操作数(between 用前两个;单目用第一个)。原样保留,校验时按 type 解析 */
+    formulae: (string | number)[];
+    /** 允许留空(空值不校验) */
+    allowBlank: boolean;
+    /** list 型可选值(= dataValidationLists 同源) */
+    options?: string[];
+    /** 出错提示(showErrorMessage 时,非法输入弹) */
+    showErrorMessage?: boolean;
+    errorStyle?: 'stop' | 'warning' | 'information';
+    errorTitle?: string;
+    error?: string;
+    /** 输入提示(showInputMessage 时,选中该格弹气泡) */
+    showInputMessage?: boolean;
+    promptTitle?: string;
+    prompt?: string;
+}
 export interface SheetModel {
     name: string;
     index: number;
@@ -219,12 +267,21 @@ export interface SheetModel {
     autoFilterRange?: MergeRange;
     /** 含"列表"型数据验证的区域(选中时画下拉箭头) */
     dataValidations: MergeRange[];
+    /** 列表型数据验证的可选值(点下拉箭头弹选;range 内任一格命中即用 options)。可选 —— 老数据/无选项时缺省 */
+    dataValidationLists?: {
+        range: MergeRange;
+        options: string[];
+    }[];
+    /** 完整数据验证规则(校验语义:编辑拦截 + 输入/出错提示)。1.8.0 起;上面两个字段从这里派生 */
+    dataValidationRules?: DataValidationRule[];
     images: ImageAnchor[];
     charts: ChartSpec[];
     /** 形状 / 文本框(DrawingML sp) */
     shapes: ShapeSpec[];
     /** 迷你图(单元格内嵌折线/柱/盈亏图) */
     sparklines: Sparkline[];
+    /** 透视表只读 UI 元数据:用于叠加字段按钮/下拉箭头;数据仍按普通单元格显示 */
+    pivotTables: PivotTableModel[];
     /** 手动分页符(0-based 边界索引): 在这些行上方/列左侧画分页虚线 */
     pageBreaks?: {
         rows: number[];
@@ -284,6 +341,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 +401,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, ConditionalRule, 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,40 @@ 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;
+    /** 当前表的条件格式规则集(只读副本)。 */
+    getConditionalRules(): ConditionalRule[];
+    /** 新增一条规则(未给 id 自动派、origin 默认 'user');返回新 id 或 false。 */
+    addConditionalRule(rule: Partial<ConditionalRule> & Pick<ConditionalRule, 'ranges' | 'type'>): string | false;
+    /** 按 id 改一条规则(浅合并)。 */
+    updateConditionalRule(ruleId: string, patch: Partial<ConditionalRule>): boolean;
+    /** 按 id 删一条规则。 */
+    removeConditionalRule(ruleId: string): boolean;
+    /** 整表替换规则集。 */
+    setConditionalRules(rules: ConditionalRule[]): boolean;
+    /** 打开条件格式管理对话框(框架无关 DOM,三壳共用)。 */
+    openConditionalFormatDialog(): boolean;
+    /** 给当前选区设数字格式代码(numFmt)。需 editable。1.11.0 */
+    setSelectionNumberFormat(code: string): boolean;
+    /** 打开数字格式编辑对话框(框架无关 DOM,三壳共用)。需 editable + 选区。1.11.0 */
+    openNumberFormatDialog(): boolean;
+    /** 读某格批注(无则 '')。1.11.0 */
+    getCellComment(row: number, col: number): string;
+    /** 设/清某格批注(空串 = 删除)。需 editable。1.11.0 */
+    setCellComment(row: number, col: number, comment: string): boolean;
+    /** 打开批注编辑对话框(默认活动格)。需 editable。1.11.0 */
+    openCommentEditor(row?: number, col?: number): boolean;
     /** 导出当前/指定表为图片 Blob(默认 png) */
     exportImage(opts?: ImageExportOptions): Promise<Blob>;
     /** 导出为图片并触发下载 */
@@ -147,11 +204,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

@@ -147,6 +147,11 @@ export declare class CanvasRenderer {
     };
     private selection;
     setSelection(sel: MergeRange | null): void;
+    /** 自动填充柄可见(= editable;1.10.0)。控制器创建后设置。 */
+    showFillHandle: boolean;
+    /** 自动填充拖拽预览区(目标范围;拖拽中由控制器设)。 */
+    private fillPreview;
+    setFillPreview(range: MergeRange | null): void;
     private findHits;
     private findCurrent;
     /** 扫描非空单元格,返回命中的格(按阅读顺序: 先行后列) */
@@ -174,6 +179,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 +240,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;
     /**
@@ -242,6 +259,17 @@ export declare class CanvasRenderer {
     private drawPageBreaks;
     /** 选区高亮: 半透明填充 + 蓝色边框，裁到表头以下的正文区。 */
     private drawSelection;
+    /** 自动填充柄的屏幕矩形(选区右下角的小方块);选区不可见/无选区返 null。 */
+    fillHandleRect(view: ViewState): {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    /** 点 (px,py) 是否落在填充柄上(命中区比绘制略大,好点中)。 */
+    fillHandleAt(view: ViewState, px: number, py: number): boolean;
+    /** 拖拽预览:目标范围的虚线框(超出源选区的部分)。 */
+    private drawFillPreview;
     private drawPane;
     /** 取某格指定边的边框样式(供相邻共享边取较重者);越界/无格返回 undefined */
     private borderEdgeOf;

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/comment-dialog-host.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 批注编辑对话框(框架无关 DOM,三壳共用一份)。1.11.0 新增。
+ * 右键「插入/编辑批注」打开:多行文本框 + 确定/删除/取消。确定回调批注文本(空 = 删除)。
+ */
+export interface CommentDialogOptions {
+    cellRef: string;
+    current: string;
+    onApply: (text: string) => void;
+}
+export declare class CommentDialogHost {
+    private el;
+    private cleanup;
+    show(opts: CommentDialogOptions): void;
+    close(): void;
+    dispose(): void;
+}

package/dist/core/viewer/conditional-format-dialog-host.d.ts

@@ -0,0 +1,30 @@
+import { ConditionalRule, MergeRange } from '../model/types';
+export interface ConditionalDialogOptions {
+    rules: ConditionalRule[];
+    selection: MergeRange | null;
+    genId: () => string;
+    onApply: (rules: ConditionalRule[]) => void;
+}
+export declare class ConditionalFormatDialogHost {
+    private el;
+    private cleanup;
+    private rules;
+    private selection;
+    private genId;
+    private onApply;
+    private editing;
+    show(opts: ConditionalDialogOptions): void;
+    private renderList;
+    private startEdit;
+    private renderEditor;
+    private defaultForType;
+    /** 类型专属字段。 */
+    private renderFields;
+    /** 通用「格式」字段(填充色 + 字体色 + 加粗),cellIs/expression/top10 用。 */
+    private formatFields;
+    /** 从 DOM 收集字段写回 draft。 */
+    private collectFields;
+    private collectFormat;
+    close(): void;
+    dispose(): void;
+}