@guodun/antdv 1.2.5 → 1.3.1

package/dist/types/components/pro-contract-template-designer/src/composables/use-template-designer.d.ts

@@ -0,0 +1,139 @@
+import { JSONContent } from '@tiptap/core';
+import { ContractTemplateData, ContractTemplateExportResult, ContractTemplateFieldStyle, ContractTemplateFieldType, ContractTemplateFieldTypeOption, ContractTemplatePage, ContractTemplatePageFormat, ContractTemplatePageSize, ContractTemplateSigningPlacement, ContractTemplateValidationError, ContractTemplateVariable } from '../types';
+/** 内置页面尺寸预设，宽高按 96 DPI 像素给出。 */
+export declare const PAGE_SIZE_OPTIONS: ContractTemplatePageSize[];
+/** 默认页面尺寸 A4；拷贝一份避免调用方改写预设数组。 */
+export declare const DEFAULT_PAGE_SIZE: ContractTemplatePageSize;
+/** 新建变量的默认展示样式；变量自身样式和类型默认值会在其之上覆盖。 */
+export declare const DEFAULT_FIELD_STYLE: ContractTemplateFieldStyle;
+/** 多行文本变量的默认行数。 */
+export declare const DEFAULT_MULTILINE_ROWS = 3;
+/** 多行文本变量的默认行高（px）。 */
+export declare const DEFAULT_MULTILINE_LINE_HEIGHT = 28;
+/** 渲染器版本快照，随导出结果一起下发，便于服务端复现渲染逻辑。 */
+export declare const CONTRACT_TEMPLATE_RENDERER_VERSION = "contract-template-renderer-1.0.0";
+/** 合同渲染 CSS 版本快照，用于服务端 PDF 复现。 */
+export declare const CONTRACT_TEMPLATE_STYLE_VERSION = "contract-render-css-1.0.0";
+/** 页数配置只接受正整数；非法值回落到默认 50 页。 */
+export declare function normalizeContractTemplateMaxPages(value: unknown): number;
+/** 正文可插入的变量类型及其默认尺寸。 */
+export declare const DEFAULT_FIELD_TYPES: ContractTemplateFieldTypeOption[];
+/** 生成设计器内部 ID；时间戳加自增序号，保证同一次会话内不重复。 */
+export declare function createDesignerId(prefix: string): string;
+/** 深拷贝模板数据，切断与响应式对象的引用。 */
+export declare function cloneTemplateValue(value: ContractTemplateData): ContractTemplateData;
+/** 按纸张格式取预设尺寸；`Custom` 或未知格式返回 undefined。 */
+export declare function getPageSizeOption(format: ContractTemplatePageFormat): ContractTemplatePageSize | undefined;
+/** 反推纸张格式：显式 format 优先，其次按宽高匹配预设。 */
+export declare function inferPageFormat(pageSize?: Partial<ContractTemplatePageSize>): ContractTemplatePageFormat | undefined;
+/**
+ * 归一化页面尺寸。
+ *
+ * 命中预设格式时强制使用预设宽高，只有 `Custom` 才保留外部传入的数值，
+ * 避免同一格式的页面在不同模板里出现细微尺寸差。
+ */
+export declare function resolvePageSize(pageSize: Partial<ContractTemplatePageSize> | undefined, fallback?: ContractTemplatePageSize): ContractTemplatePageSize;
+/** 新建带引导文案的页面，用于首次进入设计器。 */
+export declare function createDefaultPage(index?: number, pageSize?: ContractTemplatePageSize): ContractTemplatePage;
+/** 新建空白页面，用于清空模板、追加页面和自动分页。 */
+export declare function createBlankPage(index?: number, pageSize?: ContractTemplatePageSize, contentHtml?: string, contentJson?: ContractTemplatePage['contentJson']): ContractTemplatePage;
+/** 带引导文案的初始模板。 */
+export declare function createDefaultTemplate(pageSize?: ContractTemplatePageSize): ContractTemplateData;
+/** 全空白模板，`clearTemplate()` 使用。 */
+export declare function createBlankTemplate(pageSize?: ContractTemplatePageSize): ContractTemplateData;
+/** 取变量类型选项；未知类型退回第一项，保证 UI 仍有可展示的标签和尺寸。 */
+export declare function getFieldOption(type: ContractTemplateFieldType, fieldTypes?: ContractTemplateFieldTypeOption[]): ContractTemplateFieldTypeOption;
+/**
+ * 补全变量的所有字段。
+ *
+ * 优先级为「显式入参 > 类型默认值 > 类型选项默认值 > 全局默认」，样式按同样顺序
+ * 逐层覆盖，宽高和行高会做下限裁剪防止渲染出不可见控件。
+ */
+export declare function createTemplateVariable(options: Partial<ContractTemplateVariable> & Pick<ContractTemplateVariable, 'key'>, fieldTypes?: ContractTemplateFieldTypeOption[], defaultStyle?: ContractTemplateFieldStyle): ContractTemplateVariable;
+/**
+ * 把外部传入的模板归一成设计器可用的完整结构。
+ *
+ * 缺页补一页空白页、缺 ID 现场补 ID、页面尺寸逐层继承模板尺寸；变量以
+ * `variables` 字段为基础，再用正文里扫出来的节点补齐遗漏的 key。正文显式声明
+ * 的未知类型会覆盖 `variables` 里的默认 text，避免脏数据在校验前被抹平。
+ */
+export declare function normalizeTemplateValue(value: ContractTemplateData | undefined, pageSize?: ContractTemplatePageSize): ContractTemplateData;
+/** 拼接设计态整册 HTML：每页一个 `section`，正文保持编辑器原样。 */
+export declare function buildTemplateHtml(value: ContractTemplateData): string;
+/** 拼接服务端渲染用整册 HTML：变量节点文本换成 `${{key}}` 表达式。 */
+export declare function buildTemplateExpressionHtml(value: ContractTemplateData): string;
+/**
+ * 拼接预览用整册 HTML。
+ *
+ * 变量节点按 `variables` 的权威元数据重算展示文本与样式，并把页面宽高写进
+ * 行内样式，让预览弹窗不依赖设计器画布的容器尺寸。
+ */
+export declare function buildTemplatePreviewHtml(value: ContractTemplateData): string;
+/** 单页预览快照；签署位置保持独立数据，不能拼入正文 HTML。 */
+export interface ContractTemplatePreviewPage {
+    page: ContractTemplatePage;
+    contentHtml: string;
+    signingPlacements: ContractTemplateSigningPlacement[];
+}
+/**
+ * 构建供 Vue 预览页消费的只读快照。
+ *
+ * 正文仍沿用既有净化和变量展示逻辑；签署位置按 pageId 单独分组，
+ * 由受控覆盖层渲染，避免进入 contentHtml、导出 HTML 或 PDF DTO。
+ */
+export declare function buildTemplatePreviewPages(value: ContractTemplateData): ContractTemplatePreviewPage[];
+/**
+ * 生成提交给宿主的导出结果。
+ *
+ * 先深拷贝再附加渲染器/样式版本号和表达式 HTML，保证导出快照与设计态数据解耦，
+ * 宿主后续改动设计态不会污染已经拿到的导出对象。
+ */
+export declare function exportTemplateValue(value: ContractTemplateData): ContractTemplateExportResult;
+/**
+ * 全量校验模板结构，返回可定位到具体节点的错误列表。
+ *
+ * 覆盖四类问题：变量缺少 key、key 重复、显式声明了不支持的类型，以及变量配置与
+ * 正文节点两侧互相缺失（正文引用了未配置的 key，或配置了没有正文节点的变量）。
+ * 签署位置的校验委托给 `validateSigningPlacements`。
+ */
+export declare function validateTemplateValue(value: ContractTemplateData, options?: {
+    maxPages?: number;
+}): ContractTemplateValidationError[];
+/**
+ * 收集单页引用到的变量 key。
+ *
+ * 同时扫描 Tiptap JSON 和正文 HTML：前者覆盖当前编辑态，后者兼容只存了
+ * `contentHtml` 的历史模板；`templateField` 是旧节点名，必须继续识别。
+ */
+export declare function collectTemplateVariableKeys(page: ContractTemplatePage): Set<string>;
+/** 汇总整份模板引用到的变量 key。 */
+export declare function collectTemplateValueVariableKeys(value: Pick<ContractTemplateData, 'pages'>): Set<string>;
+/** 删除正文里已经不存在的变量配置，让 `variables` 与正文节点保持一致。 */
+export declare function syncTemplateVariablesWithPages(value: ContractTemplateData): ContractTemplateData;
+/** 自动分页用的单个顶层块测量结果，坐标相对正文容器顶部。 */
+export interface ContractTemplateBlockMeasurement {
+    top: number;
+    height: number;
+}
+/** 自动分页结果：`splitIndex` 为溢出块下标，`-1` 表示当前页无需拆分。 */
+export interface ContractTemplateContentSplitResult {
+    splitIndex: number;
+    currentContent: JSONContent[];
+    overflowContent: JSONContent[];
+}
+/**
+ * 依据实测块高决定当前页在哪个顶层块处溢出。
+ *
+ * 只按块边界拆分：找到第一个底边超出可用高度（留 1px 容差抵消亚像素误差）的块，
+ * 把它及之后的内容整体挪到下一页。返回 `undefined` 表示无需分页。
+ */
+export declare function splitPageContentByMeasurements(content: JSONContent[] | undefined, measurements: ContractTemplateBlockMeasurement[], maxContentHeight: number): ContractTemplateContentSplitResult | undefined;
+/** 规则导出必须先通过完整模板校验，不能只检查签署位置自身。 */
+export declare function collectTemplateLocationRuleExportErrors(value: ContractTemplateData, inputErrors?: ContractTemplateValidationError[]): ContractTemplateValidationError[];
+/**
+ * 常量的兼容转发。
+ *
+ * 这些常量的实现已经搬到 `../constants`，但历史上是从本模块对外导出的，
+ * 保留转发以免破坏 `@guodun/antdv` 的既有引用路径。
+ */
+export { CONTRACT_TEXT_STYLE_PRESETS, CONTRACT_TEXT_STYLE_PRESET_COMMANDS, DEFAULT_CONTRACT_FONT_FAMILY, DEFAULT_FONT_FAMILY_OPTIONS, DEFAULT_FONT_SIZE_PRESETS, DEFAULT_TEXT_ALIGN_OPTIONS, getContractTextStylePreset, normalizeFontFamilyValue, resolveContractTextStylePresetCommands, resolveFontFamilyOptions, } from '../constants';

