作者： Next

本页介绍三项能让打印格式编辑器的日常工作更快、更安全的功能：版本历史、可复用片段和键盘快捷键。

适用于 Frappe v16 及更高版本。

版本历史

每个格式都会保留历史记录，因此你可以放心尝试修改，不必担心丢失可用的设计。

点击工具栏中的时钟按钮即可打开。

面板中列出：

条目	说明
当前版本	你正在编辑的内容。当你有尚未应用的更改时，会显示工作草稿 · 尚未应用；没有更改时，显示与打印内容相同。
已发布版本	当前实际打印的内容。
已保存版本	之前保存的副本，最新的排在最前面。每次点击保存并应用时会自动保存一个副本，这些副本标记为保存并应用。你自己保存的副本则使用你为其指定的名称。

保存版本

在进行重大修改之前，先保留当前设计的副本：

1. 打开版本历史。
2. 点击面板顶部的书签按钮（保存命名版本）。
3. 输入版本名称，例如“新税务布局之前”，然后点击保存。

查看旧版本

点击任意条目即可在页面上查看。页面会显示一条横幅，提示你正在查看旧版本，编辑已暂停。点击当前版本可返回你的草稿。

恢复到旧版本

• 将鼠标悬停在已保存版本上，点击将此版本恢复为草稿。它会替换你的草稿。在你点击保存并应用之前，打印内容不会发生变化。
• 如果要丢弃草稿并从当前打印内容重新开始，请使用已发布版本上的按钮。
• 如果要删除已保存的版本，请将鼠标悬停在其上，然后点击删除此版本。

片段

片段是你保存下来以便日后复用的区块或字段，包含其所有设置。对于需要用在多个格式中的部分，可以使用片段：银行信息框、签名区块、条款部分等。

保存片段

1. 选择区块或字段。
2. 点击右侧面板顶部的书签按钮（保存为片段），或右键点击并选择保存为片段。
3. 输入片段名称，然后点击保存。

使用已有片段的名称保存会替换该片段。

使用片段

打开库标签页。在已保存片段下，区块列在前面，然后是字段。将片段拖到页面上，或点击它将其添加到所选内容下方。

库中会显示为同一文档类型创建的片段，以及适用于任何文档类型的片段。要删除片段，请点击其上的垃圾桶按钮。

键盘快捷键

在 Mac 上，请使用 Cmd 代替 Ctrl。

编辑

按键	操作
Ctrl+S	保存并应用
Ctrl+Z	撤销
Ctrl+Shift+Z 或 Ctrl+Y	重做
Ctrl+C	复制所选区块或字段
Ctrl+V	粘贴
Ctrl+D	复制所选内容
Delete 或 Backspace	删除所选内容
Alt+↑ / Alt+↓	将所选内容上移或下移

导航

按键	操作
↑ / ↓	选择上一项或下一项
←	在区块上，折叠该区块。在字段上，选择其所在区块。
→	在区块上，展开该区块或选择其第一项
Esc	选择父级，再按则取消选择。未选择任何内容时，右侧面板显示页面设置。
/	跳转到搜索字段
Shift+点击	选择一组连续的字段
Ctrl+点击	将字段添加到所选内容中

缩放

按键	操作
Ctrl+=	放大
Ctrl+-	缩小
Ctrl+0	重置为 100%

当你在输入框中输入、预览打开或正在查看旧版本时，快捷键不会生效。

相关主题

• 打印格式编辑器
• 区块

一个打印格式往往需要应对多种情况：已付款和未付款的发票、本地订单和出口订单、有税号和无税号的客户。与其为每种情况各做一个格式，不如给那些只在某些时候才需要打印的部分加上条件。

适用于 Frappe v16 及更高版本。

可以在哪里添加条件

对象	设置项	打印时机
一个区块	可见性 > 条件	条件为真时
一个字段或块	可见性 > 条件	条件为真时
一个表格	可见性 > 条件	条件为真时
表格的行	可见性 > 满足以下条件时显示行	该行满足条件时
表格的列	列设置 > 满足以下条件时显示列	文档满足条件时

条件留空则始终打印。

编写条件

条件是一段简短的 Python 表达式。用 doc 表示你正在打印的文档，用 doc.fieldname 表示它的字段：

doc.status == "Paid"

字段名是 字段 选项卡中的名称，而不是标签。例如“客户名称”字段是 doc.customer_name。

你可以使用比较运算符（==、!=、>、<、>=、<=）、and、or、not、in，以及函数 int、float 和 round。条件中不能使用其他 Python 函数。

