ZPL分页生成多页运单标签：Ruby on Rails Labelary Gem实现需求

阿华AIGC实验室

2026-5-25

实现循环生成多页带递增变量的ZPL运单标签（Ruby on Rails + Labelary）

嘿，刚好有过类似的实践经验，给你捋捋怎么实现循环生成多页带递增变量的ZPL标签并转成PDF哈！核心思路是先准备带占位符的ZPL模板，然后通过循环替换变量生成多个独立的ZPL页面，最后拼接后用Labelary转成多页PDF。

步骤1：定义ZPL模板（带变量占位符）

首先把你的示例ZPL改成带占位符的模板，方便后续替换递增变量。比如我们把运单编号作为递增项，用{{waybill_number}}做占位符：

# 在你的服务类或控制器里定义基础模板
BASE_SHIPPING_ZPL = <<~ZPL
^XA
^FX Top section with company logo, name and address.
^CF0,60
^FO50,50^GB100,100,100^FS
^FO75,75^FR^GB100,100,100^FS
^FO88,88^GB50,50,50^FS
^FO220,50^FDInternational Shipping^FS
^FO220,115^FD123 Main St^FS
^FO220,180^FDNew York, NY 10001^FS
^FX Bottom section with barcode and waybill number.
^BY5,2,150
^FO50,250^BC^FD{{waybill_number}}^FS
^FO50,420^CF0,40^FDWaybill #{{waybill_number}}^FS
^XZ
ZPL

步骤2：编写循环生成多页ZPL的逻辑

通过循环递增变量，替换模板里的占位符，生成多个独立的ZPL页面（每个页面都是^XA开头^XZ结尾）：

def generate_multi_page_zpl(start_number, total_count)
  zpl_pages = []
  
  # 从起始编号开始，循环生成指定数量的标签
  (start_number..start_number + total_count - 1).each do |current_number|
    # 替换模板里的占位符
    page_zpl = BASE_SHIPPING_ZPL.gsub("{{waybill_number}}", current_number.to_s)
    zpl_pages << page_zpl
  end
  
  # 把所有页面ZPL拼接成一个完整的多页ZPL文档
  zpl_pages.join("\n")
end

步骤3：用Labelary gem转成多页PDF

调用Labelary的客户端，把拼接好的ZPL内容转成PDF：

def convert_zpl_to_pdf(zpl_content)
  # 初始化Labelary客户端
  labelary_client = Labelary::Client.new
  
  # 生成PDF，这里指定标签尺寸为4x6英寸（常见运单尺寸）
  labelary_client.label(zpl_content, width: 4, height: 6, format: :pdf)
end

步骤4：在控制器里调用逻辑（示例）

把上面的方法整合到控制器中，接收前端传入的起始编号和数量，生成并返回PDF：

class ShippingLabelsController < ApplicationController
  def generate
    # 从请求参数获取起始编号和需要生成的标签数量
    start_number = params[:start_number].to_i
    total_count = params[:count].to_i
    
    # 生成多页ZPL
    multi_page_zpl = generate_multi_page_zpl(start_number, total_count)
    
    # 转成PDF
    pdf_content = convert_zpl_to_pdf(multi_page_zpl)
    
    # 返回PDF文件
    send_data pdf_content, 
              filename: "shipping_labels_#{start_number}_to_#{start_number + total_count - 1}.pdf",
              type: "application/pdf",
              disposition: "inline"
  end
end