package/dist/types/components/pro-contract-template-designer/src/composables/use-template-draft-cache.d.ts

@@ -0,0 +1,83 @@
+import { ContractTemplateData, ContractTemplateDraftCacheStatus } from '../types';
+/**
+ * 合同模板草稿的本地缓存层。
+ *
+ * 纯函数集合：storage 由调用方注入（浏览器传 localStorage，测试传内存实现），
+ * 所有失败都折成 `ContractTemplateDraftCacheStatus` 返回而不抛异常——
+ * 草稿缓存属于「尽力而为」的能力，绝不能因为写不进去而中断用户编辑。
+ */
+/** 载荷版本号。结构变更时递增，读到旧版本一律按不兼容丢弃，避免反序列化出半截数据。 */
+export declare const CONTRACT_TEMPLATE_DRAFT_CACHE_VERSION = 1;
+export declare const DEFAULT_DRAFT_CACHE_KEY = "gd-antdv:pro-contract-template-designer:draft";
+/** 自动缓存间隔，5s 是编辑手感与写盘频率的折中。 */
+export declare const DEFAULT_DRAFT_CACHE_INTERVAL = 5000;
+/** 单份草稿上限 2MB：localStorage 总配额通常 5–10MB，留出余量给宿主自己的数据。 */
+export declare const DEFAULT_DRAFT_CACHE_MAX_BYTES: number;
+/** 只取 localStorage 的三个方法，便于测试注入内存实现。 */
+export interface ContractTemplateDraftCacheStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+/** 落盘的完整载荷。`savedAt` 用于状态栏展示「几点几分已缓存」。 */
+export interface ContractTemplateDraftCachePayload {
+    version: number;
+    savedAt: number;
+    value: ContractTemplateData;
+}
+export interface SaveTemplateDraftCacheOptions {
+    storage?: ContractTemplateDraftCacheStorage;
+    key: string;
+    value: ContractTemplateData;
+    maxBytes: number;
+    /** 上一次写入时的序列化结果，用来跳过内容没变的定时写入。 */
+    previousValueSerialized?: string;
+}
+export interface SaveTemplateDraftCacheResult {
+    status: ContractTemplateDraftCacheStatus;
+    /** 回传本次序列化结果，调用方缓存下来作为下一轮的 `previousValueSerialized`。 */
+    valueSerialized?: string;
+}
+export interface LoadTemplateDraftCacheResult {
+    status: ContractTemplateDraftCacheStatus;
+    value?: ContractTemplateData;
+    valueSerialized?: string;
+}
+/**
+ * 探测可用的 localStorage。
+ *
+ * 只判断 `window` 存在不够：隐私模式、被策略禁用、配额为 0 时读写都会抛异常，
+ * 所以写一个探测键再删掉，真正能写才认为可用。
+ */
+export declare function getBrowserDraftCacheStorage(): ContractTemplateDraftCacheStorage | undefined;
+/** 状态对象工厂：统一 type 与 message 的位置，额外字段（字节数、时间、错误）按需补。 */
+export declare function createDraftCacheStatus(type: ContractTemplateDraftCacheStatus['type'], message: string, patch?: Omit<Partial<ContractTemplateDraftCacheStatus>, 'type' | 'message'>): ContractTemplateDraftCacheStatus;
+/** 估算 UTF-8 字节数，用于和 `maxBytes` 比对。 */
+export declare function estimateDraftCacheBytes(value: string): number;
+/** 状态栏只显示 `HH:mm`，日期对「几分钟前存过」这个信息没有帮助。 */
+export declare function formatDraftCacheSavedAt(savedAt?: number): string;
+/**
+ * 写入草稿。
+ *
+ * 顺序是「无 storage → 内容未变 → 超限 → 实际写入」，越便宜的判断越靠前。
+ * 注意超限和写失败也会回传 `valueSerialized`：否则下一轮定时器会对同样的内容
+ * 重新序列化、重新超限，白白消耗一次 JSON.stringify。
+ */
+export declare function saveTemplateDraftCache(options: SaveTemplateDraftCacheOptions): SaveTemplateDraftCacheResult;
+/**
+ * 读取草稿。
+ *
+ * 三类失败要分开告知用户：读不出来（read-failed）、没有草稿（idle）、
+ * 有但解析不了或版本不对（invalid）——只有第二种是正常状态，不该提示异常。
+ */
+export declare function loadTemplateDraftCache(storage: ContractTemplateDraftCacheStorage | undefined, key: string): LoadTemplateDraftCacheResult;
+/** 清理草稿。删除失败同样只回报状态，不影响后续编辑。 */
+export declare function clearTemplateDraftCache(storage: ContractTemplateDraftCacheStorage | undefined, key: string): ContractTemplateDraftCacheStatus;
+/**
+ * 判断草稿是否等价于「什么都没写」。
+ *
+ * 空模板也会被序列化成一份完整结构（一页空段落），如果不识别出来，
+ * 用户一打开设计器就会看到「已恢复本地草稿」的提示，属于噪音。
+ * 判定条件：无变量、只有一页、无签署位置，且这一页正文 HTML 与 JSON 都是空的。
+ */
+export declare function isBlankTemplateDraftValue(value: ContractTemplateData | undefined): boolean;

