@guodun/antdv 1.2.5 → 1.3.0

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

@@ -1,5 +1,8 @@
 import { JSONContent } from '@tiptap/core';
-export type ContractTemplateFieldType = 'text' | 'date' | 'number' | 'image' | 'signature' | 'seal' | 'checkbox';
+import { ContractTemplateImageCompression, ContractTemplateImageSource, ContractTemplateImageUploadHandler } from './utils/content-image';
+/** 正文变量只描述文档流内的填写项；签署位置使用独立的 signingPlacements。 */
+export type ContractTemplateFieldType = 'text' | 'date' | 'number' | 'image' | 'checkbox';
+export declare function isContractTemplateFieldType(value: unknown): value is ContractTemplateFieldType;
 export type ContractTemplatePageFormat = 'A0' | 'A1' | 'A2' | 'A3' | 'A4' | 'A5' | 'Letter' | 'Legal' | 'Custom';
 export interface ContractTemplatePageSize {
     /** 页面格式；常用预设会自动带出宽高 */
@@ -52,10 +55,69 @@ export interface ContractTemplatePage {
     contentHtml: string;
     contentJson?: JSONContent;
 }
+/** 合同正文中的真实图片节点；它不属于 variables 或 signingPlacements。 */
+export interface ContractTemplateContentImage {
+    src: string;
+    alt?: string;
+    title?: string;
+    width?: number;
+    height?: number;
+}
+/** 编辑器当前选中的正文图片；position 是当前页面 ProseMirror 文档位置。 */
+export interface ContractTemplateSelectedContentImage extends ContractTemplateContentImage {
+    position: number;
+}
+/** 与正文变量并列的 PDF 页面签署位置；坐标以所属页面原始尺寸为基准。 */
+export type ContractTemplateSigningPlacementType = 'seal' | 'signature' | 'date';
+export interface ContractTemplateSigningPlacement {
+    id: string;
+    pageId: string;
+    type: ContractTemplateSigningPlacementType;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    mustSign: boolean;
+    /** 仅印章位置允许输出印章类型；空数组等同于未选择。 */
+    sealTypes?: string[];
+}
+export interface ContractTemplateLocationRuleLocation {
+    signType: ContractTemplateSigningPlacementType;
+    signTop: number;
+    signLeft: number;
+    signWidth: number;
+    signHeight: number;
+    pageList: Record<string, number[]>;
+    sealType?: string[];
+}
+/** locationRules 的兼容 DTO；顶层元数据仅用于关联模板中的指定位置。 */
+export interface ContractTemplateLocationRule {
+    mustSign: boolean;
+    placementId: string;
+    pageId: string;
+    pageIndex: number;
+    location: ContractTemplateLocationRuleLocation;
+}
+/** 可直接传给 packages/contract 的严格 locationRules DTO。 */
+export interface ContractLocationRule {
+    mustSign: boolean;
+    location: ContractTemplateLocationRuleLocation;
+}
+export interface ContractTemplateLocationRulePageSize {
+    width: number;
+    height: number;
+}
+export type ContractTemplateLocationRuleTargetPageSizes = Record<string, ContractTemplateLocationRulePageSize> | ContractTemplateLocationRulePageSize[];
+export interface ContractTemplateLocationRuleOptions {
+    fileId: string;
+    targetPageSizes?: ContractTemplateLocationRuleTargetPageSizes;
+}
 export interface ContractTemplateData {
     pages: ContractTemplatePage[];
     variables: ContractTemplateVariable[];
     pageSize: ContractTemplatePageSize;
+    /** 旧模板可缺省；归一化后的模板始终带空数组。 */
+    signingPlacements?: ContractTemplateSigningPlacement[];
 }
 export interface ContractTemplateFieldTypeOption {
     type: ContractTemplateFieldType;
@@ -99,16 +161,37 @@ export interface ContractTemplateEditorState {
     fontSize?: number;
     textColor?: string;
     selectionText?: string;
+    /** 当前 NodeSelection 选中的正文图片；普通文本/表格选区时为空。 */
+    selectedContentImage?: ContractTemplateSelectedContentImage;
 }
 export interface ContractTemplateTableInsertOptions {
     rows: number;
     cols: number;
     withHeaderRow: boolean;
 }
+export type ContractTemplateTableCommand = 'add-table-row-before' | 'add-table-row-after' | 'delete-table-row' | 'add-table-column-before' | 'add-table-column-after' | 'delete-table-column' | 'merge-table-cells' | 'split-table-cell' | 'toggle-table-header-row' | 'toggle-table-header-column' | 'delete-table';
+export interface ContractTemplateTableCommandCapabilities {
+    addRowBefore: boolean;
+    addRowAfter: boolean;
+    deleteRow: boolean;
+    addColumnBefore: boolean;
+    addColumnAfter: boolean;
+    deleteColumn: boolean;
+    mergeCells: boolean;
+    splitCell: boolean;
+    alignLeft: boolean;
+    alignCenter: boolean;
+    alignRight: boolean;
+    toggleHeaderRow: boolean;
+    toggleHeaderColumn: boolean;
+    deleteTable: boolean;
+}
 export type ContractTemplateEditorCommand = {
     type: 'undo';
 } | {
     type: 'redo';
+} | {
+    type: 'select-all';
 } | {
     type: 'set-paragraph';
 } | {
@@ -166,6 +249,15 @@ export type ContractTemplateEditorCommand = {
 } | {
     type: 'apply-text-style-preset';
     preset: ContractTemplateTextStylePresetKey;
+} | {
+    type: 'insert-horizontal-rule';
+} | {
+    type: 'insert-content-image';
+    image: ContractTemplateContentImage;
+    position?: number | {
+        from: number;
+        to: number;
+    };
 } | {
     type: 'insert-table';
     options: ContractTemplateTableInsertOptions;
@@ -181,6 +273,13 @@ export type ContractTemplateEditorCommand = {
     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';
 } | {
@@ -191,7 +290,7 @@ export type ContractTemplateEditorCommand = {
     type: 'delete-table';
 };
 export interface ContractTemplateValidationError {
-    type: 'field' | 'variable' | 'page' | 'security';
+    type: 'field' | 'variable' | 'page' | 'security' | 'signing-placement';
     id: string;
     message: string;
     /** 服务端错误码，透传给宿主应用做精细化提示 */
@@ -219,21 +318,65 @@ export interface ContractTemplateRendererProps {
     template?: ContractTemplateData;
     /** 按变量 key 记录的填写值 */
     values?: ContractTemplateRenderValues;
-    /** 填写交互模式；panel 模式在右侧填写，inline 模式保留合同内控件 */
+    /**
+     * 填写交互模式；panel 模式在右侧填写，inline 模式保留合同内控件
+     * @default 'panel'
+     */
     interactionMode?: ContractTemplateRendererMode;
-    /** 只读模式下展示已填值，不允许继续编辑 */
+    /**
+     * 只读模式下展示已填值，不允许继续编辑
+     * @default false
+     */
     readonly?: boolean;
-    /** 禁用全部填写控件 */
+    /**
+     * 禁用全部填写控件
+     * @default false
+     */
     disabled?: boolean;
-    /** 是否展示内置提交按钮 */
+    /**
+     * 顶部标题文案
+     * @default '合同填写'
+     */
+    title?: string;
+    /**
+     * 是否在顶部 header 展示内置提交按钮
+     * @default true
+     */
     showSubmitButton?: boolean;
-    /** 点击提交时是否校验填写值；模板结构与安全错误始终阻止提交 */
+    /**
+     * 点击提交时是否校验填写值；模板结构与安全错误始终阻止提交
+     * @default true
+     */
     validateOnSubmit?: boolean;
-    /** 是否展示缩放与页面定位工具栏 */
+    /**
+     * 是否在顶部 header 展示校验按钮
+     * @default true
+     */
+    showValidateButton?: boolean;
+    /**
+     * 是否在顶部 header 展示重置默认值按钮
+     * @default true
+     */
+    showResetButton?: boolean;
+    /**
+     * 是否展示 header 内的缩放与页面定位工具组；不影响 header 容器与提交按钮
+     * @default true
+     */
     showToolbar?: boolean;
-    /** 是否展示每页的页码、标题与尺寸信息 */
+    /**
+     * 是否展示每页的页码、标题与尺寸信息
+     * @default true
+     */
     showPageMeta?: boolean;
-    /** 页面缩放比例，范围为 0.5 到 1.5 */
+    /**
+     * 面板模式是否允许收起右侧填写面板
+     * @default true
+     */
+    collapsiblePanel?: boolean;
+    /**
+     * 页面缩放比例，范围为 0.5 到 1.5
+     * @default 1
+     */
     zoom?: number;
 }
 export interface ContractTemplateRendererEmits {
@@ -291,33 +434,91 @@ export interface ContractTemplateDraftCacheStatus {
 export interface ContractTemplateDesignerProps {
     /** 合同模板数据，正文占位统一写入 variables */
     modelValue?: ContractTemplateData;
-    /** 只读模式，禁止编辑正文和字段 */
+    /**
+     * 只读模式，禁止编辑正文和字段
+     * @default false
+     */
     readonly?: boolean;
-    /** 禁用整个设计器 */
+    /**
+     * 禁用整个设计器
+     * @default false
+     */
     disabled?: boolean;
-    /** 模板默认页面尺寸，页面可通过 page.pageSize 单独覆盖 */
+    /**
+     * 模板默认页面尺寸，页面可通过 page.pageSize 单独覆盖
+     * @default A4 794×1123
+     */
     pageSize?: ContractTemplatePageSize;
-    /** 右侧可拖拽模板变量类型配置 */
+    /**
+     * 合同允许的最大页数；手动新增、复制页面与自动分页共用此上限
+     * @default 50
+     */
+    maxPages?: number;
+    /**
+     * 正文图片压缩配置；true 使用内置配置，false 保留原文件
+     * @default true
+     */
+    imageCompression?: ContractTemplateImageCompression;
+    /**
+     * 自定义图片上传。未配置时，压缩后的图片以 Base64 data URL 写入正文
+     */
+    imageUpload?: ContractTemplateImageUploadHandler;
+    /**
+     * 右侧可拖拽模板变量类型配置
+     * @default 内置 text/date/number/image/checkbox
+     */
     variableTypes?: ContractTemplateFieldTypeOption[];
-    /** 新增模板变量的默认样式 */
+    /**
+     * 新增模板变量的默认样式
+     * @default 内置默认样式
+     */
     defaultVariableStyle?: ContractTemplateFieldStyle;
     /** 内置字体集之外追加或替换的字体选项 */
     fontFamilies?: ContractTemplateFontFamilyOption[];
-    /** 自定义字体选项与内置字体集的合并方式 */
+    /**
+     * 自定义字体选项与内置字体集的合并方式
+     * @default 'append'
+     */
     fontFamilyMode?: ContractTemplateFontFamilyMode;
-    /** 是否展示内置提交数据查看入口；关闭后仍可通过 expose 方法打开 */
+    /**
+     * 是否展示内置提交数据查看入口；关闭后仍可通过 expose 方法打开
+     * @default true
+     */
     showSubmitDataViewer?: boolean;
-    /** 是否展示内置清空模板按钮；关闭后仍可通过 expose 方法清空 */
+    /**
+     * 是否展示内置清空模板按钮；关闭后仍可通过 expose 方法清空
+     * @default true
+     */
     showClearButton?: boolean;
-    /** 是否启用本地草稿缓存 */
+    /**
+     * 是否展示印章、签名与签署日期新增工具；隐藏后已有位置仍可查看、编辑和导出
+     * @default false
+     */
+    showSigningPlacementTools?: boolean;
+    /**
+     * 是否启用本地草稿缓存
+     * @default true
+     */
     enableDraftCache?: boolean;
-    /** 本地草稿缓存键；多合同编辑时宿主应传入不同 key 隔离 */
+    /**
+     * 本地草稿缓存键；多合同编辑时宿主应传入不同 key 隔离
+     * @default 'gd-antdv:pro-contract-template-designer:draft'
+     */
     draftCacheKey?: string;
-    /** 自动保存草稿间隔，单位毫秒 */
+    /**
+     * 自动保存草稿间隔，单位毫秒
+     * @default 5000
+     */
     draftCacheInterval?: number;
-    /** 单份草稿缓存最大字节数 */
+    /**
+     * 单份草稿缓存最大字节数
+     * @default 2097152
+     */
     draftCacheMaxBytes?: number;
-    /** 是否展示顶部草稿缓存状态 */
+    /**
+     * 是否展示顶部草稿缓存状态
+     * @default true
+     */
     showDraftCacheStatus?: boolean;
 }
 export interface ContractTemplateDesignerEmits {
@@ -331,6 +532,18 @@ export interface ContractTemplateDesignerEmits {
     validate: [errors: ContractTemplateValidationError[]];
     /** 本地草稿缓存状态变化 */
     'draft-cache-change': [status: ContractTemplateDraftCacheStatus];
+    /** 新增/复制/自动分页触及页数上限 */
+    'page-limit': [maxPages: number, source: 'add' | 'duplicate' | 'auto-pagination'];
+    /** 本地图片读取、压缩或上传失败 */
+    'image-error': [error: Error, source: ContractTemplateImageSource];
+    /** 新增签署位置；位置数据始终独立于正文 HTML/JSON */
+    'signing-placement-add': [placement: ContractTemplateSigningPlacement];
+    /** 签署位置几何或属性变化 */
+    'signing-placement-change': [placement: ContractTemplateSigningPlacement];
+    /** 删除签署位置 */
+    'signing-placement-remove': [placement: ContractTemplateSigningPlacement];
+    /** 选中签署位置变化；取消选中时为 undefined */
+    'signing-placement-select': [placement: ContractTemplateSigningPlacement | undefined];
 }
 export interface ContractTemplateDesignerExpose {
     /** 获取当前模板数据快照 */
@@ -355,6 +568,8 @@ export interface ContractTemplateDesignerExpose {
     getDraftCacheStatus: () => ContractTemplateDraftCacheStatus;
     /** 向当前页面插入正文变量节点 */
     insertVariable: (variable: Partial<ContractTemplateVariable> & Pick<ContractTemplateVariable, 'key' | 'label'>) => ContractTemplateVariable | undefined;
+    /** 插入正文真实图片；File 会先压缩并按 imageUpload 配置决定 Base64 或 URL */
+    insertImage: (source: File | string, image?: Omit<ContractTemplateContentImage, 'src'>) => Promise<string | undefined>;
     /** 聚焦当前页面编辑器 */
     focus: () => void;
     /** 打开当前模板的只读预览弹窗 */
@@ -371,6 +586,8 @@ export interface ContractTemplateDesignerExpose {
     clearValidationErrors: () => void;
     /** 滚动并高亮指定正文变量 */
     scrollToVariable: (variableKey: string) => void;
+    /** 滚动并选中指定签署位置 */
+    scrollToSigningPlacement: (placementId: string) => void;
     /** 滚动到指定页面 */
     scrollToPage: (pageId: string) => void;
     /** 设置设计区缩放比例，返回裁剪后的实际比例 */
@@ -379,4 +596,17 @@ export interface ContractTemplateDesignerExpose {
     resetZoom: () => number;
     /** 获取当前设计区缩放比例 */
     getZoom: () => number;
+    /** 按当前画布宽度缩放页面，并回到自动适宽模式 */
+    fitWidth: () => number;
+    /** 在指定页面创建签署位置并返回归一化后的快照。 */
+    insertSigningPlacement: (type: ContractTemplateSigningPlacementType, pageId?: string, position?: {
+        x: number;
+        y: number;
+    }) => ContractTemplateSigningPlacement | undefined;
+    /** 选中签署位置；传入空值可清除选择。 */
+    selectSigningPlacement: (id?: string) => void;
+    /** 将当前模板签署位置转换为 contract locationRules 兼容结构。 */
+    buildLocationRules: (options: ContractTemplateLocationRuleOptions) => ContractTemplateLocationRule[];
+    /** 将当前模板签署位置投影为 packages/contract 使用的严格 DTO。 */
+    buildContractLocationRules: (options: ContractTemplateLocationRuleOptions) => ContractLocationRule[];
 }

package/dist/types/components/pro-contract-template-designer/src/utils/content-image.d.ts

@@ -0,0 +1,80 @@
+export type ContractTemplateImageSource = 'toolbar' | 'paste';
+export type ContractTemplateImageMimeType = 'image/jpeg' | 'image/webp' | 'image/png';
+export interface ContractTemplateImageCompressionOptions {
+    enabled?: boolean;
+    maxWidth?: number;
+    maxHeight?: number;
+    quality?: number;
+    mimeType?: ContractTemplateImageMimeType;
+}
+/** `true` 使用默认压缩配置，`false` 关闭压缩。 */
+export type ContractTemplateImageCompression = ContractTemplateImageCompressionOptions | boolean;
+export interface NormalizedContractTemplateImageCompressionOptions {
+    enabled: boolean;
+    maxWidth: number;
+    maxHeight: number;
+    quality: number;
+    mimeType: ContractTemplateImageMimeType;
+}
+export interface ContractTemplateImageUploadContext {
+    source: ContractTemplateImageSource;
+    originalFile: File;
+    processedFile: File;
+    dataUrl: string;
+    compressed: boolean;
+}
+export type ContractTemplateImageUploadHandler = (context: ContractTemplateImageUploadContext) => Promise<string> | string;
+export interface ProcessContractTemplateImageOptions {
+    source: ContractTemplateImageSource;
+    compression?: ContractTemplateImageCompression;
+    upload?: ContractTemplateImageUploadHandler;
+}
+export interface ProcessContractTemplateImageResult {
+    src: string;
+    file: File;
+    dataUrl: string;
+    compressed: boolean;
+}
+export interface CompressContractImageResult {
+    file: File;
+    compressed: boolean;
+}
+export declare const DEFAULT_CONTRACT_IMAGE_COMPRESSION: Readonly<NormalizedContractTemplateImageCompressionOptions>;
+/** 避免超大源文件在解码或 Base64 转换时耗尽浏览器内存。 */
+export declare const MAX_CONTRACT_IMAGE_BYTES: number;
+/** 正文图片尺寸边界；统一约束插入、右键设置、拖拽缩放和 HTML 解析。 */
+export declare const MIN_CONTRACT_IMAGE_DIMENSION = 16;
+export declare const MAX_CONTRACT_IMAGE_DIMENSION = 2400;
+export type ContractImageResizeHandle = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+export interface ContractImageResizeInput {
+    width: number;
+    height: number;
+    startClientX: number;
+    startClientY: number;
+    clientX: number;
+    clientY: number;
+    handle: ContractImageResizeHandle;
+    zoom?: number;
+}
+export declare function normalizeContractImageCompression(options?: ContractTemplateImageCompression): NormalizedContractTemplateImageCompressionOptions;
+/** 把用户输入或旧模板属性归一成可写入图片节点的整数尺寸。 */
+export declare function normalizeContractImageDimension(value: unknown): number | undefined;
+/**
+ * 按页面缩放比例把四角指针位移换算成图片最终尺寸。
+ *
+ * 该计算保持宽高比，并把结果统一裁剪到图片尺寸边界；独立成纯函数后，
+ * NodeView 的视觉预览与测试可共用同一份几何规则。
+ */
+export declare function resolveContractImageResizeDimensions(input: ContractImageResizeInput): {
+    width: number;
+    height: number;
+};
+/** 读取前也校验文件，避免该公共方法绕过统一的图片输入边界。 */
+export declare function readContractImageFileAsDataUrl(file: File): Promise<string>;
+/**
+ * 在浏览器支持图片解码和 Canvas 时压缩图片；能力缺失、解码或编码失败均保留
+ * 原文件，避免一次兼容性问题造成合同正文图片丢失。
+ */
+export declare function compressContractImage(file: File, options?: ContractTemplateImageCompression): Promise<CompressContractImageResult>;
+/** 按“压缩 -> data URL -> 宿主上传”的固定顺序生成可安全插入正文的图片。 */
+export declare function processContractImageFile(file: File, options: ProcessContractTemplateImageOptions): Promise<ProcessContractTemplateImageResult>;

package/dist/types/components/pro-contract-template-designer/src/utils/context-variable.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 右键把选区转成正文控件时的纯函数。
+ *
+ * 宽度和 label 都在页面组件里算好上下文后再交给这里裁剪，避免父组件反向
+ * 调用 pageRef 去量选区。
+ */
+/**
+ * 把选区实测宽度裁进变量允许区间。
+ *
+ * 跨行、折叠选区或量不到宽度时上游会传无效值，这里返回 undefined，
+ * 让 `createVariable` 继续使用类型默认宽，避免整行被 160px 或超宽控件撑乱。
+ */
+export declare function resolveContextVariableWidth(selectionWidth: number | undefined, min: number, max: number): number | undefined;
+export type EditorContextMenuKind = 'table' | 'text';
+/**
+ * 决定右键弹表格菜单还是正文菜单。
+ *
+ * 单元格内非空选区（含 Word NBSP 下划线）必须走正文转换；
+ * 若先 `selectTableCellAt` 会把 TextSelection 改成 CellSelection，毁掉填空位。
+ *
+ * 1. 已是 CellSelection → 表格（保留多格，不要折叠）
+ * 2. 非空选区 → 正文（即便落在 td/th 内）
+ * 3. 折叠光标在表格内 → 表格
+ * 4. 折叠光标在正文 → 正文
+ */
+export declare function resolveEditorContextMenuKind(input: {
+    isCellSelection: boolean;
+    selectionEmpty: boolean;
+    inTable: boolean;
+}): EditorContextMenuKind;
+/**
+ * 从选区前置文字推断控件名称。
+ *
+ * 例如 `第一条 甲方名称：____` 先去掉尾部下划线/冒号，再取最后一个片段
+ * `甲方名称`；不足 2 个字视为没有有效字段名，交给调用方回退类型默认名。
+ */
+export declare function inferContextVariableLabel(leadingText: string | undefined): string;

package/dist/types/components/pro-contract-template-designer/src/utils/html.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 合同模板 HTML 处理原语。
+ *
+ * 设计器预览、表达式导出和填写渲染器都要在「有 DOM」和「无 DOM」两种环境下
+ * 处理同一份正文 HTML：浏览器里走 DOMParser，服务端 / SSR / 单测（Node）里走
+ * 字符串与正则。这三条流水线以前各自复制了一份转义、属性读取和变量 span 替换
+ * 逻辑，本模块把这些原语收敛到一处，两种环境的分支语义保持不变。
+ *
+ * 该模块只服务组件内部，不通过 `index.ts` 对外导出。
+ */
+/** 当前运行环境是否可以使用 DOMParser 解析 HTML。 */
+export declare function canParseHtmlDocument(): boolean;
+/**
+ * 是否可以使用浏览器 DOM 处理正文 HTML。
+ *
+ * 比 {@link canParseHtmlDocument} 更严格：额外要求 `window` 存在，用于那些
+ * 处理结果会回写进编辑器 / 预览 DOM 的流水线。净化函数本身不依赖 window，
+ * 因此单独使用 {@link canParseHtmlDocument}。
+ */
+export declare function canUseDomHtml(): boolean;
+/** 把值转义成可以直接放进双引号属性里的文本。 */
+export declare function escapeHtmlAttribute(value: string): string;
+/** 把值转义成可以直接放进标签之间的文本节点。 */
+export declare function escapeHtmlText(value: string): string;
+/** 从标签字符串里读取属性值；属性缺失时返回空字符串。 */
+export declare function getHtmlAttribute(tag: string, name: string): string;
+/** 标签字符串里是否存在该属性；用于区分「未声明」和「声明为空」。 */
+export declare function hasHtmlAttribute(tag: string, name: string): boolean;
+/**
+ * 统一读取正文变量属性的取值器。
+ *
+ * DOM 与正则两条分支都归一成「缺省或空串返回 undefined」，下游再按需要转成
+ * 数字、布尔或带默认值的字符串，避免为每种数据源重复写一遍字段映射。
+ */
+export type TemplateVariableAttributeReader = (name: string) => string | undefined;
+/** 从 DOM 元素读取 `data-*` 属性。 */
+export declare function createElementAttributeReader(element: HTMLElement): TemplateVariableAttributeReader;
+/** 从标签字符串读取 `data-*` 属性。 */
+export declare function createTagAttributeReader(tag: string): TemplateVariableAttributeReader;
+/** 把属性值转成数字；缺省或非法时返回 undefined。 */
+export declare function readOptionalNumber(value: unknown): number | undefined;
+/** 把属性值转成布尔；缺省时返回 undefined，便于与「显式 false」区分。 */
+export declare function readOptionalBoolean(value: unknown): boolean | undefined;
+/**
+ * 把属性值转成数字并套用默认值。
+ *
+ * 沿用旧代码的 `Number(attr || fallback)` 语义：`undefined`、空串和 `0` 都会
+ * 落到默认值，避免历史模板里的空属性把宽高算成 0。
+ */
+export declare function readNumberAttribute(value: unknown, fallback: number): number;
+/**
+ * 无 DOM 环境下逐个替换正文变量 span。
+ *
+ * `String.prototype.replace` 每次调用都会重置全局正则的 lastIndex，因此可以
+ * 安全复用同一个模块级正则。
+ */
+export declare function replaceTemplateVariableSpans(html: string, replacer: (node: string, attrs: string) => string): string;
+/**
+ * 遍历 HTML 中所有匹配 `pattern` 的标签。
+ *
+ * 每次调用都新建正则实例，避免 exec 循环共享 lastIndex 导致跨调用漏匹配。
+ */
+export declare function forEachHtmlTag(html: string, pattern: RegExp, visit: (tag: string) => void): void;
+/** 遍历 HTML 中所有匹配 `pattern` 的标签，把回调返回的非空字符串收集成集合。 */
+export declare function collectFromHtmlTags(html: string, pattern: RegExp, pick: (tag: string) => string | undefined): Set<string>;
+/** 页面尺寸的合法性判断：宽高必须是有限正数。 */
+export declare function isPositiveFiniteNumber(value: unknown): boolean;
+/** 判断任意对象是否具备可用的页面宽高。 */
+export declare function hasPositivePageSize(value: unknown): value is {
+    width: number;
+    height: number;
+};
+/** 去掉首尾空白后返回文本；空文本统一归一为 undefined。 */
+export declare function normalizeOptionalText(value: unknown): string | undefined;

package/dist/types/components/pro-contract-template-designer/src/utils/image-url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 图片变量与签署资源允许相对路径、协议相对路径和 http(s)/blob，以及受限
+ * base64 位图。SVG 仅允许严格校验过的 URL 编码 data URL，脚本协议和非图片
+ * data URL 一律拒绝。
+ */
+export declare function isSafeContractImageUrl(value: string): boolean;