Umbraco 示例生成器：快速创建和测试 Umbraco 后台扩展

umbraco-example-generator by umbraco/umbraco-cms-backoffice-skills

76 周安装量

17 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/umbraco/umbraco-cms-backoffice-skills --skill umbraco-example-generator

开发内容管理系统

🇨🇳中文介绍

Umbraco 示例生成器

为 Umbraco 后台生成完整、可测试的扩展示例，并使用 Umbraco 源代码的开发基础设施运行它们。

使用场景

创建演示扩展
构建可测试的扩展示例
使用热重载进行快速开发
无需 .NET 后端测试扩展

快速开始

1. 克隆 Umbraco 源代码（一次性设置）

git clone https://github.com/umbraco/Umbraco-CMS
cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm install

2. 创建你的扩展文件夹

my-extension/
├── index.ts           # 必需 - 导出清单
└── my-element.ts      # 你的元素

3. 创建 index.ts（导出清单）

import './my-element.js';

export const manifests = [
  {
    type: 'dashboard',
    alias: 'My.Dashboard',
    name: 'My Dashboard',
    element: 'my-element',
    meta: { label: 'My Dashboard', pathname: 'my-dashboard' },
    conditions: [{ alias: 'Umb.Condition.SectionAlias', match: 'Umb.Section.Content' }]
  }
];

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

4. 创建你的元素

// my-element.ts
import { LitElement, html, customElement } from '@umbraco-cms/backoffice/external/lit';

@customElement('my-element')
export class MyElement extends LitElement {
  render() {
    return html`<uui-box headline="Hello">It works!</uui-box>`;
  }
}

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
VITE_EXTERNAL_EXTENSION=/full/path/to/my-extension npm run dev:external

打开 http://localhost:5173 - 你的扩展将出现在内容部分。

Umbraco 源代码 (Umbraco-CMS/src/Umbraco.Web.UI.Client) 提供了两种加载扩展的方式：

1. 内部示例 (`npm run example`)

放置在 Umbraco 源代码 examples/ 文件夹内的示例。

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm run example
# 从示例列表中选择

工作原理：设置 VITE_EXAMPLE_PATH 并导入 ./examples/{name}/index.ts

2. 外部扩展 (`npm run dev:external`)

来自文件系统任意位置的扩展 - 非常适合开发包。

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
VITE_EXTERNAL_EXTENSION=/path/to/your/extension npm run dev:external