package/dist/types/{antdv/src/components → components}/pro-contract-template-designer/src/constants.d.ts

@@ -1,18 +1,39 @@
 import { ContractTemplateEditorCommand, ContractTemplateEditorTextAlign, ContractTemplateFontFamilyMode, ContractTemplateFontFamilyOption, ContractTemplateTextStylePreset, ContractTemplateTextStylePresetKey } from './types';
+/**
+ * 合同正文默认字体。
+ *
+ * 按「思源宋体 → 系统宋体 → 通用衬线」的顺序回退，保证 Windows / macOS / Linux
+ * 都能落到一款宋体上；合同排版对字形宽度敏感，缺字体时的替换会影响分页结果。
+ */
 export declare const DEFAULT_CONTRACT_FONT_FAMILY = "Noto Serif SC, Source Han Serif SC, Songti SC, STSong, SimSun, serif";
+/** 字体下拉的内置选项：前四项是合同常用中文字体，后三项兼顾英文合同。 */
 export declare const DEFAULT_FONT_FAMILY_OPTIONS: ContractTemplateFontFamilyOption[];
+/** 字号下拉的预设档位；不在此列表里的字号仍可手动输入，由工具栏临时补进选项。 */
 export declare const DEFAULT_FONT_SIZE_PRESETS: number[];
