块 – ERPNext中国企业实施指南

块是你在打印格式上放置的、不属于文档字段的内容：标题、徽标、二维码、来自客户记录的值，或者你自己的一段 HTML。本页介绍每一种块、它们的设置以及它们打印出来的效果。

适用于 Frappe v16 及更高版本。

添加块

打开左侧面板中的块选项卡。然后可以：

将块拖拽到页面上你想要的位置，或者
点击它。它会被添加到所选字段的下方。如果没有选中任何内容，它会进入最后一个分区。

放置之后，块就像任何字段一样可以被选中。它的设置会显示在右侧面板中，每个块的底部都有自定义 CSS和可见性，这样你可以为它设置样式，或者只在某些情况下打印它。

有哪些可用的块

块	用途
文本	固定文本：标题、备注、感谢语
图片	徽标、印章、签名、任何图片
条形码	来自字段或固定值的条形码或二维码
关联字段	来自关联文档的值，例如客户的税号
自定义表格	用你自己的模板排布的子表行
间隔	空白的垂直空间
分隔线	一条细水平线
自定义 HTML	你自己的 HTML 和 Jinja，用于其他块无法实现的内容
Typst	你自己的 Typst 标记。当 PDF 渲染器为 Typst 时，它会替代自定义 HTML。
分区	一个用于放置字段的新分区
分页符	开始新的一页

下面是其中几种在发票底部的样子：一个包含付款计划的自定义表格、一个包含客户税号的关联字段、一个二维码、一条分隔线和两个文本块。

这个列表取决于格式的PDF 渲染器。使用Chromium（默认）时，你会看到自定义 HTML。使用Typst时，你会看到Typst取代它的位置。请参阅页面设置和 PDF 渲染器。

文本

打印不来自文档的固定文本，例如“感谢您的惠顾”或“货物售出，概不退换”。

设置	作用
文本	要打印的文本。按 Enter 换行。
加粗	以粗体打印文本。
字体大小	以像素为单位的大小。留空则使用页面字体大小。
对齐	左对齐、居中或右对齐。

文本会按原样打印。当存在翻译时，它会被翻译成打印语言，但它不能包含字段值。要在句子中打印文档值，请使用自定义 HTML 块。

图片

打印一张图片：徽标、付款二维码图片、签名或印章。

设置	作用
上传图片	从你的电脑上传一张图片。它会保存在Home/Attachments中。上传后，按钮会显示为更换图片。
或图片 URL	使用来自网址的图片，而不是上传。
清除	移除图片。
大小	宽度，从 20 到 700 像素。新图片会以其自身宽度开始，最大 300 像素。
对齐	左对齐、居中或右对齐。

每次打印出来的图片都是一样的。要打印随文档变化的图片，例如物料图片，请从字段选项卡添加文档的图片字段，或者使用指向图片字段的关联字段。

注意：Typst 渲染器无法从网址加载图片。如果你使用 Typst，请改为上传图片。

条形码

打印条形码或二维码，例如将发票编号打印为条形码，或将付款链接打印为二维码。

设置	选项	作用
值来源	静态值、ID（名称）或文档的任意字段	条形码值的来源。ID（名称）使用文档的编号，例如 `ACC-SINV-2026-00006`。
值	文本	要编码的固定值。仅当值来源为静态值时显示。
格式	CODE128、CODE39、QR	CODE128是数字和字母的常用选择。CODE39用于较旧的扫描仪。QR生成方形二维码。
大小	40 到 500 像素	码的宽度。
值文本	开、关	在条形码下方以纯文本形式打印值。二维码不显示此内容。
对齐	左对齐、居中、右对齐

二维码最多可容纳 2000 个字符，因此完整的网址也能放得下。

如果文档中已有条形码字段，你可以改为从字段选项卡中拖入该字段。其格式来自字段自身的设置，且只能更改大小。

注意：Typst 渲染器只能打印二维码。如需 CODE128 或 CODE39 条形码，请使用 Chromium。

链接字段

打印本文档所链接文档中的某个值。例如，销售发票链接到客户，因此你无需在发票中添加字段，即可打印客户的税号或地区。

设置	作用
链接	要跟随的链接字段，显示其指向的文档类型，例如客户 (Customer)。
字段	要从链接文档中打印的字段，例如税号。该块的标签会设置为该字段的标签。
标签和显示标签	打印在值旁边的标签。
大小	仅当链接字段为图片时使用。即图片的宽度。

它还具有常见的加粗、字体大小、颜色和对齐设置，以及普通字段没有的一项设置：

设置	作用
为空时打印	即使链接的值为空也打印标签。对于必须始终保留该空间的表单（例如送货单上的“车牌号”），请开启此项。

