千寻打印组件在线文档

版本: 2.0 | 最后更新: 2025年10月

1. 快速入门

只需三步，即可在您的网页应用中集成打印功能：

1. 在 HTML 中引入 socket-link.js 文件。
2. 创建一个 SocketLink 实例，连接到打印服务。
3. 通过该实例按照标准指令格式发送打印或其他指令。

1.1 引入 JavaScript 文件

首先，将 socket-link.js 文件放到您的项目中（例如 js/ 目录下），然后在您的 HTML 页面的 或 底部引入它：

引入后，全局将可用 SocketLink 类。

1.2 建立 WebSocket 连接

创建一个 SocketLink 实例，它会自动尝试连接到指定的 WebSocket 服务器地址。

// 创建连接
const printLink = new SocketLink("ws://localhost:13526", {
    reconnectInterval: 5000, // 5秒重连一次
    maxReconnectAttempts: 5,
    onOpen: () => {
        console.log("链接成功");
    },
    onMessage: (event) => {
        console.log("收到消息", event);
    },
    onError: (e) => console.error("❌ Socket错误", e),
    onClose: (event) => {
        console.log("连接已关闭", event);
    }
});

1.3 通信协议

所有与后端服务的通信都必须遵循统一的指令格式。指令是一个包含 Command 和 Data 两个字段的 JSON 对象。

• Command: 指令类型，如 "print", "getprintlist"。
• Data: 指令附带的数据，通常是字符串化的 JSON。

1.3.1 打印指令

发送此指令以执行打印任务。

• Command: "print"
• Data: 一个 JSON 字符串，内容是符合“打印模板详解”章节格式的打印任务对象。

示例：

// 定义一个打印任务
const printTask = {
    "TaskId": "ORDER_123456",
    "Template": {
        "config": { "width": 80, "height": 60 },
        "nodes": [
            {
                "type": "label",
                "rect": { "x": 5, "y": 5, "width": 70, "height": 10 },
                "text": "Hello, YbPrintPlug!",
                "font": { "size": 14, "bold": true }
            }
        ]
    },
    "data": {},
    "PrintName": ""
};

// 包装成标准指令并发送
const printInstruction = {
    Command: "print",
    Data: JSON.stringify(printTask)
};
printLink.send(printInstruction);

1.3.2 获取打印机列表

发送此指令以查询系统中所有可用的打印机。

• Command: "getprintlist"
• Data: 无。

示例：

const getPrintersInstruction = {
    Command: "getprintlist"
};
printLink.send(getPrintersInstruction);

服务端响应示例：

{
    "printers": ["Microsoft Print to PDF", "HP LaserJet MFP"]
}

1.3.3 获取屏幕 DPI 信息

发送此指令以获取屏幕物理 DPI，用于前端精确渲染。

• Command: "getscreen"
• Data: 无。

示例：

const getScreenInstruction = {
    Command: "getscreen"
};
printLink.send(getScreenInstruction);

服务端响应示例：

{
    "PixelsPerMillimeterX": 3.78,
    "PixelsPerMillimeterY": 3.78
}

2. 打印模板详解

打印模板是一个 JSON 对象，它精确地定义了打印内容的布局和样式。所有尺寸单位均为毫米 (mm)，确保所见即所得。

2.1 模板根结构

2.2 Template 对象

{
  "config": {
    "width": 80,
    "height": 60
  },
  "nodes": [ ... ]
}

2.3 config 对象

3. 节点类型 (Node Types)

所有节点都必须包含一个 type 字段和一个 rect 字段，用于定义其类型和位置大小。

{
  "type": "label", // 节点类型
  "rect": { // 位置和大小
    "x": 10,
    "y": 10,
    "width": 50,
    "height": 20
  },
  // ... 其他特定于类型的配置
}

3.1 label - 文本标签

用于显示静态或动态文本。

示例：

{
  "type": "label",
  "rect": { "x": 5, "y": 5, "width": 70, "height": 10 },
  "text": "客户姓名: <%=customer.name%>",
  "font": { "size": 12, "bold": true, "family": "微软雅黑" },
  "stringFormat": { "align": "left", "valign": "middle" },
  "color": { "text": "#333333" }
}

3.2 barcode - 条形码

支持生成高精度条形码。

示例：

{
  "type": "barcode",
  "rect": { "x": 10, "y": 20, "width": 60, "height": 20 },
  "text": "<%=product.sku%>",
  "displayValue": true,
  "barcode": {
    "rotate": 0,
    "mirror": false
  }
}

3.3 qrcode - 二维码

用于生成二维码。

示例：

{
  "type": "qrcode",
  "rect": { "x": 50, "y": 5, "width": 25, "height": 25 },
  "text": "https://your-domain.com/item/<%=itemId%>"
}

3.4 image - 图片

支持 Base64、网络 URL 和本地文件路径。

示例 (Base64):

{
  "type": "image",
  "rect": { "x": 5, "y": 35, "width": 20, "height": 20 },
  "text": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
}

3.5 line - 线条

用于绘制横线或竖线。

示例：

{
  "type": "line",
  "rect": { "x": 0, "y": 30, "width": 80, "height": 0 },
  "line": {
    "type": "horizontal",
    "width": 0.3,
    "color": "#cccccc"
  }
}

3.6 table - 表格

用于绘制数据表格，支持自动行高。

示例：

{
  "type": "table",
  "rect": { "x": 5, "y": 45, "width": 70, "height": 30 },
  "text": "orderItems",
  "columns": [
    { "title": "商品", "field": "name", "width": 30, "align": "left" },
    { "title": "数量", "field": "qty", "width": 15, "align": "center" },
    { "title": "价格", "field": "price", "width": 25, "align": "right" }
  ],
  "rowsHeight": { "header": 8 }
}

3.7 box - 矩形框

通常用于绘制背景色或边框。

{
  "type": "box",
  "rect": { "x": 0, "y": 0, "width": 80, "height": 60 },
  "color": {
    "enabled": true,
    "background": "#f0f0f0"
  },
  "border": {
    "enabled": true,
    "width": 0.5,
    "color": "#000000",
    "radius": 2
  }
}

4. 样式配置

4.1 font - 字体配置

4.2 stringFormat - 文本格式

5. 数据绑定

在模板的 text 字段中，使用 <%= ... %> 语法可以绑定到 data 对象中的数据。

const printTask = {
    "Template": { ... }, // 模板定义
    "data": {
        "customer": {
            "name": "张三",
            "phone": "13800138000"
        },
        "items": [
            { "name": "苹果", "price": 5.5, "qty": 3 },
            { "name": "香蕉", "price": 3.2, "qty": 2 }
        ]
    }
};

{
  "type": "label",
  "rect": { "x": 5, "y": 5, "width": 70, "height": 10 },
  "text": "客户: <%=customer.name%> (<%=customer.phone%>)"
},
{
  "type": "table",
  "rect": { "x": 5, "y": 20, "width": 70, "height": 30 },
  "text": "items", // 绑定到 data.items 数组
  "columns": [
    { "title": "品名", "field": "name", "width": 30 },
    { "title": "单价", "field": "price", "width": 20 },
    { "title": "数量", "field": "qty", "width": 20 }
  ]
}

客户: 张三 (13800138000)
+----------------+--------+--------+
|     品名       |  单价  |  数量  |
+----------------+--------+--------+
|     苹果       |  5.5   |   3    |
|     香蕉       |  3.2   |   2    |
+----------------+--------+--------+