+/** 合同页数默认上限；组件使用方可通过 maxPages 调整。 */
+export declare const DEFAULT_CONTRACT_MAX_PAGES = 50;
+/** 对齐方式选项。合同排版不使用两端对齐，因此只有左 / 中 / 右三档。 */
 export declare const DEFAULT_TEXT_ALIGN_OPTIONS: Array<{
     label: string;
     value: ContractTemplateEditorTextAlign;
 }>;
+/**
+ * 合同文本样式预设。
+ *
+ * 每个预设描述一套完整的段落外观（标题层级或段落、字号、字体、对齐、粗斜下划线），
+ * 而不是只改其中一项，这样用户切换预设时不会残留上一次的样式。
+ */
 export declare const CONTRACT_TEXT_STYLE_PRESETS: ContractTemplateTextStylePreset[];
+/** 预设 key → 命令序列的索引，模块加载时一次性构建，避免每次点击都重新摊平。 */
 export declare const CONTRACT_TEXT_STYLE_PRESET_COMMANDS: Record<ContractTemplateTextStylePresetKey, ContractTemplateEditorCommand[]>;
 export declare function getContractTextStylePreset(key: ContractTemplateTextStylePresetKey): ContractTemplateTextStylePreset | undefined;
+/** 取预设命令时逐条浅拷贝：命令对象会被调用方改写，共享引用会污染上面的常量表。 */
 export declare function resolveContractTextStylePresetCommands(key: ContractTemplateTextStylePresetKey): ({
     type: "undo";
 } | {
     type: "redo";
+} | {
+    type: "select-all";
 } | {
     type: "set-paragraph";
 } | {
@@ -70,6 +91,15 @@ export declare function resolveContractTextStylePresetCommands(key: ContractTemp
 } | {
     type: "apply-text-style-preset";
     preset: ContractTemplateTextStylePresetKey;
+} | {
+    type: "insert-horizontal-rule";
+} | {
+    type: "insert-content-image";
+    image: import('./types').ContractTemplateContentImage;
+    position?: number | {
+        from: number;
+        to: number;
+    };
 } | {
     type: "insert-table";
     options: import('./types').ContractTemplateTableInsertOptions;
@@ -85,6 +115,13 @@ export declare function resolveContractTextStylePresetCommands(key: ContractTemp
     type: "add-table-column-after";
 } | {
     type: "delete-table-column";
+} | {
+    type: "merge-table-cells";
+} | {
+    type: "split-table-cell";
+} | {
+    type: "set-table-cell-align";
+    value: ContractTemplateEditorTextAlign;
 } | {
     type: "toggle-table-header-row";
 } | {
@@ -94,5 +131,17 @@ export declare function resolveContractTextStylePresetCommands(key: ContractTemp
 } | {
     type: "delete-table";
 })[];
+/**
+ * 把字体族字符串归一成可比较的形式：去引号、压缩逗号周边空格、转小写。
+ *
+ * 浏览器回读 `font-family` 时会自行加引号并调整空格，直接字符串比较会漏判，
+ * 因此工具栏的「当前字体」高亮和下拉去重都走这个口径。
+ */
 export declare function normalizeFontFamilyValue(value: string | undefined): string;
+/**
+ * 合并宿主传入的自定义字体与内置字体。
+ *
+ * `replace` 完全用宿主的列表（传空则退回内置），`append` 追加在内置之后；
+ * 用 Map 按归一化后的值去重，后写入的覆盖先写入的，所以宿主可以借同名项改标签。
+ */
 export declare function resolveFontFamilyOptions(customOptions: ContractTemplateFontFamilyOption[] | undefined, mode?: ContractTemplateFontFamilyMode): ContractTemplateFontFamilyOption[];

package/dist/types/components/pro-contract-template-designer/src/extensions/ContentImageNodeView.vue.d.ts

@@ -0,0 +1,5 @@
+import { NodeViewProps } from '@tiptap/core';
+declare const _default: import('vue').DefineComponent<NodeViewProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<NodeViewProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    imageElement: HTMLImageElement;
+}, any>;
+export default _default;

package/dist/types/components/pro-contract-template-designer/src/extensions/editor-extensions.d.ts

@@ -0,0 +1,16 @@
+import { AnyExtension, Editor } from '@tiptap/core';
+import { ContractTemplateEditorCommand } from '../types';
+export interface ContractTemplateEditorExtensionOptions {
+    processImageFile?: (file: File) => Promise<string | null>;
+    getZoom?: () => number;
+}
+/** 组装合同正文编辑器的扩展列表；顺序影响 Tiptap 的解析优先级，勿随意调整。 */
+export declare function createEditorExtensions(placeholder?: string, options?: ContractTemplateEditorExtensionOptions): AnyExtension[];
+/** 执行单条编辑器命令；`focus: false` 用于不希望抢回光标的场景。 */
+export declare function runContractTemplateEditorCommand(editor: Editor | null | undefined, command: ContractTemplateEditorCommand, options?: {
+    focus?: boolean;
+}): boolean;
+/** 在同一个 chain 里串联多条命令，保证它们合成一次撤销记录。 */
+export declare function runContractTemplateEditorCommands(editor: Editor | null | undefined, commands: ContractTemplateEditorCommand[], options?: {
+    focus?: boolean;
+}): boolean;

package/dist/types/{antdv/src/components → components}/pro-contract-template-designer/src/extensions/font-size.d.ts

@@ -7,4 +7,10 @@ declare module '@tiptap/core' {
         };
     }
 }
