@jcyao/print-sdk 1.0.0

package/dist/printEngine/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 打印引擎插件化架构 - 类型定义
+ */
+import type { ComponentNode, DataBinding, PipeConfig } from '../types';
+/**
+ * 渲染上下文
+ * 提供给渲染器插件使用的公共方法和数据
+ */
+export interface RenderContext {
+    /**
+     * 业务数据
+     */
+    data: any;
+    /**
+     * 解析数据绑定，返回最终值
+     */
+    resolveBinding(binding?: DataBinding): string;
+    /**
+     * 应用管道转换
+     */
+    applyPipes(value: any, pipes?: PipeConfig[]): any;
+    /**
+     * 根据路径获取数据值
+     */
+    getValueByPath(path: string, fallback?: string): any;
+    /**
+     * 格式化日期
+     */
+    formatDate(value: any, format: string): string;
+    /**
+     * mm 转 px 系数（3.78）
+     */
+    mmToPx: number;
+    /**
+     * 页面信息（用于计算可用宽度）
+     */
+    pageInfo?: {
+        widthMm: number;
+        heightMm: number;
+        marginMm: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+}
+/**
+ * 组件渲染器接口
+ * 所有组件渲染器必须实现此接口
+ */
+export interface ComponentRenderer {
+    /**
+     * 组件类型标识
+     */
+    readonly type: string;
+    /**
+     * 渲染组件为 HTML 字符串
+     * @param component 组件配置
+     * @param context 渲染上下文
+     * @returns HTML 字符串
+     */
+    render(component: ComponentNode, context: RenderContext): string;
+    /**
+     * 计算组件高度（可选，用于分页）
+     * @param component 组件配置
+     * @param context 渲染上下文
+     * @returns 高度（mm）
+     */
+    calculateHeight?(component: ComponentNode, context: RenderContext): number;
+}
+/**
+ * 样式对象类型
+ */
+export type StyleObject = Record<string, string | number>;
+/**
+ * 样式构建辅助函数类型
+ */
+export type StyleBuilder = (styles: StyleObject) => string;
+/**
+ * 分页项（单个组件在某页的信息）
+ */
+export interface PageItem {
+    type: ComponentNode['type'];
+    index: number;
+    begin?: number;
+    end?: number;
+}
+/**
+ * 页面层级（流式层 + 覆盖层）
+ */
+export interface PageLayers {
+    flowLayer: ComponentNode[];
+    overlayLayer: ComponentNode[];
+}
+/**
+ * 分页结果（多页，每页包含流式层和覆盖层）
+ */
+export type Pages = PageLayers[];

package/dist/printEngine/utils/styleBuilder.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 样式构建工具函数
+ */
+import type { StyleObject } from '../types';
+/**
+ * 将样式对象转换为 CSS 字符串
+ * @example
+ * buildStyleString({ fontSize: '14px', color: '#000' })
+ * // => "font-size: 14px; color: #000"
+ */
+export declare function buildStyleString(styles: StyleObject): string;
+/**
+ * 构建绝对定位样式
+ * @param xMm X坐标（mm）
+ * @param yMm Y坐标（mm）
+ * @param widthMm 宽度（mm）
+ * @param heightMm 高度（mm）
+ * @param mmToPx mm转px系数（默认3.78）
+ */
+export declare function buildPositionStyle(xMm: number, yMm: number, widthMm?: number, heightMm?: number, mmToPx?: number): StyleObject;

package/dist/printEngine.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 打印引擎核心类（插件化重构版）
+ * 负责：插件管理、数据绑定、Pipe 转换、虚拟分页计算
+ */
+import type { PrintTemplate, ComponentNode } from './types';
+import type { ComponentRenderer } from './printEngine/types';
+export type { ComponentRenderer, RenderContext } from './printEngine/types';
+export { MM_TO_PX, COMPONENT_DEFAULT_SIZE, TABLE_DEFAULT, STYLE_DEFAULT, TABLE_STYLE_DEFAULT, BARCODE_CONFIG, QRCODE_CONFIG } from './printEngine/constants';
+export declare class PrintEngine {
+    private template;
+    private data;
+    private renderers;
+    private readonly mmToPx;
+    constructor(template: PrintTemplate, data: any);
+    /**
+     * 注册默认渲染器
+     */
+    private registerDefaultRenderers;
+    /**
+     * 注册渲染器插件
+     * @param renderer 组件渲染器
+     */
+    registerRenderer(renderer: ComponentRenderer): void;
+    /**
+     * 注销渲染器插件
+     * @param type 组件类型
+     */
+    unregisterRenderer(type: string): void;
+    /**
+     * 根据数据路径获取值
+     * 支持嵌套路径，如：order.receiver.name
+     * 智能匹配：如果路径以 root. 开头但数据中没有 root 层，自动去掉 root. 前缀
+     */
+    private getValueByPath;
+    /**
+     * 应用管道转换
+     */
+    private applyPipes;
+    /**
+     * 执行单个管道转换
+     */
+    private executePipe;
+    /**
+     * 简单的日期格式化
+     */
+    private formatDate;
+    /**
+     * 解析数据绑定，返回最终渲染的值
+     */
+    private resolveBinding;
+    /**
+     * 创建渲染上下文
+     */
+    private createRenderContext;
+    /**
+     * 渲染单个组件（通过插件）
+     */
+    renderComponent(component: ComponentNode): string;
+    /**
+     * 获取页面尺寸（mm）
+     */
+    private getPageSize;
+    /**
+     * 判断是否需要换页
+     * @param currentHeight 当前页面累计高度
+     * @param componentHeight 组件高度
+     * @param gap 组件间距
+     * @param availableHeight 可用高度
+     * @param isFirstComponent 是否为页面第一个组件
+     */
+    private shouldBreakPage;
+    /**
+     * 计算表头高度（mm）
+     */
+    private calculateTableHeaderHeight;
+    /**
+     * 计算表格行高度（mm）
+     */
+    private calculateTableRowHeight;
+    /**
+     * 渲染单个页面（直接渲染，不做智能布局）
+     */
+    private renderSinglePage;
+    /**
+     * 虚拟分页：基于相对间距的流式布局
+     * 核心逻辑：
+     * 1. 计算每个组件与上一个组件的间距 (gap)
+     * 2. 按顺序累加高度，遇到表格就拆分
+     * 3. 换页时从 marginTop 开始，忽略原 gap
+     */
+    private calculatePages;
+    /**
+     * 表格跨页拆分（基于相对间距）
+     * 支持 repeatHeader 配置、精确行高计算、空表格检查
+     */
+    private splitTableWithGap;
+    /**
+     * 生成打印 HTML
+     */
+    generatePrintHTML(): string;
+}
+/**
+ * 工厂函数：创建打印引擎实例
+ */
+export declare function createPrintEngine(template: PrintTemplate, data: any): {
+    /**
+     * 生成完整打印 HTML
+     */
+    generatePrintHTML(): string;
+    /**
+     * 注册自定义渲染器
+     */
+    registerRenderer(renderer: ComponentRenderer): void;
+    /**
+     * 注销渲染器
+     */
+    unregisterRenderer(type: string): void;
+};

package/dist/sdk.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 打印 SDK 统一导出
+ * 这个文件将来可以直接独立为 @printer/sdk 包
+ */
+export { PrintSDK, createPrintSDK } from './PrintSDK';
+export type { PrintOptions, BatchPrintOptions, BatchPrintProgress, } from './PrintSDK';
+export { PrintEngine, createPrintEngine } from './printEngine';
+export type { ComponentRenderer, RenderContext } from './printEngine';
+export { MM_TO_PX, COMPONENT_DEFAULT_SIZE, TABLE_DEFAULT, STYLE_DEFAULT, TABLE_STYLE_DEFAULT, BARCODE_CONFIG, QRCODE_CONFIG } from './printEngine/constants';
+export { generatePrintPageStyles, generateBatchPrintStyles, generatePrintHTML, getPageSizeFromConfig, } from './printEngine/htmlTemplate';
+export { TextRenderer, TableRenderer, ImageRenderer, RectRenderer, LineRenderer, QRCodeRenderer, BarcodeRenderer, } from './printEngine/renderers';
+export type { PrintTemplate, ComponentNode, DataBinding, PipeConfig, PageConfig, ComponentType, SchemaField, SchemaDictionary, MockData, } from './types';

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+export type SchemaFieldType = 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'object' | 'array';
+export interface SchemaField {
+    key: string;
+    label: string;
+    type: SchemaFieldType;
+    description?: string;
+    children?: SchemaField[];
+    enum?: {
+        value: string | number;
+        label: string;
+    }[];
+    format?: 'date' | 'datetime' | 'money' | 'percent';
+}
+export interface SchemaDictionary {
+    id: string;
+    name: string;
+    rootType: 'object' | 'array';
+    root: SchemaField;
+    version?: string;
+    description?: string;
+}
+export interface PageConfig {
+    size: 'A4' | 'A5' | 'CUSTOM' | 'CONTINUOUS';
+    widthMm?: number;
+    heightMm?: number;
+    minHeightMm?: number;
+    orientation: 'portrait' | 'landscape';
+    marginMm: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+export type ComponentType = 'text' | 'image' | 'rect' | 'container' | 'table' | 'line' | 'qrcode' | 'barcode';
+export interface PipeConfig {
+    type: string;
+    options?: Record<string, any>;
+}
+export interface DataBinding {
+    path: string;
+    pipes?: PipeConfig[];
+    fallback?: string;
+}
+export interface TablePaginationConfig {
+    repeatHeader?: boolean;
+}
+export interface TableColumnSummary {
+    type: 'sum' | 'avg' | 'max' | 'min' | 'count';
+    precision?: number;
+    prefix?: string;
+    suffix?: string;
+}
+export interface TableColumn {
+    dataIndex: string;
+    title: string;
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+    hidden?: boolean;
+    summary?: TableColumnSummary;
+}
+export interface TableSummaryStyle {
+    backgroundColor?: string;
+    fontWeight?: string;
+    fontSize?: number;
+}
+export interface TableProps {
+    columns: TableColumn[];
+    showHeader?: boolean;
+    bordered?: boolean;
+    repeatHeader?: boolean;
+    showSummary?: boolean;
+    summaryMode?: 'page' | 'total';
+    summaryLabel?: string;
+    summaryStyle?: TableSummaryStyle;
+    _pageData?: any[];
+    _showHeader?: boolean;
+    _isLastPage?: boolean;
+    _totalData?: any[];
+}
+export interface ComponentNode {
+    id: string;
+    type: ComponentType;
+    layout: {
+        mode: 'absolute' | 'flow';
+        xMm?: number;
+        yMm?: number;
+        widthMm?: number;
+        heightMm?: number;
+        zIndex?: number;
+    };
+    style?: Record<string, any>;
+    binding?: DataBinding;
+    props?: Record<string, any>;
+    children?: ComponentNode[];
+}
+export interface PrintTemplate {
+    id: string;
+    name: string;
+    version: string;
+    description?: string;
+    schemaId: string;
+    page: PageConfig;
+    layoutMode: 'absolute' | 'flow';
+    components: ComponentNode[];
+}
+export interface MockData {
+    id: string;
+    name: string;
+    schemaId?: string;
+    templateId?: string;
+    data: any;
+    description?: string;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@jcyao/print-sdk",
+  "version": "1.0.0",
+  "description": "Universal Print SDK - Client-side print solution",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joker-yjc/printer"
+  },
+  "homepage": "https://github.com/joker-yjc/printer#readme",
+  "bugs": {
+    "url": "https://github.com/joker-yjc/printer/issues"
+  },
+  "keywords": [
+    "print",
+    "sdk",
+    "client-side",
+    "template",
+    "printer",
+    "printing",
+    "pdf",
+    "browser-print",
+    "template-engine",
+    "qrcode",
+    "barcode",
+    "typescript"
+  ],
+  "author": "joke_yao",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/qrcode": "^1.5.6",
+    "rollup": "^4.9.6",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "decimal.js": "^10.6.0",
+    "jsbarcode": "^3.12.3",
+    "qrcode": "^1.5.4"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}