From bd4e30967c63b7ecfc97ade381b381df9593d7b7 Mon Sep 17 00:00:00 2001 From: gchust Date: Wed, 31 Dec 2025 23:11:18 +0800 Subject: [PATCH] docs: update ui template docs (#8321) * docs: update ui template doc * docs: enhance popup template section with detailed matching rules * chore: update docs --- docs/docs/cn/interface-builder/_meta.json | 15 +- .../actions/action-settings/edit-popup.md | 46 +---- .../blocks/other-blocks/block-template.md | 56 ------ .../fields/field-template.md | 53 ------ .../docs/cn/interface-builder/ui-templates.md | 167 ++++++++++++++++++ .../@nocobase/plugin-ui-templates/index.md | 4 +- docs/docs/en/interface-builder/_meta.json | 15 +- .../actions/action-settings/edit-popup.md | 60 +------ .../blocks/other-blocks/block-template.md | 56 ------ .../fields/field-template.md | 53 ------ .../docs/en/interface-builder/ui-templates.md | 167 ++++++++++++++++++ .../plugin-ui-templates/package.json | 2 +- .../plugin-ui-templates/src/locale/zh-CN.json | 2 +- 13 files changed, 356 insertions(+), 340 deletions(-) delete mode 100644 docs/docs/cn/interface-builder/blocks/other-blocks/block-template.md delete mode 100644 docs/docs/cn/interface-builder/fields/field-template.md create mode 100644 docs/docs/cn/interface-builder/ui-templates.md delete mode 100644 docs/docs/en/interface-builder/blocks/other-blocks/block-template.md delete mode 100644 docs/docs/en/interface-builder/fields/field-template.md create mode 100644 docs/docs/en/interface-builder/ui-templates.md diff --git a/docs/docs/cn/interface-builder/_meta.json b/docs/docs/cn/interface-builder/_meta.json index dc29e2a5236..d5609cd9c5e 100644 --- a/docs/docs/cn/interface-builder/_meta.json +++ b/docs/docs/cn/interface-builder/_meta.json @@ -77,11 +77,6 @@ "label": "Iframe", "link": "/interface-builder/blocks/other-blocks/iframe" }, - { - "type": "custom-link", - "label": "区块模板", - "link": "/interface-builder/blocks/other-blocks/block-template" - }, { "type": "custom-link", "label": "Markdown", @@ -153,11 +148,6 @@ "label": "概述", "link": "/interface-builder/fields" }, - { - "type": "custom-link", - "label": "字段模板", - "link": "/interface-builder/fields/field-template" - }, { "type": "custom-link", "label": "通用配置项", @@ -499,6 +489,11 @@ "type": "custom-link", "label": "RunJS", "link": "/interface-builder/runjs" + }, + { + "type": "custom-link", + "label": "UI 模板", + "link": "/interface-builder/ui-templates" } ] } diff --git a/docs/docs/cn/interface-builder/actions/action-settings/edit-popup.md b/docs/docs/cn/interface-builder/actions/action-settings/edit-popup.md index 49acc664fcd..3fbd5cccf9a 100644 --- a/docs/docs/cn/interface-builder/actions/action-settings/edit-popup.md +++ b/docs/docs/cn/interface-builder/actions/action-settings/edit-popup.md @@ -28,48 +28,6 @@ - 中（默认） - 小 -## 弹窗模板 +## 模板 -弹窗模板用于复用一套弹窗界面与交互逻辑。 - - -### 保存弹窗为模板 - -1) 打开能触发弹窗的按钮/字段设置菜单，点击 `保存为模板` -2) 填写模板名称/描述，并选择保存模式： - - `将当前弹窗转为模板`：保存后，当前弹窗将切换为引用该模板 - - `复制当前弹窗为模板`：仅创建模板，当前弹窗保持不变 - -![save-as-template-popup-20251228](https://static-docs.nocobase.com/save-as-template-popup-20251228.png) - -### 在弹窗配置中使用模板 - -1) 打开该按钮/字段的弹窗配置 -2) 在 `弹窗模板` 中选择模板即可复用 - -![edit-popup-select-20251228](https://static-docs.nocobase.com/edit-popup-select-20251228.png) - -### 使用条件（模板可用范围） - -弹窗模板与触发弹窗的操作场景有关。选择器会根据当前场景自动过滤/禁用不兼容的模板（不满足条件时会提示原因）。 - -- **Collection 操作按钮**：只能使用 **Collection 操作**创建的弹窗模板，且 **Collection（数据表）必须一致**。 -- **非关联 Record 操作**：可使用 **非关联 Record 操作**创建的弹窗模板，以及 **Collection 操作**创建的弹窗模板，且 **Collection（数据表）必须一致**。 -- **关联 Record 操作**：可使用 **非关联 Record 操作**创建的弹窗模板，以及 **Collection 操作**创建的弹窗模板，且 **Collection（数据表）必须一致**；也可使用 **关联 Record 操作**创建的弹窗模板，但需要严格匹配**同一个关联字段**的操作（同一关联关系）。 - -### 引用与复制的区别 - -- `引用`：使用模板打开弹窗；模板更新会同步影响所有引用处。 -- `复制`：通过 `将引用转换为复制` 断开模板引用；后续修改仅影响当前弹窗。 - -### 管理弹窗模板 - -系统设置 → `界面模板` → `弹窗模板 (v2)` 中可查看/搜索/编辑/删除模板。 - -> 注意：若模板正在被引用中，则无法直接删除。请先在引用该模板的弹窗上使用 `将引用转换为复制` 断开引用，再删除模板。 - -### 将引用转换为复制 - -当弹窗正在引用模板时，可在设置菜单中使用 `将引用转换为复制`，把当前弹窗改为独立配置，后续修改互不影响。 - -![convert-popup-to-duplicate-20251228](https://static-docs.nocobase.com/convert-popup-to-duplicate-20251228.png) +详见 [UI 模板 - 弹窗模板](/interface-builder/ui-templates#弹窗模板)。 diff --git a/docs/docs/cn/interface-builder/blocks/other-blocks/block-template.md b/docs/docs/cn/interface-builder/blocks/other-blocks/block-template.md deleted file mode 100644 index 3acbbcc3aee..00000000000 --- a/docs/docs/cn/interface-builder/blocks/other-blocks/block-template.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -pkg: "@nocobase/plugin-ui-templates" ---- - -# 区块模板 - -## 介绍 - -区块模板用于复用已配置好的区块，避免在不同页面/位置重复搭建与配置。 - -## 保存区块为模板 - -1) 打开目标区块的设置菜单，点击 `保存为模板` -2) 填写 `模板名称` / `模板描述`，并选择保存模式： - - `将当前区块转为模板`：保存后，当前位置将替换为 `区块模板` 区块（引用该模板） - - `复制当前区块为模板`：仅创建模板，当前区块保持不变 - -![save-as-template-block-20251228](https://static-docs.nocobase.com/save-as-template-block-20251228.png) - -![save-as-template-block-full-20251228](https://static-docs.nocobase.com/save-as-template-block-full-20251228.png) - -## 使用区块模板 - -1) 添加区块 → “其他区块” → `区块模板` -2) 在配置中选择： - - `模板`：选择一个模板 - - `模式`： - - `引用`：引用模板，所有引用处保持同步 - - `复制`：生成独立区块，后续互不影响 - -![block-template-menu-20251228](https://static-docs.nocobase.com/block-template-menu-20251228.png) - -![select-block-template-20251228](https://static-docs.nocobase.com/select-block-template-20251228.png) - -### 引用与复制的区别 - -- `引用`：所有引用处共享同一份区块配置；修改模板或任一引用处，其他引用处都会同步更新。 -- `复制`：仅在复制时生成一份独立区块；后续对模板或其它区块的修改不会同步到这里。 - -## 管理区块模板 - -系统设置 → `界面模板` → `区块模板 (v2)` 中可查看/搜索/编辑/删除模板。 - -> 注意：若模板正在被引用中，则无法直接删除。请先在引用该模板的区块上使用 `将引用转换为复制` 断开引用，再删除模板。 - -![block-template-list-20251228](https://static-docs.nocobase.com/block-template-list-20251228.png) - -## 将引用转换为复制 - -当区块正在引用模板时，可在区块设置菜单中使用 `将引用转换为复制`，把当前区块改为普通区块。 - -![convert-block-template-duplicate-20251228](https://static-docs.nocobase.com/convert-block-template-duplicate-20251228.png) - -## 注意事项 - -- `复制` 模式会重新生成区块及子节点的 UID，部分依赖 UID 的配置可能需要重新配置。 diff --git a/docs/docs/cn/interface-builder/fields/field-template.md b/docs/docs/cn/interface-builder/fields/field-template.md deleted file mode 100644 index af3ebd75809..00000000000 --- a/docs/docs/cn/interface-builder/fields/field-template.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -pkg: "@nocobase/plugin-ui-templates" ---- - -# 字段模板 - -## 介绍 - -字段模板用于在**表单区块**和**详情区块**中复用字段区域的配置（字段选择、布局与字段配置），避免在多个页面/区块中重复添加字段。 - -> 字段模板只作用于“字段区域”，不会替换整个区块。若要复用整个区块，请使用 [区块模板](/interface-builder/blocks/other-blocks/block-template)。 - -## 使用前准备：先创建区块模板 - -字段模板的来源是“区块模板”。建议先在一个已配置好字段的表单区块/详情区块上创建区块模板： - -1) 打开区块设置菜单，点击 `保存为模板` -2) 填写模板名称/描述，并保存 - -![save-as-template-form-20251228](https://static-docs.nocobase.com/save-as-template-form-20251228.png) - -## 在表单/详情区块中使用字段模板 - -1) 进入配置模式，在表单区块或详情区块打开“字段”菜单 -2) 选择 `字段模板` -3) 选择一个模板，并选择模式： - - `引用`：引用模板字段，所有引用处保持同步 - - `复制`：复制模板字段为独立配置，后续互不影响 - -![field-template-menu-20251228](https://static-docs.nocobase.com/field-template-menu-20251228.png) - -![use-field-template-config-20251228](https://static-docs.nocobase.com/use-field-template-config-20251228.png) - -### 引用与复制的区别 - -- `引用`：所有引用处共享同一份字段区域配置；修改模板或任一引用处，其他引用处都会同步更新。 -- `复制`：仅在复制时生成一份独立字段配置；后续对模板或其它区块的修改不会同步到这里。 - -### 覆盖提示 - -当区块中已存在字段时，使用**引用**模式通常会提示确认（因为引用字段会替换当前字段区域）。 - -## 将引用字段转换为复制 - -当区块正在引用字段模板时，可在区块设置菜单中使用 `将引用字段转换为复制`，把当前字段区域变为独立配置。 - -![convert-field-template-duplicate-20251228](https://static-docs.nocobase.com/convert-field-template-duplicate-20251228.png) - -## 注意事项 - -- 字段模板仅适用于**表单区块**与**详情区块**。 -- 模板与当前区块的绑定数据表不一致时，模板会在选择器中显示为不可用并提示原因。 -- 若希望在当前区块对字段进行“个性化调整”，建议直接使用 `复制` 模式，或先执行“将引用字段转换为复制”。 diff --git a/docs/docs/cn/interface-builder/ui-templates.md b/docs/docs/cn/interface-builder/ui-templates.md new file mode 100644 index 00000000000..c0eed840f09 --- /dev/null +++ b/docs/docs/cn/interface-builder/ui-templates.md @@ -0,0 +1,167 @@ +--- +pkg: "@nocobase/plugin-ui-templates" +--- + +# UI 模板 + +## 介绍 + +界面模板用于复用界面搭建中的配置，减少重复搭建，并在需要时保持多处配置同步更新。 + +目前支持的模板类型包括： + +- 区块模板：复用整个区块配置 +- 字段模板：复用表单/详情区块的“字段区域”配置 +- 弹窗模板：复用操作/字段触发的弹窗配置 + +## 核心概念 + +### 引用与复制 + +使用模板时通常有两种方式： + +- `引用`：多处共享同一份模板配置；修改模板或任一引用处，其他引用处会同步更新。 +- `复制`：复制为独立配置；后续互不影响。 + +### 保存为模板 + +当某个区块/弹窗已经配置好时，可以在其设置菜单中使用 `保存为模板`，并选择保存方式： + +- `将当前...转为模板`：保存后，当前位置会切换为引用该模板的形式。 +- `复制当前...为模板`：仅创建模板，当前位置保持不变。 + +## 区块模板 + +### 保存区块为模板 + +1) 打开目标区块的设置菜单，点击 `保存为模板` +2) 填写 `模板名称` / `模板描述`，并选择保存模式： + - `将当前区块转为模板`：保存后，当前位置将替换为 `区块模板` 区块（即引用该模板） + - `复制当前区块为模板`：仅创建模板，当前区块保持不变 + +![save-as-template-block-20251228](https://static-docs.nocobase.com/save-as-template-block-20251228.png) + +![save-as-template-block-full-20251228](https://static-docs.nocobase.com/save-as-template-block-full-20251228.png) + +### 使用区块模板 + +1) 添加区块 → “其他区块” → `区块模板` +2) 在配置中选择： + - `模板`：选择一个模板 + - `模式`：`引用` 或 `复制` + +![block-template-menu-20251228](https://static-docs.nocobase.com/block-template-menu-20251228.png) + +![select-block-template-20251228](https://static-docs.nocobase.com/select-block-template-20251228.png) + +### 将引用转换为复制 + +当区块正在引用模板时，可在区块设置菜单中使用 `将引用转换为复制`，把当前区块改为普通区块（断开引用），后续修改互不影响。 + +![convert-block-template-duplicate-20251228](https://static-docs.nocobase.com/convert-block-template-duplicate-20251228.png) + +### 注意事项 + +- `复制` 模式会重新生成区块及子节点的 UID，部分依赖 UID 的配置可能需要重新配置。 + +## 字段模板 + +字段模板用于在**表单区块**和**详情区块**中复用字段区域的配置（字段选择、布局与字段配置），避免在多个页面/区块中重复添加字段。 + +> 字段模板只作用于“字段区域”，不会替换整个区块。若要复用整个区块，请使用上文的区块模板。 + +### 在表单/详情区块中使用字段模板 + +1) 进入配置模式，在表单区块或详情区块打开“字段”菜单 +2) 选择 `字段模板` +3) 选择一个模板，并选择模式：`引用` 或 `复制` + +![field-template-menu-20251228](https://static-docs.nocobase.com/field-template-menu-20251228.png) + +![use-field-template-config-20251228](https://static-docs.nocobase.com/use-field-template-config-20251228.png) + +#### 覆盖提示 + +当区块中已存在字段时，使用**引用**模式通常会提示确认（因为引用字段会替换当前字段区域）。 + +### 将引用字段转换为复制 + +当区块正在引用字段模板时，可在区块设置菜单中使用 `将引用字段转换为复制`，把当前字段区域变为独立配置（断开引用），后续修改互不影响。 + +![convert-field-template-duplicate-20251228](https://static-docs.nocobase.com/convert-field-template-duplicate-20251228.png) + +### 注意事项 + +- 字段模板仅适用于**表单区块**与**详情区块**。 +- 模板与当前区块的绑定数据表不一致时，模板会在选择器中显示为不可用并提示原因。 +- 若希望在当前区块对字段进行“个性化调整”，建议直接使用 `复制` 模式，或先执行“将引用字段转换为复制”。 + +## 弹窗模板 + +弹窗模板用于复用一套弹窗界面与交互逻辑。关于弹窗的打开方式、尺寸等常规配置，参考 [编辑弹窗](/interface-builder/actions/action-settings/edit-popup)。 + +### 保存弹窗为模板 + +1) 打开能触发弹窗的按钮/字段设置菜单，点击 `保存为模板` +2) 填写模板名称/描述，并选择保存模式： + - `将当前弹窗转为模板`：保存后，当前弹窗将切换为引用该模板 + - `复制当前弹窗为模板`：仅创建模板，当前弹窗保持不变 + +![save-as-template-popup-20251228](https://static-docs.nocobase.com/save-as-template-popup-20251228.png) + +### 在弹窗配置中使用模板 + +1) 打开按钮/字段的弹窗配置 +2) 在 `弹窗模板` 中选择模板即可复用 + +![edit-popup-select-20251228](https://static-docs.nocobase.com/edit-popup-select-20251228.png) + +### 使用条件（模板可用范围） + +弹窗模板与触发弹窗的操作场景有关。选择器会根据当前场景自动过滤/禁用不兼容的模板（不满足条件时会提示原因）。 + +| 当前操作类型 | 可使用的弹窗模板 | +| --- | --- | +| **Collection 操作** | 同一 Collection 的 Collection 操作创建的弹窗模板 | +| **非关联 Record 操作** | 同一 Collection 的 Collection 操作或非关联 Record 操作创建的弹窗模板 | +| **关联 Record 操作** | 同一 Collection 的 Collection 操作或非关联 Record 操作创建的弹窗模板；或同一关联字段的关联 Record 操作创建的弹窗模板 | + +### 关系数据弹窗 + +关系数据（关联字段）触发的弹窗模板有特殊的匹配规则： + +#### 关系弹窗模板的严格匹配 + +当弹窗模板是从**关联 Record 操作**创建时（模板带有 `associationName`），该模板只能被**完全相同关联字段**的操作/字段使用。 + +例如：在 `订单.客户` 关系字段上创建的弹窗模板，只能被其他 `订单.客户` 关系字段的操作使用，不能被 `订单.推荐人` 关系字段使用（即使两者的目标数据表都是 `客户`）。 + +这是因为关系弹窗模板内部的变量和配置依赖于特定的关联关系上下文。 + +#### 关系操作复用目标数据表模板 + +关联字段/操作可以复用**目标数据表的非关系弹窗模板**（Collection 操作或非关联 Record 操作创建的模板），只要数据表一致即可。 + +例如：`订单.客户` 关系字段可以使用 `客户` 数据表的弹窗模板。这种方式适合在多个关系字段间共享同一套弹窗配置（如统一的客户详情弹窗）。 + +### 将引用转换为复制 + +当弹窗正在引用模板时，可在设置菜单中使用 `将引用转换为复制`，把当前弹窗改为独立配置（断开引用），后续修改互不影响。 + +![convert-popup-to-duplicate-20251228](https://static-docs.nocobase.com/convert-popup-to-duplicate-20251228.png) + + +## 模板管理 + +系统设置 → `UI 模板` 中可查看和管理所有模板： + +- **区块模板 (v2)**：管理区块模板 +- **弹窗模板 (v2)**：管理弹窗模板 + +> 字段模板来源于区块模板，在区块模板中管理。 + +![block-template-list-20251228](https://static-docs.nocobase.com/block-template-list-20251228.png) + +支持的操作：查看、筛选、编辑、删除。 + +> **注意**：若模板正在被引用中，则无法直接删除。请先在引用该模板的位置使用 `将引用转换为复制` 断开引用，再删除模板。 diff --git a/docs/docs/cn/plugins/@nocobase/plugin-ui-templates/index.md b/docs/docs/cn/plugins/@nocobase/plugin-ui-templates/index.md index 4dd0c42dc09..f40030cf373 100644 --- a/docs/docs/cn/plugins/@nocobase/plugin-ui-templates/index.md +++ b/docs/docs/cn/plugins/@nocobase/plugin-ui-templates/index.md @@ -1,5 +1,5 @@ --- -displayName: "界面模板" +displayName: "UI 模板" packageName: '@nocobase/plugin-ui-templates' supportedVersions: - 2.x @@ -10,4 +10,4 @@ builtIn: true defaultEnabled: true --- -# 界面模板 +# UI 模板 diff --git a/docs/docs/en/interface-builder/_meta.json b/docs/docs/en/interface-builder/_meta.json index 956d189eb8d..123697b413a 100644 --- a/docs/docs/en/interface-builder/_meta.json +++ b/docs/docs/en/interface-builder/_meta.json @@ -77,11 +77,6 @@ "label": "Iframe", "link": "/interface-builder/blocks/other-blocks/iframe" }, - { - "type": "custom-link", - "label": "Block template", - "link": "/interface-builder/blocks/other-blocks/block-template" - }, { "type": "custom-link", "label": "Markdown", @@ -153,11 +148,6 @@ "label": "Overview", "link": "/interface-builder/fields" }, - { - "type": "custom-link", - "label": "Field template", - "link": "/interface-builder/fields/field-template" - }, { "type": "custom-link", "label": "Generic Settings", @@ -499,6 +489,11 @@ "type": "custom-link", "label": "RunJS", "link": "/interface-builder/runjs" + }, + { + "type": "custom-link", + "label": "UI Templates", + "link": "/interface-builder/ui-templates" } ] } diff --git a/docs/docs/en/interface-builder/actions/action-settings/edit-popup.md b/docs/docs/en/interface-builder/actions/action-settings/edit-popup.md index b0b78779764..9c22d809124 100644 --- a/docs/docs/en/interface-builder/actions/action-settings/edit-popup.md +++ b/docs/docs/en/interface-builder/actions/action-settings/edit-popup.md @@ -1,32 +1,25 @@ -# Edit popup +# Edit Popup ## Introduction -Any action or field that opens a popup when clicked supports configuring the popup's open mode, size, etc. +Any action/field that can open a popup when clicked supports configuring the popup's opening method, size, etc. + ![20251027212617](https://static-docs.nocobase.com/20251027212617.png) - - ![edit-popup-full-20251228](https://static-docs.nocobase.com/edit-popup-full-20251228.png) - -## Open Mode +## Opening Method - Drawer - ![20251027212832](https://static-docs.nocobase.com/20251027212832.png) - - Dialog - ![20251027212905](https://static-docs.nocobase.com/20251027212905.png) - - Sub-page - ![20251027212940](https://static-docs.nocobase.com/20251027212940.png) ## Popup Size @@ -35,47 +28,6 @@ Any action or field that opens a popup when clicked supports configuring the pop - Medium (default) - Small -## Popup templates +## Template -Popup templates let you reuse a popup UI and interaction logic. - -### Save a popup as a template - -1) Open the settings menu of a button/field that opens a popup, click `Save as template` -2) Fill in template name/description and choose a save mode: - - `Convert current popup to template`: after saving, the current popup will start referencing this template - - `Duplicate current popup as template`: only creates the template; the current popup stays unchanged - -![save-as-template-popup-20251228](https://static-docs.nocobase.com/save-as-template-popup-20251228.png) - -### Use a template in popup settings - -1) Open the popup settings of the button/field -2) Select a template in `Popup template` - -![edit-popup-select-20251228](https://static-docs.nocobase.com/edit-popup-select-20251228.png) - -### Requirements (template availability) - -Popup templates depend on the action context. The selector will automatically filter/disable incompatible templates (and show a reason). - -- **Collection action buttons**: only templates created from **Collection actions**, and the **collection must match**. -- **Non-association Record actions**: templates created from **Non-association Record actions** and **Collection actions** are available, and the **collection must match**. -- **Association Record actions**: templates created from **Non-association Record actions** and **Collection actions** are available (the **collection must match**). Templates created from **Association Record actions** are also available, but they must match the **same association field** (the same association). - -### Reference vs Duplicate - -- `Reference`: opens the popup from a template; updates to the template affect all references. -- `Duplicate`: detach via `Convert reference to duplicate`; later changes only affect the current popup. - -### Manage popup templates - -Go to Settings → `UI templates` → `Popup templates (v2)` to search/edit/delete templates. - -> Note: If a template is currently referenced, it cannot be deleted. Use `Convert reference to duplicate` to detach first, then delete the template. - -### Convert reference to duplicate - -When the popup is referencing a template, use `Convert reference to duplicate` in the settings menu to make it independent. - -![convert-popup-to-duplicate-20251228](https://static-docs.nocobase.com/convert-popup-to-duplicate-20251228.png) +See [UI Templates - Popup Template](/interface-builder/ui-templates#popup-template). diff --git a/docs/docs/en/interface-builder/blocks/other-blocks/block-template.md b/docs/docs/en/interface-builder/blocks/other-blocks/block-template.md deleted file mode 100644 index 10bd426fee1..00000000000 --- a/docs/docs/en/interface-builder/blocks/other-blocks/block-template.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -pkg: "@nocobase/plugin-ui-templates" ---- - -# Block template - -## Introduction - -Block templates let you reuse a configured block without rebuilding it each time. - -## Create a block template - -1) Open a configured block’s settings menu and click `Save as template` -2) Fill in `Template name` / `Template description` and choose a save mode: - - `Convert current block to template`: replaces the current block with a `Block template` block (referencing the template) - - `Duplicate current block as template`: only creates the template; the current block stays unchanged - -![save-as-template-block-20251228](https://static-docs.nocobase.com/save-as-template-block-20251228.png) - -![save-as-template-block-full-20251228](https://static-docs.nocobase.com/save-as-template-block-full-20251228.png) - -## Use a block template - -1) Add a block → Other blocks → `Block template` -2) Configure: - - `Template`: select a template - - `Mode`: - - `Reference`: all places that reference the template stay in sync - - `Duplicate`: creates an independent copy; later changes won’t sync - -![block-template-menu-20251228](https://static-docs.nocobase.com/block-template-menu-20251228.png) - -![select-block-template-20251228](https://static-docs.nocobase.com/select-block-template-20251228.png) - -### Reference vs Duplicate - -- `Reference`: all references share the same configuration. Changes made in the template (or in any referenced place) will be reflected everywhere. -- `Duplicate`: creates a standalone copy at the time of duplication. Later changes won’t be synchronized. - -## Manage templates - -Go to Settings → `UI templates` → `Block templates (v2)` to search/edit/delete templates. - -> Note: If a template is currently referenced, it cannot be deleted. Use `Convert reference to duplicate` on those blocks to detach from the template first, then delete the template. - -![block-template-list-20251228](https://static-docs.nocobase.com/block-template-list-20251228.png) - -## Convert reference to duplicate (detach from template) - -If a block is currently referencing a template, use `Convert reference to duplicate` in the block menu to turn it into an independent block. - -![convert-block-template-duplicate-20251228](https://static-docs.nocobase.com/convert-block-template-duplicate-20251228.png) - -## Notes - -- In `Duplicate` mode, all UIDs (including child node UIDs) will be regenerated. Some UID-based configurations may need to be reconfigured. diff --git a/docs/docs/en/interface-builder/fields/field-template.md b/docs/docs/en/interface-builder/fields/field-template.md deleted file mode 100644 index e7105892c20..00000000000 --- a/docs/docs/en/interface-builder/fields/field-template.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -pkg: "@nocobase/plugin-ui-templates" ---- - -# Field template - -## Introduction - -Field templates are used to reuse the field section configuration (field selection, layout, and field settings) in **Form blocks** and **Details blocks**, so you don’t need to add the same fields repeatedly across pages/blocks. - -> A field template only applies to the field section and does not replace the entire block. To reuse an entire block, use [Block template](/interface-builder/blocks/other-blocks/block-template). - -## Prerequisite: create a block template first - -Field templates come from **Block templates**. It is recommended to first create a block template from a Form/Details block that already has the fields configured: - -1) Open the block settings menu and click `Save as template` -2) Fill in the template name/description and save - -![save-as-template-form-20251228](https://static-docs.nocobase.com/save-as-template-form-20251228.png) - -## Use a field template in Form/Details blocks - -1) Enter configure mode and open the “Fields” menu in a Form block or Details block -2) Select `Field template` -3) Select a template and choose a mode: - - `Reference`: reference the template fields and keep all references in sync - - `Duplicate`: duplicate the template fields as an independent configuration; later changes won’t sync - -![field-template-menu-20251228](https://static-docs.nocobase.com/field-template-menu-20251228.png) - -![use-field-template-config-20251228](https://static-docs.nocobase.com/use-field-template-config-20251228.png) - -### Reference vs Duplicate - -- `Reference`: all references share the same field section configuration. Changes made to the template (or in any referenced place) will be synchronized everywhere. -- `Duplicate`: creates a standalone field configuration at the time of duplication. Later changes to the template or other blocks will not be synchronized here. - -### Overwrite prompt - -If the block already has fields, using **Reference** mode usually asks for confirmation (because referenced fields will replace the current field section). - -## Convert referenced fields to duplicate - -When a block is referencing a field template, you can use `Convert reference fields to duplicate` in the block settings menu to make the current field section an independent configuration. - -![convert-field-template-duplicate-20251228](https://static-docs.nocobase.com/convert-field-template-duplicate-20251228.png) - -## Notes - -- Field templates are supported only in **Form blocks** and **Details blocks**. -- If the template’s collection binding does not match the current block, the template will be disabled in the selector with a reason. -- If you need to customize fields in the current block, use `Duplicate` mode, or run “Convert reference fields to duplicate” first. diff --git a/docs/docs/en/interface-builder/ui-templates.md b/docs/docs/en/interface-builder/ui-templates.md new file mode 100644 index 00000000000..a78a84ca1c5 --- /dev/null +++ b/docs/docs/en/interface-builder/ui-templates.md @@ -0,0 +1,167 @@ +--- +pkg: "@nocobase/plugin-ui-templates" +--- + +# UI Templates + +## Introduction + +UI templates are used to reuse configurations in interface building, reducing repetitive setup and keeping multiple configurations in sync when needed. + +Currently supported template types include: + +- Block Template: Reuse entire block configurations +- Field Template: Reuse "fields" configurations in form/detail blocks +- Popup Template: Reuse popup configurations triggered by actions/fields + +## Core Concepts + +### Reference and Duplicate + +There are typically two ways to use templates: + +- `Reference`: Multiple places share the same template configuration; modifying the template or any reference point will sync updates to all other reference points. +- `Duplicate`: Duplicate as an independent configuration; subsequent modifications do not affect each other. + +### Save as Template + +When a block/popup is already configured, you can use `Save as template` in its settings menu and choose the save method: + +- `Convert current... to template`: After saving, the current position will switch to referencing that template. +- `Duplicate current... as template`: Only creates the template, the current position remains unchanged. + +## Block Template + +### Save Block as Template + +1) Open the settings menu of the target block, click `Save as template` +2) Fill in `Template name` / `Template description`, and choose the save mode: + - `Convert current block to template`: After saving, the current position will be replaced with a `Block template` block (i.e., referencing that template) + - `Duplicate current block as template`: Only creates the template, the current block remains unchanged + +![save-as-template-block-20251228](https://static-docs.nocobase.com/save-as-template-block-20251228.png) + +![save-as-template-block-full-20251228](https://static-docs.nocobase.com/save-as-template-block-full-20251228.png) + +### Use Block Template + +1) Add block → "Other blocks" → `Block Template` +2) In the configuration, select: + - `Template`: Choose a template + - `Mode`: `Reference` or `Duplicate` + +![block-template-menu-20251228](https://static-docs.nocobase.com/block-template-menu-20251228.png) + +![select-block-template-20251228](https://static-docs.nocobase.com/select-block-template-20251228.png) + +### Convert Reference to Duplicate + +When a block is referencing a template, you can use `Convert reference to duplicate` in the block settings menu to change the current block to a regular block (disconnect the reference), subsequent modifications will not affect each other. + +![convert-block-template-duplicate-20251228](https://static-docs.nocobase.com/convert-block-template-duplicate-20251228.png) + +### Notes + +- `Duplicate` mode will regenerate UIDs for the block and its child nodes, some configurations that depend on UIDs may need to be reconfigured. + +## Field Template + +Field templates are used to reuse field area configurations (field selection, layout, and field settings) in **form blocks** and **detail blocks**, avoiding repetitive field addition across multiple pages/blocks. + +> Field templates only affect the "field area" and do not replace the entire block. To reuse an entire block, please use Block Template described above. + +### Use Field Template in Form/Detail Blocks + +1) Enter configuration mode, open the "Fields" menu in a form block or detail block +2) Select `Field Template` +3) Choose a template and select mode: `Reference` or `Duplicate` + +![field-template-menu-20251228](https://static-docs.nocobase.com/field-template-menu-20251228.png) + +![use-field-template-config-20251228](https://static-docs.nocobase.com/use-field-template-config-20251228.png) + +#### Override Prompt + +When fields already exist in the block, using **Reference** mode will usually prompt for confirmation (because referenced fields will replace the current field area). + +### Convert Referenced Fields to Duplicate + +When a block is referencing a field template, you can use `Convert referenced fields to duplicate` in the block settings menu to make the current field area an independent configuration (disconnect the reference), subsequent modifications will not affect each other. + +![convert-field-template-duplicate-20251228](https://static-docs.nocobase.com/convert-field-template-duplicate-20251228.png) + +### Notes + +- Field templates only apply to **form blocks** and **detail blocks**. +- When the template and current block are bound to different data tables, the template will be shown as unavailable in the selector with the reason displayed. +- If you want to make "personalized adjustments" to fields in the current block, it is recommended to use `Duplicate` mode directly, or first execute "Convert referenced fields to duplicate". + +## Popup Template + +Popup templates are used to reuse a set of popup interfaces and interaction logic. For general configurations like popup opening method and size, refer to [Edit Popup](/interface-builder/actions/action-settings/edit-popup). + +### Save Popup as Template + +1) Open the settings menu of a button/field that can trigger a popup, click `Save as template` +2) Fill in the template name/description and choose the save mode: + - `Convert current popup to template`: After saving, the current popup will switch to referencing that template + - `Duplicate current popup as template`: Only creates the template, the current popup remains unchanged + +![save-as-template-popup-20251228](https://static-docs.nocobase.com/save-as-template-popup-20251228.png) + +### Use Template in Popup Configuration + +1) Open the popup configuration of the button/field +2) Select a template in `Popup template` to reuse + +![edit-popup-select-20251228](https://static-docs.nocobase.com/edit-popup-select-20251228.png) + +### Usage Conditions (Template Availability Range) + +Popup templates are related to the action scenario that triggers the popup. The selector will automatically filter/disable incompatible templates based on the current scenario (with reasons displayed when conditions are not met). + +| Current Action Type | Available Popup Templates | +| --- | --- | +| **Collection Action** | Popup templates created by Collection actions of the same Collection | +| **Non-association Record Action** | Popup templates created by Collection actions or non-association Record actions of the same Collection | +| **Association Record Action** | Popup templates created by Collection actions or non-association Record actions of the same Collection; or popup templates created by association Record actions of the same association field | + +### Association Data Popups + +Popups triggered by association data (association fields) have special matching rules: + +#### Strict Matching for Association Popup Templates + +When a popup template is created from an **Association Record action** (the template has an `associationName`), that template can only be used by actions/fields with the **exact same association field**. + +For example, a popup template created on the `Order.Customer` association field can only be used by other `Order.Customer` association field actions. It cannot be used by the `Order.Referrer` association field (even if both target the same `Customer` data table). + +This is because association popup templates' internal variables and configurations depend on the specific association relationship context. + +#### Association Actions Reusing Target Collection Templates + +Association fields/actions can reuse **non-association popup templates from the target data table** (templates created by Collection actions or non-association Record actions), as long as the data table matches. + +For example, the `Order.Customer` association field can use popup templates from the `Customer` data table. This approach is suitable for sharing the same popup configuration across multiple association fields (such as a unified customer details popup). + +### Convert Reference to Duplicate + +When a popup is referencing a template, you can use `Convert reference to duplicate` in the settings menu to make the current popup an independent configuration (disconnect the reference), subsequent modifications will not affect each other. + +![convert-popup-to-duplicate-20251228](https://static-docs.nocobase.com/convert-popup-to-duplicate-20251228.png) + + +## Template Management + +In System settings → `UI Templates`, you can view and manage all templates: + +- **Block Templates (v2)**: Manage block templates +- **Popup Templates (v2)**: Manage popup templates + +> Field templates originate from block templates and are managed within block templates. + +![block-template-list-20251228](https://static-docs.nocobase.com/block-template-list-20251228.png) + +Supported operations: View, Filter, Edit, Delete. + +> **Note**: If a template is currently being referenced, it cannot be directly deleted. Please first use `Convert reference to duplicate` at the positions referencing that template to disconnect the reference, then delete the template. diff --git a/packages/plugins/@nocobase/plugin-ui-templates/package.json b/packages/plugins/@nocobase/plugin-ui-templates/package.json index 785e4d94669..c6628b99363 100644 --- a/packages/plugins/@nocobase/plugin-ui-templates/package.json +++ b/packages/plugins/@nocobase/plugin-ui-templates/package.json @@ -1,7 +1,7 @@ { "name": "@nocobase/plugin-ui-templates", "displayName": "UI templates", - "displayName.zh-CN": "界面模板", + "displayName.zh-CN": "UI 模板", "description": "Provides block templates and popup templates for UI reuse.", "description.zh-CN": "提供区块模板和弹窗模板复用的能力。", "version": "2.0.0-alpha.59", diff --git a/packages/plugins/@nocobase/plugin-ui-templates/src/locale/zh-CN.json b/packages/plugins/@nocobase/plugin-ui-templates/src/locale/zh-CN.json index c0c5f835863..bf81e41b522 100644 --- a/packages/plugins/@nocobase/plugin-ui-templates/src/locale/zh-CN.json +++ b/packages/plugins/@nocobase/plugin-ui-templates/src/locale/zh-CN.json @@ -1,5 +1,5 @@ { - "UI templates": "界面模板", + "UI templates": "UI 模板", "Block templates (v2)": "区块模板 (v2)", "Popup templates (v2)": "弹窗模板 (v2)", "Actions": "操作",