链接字段只跟随一个链接。打印者必须有权读取链接的文档，否则该值将被省略。

自定义表格

以你自己的布局打印子表的行，而不是使用网格。当普通表格过于笨重时使用它，例如紧凑的付款条款列表，或序列号列表。

设置

设置	作用
来源	要打印的子表，例如付款计划。
标题和显示标题	行上方的可选标题。
列	每一行按这些列打印。每一列都有一个模板。点击添加列以添加一列。

点击列旁边的设置按钮，可设置其宽度（百分比）、对齐和颜色。

编写列模板

模板将你自己的文本与该行的字段混合在一起：

点击列的模板框。
输入纯文本，例如 Due on 。
输入 / 以打开该行字段的列表。继续输入以筛选，然后按回车插入该字段。它会显示为一个小徽章。
继续输入，并以相同方式添加更多字段。

对于付款计划，像这样的两列：

列	模板
1	`Due on` due_date
2	payment_amount

每行打印一行：

Due on 09-11-2026                    $ 3,315.00
Due on 09-12-2026                    $ 3,315.00

使用退格键删除光标前的徽章。字段会以格式化形式打印，因此日期、货币和数字看起来与其他地方一致。

当来源表没有行时，不打印任何内容。

间隔

在两个内容之间添加空的垂直空间。

设置	作用
高度	以像素为单位的空间。新建的间隔为 10 像素。

分隔线

在列中绘制一条细灰色线。它没有自己的设置。使用自定义 CSS 来更改它，例如 border-bottom: 2px solid #111827;。

自定义 HTML

打印你自己的 HTML。用于其他块无法完成的事情：混合多个值的句子、签名框、具有特殊格式的条款块。

选择该块并点击编辑 HTML。编辑器打开后，左侧是你的 HTML，右侧是实时预览，使用你为预览选择的文档。

你可以使用 Jinja 来打印值。文档可通过 doc 访问：

<p>
  Thank you, {{ doc.customer_name }}, for your order
  {{ doc.po_no or "" }}.
</p>
<p>Amount due: <b>{{ doc.get_formatted("grand_total") }}</b></p>

子表行以列表形式提供：

<ul>
{% for row in doc.items %}

<li>{{ row.item_name }}: {{ row.get_formatted("amount") }}</li>
{% endfor %}
</ul>

需要了解的事项：

使用 doc.get_formatted("fieldname") 以表单显示值的方式打印值，包括货币符号和日期格式。
可使用对模板安全的 frappe 实用工具，例如 frappe.format_date(doc.posting_date) 和 frappe.db.get_value("Customer", doc.customer, "tax_id")。参见 Jinja API。
为安全起见，保存时会移除脚本、样式、表单、iframe 以及诸如 onclick 的事件处理器。请改为将样式放在该块的自定义 CSS 或页面的自定义 CSS 中。
包含自定义 HTML 块的节始终会打印，即使该块不打印任何内容。

注意：包含自定义 HTML 块的格式无法使用 Typst 渲染器。

Typst

仅当格式的 PDF 渲染器 为 Typst 时才会显示。它取代自定义 HTML，用于打印您自己的 Typst 标记。

在区块的文本框中输入标记，或点击页面上的 编辑 Typst。使用 {{ doc.fieldname }} 获取文档中的值：

#text(weight: "bold", size: 14pt)[Thank you, {{ doc.customer_name }}]

Amount due: *{{ doc.get_formatted("grand_total") }}*

需要了解的事项：

值会针对 Typst 进行转义，因此包含 # 或 * 的客户名称会按原样打印。若要从某个值插入原始 Typst 标记，请写 {{ value | typst_raw }}。
诸如 {% for row in doc.items %} 之类的 Jinja 标签也可以使用。
编辑器页面会为此区块显示一个占位符。点击 显示预览 可在 PDF 中查看结果。
保存时，标记会对照真实文档进行检查。如果存在错误，保存会停止并告知您哪里有问题。
包含 Typst 区块的格式只能使用 Typst 渲染器。若要改回 Chromium，请先移除该区块。

节和分页符

这两个位于“区块”选项卡的末尾：

节会在所选节下方添加一个新节。请参阅节、列和页面。
分页符 会添加一个分页符。其后的所有内容都会从新页面开始。点击页面上的 移除分页符 可将其删除。

保存区块以供重复使用

只需设置一次区块，即可在其他格式中重复使用：选中它并点击右侧面板顶部的书签按钮，或右键单击它并选择 保存为片段。随后它会出现在库选项卡中。请参阅版本、片段和快捷键。

字段
显示或隐藏内容
页面设置和 PDF 渲染器

添加块