mcpField
U
umbraco-controllers

umbraco-controllers

github.com/umbraco开发27410 次安装6 周前更新
代码仓库

关于 umbraco-controllers

帮助开发者为 Umbraco 后台元素实现可复用控制器，管理生命周期、上下文和副作用。内容包括控制器基类、托管方式及清理逻辑示例。

主要功能

  1. 01生命周期钩子管理
  2. 02自动注册与注销
  3. 03控制器组合
  4. 04上下文访问
  5. 05订阅与定时器清理

适用场景

  1. 01在多个元素间复用逻辑
  2. 02管理订阅和定时任务
  3. 03从控制器访问 Umbraco 上下文

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/umbraco/umbraco-cms-backoffice-skills --skill umbraco-controllers

安装后在 Claude Code 中输入/umbraco-controllers确认已加载。

详细介绍

Umbraco 控制器

它是什么？

控制器是独立的类，可以在不同元素之间包含或复用逻辑，同时保持与元素生命周期的关联。控制器会分配给宿主元素，并支持生命周期方法（hostConnected、hostDisconnected、destroy），用于管理副作用、计时器、订阅和清理工作。控制器可以托管其他控制器，从而实现功能的组合与复用。

文档

实现之前务必获取最新文档：

工作流

  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 技能。

就是这样！务必获取最新文档，保持示例简洁，并生成完整可运行的代码。

评论

支持 Markdown