---
pkg: "@nocobase/plugin-ui-templates"
---

# UI テンプレート

## 導入

UI テンプレートは、インターフェース構築における設定を再利用するための機能です。重複する構築作業を減らし、必要に応じて複数の箇所の設定を同期して更新することができます。

現在サポートされているテンプレートの種類は以下の通りです：

- ブロックテンプレート：ブロック全体の設定を再利用します。
- フィールドテンプレート：フォーム/詳細ブロックの「フィールドエリア」の設定を再利用します。
- ポップアップテンプレート：アクションやフィールドによってトリガーされるポップアップの設定を再利用します。

## コア概念

### 参照と複製

テンプレートを使用する際には、通常 2 つの方法があります：

- `参照`：複数の場所で同一のテンプレート設定を共有します。テンプレートまたは参照先のいずれかを変更すると、他の参照先も同期して更新されます。
- `複製`：独立した設定としてコピーします。その後の変更は互いに影響しません。

### テンプレートとして保存

ブロックやポップアップの設定が完了している場合、設定メニューの「テンプレートとして保存」から保存方法を選択できます：

- `現在の...をテンプレートに変換する`：保存後、現在の場所はそのテンプレートを参照する形式に切り替わります。
- `現在の...をテンプレートとして複製する`：テンプレートのみを作成し、現在の場所の設定はそのまま維持されます。

## ブロックテンプレート

### ブロックをテンプレートとして保存

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)

### 使用条件（テンプレートの利用可能範囲）

ポップアップテンプレートは、ポップアップをトリガーするアクションのシナリオに関連しています。セレクターは、現在のシナリオに基づいて互換性のないテンプレートを自動的にフィルタリングまたは無効化します（条件を満たさない場合は理由が表示されます）。

| 現在のアクションタイプ | 使用可能なポップアップテンプレート |
| --- | --- |
| **コレクションアクション** | 同一コレクションのコレクションアクションで作成されたポップアップテンプレート |
| **非関連レコードアクション** | 同一コレクションのコレクションアクションまたは非関連レコードアクションで作成されたポップアップテンプレート |
| **関連レコードアクション** | 同一コレクションのコレクションアクションまたは非関連レコードアクションで作成されたポップアップテンプレート、または同一の関連フィールドの関連レコードアクションで作成されたポップアップテンプレート |

### 関連データのポップアップ

関連データ（関連フィールド）によってトリガーされるポップアップテンプレートには、特別な一致ルールがあります：

#### 関連ポップアップテンプレートの厳密な一致

ポップアップテンプレートが**関連レコードアクション**から作成された場合（テンプレートに `associationName` が含まれる場合）、そのテンプレートは**完全に同じ関連フィールド**のアクションまたはフィールドでしか使用できません。

例えば、`注文.顧客` 関連フィールドで作成されたポップアップテンプレートは、他の `注文.顧客` 関連フィールドのアクションでのみ使用でき、`注文.紹介者` 関連フィールドでは使用できません（たとえ両方のターゲットデータテーブルが `顧客` であっても同様です）。

これは、関連ポップアップテンプレート内部の変数や設定が、特定の関連関係のコンテキストに依存しているためです。

#### 関連アクションによるターゲットデータテーブルテンプレートの再利用

関連フィールドやアクションは、データテーブルが一致していれば、**ターゲットデータテーブルの非関連ポップアップテンプレート**（コレクションアクションまたは非関連レコードアクションで作成されたテンプレート）を再利用できます。

例えば、`注文.顧客` 関連フィールドは、`顧客` データテーブルのポップアップテンプレートを使用できます。この方法は、複数の関連フィールド間で同一のポップアップ設定（統一された顧客詳細ポップアップなど）を共有するのに適しています。

### 参照を複製に変換

ポップアップがテンプレートを参照している場合、設定メニューから「参照を複製に変換」を使用することで、現在のポップアップを独立した設定に変更（参照を解除）できます。その後の変更は互いに影響しません。

![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)

サポートされている操作：表示、フィルタリング、編集、削除。

> **注意**：テンプレートが参照されている間は、直接削除することはできません。まず、そのテンプレートを参照している場所で「参照を複製に変換」を使用して参照を解除してから、テンプレートを削除してください。