块是你在打印格式上放置的、不属于文档字段的内容：标题、徽标、二维码、来自客户记录的值，或者你自己的一段 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 渲染器