Back to Details

umbraco-global-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Global Context

Umbraco全局上下文

What is it?

什么是全局上下文？

Global contexts create a shared, type-safe layer of data and functions accessible throughout the backoffice. Unlike scoped contexts (like Workspace Contexts), global contexts persist for the entire backoffice session. Use them for sharing state between extensions, managing centralized services, or coordinating communication. Note: Prefer more specific context types when possible - Umbraco uses global contexts sparingly.
全局上下文会创建一个共享的、类型安全的数据和函数层，可在整个后台中访问。与作用域上下文（如工作区上下文）不同，全局上下文在整个后台会话期间持续存在。可使用它们在扩展之间共享状态、管理集中式服务或协调通信。注意：尽可能优先使用更具体的上下文类型——Umbraco很少使用全局上下文。

Documentation

文档

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

Related Foundation Skills

相关基础技能

  • Context API: For understanding context consumption patterns
    • Reference skill: 
      umbraco-context-api
  • State Management: For reactive state within contexts
    • Reference skill: 
      umbraco-state-management
  • Context API：用于理解上下文使用模式
    • 参考技能：
      umbraco-context-api
  • 状态管理：用于上下文内的响应式状态
    • 参考技能：
      umbraco-state-management

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - What state to share? What services needed? Could a workspace context work instead?
  3. Generate files - Create context token + implementation + manifest based on latest docs
  4. Explain - Show what was created and how to consume the context
  1. 获取文档 - 使用WebFetch访问上述URL
  2. 提出问题 - 要共享什么状态？需要哪些服务？是否可以改用工作区上下文？
  3. 生成文件 - 根据最新文档创建上下文令牌 + 实现代码 + 清单文件
  4. 说明 - 展示创建的内容以及如何使用该上下文

Minimal Examples

最简示例

Context Token (my-global-context.token.ts)

上下文令牌（my-global-context.token.ts）

typescript
import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
import type { MyGlobalContext } from './my-global-context.js';

export const MY_GLOBAL_CONTEXT = new UmbContextToken<MyGlobalContext>(
  'My.GlobalContext'
);
typescript
import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
import type { MyGlobalContext } from './my-global-context.js';

export const MY_GLOBAL_CONTEXT = new UmbContextToken<MyGlobalContext>(
  'My.GlobalContext'
);

Context Implementation (my-global-context.ts)

上下文实现（my-global-context.ts）

typescript
import { UmbContextBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import { MY_GLOBAL_CONTEXT } from './my-global-context.token.js';

export class MyGlobalContext extends UmbContextBase {
  #currentValue = '';

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

  getValue(): string {
    return this.#currentValue;
  }

  setValue(value: string): void {
    this.#currentValue = value;
  }
}
typescript
import { UmbContextBase } from '@umbraco-cms/backoffice/class-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import { MY_GLOBAL_CONTEXT } from './my-global-context.token.js';

export class MyGlobalContext extends UmbContextBase {
  #currentValue = '';

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

  getValue(): string {
    return this.#currentValue;
  }

  setValue(value: string): void {
    this.#currentValue = value;
  }
}

Manifest (umbraco-package.json)

清单文件（umbraco-package.json）

json
{
  "name": "My Global Context Package",
  "extensions": [
    {
      "type": "globalContext",
      "alias": "My.GlobalContext",
      "name": "My Global Context",
      "js": "/App_Plugins/MyPackage/my-global-context.js"
    }
  ]
}
json
{
  "name": "My Global Context Package",
  "extensions": [
    {
      "type": "globalContext",
      "alias": "My.GlobalContext",
      "name": "My Global Context",
      "js": "/App_Plugins/MyPackage/my-global-context.js"
    }
  ]
}

Consuming the Context

使用上下文

typescript
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { MY_GLOBAL_CONTEXT } from './my-global-context.token.js';

class MyElement extends UmbElementMixin(LitElement) {
  #myContext?: MyGlobalContext;

  constructor() {
    super();
    this.consumeContext(MY_GLOBAL_CONTEXT, (instance) => {
      this.#myContext = instance;
    });
  }
}
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
typescript
import { UmbElementMixin } from '@umbraco-cms/backoffice/element-api';
import { MY_GLOBAL_CONTEXT } from './my-global-context.token.js';

class MyElement extends UmbElementMixin(LitElement) {
  #myContext?: MyGlobalContext;

  constructor() {
    super();
    this.consumeContext(MY_GLOBAL_CONTEXT, (instance) => {
      this.#myContext = instance;
    });
  }
}
就是这样！务必获取最新文档，保持示例简洁，生成完整可运行的代码。