umbraco-workspace

Umbraco ワークスペース

これは何ですか？

ワークスペースは、Umbraco の特定のエンティティタイプ向けに設計された専用の編集環境です。コンテンツ、メディア、メンバー、その他のエンティティを、タイプごとに特化したインターフェースで編集できる分離された領域を作成します。ワークスペースは、公開バージョンとは別にエンティティデータの下書きコピーを保持し、コンテキスト、ビュー、アクション、フッターアプリなど複数の拡張タイプをサポートします。

ドキュメント

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

• メインドキュメント: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces
• ワークスペースコンテキスト: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-context
• ワークスペースビュー: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-views
• ワークスペースアクション: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/workspaces/workspace-editor-actions
• 基盤: 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' と kind: 'routable'

機能	kind: 'default'	kind: 'routable'
用途	静的ページ、ルートワークスペース	一意の ID を持つエンティティの編集
ツリー連携	選択状態なし	適切な選択状態
URL ルーティング	ルートパラメータなし	edit/:unique をサポート
コンテキスト	シンプル	unique observable を持つ

ツリー項目のナビゲーションには、常に kind: 'routable' を使用してください - そうしないと:

• 項目間をクリックしてもツリー項目の選択が更新されません
• 同じタイプの項目間のナビゲーションが機能しません
• 「永久に読み込み中」が発生することがあります

ルーティング可能なワークスペースコンテキストのパターン

kind: 'routable' のワークスペースでは、ワークスペースコンテキストクラスを作成する必要があります:

import { UmbWorkspaceRouteManager, UMB_WORKSPACE_CONTEXT } from '@umbraco-cms/backoffice/workspace';
import { UmbObjectState } from '@umbraco-cms/backoffice/observable-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import { UmbContextBase } from '@umbraco-cms/backoffice/class-api';
import { LitElement, html } from '@umbraco-cms/backoffice/external/lit';
import { customElement } from '@umbraco-cms/backoffice/external/lit';

// Workspace editor element that renders views
@customElement('my-workspace-editor')
class MyWorkspaceEditorElement extends LitElement {
  override render() {
    return html`<umb-workspace-editor></umb-workspace-editor>`;
  }
}

interface MyEntityData {
  unique: string;
  name?: string;
}

export class MyWorkspaceContext extends UmbContextBase {
  public readonly workspaceAlias = 'My.Workspace';

  #data = new UmbObjectState<MyEntityData | undefined>(undefined);
  readonly data = this.#data.asObservable();

  // CRITICAL: Observable unique for workspace views to consume
  readonly unique = this.#data.asObservablePart((data) => data?.unique);
  readonly name = this.#data.asObservablePart((data) => data?.name);

  readonly routes = new UmbWorkspaceRouteManager(this);

  constructor(host: UmbControllerHost) {
    super(host, UMB_WORKSPACE_CONTEXT);

    // Route pattern for tree item navigation
    this.routes.setRoutes([
      {
        path: 'edit/:unique',
        component: MyWorkspaceEditorElement,
        setup: (_component, info) => {
          const unique = info.match.params.unique;
          this.load(unique);
        },
      },
    ]);
  }

  async load(unique: string) {
    // Load entity data and update state
    this.#data.setValue({ unique });
  }

  getUnique() {
    return this.#data.getValue()?.unique;
  }

  getEntityType() {
    return 'my-entity';  // Must match tree item entityType!
  }

  public override destroy(): void {
    this.#data.destroy();
    super.destroy();
  }
}

export { MyWorkspaceContext as api };

コンテキストを利用するワークスペースビュー

ワークスペースビューは、ナビゲーションに反応するためにコンテキストの unique を監視します:

import { UMB_WORKSPACE_CONTEXT } from '@umbraco-cms/backoffice/workspace';

override connectedCallback() {
  super.connectedCallback();

  this.consumeContext(UMB_WORKSPACE_CONTEXT, (context) => {
    if (!context) return;

    // Observe unique - will fire when navigating between items
    this.observe((context as any).unique, (unique: string | null) => {
      if (unique) {
        this._loadData(unique);
      }
    });
  });
}

参照例

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

ワークスペースコンテキストカウンター: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/workspace-context-counter/

この例では、コンテキスト、ビュー、フッターアプリを備えたワークスペースを紹介します。ユニットテストも含まれます。

ワークスペースコンテキストの初期名: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/workspace-context-initial-name/

この例では、ワークスペースコンテキストの初期化パターンを示します。

ワークスペースビューヒント: /Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/workspace-view-hint/

この例では、ワークスペースビューのヒントとメタデータを紹介します。

関連する基盤スキル

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

• Context API: ワークスペースコンテキストの実装、コンテキストの利用、またはワークスペース拡張の通信を説明する場合

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

• 状態管理: 下書き状態、observable、リアクティブ更新、またはワークスペースデータ管理を実装する場合

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

• Umbraco Element: ワークスペースビュー要素の実装、UmbElementMixin の説明、またはワークスペースコンポーネントの作成を行う場合

  • 参照スキル: umbraco-umbraco-element

• コントローラー: ワークスペースアクション、コントローラー、副作用、またはアクションロジックを実装する場合

  • 参照スキル: umbraco-controllers

• ツリー: ワークスペースがツリーナビゲーションにリンクされている場合

  • 参照スキル: umbraco-tree

ワークフロー

1. ドキュメントを取得 - 上記のドキュメント URL に対して WebFetch を使用し、最新のコード例とパターンを取得します
2. 質問する - どのエンティティ型ですか？どのビューが必要ですか？どのアクションが必要ですか？これはツリーにリンクされていますか？
3. kind を選択 - ツリーナビゲーションには kind: 'routable' を、静的ページには kind: 'default' を使用します
4. ファイルを生成 - 取得したドキュメントに基づいて、マニフェスト + ワークスペースコンテキスト + ビュー + アクションを作成します
5. プロジェクト参照を追加 - 拡張機能が動作するには、メインの Umbraco プロジェクトから参照される必要があります：
   • 現在の作業ディレクトリで .csproj ファイルを検索します
   • Umbraco インスタンスがちょうど 1 つ見つかった場合は、それに参照を追加します
   • Umbraco インスタンスが複数見つかった場合は、どれを使用するかをユーザーに尋ねます
   • Umbraco インスタンスが見つからない場合は、パスをユーザーに尋ねます
6. 説明 - 何が作成されたか、およびテスト方法を示します

最小限のマニフェスト例

export const manifests: UmbExtensionManifest[] = [
  // Routable workspace for tree integration
  {
    type: 'workspace',
    kind: 'routable',
    alias: 'My.Workspace',
    name: 'My Workspace',
    api: () => import('./my-workspace.context.js'),
    meta: {
      entityType: 'my-entity',  // Must match tree item entityType!
    },
  },
  // Workspace view
  {
    type: 'workspaceView',
    alias: 'My.WorkspaceView',
    name: 'My Workspace View',
    element: () => import('./my-workspace-view.element.js'),
    weight: 100,
    meta: {
      label: 'Details',
      pathname: 'details',
      icon: 'icon-info',
    },
    conditions: [
      {
        alias: 'Umb.Condition.WorkspaceAlias',
        match: 'My.Workspace',
      },
    ],
  },
];

コードを生成する前に、常に最新のドキュメントを取得してください - API とパターンが変更されている可能性があります。