容器循环渲染 box

约 792 字大约 3 分钟

...

2026-09-28

插件说明

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

核心能力：

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

无第三方依赖。要求 sv-print >= 0.1.20。

npm install @sv-print/plugin-ele-box

示例代码

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

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

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

// 唯一注册入口，须在创建模板/打开设计器之前
await hiprint.register({ plugins });

数据与 HTML 模板示例：

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

boxTemplate 用 #{field} 占位符引用数组项字段：

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

高级用法

子模板两种模式

模式	说明
HTML 模板	`#{field}` 占位符，支持 `#{obj.name}` 深层路径
JSON 模板	`{"panels":[...]}` 子模板 JSON，通过 `hiprint.PrintTemplate` 渲染每项，支持所有已注册元素类型；点击「设计」按钮在可视化设计器中编辑后自动存储

元素参数

参数	说明
`boxTemplate`	子项模板（HTML 字符串或模板 JSON 字符串）
`boxJustify`	主轴对齐（flex 值）
`boxAlign`	交叉轴对齐（flex 值）
`boxGapV` / `boxGapH`	垂直 / 水平间距（pt）
`boxDirection`	排列方向：空为垂直，`horizontal` 为水平
`boxMode`	分页方式：1 超高尝试移下页；2 留当前页截断

插件 config

参数	说明
`showDesign`	是否显示「设计」按钮
`onDesignClick(json, callback)`	自定义子模板设计入口，处理后回调新的模板字符串
`designerOptions`	内置设计器弹窗参数（如 `onBuildElement`）

版权所有

版权归属：sv-print

许可证：署名 4.0 国际 (CC-BY-4.0)