Back to Details

umbraco-umbraco-element

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Element

Umbraco Element

What is it?

什么是Umbraco Element？

An Umbraco Element is a Web Component enhancement that simplifies integration with the Umbraco Backoffice through the UmbElementMixin. It provides methods to consume/provide contexts, observe states, handle localization, and host controllers. UmbElementMixin can be applied to any Web Component-compatible base class, while UmbLitElement is a convenience wrapper combining the mixin with Lit.
Umbraco Element是一种Web Component增强功能，通过UmbElementMixin简化与Umbraco后台的集成。它提供了消费/提供上下文、观察状态、处理本地化以及托管控制器的方法。UmbElementMixin可以应用于任何兼容Web Component的基类，而UmbLitElement是一个便捷的包装器，将该mixin与Lit结合在一起。

Documentation

文档

Always fetch the latest docs before implementing:
在开始实现前，请务必获取最新文档：

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - Using Lit? Need contexts? Need localization? Which base class?
  3. Generate files - Create element using UmbElementMixin or UmbLitElement based on latest docs
  4. Explain - Show what was created and how to use it
  1. 获取文档 - 使用WebFetch获取上述URL的内容
  2. 确认需求 - 是否使用Lit？是否需要上下文？是否需要本地化？使用哪个基类？
  3. 生成文件 - 根据最新文档，使用UmbElementMixin或UmbLitElement创建元素
  4. 说明解释 - 展示创建的内容以及使用方法

Minimal Examples

极简示例

Using UmbLitElement (Recommended for Lit)

使用UmbLitElement（推荐用于Lit项目）

typescript
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;
typescript
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;

Using UmbElementMixin with HTMLElement

使用UmbElementMixin结合HTMLElement

typescript
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;
typescript
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;

Using UmbElementMixin with UI Library Component

使用UmbElementMixin结合UI库组件

typescript
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;
typescript
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;

Consuming Context

消费上下文

typescript
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' }
    });
  }
}
typescript
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' }
    });
  }
}

Using Observable State

使用可观察状态

typescript
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'
      );
    });
  }
}
typescript
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'
      );
    });
  }
}

Key Features

核心功能

  • consumeContext() - Subscribe to and consume contexts from parent elements
  • provideContext() - Provide contexts to child elements
  • observe() - Watch observable state and trigger reactive updates
  • localize - Built-in localization controller for translations
  • hostController() - Host and manage controllers within the element
  • consumeContext() - 订阅并消费父元素的上下文
  • provideContext() - 向子元素提供上下文
  • observe() - 监听可观察状态并触发响应式更新
  • localize - 内置本地化控制器，用于处理翻译
  • hostController() - 在元素内部托管和管理控制器

UmbLitElement vs UmbElementMixin

UmbLitElement 与 UmbElementMixin对比

FeatureUmbLitElementUmbElementMixin
BasePre-configured with LitApply to any base class
Usage
extends UmbLitElement
extends UmbElementMixin(BaseClass)
Best forLit-based componentsCustom base classes or UI library components
FeaturesSame featuresSame features
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
特性UmbLitElementUmbElementMixin
基类预配置Lit可应用于任意基类
使用方式
extends UmbLitElement
extends UmbElementMixin(BaseClass)
适用场景基于Lit的组件自定义基类或UI库组件
功能功能一致功能一致
就是这样！请始终获取最新文档，保持示例简洁，生成完整可运行的代码。