@worm-vue3-print/core 1.0.1

package/dist/index.d.cts

@@ -0,0 +1,376 @@
+type TokenType = 'num' | 'str' | 'bool' | 'ident' | 'punc';
+interface Token {
+    type: TokenType;
+    value: string;
+    position: number;
+}
+type ASTNode = {
+    type: 'num';
+    value: number;
+} | {
+    type: 'str';
+    value: string;
+} | {
+    type: 'bool';
+    value: boolean;
+} | {
+    type: 'ident';
+    name: string;
+} | {
+    type: 'binary';
+    op: string;
+    left: ASTNode;
+    right: ASTNode;
+} | {
+    type: 'unary';
+    op: string;
+    arg: ASTNode;
+    prefix: boolean;
+} | {
+    type: 'ternary';
+    cond: ASTNode;
+    consequent: ASTNode;
+    alternate: ASTNode;
+} | {
+    type: 'member';
+    object: ASTNode;
+    property: string;
+    computed: boolean;
+} | {
+    type: 'call';
+    callee: ASTNode;
+    args: ASTNode[];
+} | {
+    type: 'array';
+    elements: ASTNode[];
+} | {
+    type: 'object';
+    properties: Array<{
+        key: string;
+        value: ASTNode;
+    }>;
+};
+type TemplatePart = {
+    type: 'text';
+    value: string;
+} | {
+    type: 'expr';
+    expression: ASTNode;
+};
+interface TemplateAST {
+    type: 'template';
+    parts: TemplatePart[];
+}
+type ExprFunction = (...args: any[]) => any;
+interface EngineOptions {
+    /** 自定义函数注册表 */
+    functions?: Record<string, ExprFunction>;
+}
+
+declare function tokenize(input: string): Token[];
+
+declare function parse(tokens: Token[]): ASTNode;
+
+declare function evaluate(node: ASTNode, context: Record<string, any>, functions?: Record<string, ExprFunction>): any;
+
+/**
+ * 解析模板字符串为 TemplateAST
+ * 语法: {expr} 内为表达式，外部为字面文本
+ * 转义: \{ \} 不解析为表达式
+ */
+declare function parseTemplate(template: string): TemplateAST;
+/**
+ * 将 TemplateAST 渲染为最终字符串
+ */
+declare function renderTemplate(ast: TemplateAST, context: Record<string, any>, functions?: Record<string, ExprFunction>): string;
+/**
+ * 编译模板，返回渲染函数（性能优化：AST 只解析一次）
+ */
+declare function compileTemplate(template: string, functions?: Record<string, ExprFunction>): (context: Record<string, any>) => string;
+
+/**
+ * 按点分路径取值；优先扁平 key（含点），其次嵌套路径。取不到返回 undefined。
+ */
+declare function getByPath(obj: any, path: string): any;
+
+/**
+ * 金额格式化：千分位 + 两位小数
+ */
+declare function formatMoney(value: any): string;
+/**
+ * 日期格式化
+ * 支持: YYYY, MM, DD, HH, mm, ss
+ */
+declare function formatDate(value: any, fmt: string): string;
+/**
+ * 数字转大写金额
+ */
+declare function toUpperCaseAmount(value: any): string;
+/**
+ * 条件判断函数
+ */
+declare function ifFn(condition: any, trueVal: any, falseVal: any): any;
+
+declare function sum(rows: any[], field: string): number;
+declare function avg(rows: any[], field: string): number;
+declare function count(rows: any[], field: string): number;
+declare function min(rows: any[], field: string): number;
+declare function max(rows: any[], field: string): number;
+
+declare function setPageIndex(v: number): void;
+declare function setTotalPages(v: number): void;
+declare const systemVars: {
+    pageIndex: () => number;
+    totalPages: () => number;
+    printDate: () => string;
+    printTime: () => number;
+};
+
+type PaperSize = 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'CUSTOM';
+/** 纸张尺寸映射（mm） */
+declare const PAPER_DIMENSIONS: Record<PaperSize, {
+    width: number;
+    height: number;
+}>;
+interface TemplateData {
+    paperSize: PaperSize;
+    orientation: 'portrait' | 'landscape';
+    /** 自定义纸张宽度（mm），仅 paperSize='CUSTOM' 时生效 */
+    customWidth?: number;
+    /** 自定义纸张高度（mm），仅 paperSize='CUSTOM' 时生效 */
+    customHeight?: number;
+    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 表达式，渲染阶段以当前页数据行上下文求值 */
+    rawFormatter?: string;
+    /** 内容类型：text（默认）/ barcode / qrcode，非 text 时 content 为码值 */
+    cellType?: string;
+    /** 条形码码制（jsbarcode 格式名），仅 cellType='barcode' 时生效 */
+    barcodeType?: string;
+    /** 二维码纠错级别 L/M/Q/H，仅 cellType='qrcode' 时生效 */
+    qrCodeLevel?: string;
+    /** 条形码下方是否显示文本，仅 cellType='barcode' 时生效 */
+    showBarcodeText?: boolean;
+    rowspan: number;
+    colspan: number;
+    merged: boolean;
+    align?: string;
+    valign?: string;
+    fontSize?: number;
+    fontWeight?: string;
+    color?: string;
+    backgroundColor?: string;
+    borders?: RenderCellBorders;
+    padding?: number;
+    wordWrap?: boolean;
+}
+/** 绑定后的渲染行，存入 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;
+    /** 条码模块宽度倍率 */
+    barWidth?: number;
+    /** 条码下方文本字号（pt） */
+    fontSize?: number;
+}
+/**
+ * 码值 → SVG 字符串渲染器。
+ * 服务端由 print-render 用 bwip-js 实现；浏览器由 print-canvas 用 jsbarcode/qrcode 实现。
+ * 码值非法时抛出异常，由调用方降级为文本占位。
+ */
+interface CodeRenderer {
+    render(value: string, cellType: 'barcode' | 'qrcode', opts?: CodeRenderOptions): string;
+}
+interface RenderRequest {
+    templateJson: TemplateData;
+    printData?: Record<string, any>;
+    /** 服务端对外访问 base URL，用于把 /docfiles/... 等相对路径图片拼接为完整地址 */
+    baseUrl?: string;
+}
+interface MeasuredElement {
+    id: string;
+    measuredHeight: number;
+    /** 表格每行实际高度（mm），仅表格元素有值 */
+    measuredRowHeights?: number[];
+    /** 重复表头段实际高度（mm）= 前 _repeatHeaderCount 个渲染行高之和，仅表格元素有值 */
+    repeatHeaderHeight?: number;
+}
+interface PageLayout {
+    pageIndex: number;
+    sections: PageSection[];
+}
+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[];
+}
+/** 获取纸张物理尺寸（考虑方向） */
+declare function getPaperDimensions(template: TemplateData): {
+    width: number;
+    height: number;
+};
+
+/**
+ * 将模板中元素的 formatter 表达式求值为实际值。
+ * 返回新的模板对象（深拷贝），不修改原始模板。
+ */
+declare function bindData(template: TemplateData, printData?: Record<string, any> | Record<string, any>[], baseUrl?: string): TemplateData;
+declare function injectSystemVariables(html: string): string;
+
+interface GenerateOptions {
+    /** 第一遍测量模式：所有元素在一个连续区域，不分页 */
+    isMeasurementPass?: boolean;
+    /** 条码/二维码 SVG 渲染器；缺省或渲染抛错时降级为文本占位 */
+    codeRenderer?: CodeRenderer;
+}
+/**
+ * 生成完整 HTML 字符串。
+ *
+ * - 第一遍（isMeasurementPass=true）：单页连续区域，每个元素带 data-measure-id
+ * - 第二遍：按分页结果生成多页 HTML，填充 {pageIndex}/{totalPages}
+ */
+declare function generateHtml(template: TemplateData, pageLayouts: PageLayout[], printData?: Record<string, any>, options?: GenerateOptions): string;
+
+/** mm 值转 CSS 字符串 */
+declare function mm(value: number): string;
+/**
+ * 生成完整的打印页面 CSS。
+ * 包含纸张尺寸、边距、页眉页脚、内容区、首页叠加区域等样式。
+ */
+declare function buildPageCss(template: TemplateData): string;
+/**
+ * 生成内联样式：元素绝对定位（mm 单位）
+ */
+declare function elementPositionStyle(left: number, top: number, width: number, height?: number): string;
+
+/**
+ * 表格设计底部（mm）= 设计 top + 设计高度。
+ * 设计高度优先取 tableRows 设计行高之和（设计意图，不受渲染数据量影响），
+ * 缺失时回退 options.height。
+ */
+declare function tableDesignBottom(el: TemplateElement): number;
+/**
+ * 基于测量结果执行分页计算，返回每页的布局方案。
+ *
+ * 算法流程：
+ * 1. 计算页面可用高度（contentHeight / availableHeight）
+ * 2. 按 Y 坐标顺序遍历内容区元素
+ * 3. 表格：逐行切片；非表格：元素级不拆分
+ * 4. 处理 keepWithNext、单行超高、首页叠加等边界
+ * 5. 表格下方跟随区：与最后一片同页时包成 flow-group；放不下整体移下一页
+ */
+declare function paginate(template: TemplateData, measuredElements: Map<string, MeasuredElement>): PageLayout[];
+
+/**
+ * 在受限沙箱内求值表达式
+ * @param expr 表达式字符串
+ * @param context 上下文变量
+ */
+declare function safeEval(expr: string, context: Record<string, any>): any;
+/**
+ * 模板字符串求值：{表达式} 内求值，外为字面文本。
+ * 聚合函数 SUM/AVG/COUNT/MIN/MAX(field) 预处理（需 ctx.rows）。
+ * 单个 {expr} 求值失败时保留原 {expr} 文本。
+ */
+declare function evaluateTemplate(text: string, ctx: Record<string, any>): string;
+
+declare class TemplateEngine {
+    private functions;
+    constructor(options?: EngineOptions);
+    registerFunction(name: string, fn: ExprFunction): void;
+    evaluate(expression: string, context: Record<string, any>): any;
+    render(template: string, context: Record<string, any>): string;
+}
+
+export { type ASTNode, type CodeRenderOptions, type CodeRenderer, type EngineOptions, type ExprFunction, type GenerateOptions, type MeasuredElement, PAPER_DIMENSIONS, type PageLayout, type PageSection, type PaperSize, type TemplateData as PrintTemplateData, type TemplateElement as PrintTemplateElement, type RenderCell, type RenderRequest, type RenderRow, type TemplateAST, TemplateEngine, avg, bindData, buildPageCss, compileTemplate, count, elementPositionStyle, evaluate, evaluateTemplate, formatDate, formatMoney, generateHtml, getByPath, getPaperDimensions, ifFn, injectSystemVariables, max, min, mm, paginate, parse, parseTemplate, renderTemplate, safeEval, setPageIndex, setTotalPages, sum, systemVars, tableDesignBottom, toUpperCaseAmount, tokenize };