@sv-print/plugin-ele-box

sv-print 的 可循环渲染的容器元素插件。field 绑定数组数据，对每个数组项通过模板/formatter 渲染子元素内容，并根据总高度自动分页。

特性

• 绑定数组字段，循环渲染子项内容
• 支持 #{field} 占位符模板（含嵌套路径如 #{obj.name}）
• 支持 PrintTemplateJson 格式的子模板（通过可视化设计器创建）
• 内置子模板设计器弹窗，可拖拽元素、绑定字段，所见即所得
• 垂直间距、水平间距、水平/垂直排列方向可配置
• 自动按纸张高度进行分页处理
• 自定义分页方式（尝试下页 / 当前页）
• 支持 formatter 自定义内容渲染
• 自动等待图片加载完成后再计算分页

安装

npm install @sv-print/plugin-ele-box
# 或
pnpm add @sv-print/plugin-ele-box

要求 sv-print >= 0.1.20

使用

sv-print 插件引入的两种方式见：sv-print 插件文档

import pluginEleBox from "@sv-print/plugin-ele-box";

const plugins = [
  pluginEleBox({
    showDesign: true, // 是否显示设计按钮
    onDesignClick: (json, callback) => {
      console.log(json); // 当前的模板字符串/模板json
      // 可以打开新页面，可以用自定义设计器
      callback(json); // 处理完后, 回调新的模板字符串
    },
    // 设计计器弹窗 配置项
    designerOptions: {
      onBuildElement: (container: string) => {
        // 这里自己构建拖拽元素
        console.log(container);
        // 构建默认模块
        hiprint.PrintElementTypeManager.build(container, "defaultModule");
      },
    },
  }),
];

注册后，拖拽面板的「插件」分组中会出现 box 子模板 元素，可直接拖入模板设计区。

数据格式

// 打印数据示例
const printData = {
  boxItems: [
    { name: "Alice", age: 30, avatar: "1.png" },
    { name: "Bob", age: 25, avatar: "2.png" },
  ],
};

模板语法

boxTemplate 支持两种模式：

1. HTML 模板（#{field} 占位符）

在「子项模板」中使用 #{field} 占位符引用数组项的字段：

<div style="display:flex;align-items:center;">
  <img src="#{avatar}" style="width:30pt;height:30pt;" />
  <span>#{name} - #{age}岁</span>
</div>

支持嵌套路径：#{address.city}

2. JSON 模板（PrintTemplateJson）

点击「子项模板」旁的「设计」按钮，打开可视化子模板设计器。在设计器中拖入元素、绑定字段后保存，boxTemplate 会自动存储为 JSON 格式：

{"panels":[{"width":100,"height":60,"printElements":[...]}]}

JSON 模板通过 hiprint.PrintTemplate 渲染，支持所有已注册的元素类型。

License

LGPL

开源使用须知

1. 请自觉遵守 LGPL 协议，其他用途可联系作者；
2. 允许用于个人学习、毕业设计、教学案例、公益事业、商业使用；
3. 如果商用必须保留版权信息，请自觉遵守；
4. 禁止将本开源的代码和资源进行任何形式任何名义的出售，否则产生的一切任何后果责任由侵权者自负；
5. 商用请仔细审查代码和漏洞，不得用于任一国家许可范围之外的商业应用，产生的一切任何后果责任自负；