umbraco-context-api

Umbraco Context API

它是什么？

Context API 是 Umbraco 的通信系统，可让扩展通过组件层级共享数据和功能，而无需紧密耦合。它采用提供者-使用者模式，由父元素提供上下文，后代组件可以访问这些上下文。上下文沿 DOM 树向下传递，并使用令牌以类型安全的方式访问通知、工作区和用户信息等服务。

文档

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

• 主要文档：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/context-api/consume-a-context
• 提供上下文：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation/context-api/provide-a-context
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 需要使用还是提供上下文？是哪种上下文？一次性获取还是订阅？
3. 生成代码 - 根据最新文档实现上下文的使用或提供
4. 说明 - 展示创建的内容以及上下文的传递方式

最简示例

使用上下文（订阅模式）

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();

    // Subscribe to context - callback runs when context is available
    this.consumeContext(UMB_NOTIFICATION_CONTEXT, (context) => {
      this.#notificationContext = context;
    });
  }

  showMessage() {
    this.#notificationContext?.peek('positive', {
      data: { message: 'Hello from Context API!' }
    });
  }
}

使用上下文（一次性模式）

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

export class MyService extends UmbControllerBase {
  async showNotification(text: string) {
    // Get context once, use it, then release
    const context = await this.getContext(UMB_NOTIFICATION_CONTEXT);
    context?.peek('positive', { data: { message: text } });
  }
}

提供上下文

import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';

// Define a context token
export const MY_CUSTOM_CONTEXT = new UmbContextToken<MyCustomContext>(
  'MyCustomContext'
);

export class MyCustomContext {
  getData() {
    return { message: 'Hello from custom context!' };
  }
}

export class MyProviderElement extends UmbLitElement {
  constructor() {
    super();

    // Provide context to all descendants
    this.provideContext(MY_CUSTOM_CONTEXT, new MyCustomContext());
  }
}

常见内置上下文

// Notifications
import { UMB_NOTIFICATION_CONTEXT } from '@umbraco-cms/backoffice/notification';

// Current User
import { UMB_CURRENT_USER_CONTEXT } from '@umbraco-cms/backoffice/current-user';

// Modal Manager
import { UMB_MODAL_MANAGER_CONTEXT } from '@umbraco-cms/backoffice/modal';

// Workspace (varies by type)
import { UMB_DOCUMENT_WORKSPACE_CONTEXT } from '@umbraco-cms/backoffice/document';

// Block Entry (for block editors)
import { UMB_BLOCK_ENTRY_CONTEXT } from '@umbraco-cms/backoffice/block';

// Property Dataset (for property editors)
import { UMB_PROPERTY_DATASET_CONTEXT } from '@umbraco-cms/backoffice/property';

核心概念

上下文令牌：用于标识上下文的类型安全标识符

const MY_TOKEN = new UmbContextToken<MyType>('UniqueName');

提供者：通过 provideContext() 向后代提供上下文的元素

使用者：通过 consumeContext() 或 getContext() 访问上下文的元素

订阅与一次性获取：

• 需要在初始化期间获取上下文时，使用 consumeContext()
• 对于由用户交互触发的操作，使用 getContext()

层级关系：上下文沿 DOM 树从提供者向下传递给使用者

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