@worm-vue3-print/core 1.2.2 → 1.3.1

package/dist/driver-Dn_YAzO5.d.ts

@@ -0,0 +1,935 @@
+/** 拼版配置（模板级，随模板保存） */
+interface TilingOptions {
+    enabled: boolean;
+    /** 目标纸张（张）预设；缺省 A4。不含 CONTINUOUS */
+    sheetPaperSize?: Exclude<PaperSize, 'CONTINUOUS'>;
+    /** 目标纸张方向；缺省 portrait。只影响目标纸，不影响标签朝向 */
+    sheetOrientation?: 'portrait' | 'landscape';
+    /** sheetPaperSize='CUSTOM' 时的纸宽（mm）；缺省 210 */
+    sheetCustomWidth?: number;
+    /** sheetPaperSize='CUSTOM' 时的纸高（mm）；缺省 297 */
+    sheetCustomHeight?: number;
+    /** 目标纸四边留白（mm）；与模板 margins（标签内部边距）不是一回事 */
+    sheetMargin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** 相邻格横向间距（mm） */
+    gapX: number;
+    /** 相邻格纵向间距（mm） */
+    gapY: number;
+    /** 列数（手工指定，必填，≥1 的整数）；行数由纸面自动推导 */
+    columns: number;
+}
+/** 打开拼版开关时的初值（列数还会按纸面收敛，见设计器 TilingConfig） */
+declare const TILE_DEFAULTS: TilingOptions;
+/**
+ * 拼版几何所需的最小模板信息。
+ * 刻意不含 elements——布局只依赖纸张与拼版配置，因此设计器侧（元素 id 可选）
+ * 与渲染侧（元素 id 必需）两种 TemplateData 都能直接传入。
+ */
+interface TilingTemplateInput {
+    paperSize: PaperSize;
+    orientation: 'portrait' | 'landscape';
+    customWidth?: number;
+    customHeight?: number;
+    tiling?: TilingOptions;
+}
+type TilingIssueCode = 'COLUMNS_INVALID' | 'COLUMNS_OVERFLOW' | 'SHEET_SIZE_INVALID' | 'LABEL_TOO_TALL' | 'CONTINUOUS_UNSUPPORTED' | 'SHEET_CONTINUOUS';
+interface TilingIssue {
+    code: TilingIssueCode;
+    message: string;
+}
+interface TilingResolveOptions {
+    paperOverride?: {
+        width?: number;
+        height?: number;
+    };
+}
+interface TileLayout {
+    tile: {
+        width: number;
+        height: number;
+    };
+    sheet: {
+        width: number;
+        height: number;
+    };
+    columns: number;
+    rows: number;
+    perSheet: number;
+    /** 本纸最多可放列数；列数超宽时用于提示「最多可放 N 列」 */
+    maxColumns: number;
+    margin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    gapX: number;
+    gapY: number;
+}
+/** 拼版校验失败（message 与 validateTiling 首条 issue 完全一致） */
+declare class TilingError extends Error {
+    readonly code: TilingIssueCode;
+    constructor(code: TilingIssueCode, message: string);
+}
+/** 保留一位小数：错误文案里的 mm 值可读性 */
+declare function roundMm(value: number): number;
+/** 配置归一化：缺省字段补 TILE_DEFAULTS，sheetMargin 做深合并 */
+declare function normalizeTilingOptions(t: TilingTemplateInput): TilingOptions;
+/** 目标纸张解析；优先级：paperOverride → CUSTOM 自定义宽高 → 预设 → 缺省 A4 纵向 */
+declare function resolveSheetMm(t: TilingTemplateInput, opts?: TilingResolveOptions): {
+    width: number;
+    height: number;
+};
+/**
+ * 拼版布局（纯函数）。调用方负责判断 enabled——本函数不做开关判断：
+ * 管线在分流后调用、设计器在开关打开时调用。
+ * 配置非法时抛 TilingError，message 与 validateTiling 首条 issue 一致。
+ */
+declare function computeTileLayout(t: TilingTemplateInput, opts?: TilingResolveOptions): TileLayout;
+/** 第 index 格的绝对位置（mm）；行优先：左→右、上→下 */
+declare function tilePosition(layout: TileLayout, index: number): {
+    left: number;
+    top: number;
+};
+/**
+ * 本纸最多可放列数（纯几何，**不校验、不抛错**）。
+ * 供设计器在「列数已超宽」的非法态下仍能提示「最多可放 N 列」并约束输入上限——
+ * 此时 computeTileLayout 会抛错，用不了。
+ */
+declare function computeMaxColumns(t: TilingTemplateInput, opts?: TilingResolveOptions): number;
+/**
+ * 拼版配置校验；永不抛错，合法返回 []。
+ * 判定顺序：纸面类 → 列数类 → 高度类（设计文档 §9）。
+ * 不检查 enabled——由调用方决定是否校验。
+ */
+declare function validateTiling(t: TilingTemplateInput, opts?: TilingResolveOptions): TilingIssue[];
+
+/** 模板声明的字体文件：`url` 以 '/' 开头时按渲染端 baseUrl 解析，绝对 URL 原样使用 */
+interface PrintFontFile {
+    url: string;
+    /** CSS 字重；缺省 400。必须与模板里元素实际使用的字重一致，否则 Chromium 会合成粗体（度量不同） */
+    weight?: number;
+    /** CSS 字型；缺省 normal */
+    style?: 'normal' | 'italic';
+}
+/**
+ * 模板级字体声明：随模板保存，服务端/客户端/浏览器据此生成同一份 @font-face，
+ * 从而不依赖各端系统里装了什么字体。
+ */
+interface PrintFontDeclaration {
+    /** CSS 族名，必须与元素 options.fontFamily 的写法一致 */
+    family: string;
+    /** 设计器下拉里的显示名；缺省用 family */
+    label?: string;
+    files: readonly PrintFontFile[];
+}
+/**
+ * 生成模板声明字体的 @font-face CSS。
+ *
+ * - `font-display: block`：测量与出图期间绝不能用兜底字体顶上，否则分页按兜底度量算。
+ * - 无声明或声明不合法（无族名/无可用 url）时返回空串，调用方可直接拼接。
+ */
+declare function buildFontFaceCss(fonts?: readonly PrintFontDeclaration[]): string;
+/**
+ * 全局兜底字体栈，逐字对齐原 css-builder 中 body 的 font-family 输出。
+ * 元素是可直接拼接的合法 CSS 片段：需要引号的族名自带引号，
+ * 通用族名（sans-serif）绝不能加引号——加了会被解析为字面字体名而失效。
+ */
+declare const FALLBACK_FONT_STACK: readonly string[];
+/**
+ * 把 CSS 值转义为可安全放入双引号包裹的内联样式属性（style="..."）的形式。
+ * 属性值中直接出现 `"` 会提前闭合属性，导致其后的声明整条丢失
+ * （实测：`style="font-family:"SimSun", Arial"` 解析后 fontFamily 为空串）。
+ */
+declare function escapeInlineStyleValue(cssValue: string): string;
+/**
+ * 生成 CSS font-family 值：显式族名 + 全局兜底栈。
+ * - 未设置/空白 → 纯兜底栈
+ * - 值已含逗号 → 视为调用方给出的完整栈，原样前置（不整体加引号，否则整串会变成一个字体名）
+ * - 其余 → 作为单个族名加引号后前置
+ */
+declare function toFontFamilyStack(family?: string): string;
+
+/**
+ * 纸张尺寸。
+ * - DOT_FULL / DOT_HALF / DOT_THIRD：针式打印纸 241 系列全等分 / 二等分 / 三等分；
+ * - LABEL_80X60 / LABEL_60X40 / LABEL_40X30：标签纸；
+ * - THERMAL_57 / THERMAL_80 / THERMAL_110：小票纸（热敏卷纸，连续纸，出纸高度按内容推导）；
+ * - CONTINUOUS=连续纸（热敏/标签，设计高度固定 297mm，出纸高度按内容推导，底边距用 margins.bottom）。
+ * 连续纸（含小票纸）设计高度仅作画布，方向强制纵向，纸宽可用 customWidth 覆盖。
+ */
+type PaperSize$1 = 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'DOT_FULL' | 'DOT_HALF' | 'DOT_THIRD' | 'LABEL_80X60' | 'LABEL_60X40' | 'LABEL_40X30' | 'THERMAL_57' | 'THERMAL_80' | 'THERMAL_110' | 'CUSTOM' | 'CONTINUOUS';
+/** 元素所属区域（运行时标记，序列化时剥离；区域元素 left/top 相对所在区域左上角，单位 pt） */
+type ElementZone = 'content' | 'header' | 'footer';
+/** 元素分页属性（非表格元素） */
+interface PaginationConfig$1 {
+    pageable: boolean;
+    keepWithNext: boolean;
+}
+/** 表格分页配置 */
+interface TablePaginationConfig$1 {
+    enabled: boolean;
+}
+/** 新模板数据模型（替代旧 PrintPanel / PrintTemplateJson） */
+interface TemplateData$1 {
+    paperSize: PaperSize$1;
+    /** 方向（纸张方向）= 当前纸张长宽；切换时直接交换纸张宽高（设计稿内容随之铺在该尺寸上） */
+    orientation: 'portrait' | 'landscape';
+    /**
+     * 出纸旋转角度（整页内容旋转出纸）：缺省 0（不旋转）。仅固定纸（非连续纸、非拼版）生效。
+     * 0° 纸张不变、内容不旋转；180° 纸张不变、内容翻转；90°/270° 纸张长宽互换以贴合旋转后的内容包围盒，
+     * 设计稿内容保持原方向不变，不被拉伸或裁切。
+     */
+    outputRotation?: 0 | 90 | 180 | 270;
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    header: {
+        height: number;
+        elements: TemplateElement$1[];
+    };
+    footer: {
+        height: number;
+        elements: TemplateElement$1[];
+    };
+    firstPageOverlay: {
+        height: number;
+        elements: TemplateElement$1[];
+    };
+    elements: TemplateElement$1[];
+    /** 页面名称（多页面模板中用于设计器页签显示；渲染端忽略） */
+    name?: string;
+    /** 模板级字体声明（由设计器 prop 同步写入）：三端据此生成同一份 @font-face */
+    fonts?: PrintFontDeclaration[];
+    /** 拼版打印配置（模板级）；缺省不写 = 不拼版 */
+    tiling?: TilingOptions;
+    /** 元素坐标单位（新保存模板固定 'mm'；旧数据无此字段按 pt 迁移） */
+    unit?: 'pt' | 'mm';
+    /** 自定义纸张宽度（mm），paperSize='CUSTOM' 时有效；连续纸（含小票纸）时为纸宽，缺省取预设纸宽 */
+    customWidth?: number;
+    /** 自定义纸张高度（mm），仅 paperSize='CUSTOM' 时有效；连续纸（含小票纸）时仅作设计画布高度（缺省 297，出纸按内容推导） */
+    customHeight?: number;
+    /** 页面（纸张）背景色；未设置时默认白色 */
+    pageBackground?: string;
+    /** 水印配置 */
+    watermark?: WatermarkOptions;
+    /** 手动参考线（设计态辅助，序列化保留，渲染端忽略） */
+    guides?: AlignLine[];
+    /** 设计背景（定位底图）：仅设计画布显示，用于套打对位；预览与打印管线一律忽略 */
+    designBackground?: DesignBackground;
+}
+/**
+ * 多页面模板（设计器侧 wrapper）：pages 为设计器完整模型 TemplateData。
+ * 与主入口 render 管线的同名 MultiPageTemplateData（pages 为简化 TemplateData）有意分离，
+ * 两侧运行时代表同一份 JSON（{version, pages}），由 canvas 侧经 normalizeTemplate 交给渲染端。
+ */
+interface MultiPageTemplateData$1 {
+    version?: 1;
+    pages: TemplateData$1[];
+}
+/** 模板元素引用（用于 TemplateData 各区域） */
+type TemplateElement$1 = PrintElementData;
+/** 元素类型 */
+type ElementType = 'text' | 'image' | 'longText' | 'table' | 'hline' | 'vline' | 'rect' | 'oval' | 'barcode' | 'qrcode' | 'html' | 'pageNumber';
+/** 对齐方式 */
+type TextAlign = 'left' | 'center' | 'right';
+/**
+ * 文字超出可用空间时的显示形式（文本类元素与表格单元格共用）：
+ * - `clip`：截断，超出部分不显示；不换行（`wordWrap=false`）时以省略号收尾
+ * - `shrink`：自动缩小字号，缩到下限字号仍放不下则退化为截断
+ * - `autoHeight`：自适应高度，元素高度 / 表格行高随内容增高
+ *
+ * 未显式设置时按元素类型取默认值（text=clip、longText=autoHeight、单元格=autoHeight），
+ * 与既有渲染行为一致，存量模板不受影响。
+ */
+type TextFit = 'clip' | 'shrink' | 'autoHeight';
+/** 垂直对齐方式（文本类元素，未设置时按顶部处理，与打印端一致） */
+type VerticalAlign = 'top' | 'middle' | 'bottom';
+/** 缩放手柄方向 */
+type ResizePoint = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+/** 设计背景（定位底图）：仅设计画布显示，预览/PDF/打印/截图均不输出 */
+interface DesignBackground {
+    /** 宿主上传接口返回的完整图片路径，可直接用于 <img src> */
+    src: string;
+    /** 旋转角度，仅允许 90° 步进；非法值读取时按 0 处理 */
+    rotation: 0 | 90 | 180 | 270;
+}
+/** 引导线 */
+interface AlignLine {
+    type: 'vertical' | 'horizontal';
+    position: number;
+    id?: string;
+    /** 引导线颜色(区分左/中/右对齐类型) */
+    color?: string;
+}
+/** 吸附结果 */
+interface AdsorbResult {
+    left: number;
+    top: number;
+    lines: AlignLine[];
+}
+/** 元素矩形（用于吸附检测） */
+interface ElementRect {
+    id: string;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** 表格行类型：header 标题 / data 数据（全表唯一） / subtotal 当前页小计（每页末尾） / summary 整表汇总 */
+type TableRowType = 'header' | 'data' | 'subtotal' | 'summary';
+/** 单边边框样式 */
+interface TableCellBorder {
+    width: number;
+    style: 'solid' | 'dashed' | 'dotted' | 'double' | 'none';
+    color: string;
+}
+/** 四边边框 */
+interface TableCellBorders {
+    top?: TableCellBorder;
+    right?: TableCellBorder;
+    bottom?: TableCellBorder;
+    left?: TableCellBorder;
+}
+/** 单元格内容类型 */
+type TableCellType = 'text' | 'barcode' | 'qrcode' | 'image';
+/** 单元格 */
+interface TableCell {
+    id: string;
+    formatter?: string;
+    cellType?: TableCellType;
+    barcodeType?: string;
+    qrCodeLevel?: string;
+    showBarcodeText?: boolean;
+    /**
+     * 打印机分辨率（点/英寸，常见 203/300/600），仅 cellType='barcode' 时生效：
+     * 条形码尺寸由「条宽 → dpi → 等比缩小」结算（见 render/barcode-dot.ts），
+     * 给出本字段时首选尺寸吸附到整数打印点（dpi 优先于条宽的精确毫米值），
+     * 单元格可用宽高不足则整体等比缩小，消除热敏出纸「条宽忽宽忽窄」。
+     */
+    printerDpi?: number;
+    /** 条码模块宽度倍率（2-4），仅 cellType='barcode' 时生效：每模块首选宽度 = 倍率/2 × 0.25mm */
+    barWidth?: number;
+    /** 条码下方文本字号（相对条高，条高为 30），仅 cellType='barcode' 时生效 */
+    barFontSize?: number;
+    rowspan?: number;
+    colspan?: number;
+    merged?: boolean;
+    align?: TextAlign;
+    valign?: 'top' | 'middle' | 'bottom';
+    fontFamily?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    color?: string;
+    backgroundColor?: string;
+    borders?: TableCellBorders;
+    padding?: number;
+    wordWrap?: boolean;
+    /** 文字溢出显示形式；缺省按「不换行→截断，否则自适应行高」判定 */
+    textFit?: TextFit;
+    /** 自动缩小（textFit='shrink'）的下限字号（pt）；缺省 6pt */
+    shrinkMinFontSize?: number;
+    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down';
+    maxWidth?: number;
+    maxHeight?: number;
+}
+/** 表格行 */
+interface TableRow {
+    id: string;
+    type: TableRowType;
+    height: number;
+    repeatOnPage?: boolean;
+    cells: TableCell[];
+}
+/** 单元格选区（r/c 均为 0 基，闭区间） */
+interface TableSelection {
+    elementId: string;
+    r1: number;
+    c1: number;
+    r2: number;
+    c2: number;
+}
+/** 表格历史字段绑定（兼容存量模板，实际取 fields[0].dataSource） */
+interface ElementFieldBinding {
+    text?: string;
+    dataSource?: string;
+}
+/** 元素选项（序列化到 JSON） */
+interface ElementOptions {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    /** @deprecated 统一使用 formatter */
+    title?: string;
+    testData?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    fontFamily?: string;
+    color?: string;
+    backgroundColor?: string;
+    textAlign?: TextAlign;
+    verticalAlign?: VerticalAlign;
+    lineHeight?: number;
+    letterSpacing?: number;
+    /** 文字溢出显示形式（text/longText）；缺省按元素类型取默认值 */
+    textFit?: TextFit;
+    /** 自动缩小（textFit='shrink'）的下限字号（pt）；缺省 6pt */
+    shrinkMinFontSize?: number;
+    /** 自动换行（text/longText）；缺省 true。false 时单行显示，截断形式下以省略号收尾 */
+    wordWrap?: boolean;
+    fixed?: boolean;
+    locked?: boolean;
+    /** 元素可见性（图层面板切换） */
+    visible?: boolean;
+    borderWidth?: number;
+    borderStyle?: string;
+    borderColor?: string;
+    contentPaddingLeft?: number;
+    contentPaddingTop?: number;
+    contentPaddingRight?: number;
+    contentPaddingBottom?: number;
+    textDecoration?: string;
+    textType?: 'barcode' | 'qrcode';
+    barcodeType?: string;
+    barWidth?: number;
+    barAutoWidth?: string;
+    /**
+     * 打印机分辨率（点/英寸，常见 203/300/600）：条形码尺寸由「条宽 → dpi → 等比缩小」结算
+     * （见 render/barcode-dot.ts），给出本字段时首选尺寸吸附到整数打印点，dpi 优先于条宽的
+     * 精确毫米值；可用框放不下则整体等比缩小。缺省不启用（按条宽的毫米值落纸）。
+     */
+    printerDpi?: number;
+    qrCodeLevel?: string;
+    src?: string;
+    /** 内容缩放模式（image/qrcode）：contain | cover | fill | none | scale-down。条形码不接受拉伸——尺寸已由结算确定 */
+    fit?: string;
+    /** 内容最大宽度（mm，image/barcode/qrcode）；缺省不限制 */
+    maxWidth?: number;
+    /** 内容最大高度（mm，image/barcode/qrcode）；缺省不限制 */
+    maxHeight?: number;
+    hideTitle?: boolean;
+    draggable?: boolean;
+    axis?: string;
+    transform?: number;
+    zIndex?: number;
+    groupId?: string;
+    pagination?: PaginationConfig$1;
+    tablePagination?: TablePaginationConfig$1;
+    /** @deprecated 静态布局模式已移除，所有表格统一使用动态模式 */
+    tableMode?: 'dynamic' | 'static';
+    tableRows?: TableRow[];
+    tableColWidths?: number[];
+    tableDefaultFontSize?: number;
+    tableDefaultColor?: string;
+    tableDefaultPadding?: number;
+    /** 列表数据源路径（data 行迭代的数据数组） */
+    dataSource?: string;
+    /** @deprecated 兼容存量表格模型；列表数据源优先使用 dataSource */
+    fields?: ElementFieldBinding[];
+    formatter?: string;
+    styler?: string;
+    rowStyler?: string;
+    longTextIndent?: number;
+    leftSpaceRemoved?: boolean;
+    lHeight?: number;
+}
+/** 元素类型元数据 */
+interface PrintElementTypeMeta {
+    title?: string;
+    type: ElementType;
+    editable?: boolean;
+    formatter?: string;
+    styler?: string;
+}
+/** 序列化元素数据 */
+interface PrintElementData {
+    id?: string;
+    type?: ElementType;
+    options: ElementOptions;
+    printElementType: PrintElementTypeMeta;
+}
+/** 水印配置 */
+interface WatermarkOptions {
+    /** 水印模式：fixed=固定文本，binding=绑定字段 */
+    mode?: 'fixed' | 'binding';
+    /** 固定文本（mode=fixed 时使用） */
+    content?: string;
+    /** 绑定字段（mode=binding 时使用） */
+    binding?: string;
+    /** 测试值（设计态预览使用） */
+    testData?: string;
+    /** 旋转角度 */
+    rotate?: number;
+    /** 颜色 */
+    color?: string;
+    /** 透明度 */
+    opacity?: number;
+    /** 显示时间戳 */
+    timestamp?: boolean;
+    /** 时间格式（timestamp=true 时使用，token 支持 YYYY/MM/DD/HH/mm/ss） */
+    format?: string;
+    /** 平铺瓦片宽度（px，控制水印密度：越小越密，默认 260，下限 140） */
+    tileWidth?: number;
+    /** 平铺瓦片高度（px，控制水印密度：越小越密，默认 180，下限 100） */
+    tileHeight?: number;
+}
+/** 运行时元素（设计器中带状态） */
+interface RuntimeElement {
+    id: string;
+    options: ElementOptions;
+    printElementType: PrintElementTypeMeta;
+    selected?: boolean;
+    /** 运行时所属区域，序列化时剥离，缺省视为 content */
+    zone?: ElementZone;
+}
+/** 业务字段（宿主查询后传入，核心不内置字段字典） */
+interface PrintBusinessField {
+    id?: string;
+    fieldKey: string;
+    fieldLabel: string;
+    /** 字段类型；'list' 表示明细列表字段（用于表格数据源选择） */
+    fieldType: string;
+    sortOrder: number;
+}
+/**
+ * 绑定位置描述（用于属性面板自动渲染绑定控件）
+ */
+interface BindingDescriptor {
+    /** 绑定的属性路径（如 'options.formatter'、'options.tableRows[0].cells[0].formatter'） */
+    targetPath: string;
+    /** 显示名称 */
+    label: string;
+    /** 数据源上下文 */
+    dataSource: 'main' | 'list' | 'subtotal' | 'summary';
+    /** 绑定的列表字段（仅表格行需要） */
+    listField?: string;
+    /** 提示文本 */
+    placeholder?: string;
+    /** 是否允许清空 */
+    clearable?: boolean;
+}
+/** 截图请求载荷（设计器叠层对比用） */
+interface ScreenshotRequest {
+    templateJson: TemplateData$1;
+    printData: Record<string, any>;
+}
+/** 截图适配器：宿主依据模板 + 数据返回 PNG Blob */
+type RequestScreenshotFn = (req: ScreenshotRequest) => Promise<Blob>;
+/** 图片上传适配器：宿主上传文件并返回可访问的图片 URL */
+type UploadImageFn = (file: File) => Promise<string>;
+/**
+ * 设计背景图上传适配器（由宿主实现注入）。
+ * 入参为用户选择的图片文件；返回值必须是可直接 <img src> 访问的完整图片路径。
+ * 与 UploadImageFn 语义独立：不配合 baseUrl，不要求相对路径。
+ */
+type UploadDesignBackgroundFn = (file: File) => Promise<string>;
+
+declare const MAX_BATCH_COPIES = 500;
+type PrintDataInput = Record<string, any> | Record<string, any>[];
+type NormalizedPrintData = {
+    mode: 'single';
+    data: Record<string, any>;
+} | {
+    mode: 'batch';
+    dataList: Record<string, any>[];
+};
+declare function normalizePrintData(raw: PrintDataInput | undefined): NormalizedPrintData;
+
+type PaperSize = 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'DOT_FULL' | 'DOT_HALF' | 'DOT_THIRD' | 'LABEL_80X60' | 'LABEL_60X40' | 'LABEL_40X30' | 'THERMAL_57' | 'THERMAL_80' | 'THERMAL_110' | 'CUSTOM' | 'CONTINUOUS';
+/** 连续纸纸型：出纸高度按渲染内容推导 */
+type ContinuousPaperSize = 'CONTINUOUS' | 'THERMAL_57' | 'THERMAL_80' | 'THERMAL_110';
+/** 固定尺寸纸型：纸面确定，可作拼版目标纸等需要确定纸面的场景 */
+type SheetPaperSize = Exclude<PaperSize, ContinuousPaperSize>;
+/** 纸张尺寸映射（mm） */
+declare const PAPER_DIMENSIONS: Record<PaperSize, {
+    width: number;
+    height: number;
+}>;
+/** 纸型是否连续纸（小票纸/热敏卷纸）：出纸高度按渲染内容推导 */
+declare function isContinuousPaperSize(paperSize: string): boolean;
+interface TemplateData {
+    paperSize: PaperSize;
+    orientation: 'portrait' | 'landscape';
+    /**
+     * 出纸旋转角度（整页内容旋转出纸）：缺省 0（不旋转）。仅固定纸（非连续纸、非拼版）生效。
+     * 0° 纸张不变、内容不旋转；180° 纸张不变、内容翻转；90°/270° 纸张长宽互换以贴合旋转后的内容包围盒，
+     * 设计稿内容保持原方向不变，不被拉伸或裁切。
+     */
+    outputRotation?: 0 | 90 | 180 | 270;
+    /** 自定义纸张宽度（mm），paperSize='CUSTOM' 时生效；连续纸（含小票纸）时为纸宽，缺省取预设纸宽 */
+    customWidth?: number;
+    /** 自定义纸张高度（mm），仅 paperSize='CUSTOM' 时生效；连续纸（含小票纸）时仅作设计画布高度（缺省 297，出纸按内容推导） */
+    customHeight?: number;
+    /** 页面（纸张）背景色；未设置时默认白色 */
+    pageBackground?: string;
+    /** 水印配置（同 design/WatermarkOptions，渲染端读取其颜色/透明度/角度/密度/绑定） */
+    watermark?: WatermarkOptions;
+    /** 页面名称（多页面模板中用于设计器页签与错误上下文；渲染端忽略） */
+    name?: string;
+    /** 模板级字体声明：三端据此生成同一份 @font-face，不依赖各端系统字体 */
+    fonts?: PrintFontDeclaration[];
+    /** 拼版打印配置（模板级）；缺省不写 = 不拼版 */
+    tiling?: TilingOptions;
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    header: {
+        height: number;
+        elements: TemplateElement[];
+    };
+    footer: {
+        height: number;
+        elements: TemplateElement[];
+    };
+    firstPageOverlay: {
+        height: number;
+        elements: TemplateElement[];
+    };
+    elements: TemplateElement[];
+}
+/** 元素分页属性（非表格元素） */
+interface PaginationConfig {
+    pageable: boolean;
+    keepWithNext: boolean;
+}
+/** 表格分页配置 */
+interface TablePaginationConfig {
+    enabled: boolean;
+}
+/**
+ * 模板元素 — print-render 侧的简化视图。
+ * 兼容前端 PrintElementData 的 options 嵌套结构，
+ * 同时提供扁平访问器方便分页引擎使用。
+ */
+interface TemplateElement {
+    id: string;
+    type: string;
+    /** 元素选项（与前端 ElementOptions 对齐） */
+    options: Record<string, any>;
+    /** 元素类型元数据（与前端 PrintElementTypeMeta 对齐） */
+    printElementType?: {
+        type: string;
+        title?: string;
+        [key: string]: any;
+    };
+    /** 分页属性（非表格元素） */
+    pagination?: PaginationConfig;
+    /** 表格分页配置（表格元素） */
+    tablePagination?: TablePaginationConfig;
+}
+type RenderRowType = 'header' | 'data' | 'summary' | 'subtotal' | 'static';
+interface RenderCellBorder {
+    width: number;
+    style: string;
+    color: string;
+}
+interface RenderCellBorders {
+    top?: RenderCellBorder;
+    right?: RenderCellBorder;
+    bottom?: RenderCellBorder;
+    left?: RenderCellBorder;
+}
+/** 绑定后的单元格：content 已是最终文本（小计行 content 为占位值，真实值按每页数据渲染时求值） */
+interface RenderCell {
+    content: string;
+    /**
+     * 单元格原始 formatter 表达式，渲染阶段重新求值：
+     * 小计行以当前页数据行上下文求值；引用了页码（pageIndex / totalPages）的单元格按该页页码求值。
+     */
+    rawFormatter?: string;
+    /** 内容类型：text（默认）/ barcode / qrcode / image，非 text 时 content 为码值或图片 URL */
+    cellType?: string;
+    /** 条形码码制（jsbarcode 格式名），仅 cellType='barcode' 时生效 */
+    barcodeType?: string;
+    /** 二维码纠错级别 L/M/Q/H，仅 cellType='qrcode' 时生效 */
+    qrCodeLevel?: string;
+    /** 条形码下方是否显示文本，仅 cellType='barcode' 时生效 */
+    showBarcodeText?: boolean;
+    /** 打印机分辨率（点/英寸），仅 cellType='barcode' 时生效：给出后条码尺寸优先适配打印机点阵 */
+    printerDpi?: number;
+    /** 图片缩放模式，仅 cellType='image' 时生效 */
+    fit?: string;
+    /** 图片最大宽度（mm），仅 cellType='image' 时生效 */
+    maxWidth?: number;
+    /** 图片最大高度（mm），仅 cellType='image' 时生效 */
+    maxHeight?: number;
+    rowspan: number;
+    colspan: number;
+    merged: boolean;
+    align?: string;
+    valign?: string;
+    fontSize?: number;
+    /** 字体族名；未设置时单元格不输出 font-family，交还 CSS 继承 */
+    fontFamily?: string;
+    fontWeight?: string;
+    color?: string;
+    backgroundColor?: string;
+    borders?: RenderCellBorders;
+    padding?: number;
+    wordWrap?: boolean;
+    /** 文字溢出显示形式；缺省按「不换行→截断，否则自适应行高」判定 */
+    textFit?: string;
+    /** 自动缩小（textFit='shrink'）的下限字号（pt）；缺省 6pt */
+    shrinkMinFontSize?: number;
+    /** 自动缩小求得的最终字号（pt）：测量趟算出后回写，最终趟据此渲染 */
+    fittedFontSize?: number;
+}
+/** 绑定后的渲染行，存入 options._renderRows */
+interface RenderRow {
+    type: RenderRowType;
+    height: number;
+    cells: RenderCell[];
+}
+interface CodeRenderOptions {
+    /** 条形码码制（jsbarcode 格式名），仅 barcode 类型使用 */
+    barcodeType?: string;
+    /** 二维码纠错级别 L/M/Q/H，仅 qrcode 类型使用 */
+    qrCodeLevel?: string;
+    /** 条形码下方是否显示文本 */
+    showText?: boolean;
+    /** 条码模块宽度倍率；决定每模块的首选物理宽度（倍率/2 × 0.25mm），给 dpi 后吸附到最近整数点 */
+    barWidth?: number;
+    /** 条码下方文本字号（pt） */
+    fontSize?: number;
+    /**
+     * 打印机分辨率（点/英寸）；给出时首选尺寸吸附到「每模块整数个打印点」，dpi 优先于条宽的精确毫米值。
+     */
+    printerDpi?: number;
+    /** 目标可用宽度（mm）：条形码元素框宽或单元格内容区宽，渲染器据此决定是否等比缩小 */
+    targetWidthMm?: number;
+    /** 目标可用高度（mm）：条形码元素框高或单元格内容区高，同上 */
+    targetHeightMm?: number;
+}
+/**
+ * 码值 → SVG 字符串渲染器。
+ * 三端统一由 core 的 DOM 执行器实现（jsbarcode/qrcode 算法只有一份）：
+ * 浏览器进程内直调，服务端与桌面客户端注入 IIFE 产物后在页面上下文执行。
+ * 码值非法时抛出异常，由调用方降级为文本占位。
+ */
+interface CodeRenderer {
+    render(value: string, cellType: 'barcode' | 'qrcode', opts?: CodeRenderOptions): string;
+}
+interface RenderRequest {
+    /** 模板 JSON：单模板或 { pages } 多页面模板 */
+    templateJson: TemplateData | MultiPageTemplateData;
+    /** 业务数据：对象=单份；非空对象数组=批量（数组长度即份数，上限 500） */
+    printData?: PrintDataInput;
+    /** 服务端对外访问 base URL，用于把 /docfiles/... 等相对路径图片拼接为完整地址 */
+    baseUrl?: string;
+    /** 相对路径字体基址；缺省回落 `baseUrl`（缺省时二者同域），传空串表示不拼接 */
+    fontBaseUrl?: string;
+    /** 宿主纸张覆盖（mm）：宽/高沿用 print.paperSize 语义，0 或负数视为未提供 */
+    paperOverride?: {
+        width?: number;
+        height?: number;
+    };
+    /** 连续纸显式纸高（mm）逃生门 */
+    paperHeightMm?: number;
+}
+interface MeasuredElement {
+    id: string;
+    measuredHeight: number;
+    /** 表格每行实际高度（mm），仅表格元素有值 */
+    measuredRowHeights?: number[];
+    /** 重复表头段实际高度（mm）= 前 _repeatHeaderCount 个渲染行高之和，仅表格元素有值 */
+    repeatHeaderHeight?: number;
+}
+interface PageLayout {
+    pageIndex: number;
+    sections: PageSection[];
+    /**
+     * 本页含「分页预算放不下、被强制留在本页」的内容（首个元素/单元即放不下）。
+     * 该场景不产出空白页，但内容可能超出纸面，需由上层（如拼版「每份恰好 1 页」校验）据此阻断。
+     */
+    overflow?: boolean;
+}
+interface PageSection {
+    elementId: string;
+    type: 'element' | 'table-slice' | 'flow-group';
+    /** table-slice 专用：渲染行起始索引（含表头行） */
+    startRow?: number;
+    /** table-slice 专用：渲染行结束索引（不含） */
+    endRow?: number;
+    /** table-slice 专用：非首片时在切片前重复表头段 */
+    repeatHeader?: boolean;
+    /** table-slice 专用：本片末尾是否渲染小计行（当前页数据小计，每页重复） */
+    subtotal?: boolean;
+    /** table-slice 专用：本片末尾是否渲染整表汇总行（总计，仅最后一页） */
+    summary?: boolean;
+    /** 本节在本页内容区内的实际 top（mm）。发生换页后的内容为 0；缺省回退元素设计 top */
+    renderTop?: number;
+    /**
+     * flow-group 专用：相对容器在本页的实际 top（mm），覆盖元素设计 top。
+     * 同页时 = 表格设计 top（容器顶部对齐表格 slice 顶部）；
+     * 跟随区整体移页时 = 新页内容区顶部（0）。
+     */
+    groupTop?: number;
+    /** flow-group 专用：跟随区成员元素 id（容器内按文档流渲染） */
+    followElementIds?: string[];
+}
+/**
+ * 获取纸张物理尺寸（考虑方向）。
+ * - CUSTOM：宽高取 customWidth/customHeight，缺省回退 A4；
+ * - 连续纸（小票纸/热敏卷纸）：强制纵向，宽度取 customWidth（缺省取预设纸宽），
+ *   高度仅为设计画布高度（取 customHeight，缺省取预设值），出纸高度由内容推导；
+ * - 其余预设：取 PAPER_DIMENSIONS，横向时宽高互换。
+ * 参数刻意只用纸张相关字段——不需要 elements，故设计器侧与渲染侧模板均可直接传入。
+ */
+declare function getPaperDimensions(template: {
+    paperSize: PaperSize;
+    orientation: 'portrait' | 'landscape';
+    customWidth?: number;
+    customHeight?: number;
+}): {
+    width: number;
+    height: number;
+};
+/** 是否连续纸（热敏/小票/标签卷纸）：出纸高度按渲染内容推导 */
+declare function isContinuousPaper(template: {
+    paperSize: string;
+}): boolean;
+interface MultiPageTemplateData {
+    /** 版本号，缺省 1 */
+    version?: 1;
+    /** 按打印顺序排列的页面模板，每个都是完整的单页 TemplateData */
+    pages: TemplateData[];
+}
+
+/** 物理尺寸（毫米）；三端与协议的公共纸尺寸表示 */
+interface PaperMm {
+    width: number;
+    height: number;
+}
+/** 测量容器尺寸（CSS 像素）；浏览器为 iframe 尺寸，服务端为 page viewport */
+interface ViewportPx {
+    width: number;
+    height: number;
+}
+/** 纸高来源：config = 模板/宿主给定，derived = 连续纸探针推导 */
+type HeightSource = 'config' | 'derived';
+interface MarginsMm {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** 出图目标规格：与宿主无关，宿主负责翻译成自己的选项 */
+interface PdfTargetSpec {
+    paperMm: PaperMm;
+    marginsMm: MarginsMm;
+    printBackground: boolean;
+    scale: number;
+    preferCSSPageSize: boolean;
+}
+interface ScreenshotTargetSpec {
+    type: 'png';
+    fullPage: boolean;
+    omitBackground: boolean;
+}
+/** 宿主回传的原始测量值（CSS px，不做任何业务换算） */
+interface RawMeasurement {
+    id: string;
+    heightPx: number;
+    /** 表格行高（px），仅表格元素有值 */
+    rowHeightsPx?: number[];
+}
+/** 一次码值渲染请求；key 为稳定键，用于跨进程映射 */
+interface CodeSpec {
+    key: string;
+    value: string;
+    cellType: 'barcode' | 'qrcode';
+    opts: CodeRenderOptions;
+}
+interface PrintJob {
+    /** 模板 JSON（设计器 TemplateData 结构兼容；含 { pages } 多页面模板） */
+    templateJson: TemplateData | MultiPageTemplateData;
+    /** 业务数据：对象=单份；非空对象数组=按数组长度批量合并为一个作业 */
+    printData?: PrintDataInput;
+    /** 相对路径图片基址 */
+    baseUrl?: string;
+    /**
+     * 相对路径字体基址；缺省回落 `baseUrl`，传空串表示不拼接（浏览器端按文档 origin 解析）。
+     * 出图端必须能访问解析后的字体地址，否则声明字体会静默回退到系统字体。
+     */
+    fontBaseUrl?: string;
+    /** 宿主纸张覆盖（mm）；0 或负数视为未提供 */
+    paperOverride?: {
+        width?: number;
+        height?: number;
+    };
+    /** 连续纸显式纸高逃生门（mm） */
+    paperHeightMm?: number;
+    /** 单任务总预算（ms），缺省 30000 */
+    timeoutMs?: number;
+    /** 就绪等待（ms），缺省 5000 */
+    readinessMs?: number;
+    /** 调用方提供的码值渲染器（浏览器端覆盖语义）；提供时跳过多趟收集 */
+    codeRenderer?: CodeRenderer;
+}
+interface PreparedDocument {
+    html: string;
+    pageCount: number;
+    paperMm: PaperMm;
+    continuous: boolean;
+    heightSource: HeightSource;
+    pageLayouts: PageLayout[];
+    /** 份数：单对象=1，数组=数组长度 */
+    copies: number;
+    /** 批量时每份的物理纸张尺寸（连续纸各份高度不同）；单份无此字段 */
+    copyPaperMm?: PaperMm[];
+}
+interface RenderPdfResult {
+    pdf: Uint8Array;
+    prepared: PreparedDocument;
+}
+
+/** 执行器可被宿主调用的方法名（与 browser/dom-executor.ts 一一对应） */
+type ExecutorMethod = 'waitReady' | 'readMeasurements' | 'readContentBottom' | 'renderCodes' | 'applyTextFit';
+/** 执行器方法的宿主目标种类：window（waitReady）/ document（读 DOM）/ none（纯计算，无首参） */
+type ExecutorTargetKind = 'window' | 'document' | 'none';
+/**
+ * 各执行器方法的宿主目标注入方式：宿主据此决定是否补首参。
+ * 三端 driver 均按本表装配参数，不得各自假设「非 waitReady 一律传 document」。
+ */
+declare const EXECUTOR_TARGETS: Record<ExecutorMethod, ExecutorTargetKind>;
+/** core 自带的 DOM 执行器产物；宿主负责把它送进页面 */
+interface ExecutorBundle {
+    source: string;
+    version: string;
+}
+/**
+ * 单文档槽位原语：只做宿主 I/O，不含任何业务规则（纸张、分页、码制参数均不得出现在实现里）。
+ * 工厂返回时该槽位必须已存在一个空白文档（open 只负责调整视口）。
+ */
+interface PageDriver {
+    /**
+     * 是否需要注入 core 的 DOM 执行器产物；缺省 true。
+     * 浏览器 iframe driver 在进程内直调执行器，置 false 即可不传 bundle。
+     */
+    requiresExecutor?: boolean;
+    open(viewport: ViewportPx): Promise<void>;
+    setContent(html: string): Promise<void>;
+    /** 同一文档内幂等；文档重建后必须重新注入 */
+    injectExecutor(bundle: ExecutorBundle): Promise<void>;
+    evaluate<T>(method: ExecutorMethod, args?: unknown[]): Promise<T>;
+    pdf?(html: string, spec: PdfTargetSpec): Promise<Uint8Array>;
+    screenshot?(html: string, spec: ScreenshotTargetSpec): Promise<Uint8Array>;
+    close(): Promise<void>;
+}
+interface DriverFactory {
+    createDriver(): Promise<PageDriver>;
+}
+
+export { type PrintJob as $, type AdsorbResult as A, type BindingDescriptor as B, type CodeRenderer as C, type DriverFactory as D, type ElementOptions as E, type TextAlign as F, type TextFit as G, type UploadImageFn as H, type MeasuredElement as I, type TemplateElement as J, type PaperMm as K, type ViewportPx as L, type MultiPageTemplateData as M, type HeightSource as N, type MarginsMm as O, type PageLayout as P, type PdfTargetSpec as Q, type RawMeasurement as R, type ScreenshotRequest as S, type TemplateData as T, type UploadDesignBackgroundFn as U, type VerticalAlign as V, type WatermarkOptions as W, type ScreenshotTargetSpec as X, type CodeRenderOptions as Y, type ExecutorBundle as Z, type TileLayout as _, type CodeSpec as a, type PreparedDocument as a0, type RenderPdfResult as a1, type PrintFontDeclaration as a2, type ContinuousPaperSize as a3, EXECUTOR_TARGETS as a4, type ExecutorMethod as a5, type ExecutorTargetKind as a6, FALLBACK_FONT_STACK as a7, MAX_BATCH_COPIES as a8, type NormalizedPrintData as a9, resolveSheetMm as aA, roundMm as aB, tilePosition as aC, toFontFamilyStack as aD, validateTiling as aE, PAPER_DIMENSIONS as aa, type PageDriver as ab, type PageSection as ac, type PaperSize as ad, type PrintDataInput as ae, type PrintFontFile as af, type RenderCell as ag, type RenderRequest as ah, type RenderRow as ai, type SheetPaperSize as aj, TILE_DEFAULTS as ak, TilingError as al, type TilingIssue as am, type TilingIssueCode as an, type TilingOptions as ao, type TilingResolveOptions as ap, type TilingTemplateInput as aq, buildFontFaceCss as ar, computeMaxColumns as as, computeTileLayout as at, escapeInlineStyleValue as au, getPaperDimensions as av, isContinuousPaper as aw, isContinuousPaperSize as ax, normalizePrintData as ay, normalizeTilingOptions as az, type TemplateData$1 as b, type TableRow as c, type TableCellBorder as d, type TableCell as e, type TableRowType as f, type ElementType as g, type RuntimeElement as h, type ElementZone as i, type PrintBusinessField as j, type ElementRect as k, type ResizePoint as l, type AlignLine as m, type DesignBackground as n, type ElementFieldBinding as o, type MultiPageTemplateData$1 as p, type PaginationConfig$1 as q, type PaperSize$1 as r, type PrintElementData as s, type PrintElementTypeMeta as t, type RequestScreenshotFn as u, type TableCellBorders as v, type TableCellType as w, type TablePaginationConfig$1 as x, type TableSelection as y, type TemplateElement$1 as z };