设置 VITE_UMBRACO_USE_MSW=on（模拟 API）
创建指向你的扩展路径的 @external-extension 别名
导入 @external-extension/index.ts 并使用 umbExtensionsRegistry 注册导出
从主项目解析 @umbraco-cms/backoffice/* 导入（避免重复的元素注册）

扩展加载 (index.ts)

// 来自 Umbraco-CMS/src/Umbraco.Web.UI.Client/index.ts
if (import.meta.env.VITE_EXTERNAL_EXTENSION) {
  const js = await import('@external-extension/index.ts');
  if (js) {
    Object.keys(js).forEach((key) => {
      const value = js[key];
      if (Array.isArray(value)) {
        umbExtensionsRegistry.registerMany(value);
      } else if (typeof value === 'object') {
        umbExtensionsRegistry.register(value);
      }
    });
  }
}

关键点：你的 index.ts 必须导出清单（数组或对象），这些清单会被自动注册。

克隆并设置 Umbraco 源代码：

git clone https://github.com/umbraco/Umbraco-CMS
cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm install

你的扩展需要以下最小结构：

my-extension/
├── index.ts              # 导出清单数组（必需）
├── my-element.ts         # 你的元素
├── my-context.ts         # 上下文（如果需要）
├── package.json          # 可选 - 用于 IDE 支持和测试
├── tsconfig.json         # 可选 - 用于 IDE 支持
└── README.md             # 文档

你的 index.ts 必须导出将被注册的清单：

import './my-dashboard.element.js';

export const manifests = [
  {
    type: 'dashboard',
    alias: 'My.Dashboard',
    name: 'My Dashboard',
    element: 'my-dashboard',
    weight: 100,
    meta: {
      label: 'My Dashboard',
      pathname: 'my-dashboard'
    },
    conditions: [
      {
        alias: 'Umb.Condition.SectionAlias',
        match: 'Umb.Section.Content'
      }
    ]
  }
];

可选：package.json（用于 IDE 支持）

{
  "name": "my-extension",
  "type": "module",
  "devDependencies": {
    "@umbraco-cms/backoffice": "^17.0.0",
    "typescript": "~5.8.0"
  }
}

重要：@umbraco-cms/backoffice 依赖项仅用于 IDE TypeScript 支持。在运行时，导入是从主 Umbraco 项目解析的。

cd /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
VITE_EXTERNAL_EXTENSION=/absolute/path/to/my-extension npm run dev:external

在浏览器中打开

导航到 http://localhost:5173 - 你的扩展会自动加载。

对你的扩展文件的更改会触发热重载 - 无需重启。

// my-dashboard.element.ts
import { LitElement, html, css, customElement } from '@umbraco-cms/backoffice/external/lit';

@customElement('my-dashboard')
export class MyDashboardElement extends LitElement {
  static override styles = css`
    :host {
      display: block;
      padding: var(--uui-size-layout-1);
    }
  `;

  override render() {
    return html`
      <uui-box headline="My Extension">
        <p>Running in the mocked backoffice!</p>
      </uui-box>
    `;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'my-dashboard': MyDashboardElement;
  }
}

带上下文的元素

import { html, customElement, state } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { EXAMPLE_MY_CONTEXT } from './my-context.js';

@customElement('example-my-feature-view')
export class ExampleMyFeatureViewElement extends UmbLitElement {
  @state()
  private _value?: string;

  constructor() {
    super();
    this.consumeContext(EXAMPLE_MY_CONTEXT, (context) => {
      this.observe(context.value, (value) => {
        this._value = value;
      });
    });
  }

  override render() {
    return html`
      <uui-box headline="My Feature Example">
        <p>Current value: ${this._value ?? 'Loading...'}</p>
      </uui-box>
    `;
  }
}

export default ExampleMyFeatureViewElement;

declare global {
  interface HTMLElementTagNameMap {
    'example-my-feature-view': ExampleMyFeatureViewElement;
  }
}

import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
import { UmbContextBase } from '@umbraco-cms/backoffice/class-api';
import { UmbStringState } from '@umbraco-cms/backoffice/observable-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class ExampleMyContext extends UmbContextBase {
  #value = new UmbStringState('initial');
  readonly value = this.#value.asObservable();

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

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

  getValue() {
    return this.#value.getValue();
  }

  public override destroy(): void {
    this.#value.destroy();
    super.destroy();
  }
}

export const EXAMPLE_MY_CONTEXT = new UmbContextToken<ExampleMyContext>(
  'ExampleMyContext'
);

export { ExampleMyContext as api };

使用 @open-wc/testing 添加单元测试。完整设置请参见 umbraco-unit-testing 技能。

npm install --save-dev @open-wc/testing @web/test-runner @web/test-runner-playwright

端到端测试 (Playwright)

添加针对模拟后台运行的端到端测试。模式请参见 umbraco-mocked-backoffice 技能。

npm install --save-dev @playwright/test
npx playwright install chromium

位置：./examples/workspace-feature-toggle/

一个完整的独立示例，演示了：

使用 UmbArrayState 的工作区上下文
使用上下文的工作区视图
执行上下文方法的工作区操作
显示摘要的工作区页脚应用
38 个单元测试 + 13 个端到端测试

cd examples/workspace-feature-toggle npm install npm test # 单元测试 npm run test:e2e # 端到端测试（需要运行模拟后台）

官方 Umbraco 示例

位置：Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/

27 个官方示例，涵盖所有扩展类型。运行任何示例：

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm run example
# 从列表中选择

项目	约定	示例
目录	描述功能的 kebab-case	`workspace-context-counter`
别名前缀	`example.`	`example.workspaceView.counter`
元素前缀	`example-`	`example-counter-view`
上下文令牌	`EXAMPLE_` + SCREAMING_CASE	`EXAMPLE_COUNTER_CONTEXT`

检查 index.ts 是否导出了 manifests 数组
验证 VITE_EXTERNAL_EXTENSION 中的路径是否为绝对路径
检查浏览器控制台是否有 📦 Loading external extension from: 消息
确保条件与你正在查看的部分匹配

导入应使用 @umbraco-cms/backoffice/*。Vite 插件会从主项目解析这些导入。

"CustomElementRegistry" 已定义

你的扩展的 node_modules 正在被使用，而不是主项目的。external-extension-resolver 插件应该处理这个问题，但请确保：

你正在使用 npm run dev:external
导入使用 @umbraco-cms/backoffice/* 而不是指向 node_modules 的相对路径

更改未触发热重载

确保文件位于 VITE_EXTERNAL_EXTENSION 指定的路径内。只有该目录树中的文件会被监视。

🇺🇸English

Umbraco Example Generator

Generate complete, testable example extensions for the Umbraco backoffice and run them using the Umbraco source's dev infrastructure.

When to Use

Creating demonstration extensions
Building testable extension examples
Rapid development with hot reload
Testing extensions without .NET backend

Related Skills

umbraco-unit-testing - Add unit tests to examples
umbraco-mocked-backoffice - E2E testing patterns
umbraco-backoffice - Extension type blueprints

Quick Start

1. Clone Umbraco source (one-time setup)

git clone https://github.com/umbraco/Umbraco-CMS
cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm install

2. Create your extension folder

my-extension/
├── index.ts           # REQUIRED - exports manifests
└── my-element.ts      # Your element(s)

3. Create index.ts (exports manifests)

import './my-element.js';

export const manifests = [
  {
    type: 'dashboard',
    alias: 'My.Dashboard',
    name: 'My Dashboard',
    element: 'my-element',
    meta: { label: 'My Dashboard', pathname: 'my-dashboard' },
    conditions: [{ alias: 'Umb.Condition.SectionAlias', match: 'Umb.Section.Content' }]
  }
];

4. Create your element

// my-element.ts
import { LitElement, html, customElement } from '@umbraco-cms/backoffice/external/lit';

@customElement('my-element')
export class MyElement extends LitElement {
  render() {
    return html`<uui-box headline="Hello">It works!</uui-box>`;
  }
}

5. Run it

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
VITE_EXTERNAL_EXTENSION=/full/path/to/my-extension npm run dev:external

Open http://localhost:5173 - your extension appears in the Content section.

How It Works

The Umbraco source (Umbraco-CMS/src/Umbraco.Web.UI.Client) provides two ways to load extensions:

1. Internal Examples (`npm run example`)

Examples placed in the examples/ folder inside the Umbraco source.

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm run example
# Select from list of examples

How it works : Sets VITE_EXAMPLE_PATH and imports ./examples/{name}/index.ts

2. External Extensions (`npm run dev:external`)

Extensions from any location on your filesystem - perfect for developing packages.

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
VITE_EXTERNAL_EXTENSION=/path/to/your/extension npm run dev:external

How it works :

Sets VITE_UMBRACO_USE_MSW=on (mocked APIs)
Creates @external-extension alias pointing to your extension path
Imports @external-extension/index.ts and registers exports with umbExtensionsRegistry
Resolves @umbraco-cms/backoffice/* imports from the main project (avoids duplicate element registrations)

Extension Loading (index.ts)

// From Umbraco-CMS/src/Umbraco.Web.UI.Client/index.ts
if (import.meta.env.VITE_EXTERNAL_EXTENSION) {
  const js = await import('@external-extension/index.ts');
  if (js) {
    Object.keys(js).forEach((key) => {
      const value = js[key];
      if (Array.isArray(value)) {
        umbExtensionsRegistry.registerMany(value);
      } else if (typeof value === 'object') {
        umbExtensionsRegistry.register(value);
      }
    });
  }
}

Key point : Your index.ts must export manifests (arrays or objects) that get registered automatically.

Setup

Prerequisites

Clone and set up the Umbraco source:

git clone https://github.com/umbraco/Umbraco-CMS
cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm install

Extension Structure

Your extension needs this minimal structure:

my-extension/
├── index.ts              # Exports manifests array (REQUIRED)
├── my-element.ts         # Your element(s)
├── my-context.ts         # Context (if needed)
├── package.json          # Optional - for IDE support and tests
├── tsconfig.json         # Optional - for IDE support
└── README.md             # Documentation

Required: index.ts

Your index.ts must export manifests that will be registered:

import './my-dashboard.element.js';

export const manifests = [
  {
    type: 'dashboard',
    alias: 'My.Dashboard',
    name: 'My Dashboard',
    element: 'my-dashboard',
    weight: 100,
    meta: {
      label: 'My Dashboard',
      pathname: 'my-dashboard'
    },
    conditions: [
      {
        alias: 'Umb.Condition.SectionAlias',
        match: 'Umb.Section.Content'
      }
    ]
  }
];

Optional: package.json (for IDE support)

{
  "name": "my-extension",
  "type": "module",
  "devDependencies": {
    "@umbraco-cms/backoffice": "^17.0.0",
    "typescript": "~5.8.0"
  }
}

Important : The @umbraco-cms/backoffice dependency is only for IDE TypeScript support. At runtime, imports are resolved from the main Umbraco project.

Running Your Extension

Start the mocked backoffice

cd /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client
VITE_EXTERNAL_EXTENSION=/absolute/path/to/my-extension npm run dev:external

Open in browser

Navigate to http://localhost:5173 - your extension is loaded automatically.

Hot reload

Changes to your extension files trigger hot reload - no restart needed.

Patterns

Basic Element

// my-dashboard.element.ts
import { LitElement, html, css, customElement } from '@umbraco-cms/backoffice/external/lit';

@customElement('my-dashboard')
export class MyDashboardElement extends LitElement {
  static override styles = css`
    :host {
      display: block;
      padding: var(--uui-size-layout-1);
    }
  `;

  override render() {
    return html`
      <uui-box headline="My Extension">
        <p>Running in the mocked backoffice!</p>
      </uui-box>
    `;
  }
}

declare global {
  interface HTMLElementTagNameMap {
    'my-dashboard': MyDashboardElement;
  }
}

Element with Context

import { html, customElement, state } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { EXAMPLE_MY_CONTEXT } from './my-context.js';

@customElement('example-my-feature-view')
export class ExampleMyFeatureViewElement extends UmbLitElement {
  @state()
  private _value?: string;

  constructor() {
    super();
    this.consumeContext(EXAMPLE_MY_CONTEXT, (context) => {
      this.observe(context.value, (value) => {
        this._value = value;
      });
    });
  }

  override render() {
    return html`
      <uui-box headline="My Feature Example">
        <p>Current value: ${this._value ?? 'Loading...'}</p>
      </uui-box>
    `;
  }
}

export default ExampleMyFeatureViewElement;

declare global {
  interface HTMLElementTagNameMap {
    'example-my-feature-view': ExampleMyFeatureViewElement;
  }
}

Context

import { UmbContextToken } from '@umbraco-cms/backoffice/context-api';
import { UmbContextBase } from '@umbraco-cms/backoffice/class-api';
import { UmbStringState } from '@umbraco-cms/backoffice/observable-api';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class ExampleMyContext extends UmbContextBase {
  #value = new UmbStringState('initial');
  readonly value = this.#value.asObservable();

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

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

  getValue() {
    return this.#value.getValue();
  }

  public override destroy(): void {
    this.#value.destroy();
    super.destroy();
  }
}

export const EXAMPLE_MY_CONTEXT = new UmbContextToken<ExampleMyContext>(
  'ExampleMyContext'
);

export { ExampleMyContext as api };

Adding Tests

Unit Tests

Add unit tests using @open-wc/testing. See umbraco-unit-testing skill for full setup.

npm install --save-dev @open-wc/testing @web/test-runner @web/test-runner-playwright

E2E Tests (Playwright)

Add E2E tests that run against the mocked backoffice. See umbraco-mocked-backoffice skill for patterns.

npm install --save-dev @playwright/test
npx playwright install chromium

Examples

Reference Example

Location : ./examples/workspace-feature-toggle/

A complete standalone example demonstrating:

Workspace context with UmbArrayState
Workspace view consuming context
Workspace action executing context methods
Workspace footer app showing summary
38 unit tests + 13 E2E tests

cd examples/workspace-feature-toggle npm install npm test # Unit tests npm run test:e2e # E2E tests (requires mocked backoffice running)

Official Umbraco Examples

Location : Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/

27 official examples covering all extension types. Run any example:

cd Umbraco-CMS/src/Umbraco.Web.UI.Client
npm run example
# Select from list

Naming Conventions

Item	Convention	Example
Directory	kebab-case describing feature	`workspace-context-counter`
Alias prefix	`example.`	`example.workspaceView.counter`
Element prefix	`example-`	`example-counter-view`
Context token	`EXAMPLE_` + SCREAMING_CASE

Troubleshooting

Extension not appearing

Check index.ts exports a manifests array
Verify the path in VITE_EXTERNAL_EXTENSION is absolute
Check browser console for 📦 Loading external extension from: message
Ensure condition matches the section you're viewing

Import errors

Imports should use @umbraco-cms/backoffice/*. The Vite plugin resolves these from the main project.

"CustomElementRegistry" already defined

Your extension's node_modules is being used instead of the main project's. The external-extension-resolver plugin should handle this, but ensure:

You're using npm run dev:external
Imports use @umbraco-cms/backoffice/* not relative paths to node_modules

Changes not hot reloading

Ensure the file is within the path specified by VITE_EXTERNAL_EXTENSION. Only files in that directory tree are watched.

Weekly Installs

Repository

umbraco/umbraco…e-skills

GitHub Stars

First Seen

Feb 4, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

github-copilot55

codex25

opencode24

cursor22

gemini-cli21

amp21

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

122,000 周安装