示例

doc.status == "Paid"                       # only on paid invoices
doc.status != "Paid"                       # only on unpaid invoices
doc.discount_amount > 0                    # only when there is a discount
doc.currency != "USD"                      # only for foreign currency
doc.customer_group == "Export"             # only for export customers
doc.tax_id                                 # only when a tax ID is filled in
not doc.is_return                          # hide on credit notes
doc.status in ("Overdue", "Unpaid")        # one of several values
doc.grand_total >= 10000 and doc.po_no     # both must be true
doc.total_qty > 100                        # only large orders

表格行

在 满足以下条件时显示行 中，用 row 表示正在打印的行：

row.qty > 0                    # skip zero quantity rows
row.item_group == "Products"   # only products
not row.is_free_item           # hide free items

表格列

满足以下条件时显示列 是针对整个文档检查一次，而不是逐行检查，所以使用 doc：

doc.discount_amount            # show the discount column only when there is a discount
doc.currency != "USD"          # show an exchange rate column for foreign currency

打印设置

print_settings 保存了站点的打印设置，因此条件可以跟随站点范围的开关：

print_settings.print_taxes_with_zero_amount or doc.total_taxes_and_charges

实时查看

在预览中选定一个文档后，编辑器会在你输入时检查条件，并在下方显示以下之一：

标记	含义
当前可见	该文档满足条件。它将被打印。
当前隐藏	条件为假。该文档不会打印它。
无法检查此条件	条件有错误。将鼠标悬停在标记上可查看。
加载文档以查看实时状态	尚未选择预览文档。

在页面上，隐藏的部分会显示为灰色。在 图层 选项卡中，任何带条件的部分都有一个眼睛图标，将鼠标悬停在其上会显示条件。

条件出错时

• 如果条件不是有效的 Python，例如缺少引号，保存并应用 会停止并显示哪个条件有误。
• 如果条件有效但在打印时失败，例如使用了不存在的字段，该部分仍会 照常打印，以免信息丢失。错误会记录一次到 错误日志 中，标题为“打印格式条件失败”，并附上格式名称。

相关主题

• 字段
• 表格

块是你在打印格式上放置的、不属于文档字段的内容：标题、徽标、二维码、来自客户记录的值，或者你自己的一段 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)。
字段	要从链接文档中打印的字段，例如税号。该块的标签会设置为该字段的标签。
标签和显示标签	打印在值旁边的标签。
大小	仅当链接字段为图片时使用。即图片的宽度。

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

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

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

自定义表格

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

设置

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

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

编写列模板

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

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

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

列	模板
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 渲染器

子表格，比如发票上的明细项或订单上的税费，会以表格形式打印。本页介绍如何选择它们的列、设置样式、将多个值合并到一个单元格中，以及只打印部分行。

适用于 Frappe v16 及更高版本。

添加表格

子表格和其他字段一样位于字段选项卡中，类型为表格。将其拖入某个区域即可。表格通常单独放在一个单列区域中，这样它就能占满页面的整个宽度。

如果你想按自己的方式排列每一行，而不是使用网格布局，请使用自定义表格块。

表格设置

选中表格即可查看其设置。

表格

设置	选项	作用
标题	文本，配合显示标题	表格上方的标题，例如“明细项”。
样式	网格、行、斑马纹、无	网格绘制所有线条。行仅在行之间绘制线条。斑马纹为每隔一行添加底纹。无不绘制任何线条。
表头	带样式、普通、无	带样式为表头行添加背景色。普通将其作为普通文本打印。无隐藏表头行。
单元格内边距	像素	每个单元格内部的空间。
圆角	像素	将表格的角变为圆角。
最小高度	像素	即使行数很少，也保持表格至少有这么高。适用于预印好的信纸。

列

列列表按打印顺序显示各列，顶部显示列数。

• 添加列：在添加列…中输入内容并选择一个字段。序号会添加行号。
• 重新排序：通过拖动手柄来拖动某一列。
• 重命名：点击列名并输入新的标题。
• 移除：点击旁边的×。

点击列旁边的设置按钮可进行更多操作：

设置	作用
宽度	该列占表格的比例，以百分比表示。留空则平均分配空间。
日期格式	用于日期列。
合并字段	在同一单元格中、主值下方显示更多字段。见下文。
显示列条件	仅当关于文档的条件为真时才打印该列。

如果某一列在每一行中的单元格都为空，该列会被自动省略，其他列会扩展以填补空间。

将字段合并到一个单元格

合并可以让一个单元格承载多个值，例如以粗体显示明细项名称，并在其下方以灰色显示其编码和描述。

