umbraco-controllers

Umbraco コントローラー

これは何ですか？

コントローラーは、要素のライフサイクルとの接続を維持しながら、要素間でロジックを格納または再利用する独立したクラスです。コントローラーはホスト要素に割り当てられ、副作用、タイマー、サブスクリプション、クリーンアップを管理するためのライフサイクルメソッド（hostConnected、hostDisconnected、destroy）をサポートします。コントローラーは他のコントローラーをホストでき、機能の構成と再利用を可能にします。

ドキュメント

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

• メインドキュメント: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/umbraco-controller
• カスタムコントローラーの作成: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/umbraco-controller/write-your-own-controller
• 基盤: https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

ワークフロー

1. ドキュメントを取得 - 上記の URL に対して WebFetch を使用します
2. 質問する - カスタムコントローラーが必要ですか？どのライフサイクルイベントですか？どのようなクリーンアップが必要ですか？
3. コードを生成 - 最新のドキュメントに基づいて UmbControllerBase を継承したコントローラーを実装します
4. 説明 - 作成した内容とそのホスト方法を示します

最小限の例

基本的なカスタムコントローラー

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class MyController extends UmbControllerBase {
  constructor(host: UmbControllerHost) {
    super(host);
    // Auto-registers with host
  }

  override hostConnected() {
    super.hostConnected();
    console.log('Controller connected!');
  }

  override hostDisconnected() {
    super.hostDisconnected();
    console.log('Controller disconnected!');
  }

  override destroy() {
    super.destroy();
    console.log('Controller destroyed!');
  }
}

タイマーコントローラーの例

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class TimerController extends UmbControllerBase {
  #timer?: number;
  #secondsAlive = 0;

  constructor(host: UmbControllerHost) {
    super(host);
  }

  override hostConnected() {
    super.hostConnected();
    // Start timer when element connects to DOM
    this.#timer = window.setInterval(this.#onInterval, 1000);
  }

  override hostDisconnected() {
    super.hostDisconnected();
    // Clean up timer when element disconnects
    if (this.#timer) {
      clearInterval(this.#timer);
    }
  }

  #onInterval = () => {
    this.#secondsAlive++;
    console.log(`Controller active for ${this.#secondsAlive} seconds`);
  };

  override destroy() {
    super.destroy();
    if (this.#timer) {
      clearInterval(this.#timer);
    }
  }

  getSecondsAlive(): number {
    return this.#secondsAlive;
  }
}

要素内でのコントローラーのホスト

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { TimerController } from './timer-controller.js';

export class MyElement extends UmbLitElement {
  #timerController = new TimerController(this);

  render() {
    return html`
      <div>
        Active for: ${this.#timerController.getSecondsAlive()}s
      </div>
    `;
  }
}

手動登録（推奨されません）

export class MyManualController {
  #host: UmbControllerHost;

  constructor(host: UmbControllerHost) {
    this.#host = host;
    // Manual registration required
    this.#host.addUmbController(this);
  }

  hostConnected() {
    console.log('Connected');
  }

  destroy() {
    // Manual deregistration required
    this.#host.removeUmbController(this);
  }
}

コンテキストアクセスを備えたコントローラー

import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class NotificationController extends UmbControllerBase {
  async showSuccess(message: string) {
    // Controllers can access contexts via getContext
    const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
    context?.peek('positive', { data: { message } });
  }
}

主要な概念

ホスト要素: コントローラーをホストする Web コンポーネント（すべての Umbraco 要素がホストになれます）

ライフサイクルメソッド:

• hostConnected() - ホスト要素が DOM に接続されたときに呼び出されます
• hostDisconnected() - ホスト要素が DOM から切断されたときに呼び出されます
• destroy() - コントローラーが完全に破棄されたときに呼び出されます

自動登録: UmbControllerBase を継承すると自動的に登録/登録解除されます

コントローラーの構成: コントローラーは他のコントローラーをホストできます

コンテキストアクセス: コントローラーは getContext() と consumeContext() を介してコンテキストを利用できます

ユースケース:

• サブスクリプションとクリーンアップの管理
• タイマーとインターバルの処理
• 副作用の調整
• 複数の要素間でのロジックの再利用
• API 呼び出しとデータ取得の管理

API 呼び出し: コントローラーから API 呼び出しを行う場合、生の fetch() を絶対に使用しないでください。常に Umbraco の認証コンテキストで構成された生成済みの OpenAPI クライアントを使用してください。セットアップについては umbraco-openapi-client スキルを参照してください。

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