umbraco-umbraco-element

Umbraco Element

这是什么？

Umbraco Element 是一种 Web Component 增强功能，可通过 UmbElementMixin 简化与 Umbraco Backoffice 的集成。它提供了用于使用和提供上下文、观察状态、处理本地化以及托管控制器的方法。UmbElementMixin 可应用于任何兼容 Web Component 的基类，而 UmbLitElement 则是将该混入与 Lit 结合起来的便捷封装。

文档

实施前请务必获取最新文档：

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/umbraco-element
• 上下文 API：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/context-api
• 控制器：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/localization
• 基础知识：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提出问题 - 使用 Lit 吗？需要上下文吗？需要本地化吗？使用哪个基类？
3. 生成文件 - 根据最新文档，使用 UmbElementMixin 或 UmbLitElement 创建元素
4. 说明 - 展示创建的内容及其用法

最简示例

使用 UmbLitElement（推荐用于 Lit）

import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-element')
export class MyElement extends UmbLitElement {

  constructor() {
    super();
    // Access built-in features
    this.consumeContext(MY_CONTEXT, (context) => {
      console.log('Context consumed:', context);
    });
  }

  render() {
    return html`
      <div>
        <h3>${this.localize.term('myKey')}</h3>
        <p>My custom element</p>
      </div>
    `;
  }
}

export default MyElement;

将 UmbElementMixin 与 HTMLElement 配合使用

import { customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';

@customElement('my-element')
export class MyElement extends UmbElementMixin(HTMLElement) {

  constructor() {
    super();
    this.consumeContext(MY_CONTEXT, (context) => {
      // Use context
    });
  }

  connectedCallback() {
    this.innerHTML = `
      <div>
        <h3>My Element</h3>
      </div>
    `;
  }
}

export default MyElement;

将 UmbElementMixin 与 UI 库组件配合使用

import { customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { UUIButtonElement } from '@umbraco-cms/backoffice/external/uui';

@customElement('my-custom-button')
export class MyCustomButton extends UmbElementMixin(UUIButtonElement) {

  constructor() {
    super();
    // Now has access to Umbraco contexts and controllers
  }
}

export default MyCustomButton;

使用上下文

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

export class MyElement extends UmbLitElement {

  #notificationContext?: typeof UMB_NOTIFICATION_CONTEXT.TYPE;

  constructor() {
    super();

    this.consumeContext(UMB_NOTIFICATION_CONTEXT, (context) => {
      this.#notificationContext = context;
    });
  }

  showNotification() {
    this.#notificationContext?.peek('positive', {
      data: { headline: 'Success!', message: 'Operation completed' }
    });
  }
}

使用可观察状态

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UMB_CURRENT_USER_CONTEXT } from '@umbraco-cms/backoffice/current-user';

export class MyElement extends UmbLitElement {

  @state()
  private _userName?: string;

  constructor() {
    super();

    this.consumeContext(UMB_CURRENT_USER_CONTEXT, (context) => {
      this.observe(
        context.currentUser,
        (user) => {
          this._userName = user?.name;
        },
        '_userName'
      );
    });
  }
}

主要功能

• consumeContext() - 订阅并使用父元素提供的上下文
• provideContext() - 向子元素提供上下文
• observe() - 监视可观察状态并触发响应式更新
• localize - 内置用于翻译的本地化控制器
• hostController() - 在元素中托管和管理控制器

UmbLitElement 与 UmbElementMixin

功能	UmbLitElement	UmbElementMixin
基类	预先配置了 Lit	可应用于任何基类
用法	extends UmbLitElement	extends UmbElementMixin(BaseClass)
适用场景	基于 Lit 的组件	自定义基类或 UI 库组件
功能	功能相同	功能相同

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