+/**
+ * 字号扩展。
+ *
+ * Tiptap 官方 text-style 只带字体和颜色，字号需要自己挂到 `textStyle` mark 上。
+ * 取消字号时同时清理空的 textStyle，避免正文里残留无意义的空 span。
+ */
 export declare const FontSize: Extension<any, any>;

package/dist/types/components/pro-contract-template-designer/src/extensions/office-content.d.ts

@@ -0,0 +1,11 @@
+import { Extension, Mark, Node } from '@tiptap/core';
+/** Word 可表达、设计器可稳定 round-trip 的块级与表格样式属性。 */
+export declare const OfficeContentFormatting: Extension<any, any>;
+export interface ContractContentImageOptions {
+    /** 页面 CSS transform 缩放比例；仅用于把指针视口位移换算回页面像素。 */
+    getZoom?: () => number;
+}
+/** 合同正文图片是行内 atom，可与 Word 中图片前后的文本保持同一段落顺序。 */
+export declare const ContractContentImage: Node<ContractContentImageOptions, any>;
+export declare const ContractSuperscript: Mark<any, any>;
+export declare const ContractSubscript: Mark<any, any>;

package/dist/types/{antdv/src/components → components}/pro-contract-template-designer/src/extensions/template-variable.d.ts

@@ -1,5 +1,6 @@
-import { Node } from '@tiptap/core';
-import { ContractTemplateFieldStyle, ContractTemplateFieldType } from '../types';
+import { Node, Editor } from '@tiptap/core';
+import { ContractTemplateFieldStyle, ContractTemplateFieldType, ContractTemplateVariable } from '../types';
+/** 正文变量节点在 Tiptap 中持久化的全部属性；每一项都对应一个 `data-*`。 */
 export interface TemplateVariableAttrs {
     key: string;
     label: string;
@@ -29,7 +30,14 @@ export interface TemplateVariableAttrs {
     borderStyle: string;
     objectFit: string;
 }
+/** 行内可拖动的原子节点，是合同正文里唯一的填写占位符。 */
 export declare const TemplateVariable: Node<any, any>;
+/**
+ * 把设计器的变量模型转换成 Tiptap 节点属性。
+ *
+ * 默认边框和下划线按类型推断（图片默认带框，图片和勾选框默认不带下划线），
+ * 行数与行高做下限裁剪，避免插入出不可见的控件。
+ */
 export declare function buildTemplateVariableAttrs(variable: {
     key: string;
     label: string;
@@ -49,3 +57,10 @@ export declare function buildTemplateVariableAttrs(variable: {
     lineHeight?: number;
     style?: ContractTemplateFieldStyle;
 }): TemplateVariableAttrs;
+/**
+ * 在当前选区插入正文变量节点。
+ *
+ * 不传文档位置时，Tiptap 会用当前选区替换被选中的 Word 下划线；传入位置则用于
+ * 左侧控件拖拽落点。两条入口共用这里，确保右键转换和侧栏插入的节点属性一致。
+ */
+export declare function insertTemplateVariableNode(editor: Editor | null | undefined, variable: ContractTemplateVariable, position?: number): boolean;

package/dist/types/components/pro-contract-template-designer/src/extensions/word-paste.d.ts

@@ -0,0 +1,25 @@
+import { Extension } from '@tiptap/core';
+import { ClipboardHtmlSource } from '../utils/word-paste';
+interface PendingPastePayload {
+    html: string;
+    plainText: string;
+    rtf: string;
+    files: File[];
+    source: ClipboardHtmlSource;
+    recoveredRtfImages: number;
+    trustedInternal: boolean;
+}
+interface WordPasteStorage {
+    pending?: PendingPastePayload;
+}
+interface WordPasteOptions {
+    processImageFile?: (file: File) => Promise<string | null>;
+}
+/**
+ * Office 粘贴扩展优先恢复/清洗 HTML，但保留 ProseMirror 默认事务与 table paste。
+ * 剪贴板含图片 File 且同步 RTF 无法恢复、也不是内部复制时，接管一次插入并走宿主上传管线。
+ */
+export declare const WordPaste: Extension<WordPasteOptions, WordPasteStorage>;
+/** 测试与诊断使用：确认 RTF 是否已足以避免异步接管粘贴。 */
+export declare function countRecoverableRtfImages(rtf: string): number;
+export {};