1. 打开该列的设置，例如明细项。
2. 在合并字段下，点击添加字段…并选择一个字段，例如描述。
3. 为每个合并字段选择一种样式。该列自身的字段始终以主要样式首先打印。

样式	外观
主要	粗体、深色文本
次要	正常字重、深色文本
代码	小号灰色等宽文本，用于编码和 SKU
弱化	小号灰色文本，用于较长的描述

你添加的第一个字段默认为次要，后续字段默认为弱化。

图像字段（例如明细项图片）则会改为获得一个尺寸设置，这样你就可以在明细项名称旁边打印一个小缩略图。

4. 将方向设置为垂直以堆叠这些值，或设置为水平以将它们并排放置。

样式

设置	作用
表头	表头行的背景颜色。当表头为带样式时显示。
边框	线条的颜色。
自定义 CSS	你为表格编写的自定义 CSS。

可见性

设置	作用
条件	仅当此条件为真时才打印整个表格。
显示行条件	仅打印满足此条件的行。使用 row. 来引用该行的字段。留空则打印每一行。

显示行条件的一些示例：

row.qty > 0                      # skip zero quantity rows
row.item_group != "Services"     # leave out service items
not row.is_free_item             # hide free items

有关条件如何工作，请参阅显示或隐藏内容。

相关主题

• 块：自定义表格
• 显示或隐藏内容

字段就是文档中的各种值：客户名称、过账日期、总计金额。本页介绍如何把它们放到页面上，以及如何修改每个字段的打印方式。

适用于 Frappe v16 及更高版本。

添加字段

1. 打开左侧面板中的字段标签页。它会列出文档的所有字段，右侧显示字段类型。
2. 在搜索字段中输入内容来查找字段。在编辑器任意位置按 / 可快速跳到此输入框。
3. 将字段拖入某一列，或点击它将其添加到所选字段的下方。如果没有选中任何内容，它会添加到最后一个区块中。

要移动字段，把它拖到其他位置，或选中后按 Alt+↑ 或 Alt+↓。要删除字段，选中后按 Delete。

你可以一次选中多个字段：Shift+点击选中一个范围，Ctrl+点击（Mac 上为 Cmd+点击）逐个添加字段。

字段设置

选中一个字段后，右侧面板会显示它的设置。只有适用于该字段的设置才会出现，所以日期字段有日期格式选项，长文本字段可以跨页拆分。

字段

设置	作用
标签	打印在值旁边的文字。可以在这里修改，而不用改动表单，例如把“客户名称”改成“账单抬头”。
显示标签	关闭后只打印值。
日期格式	用于日期字段。选择一种格式，例如 dd-mm-yyyy 或 d MMM yyyy。每个选项都会用该格式显示今天的日期。系统默认使用系统设置中的格式。
隐藏冒号	仅当页面设置中开启了标签后加冒号时显示。用于单独去掉这个字段的冒号。

样式

设置	作用
加粗	以粗体打印值。
字体大小	该字段文字的大小，单位为像素。留空则使用页面字体大小。
标签和值	标签和值的颜色。保持默认则使用页面颜色。

布局

设置	选项	作用
对齐	左、居中、右	设置字段在其列中的对齐方式。
间距	正常、两端对齐、均匀分布	仅当区块的标签位置为左侧时可用。两端对齐会把值推到右边缘，很适合用于合计。
标签间距	像素	仅当标签位置为左侧时可用。标签和值之间的间距。
跨页拆分	开、关	用于条款和备注等长文本字段。让较长的值延续到下一页，而不是整体跳到下一页。

自定义 CSS

仅作用于该字段的 CSS。它会以内联样式应用到该字段，所以直接写声明，不要写选择器：

border-top: 1px solid #e5e7eb;
padding-top: 6px;

可见性

仅在条件成立时打印该字段。参见“显示或隐藏内容”。

空字段

没有值的字段不会出现在打印结果中，标签和值都不会显示。这样可以让页面保持整洁，例如发票没有采购订单号时。在页面上，空字段会以灰色加短横线显示。

如果你希望即使没有值也打印标签，请使用“关联字段”区块，它有一个为空时打印设置。

提示

• 要让标签和值显示在同一行，请把区块的标签位置设为左侧，而不是逐个设置字段。
• 要打印其他文档中的值，例如客户的税号，请使用“关联字段”区块。
• 要打印固定文字，例如“感谢您的惠顾”，请使用“文本”区块。

相关主题

• 表格
• 区块
• 显示或隐藏内容