手把手教你在 iVX 中集成 PeachPrinter，实现企业单据套打

PeachTeam
55 阅读8分钟

手把手教你在 iVX 中集成 PeachPrinter，实现企业单据套打

在企业日常运营中，单据套打（如订单、发票、出库单等）是高频需求，PeachPrinter 作为轻量高效的打印工具，支持自定义模板设计与跨设备打印，结合 iVX 低代码平台的快速开发能力，可快速实现企业级单据套打功能。以下是详细的集成步骤，零基础也能轻松上手。

一、前置准备

  1. 核心工具：PeachPrinter 客户端程序、PeachPrinter JS 依赖文件（peach-jprinter-min.js）

  2. 基础条件：已注册并登录的 iVX 账号、本地设备已安装 PeachPrinter 客户端（启动后默认监听 9623 端口，无需手动配置）

  3. 资源获取：从 PeachPrinter 官方渠道（Gitee 仓库 / 官网）下载客户端安装包及 JS 依赖文件，确保资源完整性

二、详细操作步骤

步骤 1：准备 PeachPrinter 相关资源

1.1 安装并启动 PeachPrinter 客户端

  • 下载与本地设备适配的 PeachPrinter 客户端（Windows/Mac/Linux 版本均支持），按照引导完成安装

  • 安装完成后启动客户端，启动成功后会默认监听本地 9623 端口，用于接收打印请求（端口占用时可在客户端设置中修改）

1.2 设计并导出单据打印模板

PeachPrinter 提供可视化模板设计器，支持 Excel 风格的灵活布局，操作如下：

  1. 打开 PeachPrinter 官方在线模板设计器，无需安装本地软件，直接在线设计

  2. 设计器采用单元格合并、属性配置（字体、对齐方式、边框等）的方式，搭建单据结构（如抬头、表体、签字区等）

  3. 设计完成后，点击设计器顶部的「模板代码」按钮，复制生成的模板 JSON 字符串（含布局、样式配置），单独保存备用（后续用于绑定动态数据）；也可点击「保存模板」，后续可重新编辑

步骤 2：搭建 iVX 基础项目页面

登录 iVX 在线编辑器，快速搭建用于单据录入、预览、打印的页面：

  1. 新建 Web 项目（选择 “空白项目” 或 “自定义项目” 均可）

  2. 在前台页面添加核心组件，按需配置：

  • 功能按钮：命名为「printBtn」，用于触发打印操作

  • 数据录入组件：输入框（客户名称、订单号）、数字输入框（订单金额）、日期选择器（打印日期）等，绑定单据动态字段

  • 预览组件（可选）：添加面板组件，命名为「billPreview」，用于实时展示单据数据，方便测试时核对

  1. 调整组件位置与样式，确保页面布局清晰、操作流程顺畅（如录入区在上、预览区在中、打印按钮在下）

步骤 3：在 iVX 中引入 PeachPrinter 的 JS 文件

通过自定义函数动态引入外部 JS 依赖，确保打印接口可调用：

3.1 创建「加载 JS 文件」自定义函数

  1. 在 iVX 编辑器右侧「逻辑工具栏」中，点击「添加函数组件」，命名为 loadPeachPrinterJS（便于识别功能）

  2. 编辑函数，粘贴以下代码（动态创建 script 标签，引入 PeachPrinter JS 文件）：

// 创建 script 标签，用于加载外部 JS 依赖

const script = document.createElement('script');

// 配置 JS 文件路径：若已上传至 iVX 项目资源库，填相对路径；若用在线链接，直接填官方下载地址

script.src = "https://gitee.com/ctxb2004/peach-printer3.0/releases/download/printer-v3.1.0/peach-jprinter-min.js";

script.type = "text/javascript";

// 监听 JS 加载完成事件，确保后续接口可用

script.onload = () => {

 console.log("PeachPrinter JS 文件加载成功");

};

// 加载失败时提示

script.onerror = () => {

 console.error("PeachPrinter JS 文件加载失败，请检查路径是否正确");

};

// 将 script 标签插入页面 head 节点，完成加载

document.head.appendChild(script);

// 返回加载状态

return { status: "success", msg: "JS 文件开始加载" };
3.2 绑定页面初始化事件

确保 JS 文件在页面加载时自动加载，避免调用打印接口时依赖未就绪：

  • 选中 iVX 页面（点击页面空白区域），在右侧「事件面板」中添加「页面加载完成」事件

  • 事件配置：选择「同步调用」→ 选中 loadPeachPrinterJS 函数，无需传参，保存配置

步骤 4：编写打印核心函数（绑定模板与动态数据）

创建 printBill 函数，实现 “模板 + 动态数据” 拼接，并调用 PeachPrinter 打印接口：

