单据类型布局

文档类型布局

文档类型布局允许您为同一文档类型创建多个表单视图——每个视图可以有不同的字段标签、可见性规则和默认值——而无需修改文档类型本身。布局会根据文档状态自动激活，因此无需手动操作即可显示正确的视图。

常见用例

  • 隐藏高级字段的简化数据录入视图
  • 重新标记字段以提高清晰度的侧重阅读的审阅视图
  • 当 doc.is_return == 1 时自动切换到“退货”布局
  • 由条件或工作区链接驱动的状态或上下文特定布局

创建布局

转到文档类型布局列表，然后点击新建。

字段 描述
标题 在布局指示器和面包屑中显示的显示名称（例如 紧凑视图）。
文档类型 此布局适用的文档类型。设置后无法更改。
条件 可选的 JS 表达式。当表达式为真时，此布局会在表单刷新时自动激活。
基于 从同一文档类型的另一个布局继承字段配置。
是子表 将此布局标记为子表布局。选中后，它将出现在其他文档类型布局的子布局选择器中。
默认打印格式 当此布局激活时，预选此打印格式。
默认电子邮件模板 当此布局激活时，预选此电子邮件模板。

选择文档类型后，点击同步字段以拉取文档类型中的所有字段。一个可视化表单构建器将在父布局选项卡中打开，您可以在其中重新排序和配置字段。

覆盖字段属性

在表单构建器中，选择任意字段以覆盖其属性。以下属性可以按布局设置，而不会影响基础文档类型：

属性 效果
label 为此布局重命名字段
hidden 隐藏字段
reqd 将字段设为必填
read_only 将字段设为只读
bold 强调标签
allow_in_quick_entry 在快速录入对话框中包含此字段
in_list_view 在列表视图中将字段显示为列
in_standard_filter 在标准筛选器栏中包含此字段
default 为新文档设置默认值
description 覆盖帮助文本
depends_on 条件可见性表达式
mandatory_depends_on 条件必填表达式
read_only_depends_on 条件只读表达式

布局中未设置的属性将回退到基础文档类型的定义。

自动布局切换

布局选择完全由条件驱动——没有手动切换器。设置一个条件，使布局在表单刷新后表达式评估为真时自动激活：

// Activates for return transactions
doc.is_return == 1

// Activates for high-value orders
doc.grand_total > 100000

// Activates for a specific status
doc.status === "Closed"

当条件匹配时，布局将被应用，并且 URL 会更新为 ?layout=<name></name>。第一个匹配的布局优先；布局按其在列表中出现的顺序进行评估。每当非默认布局激活时，文档标题旁边会出现一个布局指示器徽章。

当布局激活时，面包屑栏会反映出来：

  • 在表单视图中，布局标题作为可点击的面包屑显示在文档类型和文档名称之间。点击它会打开按布局条件过滤的列表（从 doc.field OP value 表达式解析）。
  • 在该过滤列表上，布局标题显示为不可点击的面包屑，以便活动上下文保持可见。
  • 当布局激活时，点击文档类型面包屑会清除所有筛选器并移除布局面包屑，返回到未过滤的列表。

子表布局

布局可以为其子表指定不同的布局。在子布局选项卡中，为您要自定义的每个子表添加一行：

字段 描述
表字段名 父文档类型中子表的字段名
子布局 一种文档类型布局，其文档类型与子表的文档类型匹配

当父布局处于活动状态时，每个子表网格会自动使用其指定的子布局进行渲染——应用与父布局相同的字段级覆盖。

重要提示。 子布局的文档类型必须与子表的文档类型匹配（例如 Sales Invoice Item），而不是父文档类型。请先为子表创建单独的布局，然后在此处引用它。

父布局上可用的相同字段属性——label、hidden、reqd、read_only、depends_on、列顺序等——在子布局激活时同样适用于网格内部。

示例。 一个财务视图父布局将项目表映射到紧凑项目子布局，该子布局隐藏了 description、uom 和其他明细列，仅保留 item_code、qty 和 amount 可见。切换到父布局会自动压缩网格——用户无需额外操作。

布局继承

使用基于来继承同一文档类型的另一个布局的字段配置。子布局以父布局的字段顺序和覆盖为起点，并可以进一步自定义单个字段或添加新字段。

这对于创建一系列相关布局非常有用：先定义一个包含通用字段顺序的基础布局，然后创建继承并调整它的专门布局（例如销售视图、财务视图）。

保持字段同步

同步字段按钮会将布局的字段列表与当前文档类型定义进行比较，并报告：

  • 已添加 — 文档类型中存在但布局中缺少的字段（添加到末尾）
  • 已移除 — 布局中存在但文档类型中已不再存在的字段（已删除）

在修改底层文档类型后运行此操作，以保持布局的一致性。

工作区集成

侧边栏工作区中的任何文档类型链接都可以绑定到特定布局。以编辑模式打开工作区，选择一个文档类型链接，然后将文档类型布局字段设置为您想要的布局。点击该链接会打开预先限定为该布局的列表（URL 携带 ?layout=<name></name>），并且从列表创建的新文档会在该布局下打开。

面向开发者：标准布局

通过设置为标准并选择模块，布局可以作为应用的一部分发布。在开发者模式下，保存标准布局会自动将其导出为 JSON 文件到：

{app}/{module}/doctype/{doctype}/doctype_layout/{layout_name}.json

该文件包含在迁移中，并通过 bench migrate 自动部署。标准布局在生产实例（开发者模式之外）上是只读的。