umbraco-tree

Umbraco Tree

これは何ですか？

Umbraco のツリーは、Backoffice 拡張レジストリに登録されたノードの階層構造です。ツリーは整理されたコンテンツ階層を表示し、<umb-tree /> 要素を使用して Backoffice の任意の場所にレンダリングできます。ルート項目、子、祖先を取得するためのデータソースの実装が必要です。

ドキュメント

実装する前に、常に最新のドキュメントを取得してください:

• メインドキュメント: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/tree
• セクションとツリー: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions
• Foundation: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 拡張レジストリ: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

重要: ツリーとワークスペースの統合

ツリーとワークスペースは密接に結合しています。 kind: 'default' のツリー項目を使用する場合:

1. ツリー項目にはワークスペースが必須です - ツリー項目をクリックすると、そのエンティティ型のワークスペースに移動します。entityType に登録されたワークスペースがない場合、クリックすると「永遠に読み込み中」の状態になります

2. ワークスペースは kind: 'routable' である必要があります - 適切なツリー項目の選択状態と、同じ型の項目間のナビゲーションのためには、kind: 'routable' ワークスペースを使用してください（kind: 'default' ではありません）

3. エンティティ型がツリーとワークスペースをリンクします - ツリー項目データの entityType は、ワークスペースマニフェストの entityType と一致する必要があります

クリック可能な項目を持つツリーを実装する場合は、umbraco-workspace スキルも参照してください。

ファイル構造

モダンなツリーは 2〜3 ファイルを使用します:

my-tree/
├── manifest.ts          # Registers repository and tree
├── tree.repository.ts   # Repository + inline data source
└── types.ts             # Type definitions (optional)

リファレンス例

Umbraco のソースには動作する例が含まれています:

場所: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/tree/

この例では、データソース、リポジトリ、メニュー統合を備えた完全なカスタムツリーを示しています。本番環境のパターンとして研究してください。

関連する Foundation スキル

ツリーを実装する際にこれらの基盤となる概念を説明する必要がある場合は、以下のスキルを参照してください:

• リポジトリパターン: ツリーデータソース、リポジトリ、データ取得、または CRUD 操作を実装する場合

  • 参照スキル: umbraco-repository-pattern

• Context API: リポジトリコンテキストを実装する場合、またはリポジトリが UI コンポーネントにどのように接続するかを説明する場合

  • 参照スキル: umbraco-context-api

• 状態管理: リアクティブなツリー更新、オブザーバブル、またはツリー状態の管理を実装する場合

  • 参照スキル: umbraco-state-management

ワークフロー

1. ドキュメントを取得 - 上記の URL に対して WebFetch を使用します
2. 質問する - ツリーはどのようなデータを表示しますか？どのリポジトリがデータを提供しますか？どこに表示されますか？ツリー項目はクリック可能ですか？
3. ファイルを生成 - 最新のドキュメントに基づいて最小限のファイルを作成します
   • ✅ 作成: manifest.ts、tree.repository.ts（インラインデータソース付き）
   • ❌ 作成しない: tree.store.ts（v18 で削除）、別個の tree.data-source.ts（インライン化可能）
   • 以下の例に示すインラインデータソースパターンを使用してください
4. クリック可能な場合 - 各エンティティ型に対してルーティング可能なワークスペースも作成します（umbraco-workspace スキルを参照）
5. 説明 - 作成した内容とテスト方法を示します

主要な設定オプション

MenuItem の hideTreeRoot（Tree ではない）

ルートレベルでツリー項目を表示する場合（親フォルダなし）、menuItem マニフェストに hideTreeRoot: true を使用します:

// CORRECT - hideTreeRoot on menuItem
{
  type: 'menuItem',
  kind: 'tree',
  alias: 'My.MenuItem.Tree',
  meta: {
    treeAlias: 'My.Tree',
    menus: ['My.Menu'],
    hideTreeRoot: true,  // Shows items at root level
  },
}

// WRONG - hideTreeRoot on tree (has no effect)
{
  type: 'tree',
  meta: {
    hideTreeRoot: true,  // This does nothing!
  },
}

最小限の例

ツリーマニフェスト

export const manifests: UmbExtensionManifest[] = [
  // Repository
  {
    type: 'repository',
    alias: 'My.Tree.Repository',
    name: 'My Tree Repository',
    api: () => import('./tree.repository.js'),
  },
  // Tree
  {
    type: 'tree',
    kind: 'default',
    alias: 'My.Tree',
    name: 'My Tree',
    meta: {
      repositoryAlias: 'My.Tree.Repository',
    },
  },
  // Tree Items - use kind: 'default' when workspaces exist
  {
    type: 'treeItem',
    kind: 'default',
    alias: 'My.TreeItem',
    name: 'My Tree Item',
    forEntityTypes: ['my-entity'],
  },
  // MenuItem - hideTreeRoot here
  {
    type: 'menuItem',
    kind: 'tree',
    alias: 'My.MenuItem.Tree',
    meta: {
      treeAlias: 'My.Tree',
      menus: ['My.Menu'],
      hideTreeRoot: true,
    },
  },
];

インラインデータソースを含むリポジトリ (tree.repository.ts)

モダンで簡素化されたパターン - すべてを 1 つのファイルに:

import { UmbTreeRepositoryBase, UmbTreeServerDataSourceBase } from '@umbraco-cms/backoffice/tree';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import type { UmbApi } from '@umbraco-cms/backoffice/extension-api';
import type { MyTreeItemModel, MyTreeRootModel } from './types.js';
import { MY_ROOT_ENTITY_TYPE, MY_ENTITY_TYPE } from './entity.js';

// Data source as simple class using helper base
class MyTreeDataSource extends UmbTreeServerDataSourceBase<any, MyTreeItemModel> {
  constructor(host: UmbControllerHost) {
    super(host, {
      getRootItems: async (args) => {
        // Fetch from API or return mock data
        const items: MyTreeItemModel[] = [
          {
            unique: 'item-1',
            parent: { unique: null, entityType: MY_ROOT_ENTITY_TYPE },
            entityType: MY_ENTITY_TYPE,
            name: 'Item 1',
            hasChildren: false,
            isFolder: false,
            icon: 'icon-document',
          },
        ];
        return { data: { items, total: items.length } };
      },
      getChildrenOf: async (args) => {
        // Return children for parent
        return { data: { items: [], total: 0 } };
      },
      getAncestorsOf: async (args) => {
        // Return ancestor path
        return { data: [] };
      },
      mapper: (item: any) => item, // Identity mapper for this example
    });
  }
}

// Repository
export class MyTreeRepository
  extends UmbTreeRepositoryBase<MyTreeItemModel, MyTreeRootModel>
  implements UmbApi
{
  constructor(host: UmbControllerHost) {
    super(host, MyTreeDataSource);
  }

  async requestTreeRoot() {
    const data: MyTreeRootModel = {
      unique: null,
      entityType: MY_ROOT_ENTITY_TYPE,
      name: 'My Tree',
      hasChildren: true,
      isFolder: true,
    };
    return { data };
  }
}

export { MyTreeRepository as api };

これがよりシンプルである理由:

• ✅ 2 つではなく 1 つのファイル
• ✅ UmbTreeServerDataSourceBase ヘルパーを使用（メソッドではなく関数を渡す）
• ✅ データ取得ロジックがインライン（理解しやすい）
• ✅ 保守すべき別個のデータソースファイルが不要

API 呼び出しを伴う複雑なツリーの場合、別々のファイルに分割することもできますが、必須ではありません。

以上です！常に最新のドキュメントを取得し、例は最小限に保ち、完全に動作するコードを生成してください。