4.1 创建打印函数并配置参数

  1. 新增自定义函数组件，命名为 printBill

  2. 配置函数参数（对应单据动态字段，与页面录入组件一一对应）：

  • customerName：客户名称（字符串类型）

  • orderAmount：订单金额（数字类型）

  • orderNo：订单号（字符串类型）

  • printTime：打印时间（字符串类型）

  • 可根据实际单据需求，添加更多参数（如商品名称、数量、备注等）

4.2 编写函数核心代码

函数体内完成模板替换、数据绑定、调用打印接口，完整代码如下（替换模板 JSON 为实际导出内容）：

// 接收函数参数（页面录入的动态数据）

const { customerName, orderAmount, orderNo, printTime } = arguments\[0];

// 授权信息（免费版无需填写，保持空对象即可；商业版需填写官方提供的 licence 信息）

const licence = {

 code: "",

 name: "",

};

// 单据模板 JSON（替换为步骤 1.2 中导出的模板代码，确保格式正确）

const billTemplate = {

 // 此处粘贴实际导出的模板 JSON 字符串，示例格式如下（需替换为自己的模板）：

 // "width":80,"height":100,"rows":10,"cols":20,"cells":\[...]

};

// 主表动态数据（与模板中的字段名对应，字段名需和模板设计时一致）

const mainData = {

 customerName: customerName,  // 客户名称

 orderAmount: orderAmount.toFixed(2),  // 订单金额（保留 2 位小数）

 orderNo: orderNo,  // 订单号

 printTime: printTime,  // 打印时间

 // 若模板中有其他动态字段，需在此补充

};

// 子表数据（如订单明细、商品列表等，无则留空数组）

const listData = \[];

// 校验 PeachPrinter 是否加载成功

if (window.PeachPrinter) {

 try {

   // 调用 PeachPrinter 静默打印接口（无需预览，直接发送打印请求）

   PeachPrinter.print(billTemplate, mainData, listData, licence, (result) => {

     if (result.code=='1') {

       console.log("打印请求发送成功", result);

       alert("打印请求已发送，请检查打印机状态");

     } else {

       console.error("打印失败", result.msg);

       alert("打印失败：" + result.msg);

     }

   });

 } catch (error) {

   console.error("打印接口调用异常", error);

   alert("打印功能异常，请检查客户端是否已启动");

 }

} else {

 alert("PeachPrinter 未加载完成，请刷新页面重试");

}

步骤 5：绑定按钮点击事件，触发打印

将打印函数与页面按钮关联，实现 “录入数据 → 点击打印” 的流程：

  1. 选中页面中的「printBtn」按钮，在右侧「事件面板」中添加「点击」事件

  2. 事件配置：选择「同步调用」→ 选中 printBill 函数

  3. 给函数参数赋值（绑定页面录入组件的数值）：

  • customerName：绑定输入框（客户名称）的「value」属性

  • orderAmount：绑定数字输入框（订单金额）的「value」属性

  • orderNo：绑定输入框（订单号）的「value」属性

  • printTime：绑定日期选择器的「value」属性（或直接填写 new Date().toLocaleString() 获取当前时间）

  1. 保存事件配置，完成绑定

步骤 6：测试与调试套打功能

确保所有配置生效，排查可能的问题：

6.1 基础测试流程

  1. 确认本地 PeachPrinter 客户端已启动（任务栏 / 托盘可见图标）

  2. 点击 iVX 编辑器顶部的「预览」按钮，进入项目预览页面

  3. 填写测试数据（如客户名称 “XX 科技有限公司”、订单金额 “5800.00”、订单号 “ORD20240520001”）

  4. 点击「打印」按钮，查看打印结果：

  • 若打印机正常连接，会直接输出单据

  • 若未打印，检查客户端是否启动、端口是否占用、模板 JSON 格式是否正确

6.2 预览功能调试（可选）

若需先预览单据格式，再执行打印，可将打印接口替换为预览接口：

// 替换 print 接口为 preview 接口，弹出预览窗口

PeachPrinter.preview(billTemplate, mainData, listData);

预览确认格式无误后，再改回 print 接口实现直接打印。

三、注意事项

  1. 端口占用问题：PeachPrinter 默认使用 9623 端口，若提示 “端口被占用”，可在客户端「设置」中修改端口，并同步更新 JS 中的连接配置

  2. JS 文件路径：若使用本地 JS 文件，需先上传至 iVX 项目「资源库」，再填写相对路径（如 ./peach-jprinter-min.js），避免跨域或路径错误

  3. 模板格式校验：导出的模板 JSON 需完整粘贴，不可遗漏字段，否则会导致打印格式错乱

  4. 数据字段匹配：mainData 中的字段名需与模板设计时的 “字段标识” 完全一致（区分大小写），否则动态数据无法渲染

  5. 客户端状态：打印前需确保 PeachPrinter 客户端已启动，且打印机已正常连接（本地打印机 / 网络打印机均可）

通过以上步骤，即可在 iVX 项目中快速集成 PeachPrinter 套打功能，支持各类企业单据的自定义设计与高效打印，适配订单、发票、出库单等多种场景。

avatar
文章
阅读
粉丝