umbraco-extension-registry

Umbraco 扩展注册表

这是什么？

扩展注册表是管理所有 Umbraco 后台 UI 元素的核心系统——后台中几乎所有 UI 都是由扩展注册表管理的扩展。开发者可以使用 umbExtensionsRegistry 在运行时动态添加、移除或修改扩展。开发者拥有与 Umbraco HQ 相同的操作能力，也就是说，你几乎可以更改 Umbraco 默认提供的所有内容。

文档

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

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry
• 注册扩展：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry/register-extensions
• 替换/排除：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry/replace-exclude-or-unregister
• 扩展清单：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry/extension-manifest
• 基础组件：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提出问题 - 是要注册、排除还是替换？在运行时还是静态操作？是否需要条件？
3. 生成代码 - 根据最新文档实现注册表操作
4. 说明 - 展示创建的内容以及扩展的管理方式

最简示例

注册扩展（运行时）

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

const manifest = {
  type: 'dashboard',
  alias: 'My.Dashboard',
  name: 'My Dashboard',
  element: () => import('./dashboard.element.js'),
  meta: {
    label: 'My Dashboard',
    pathname: 'my-dashboard'
  }
};

umbExtensionsRegistry.register(manifest);

排除扩展

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

// Permanently hide an extension
umbExtensionsRegistry.exclude('Umb.WorkspaceAction.Document.SaveAndPreview');

取消注册扩展

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

// Remove extension from registry (can be re-registered)
umbExtensionsRegistry.unregister('My.WorkspaceAction.AutoFillWithUnicorns');

替换扩展（覆盖）

const manifest = {
  type: 'workspaceAction',
  alias: 'My.WorkspaceAction.ExternalPreview',
  name: 'My Custom Preview',
  overwrites: 'Umb.WorkspaceAction.Document.SaveAndPreview',
  element: () => import('./custom-preview.element.js'),
  // ... rest of manifest
};

umbExtensionsRegistry.register(manifest);

替换多个扩展

const manifest = {
  type: 'workspaceAction',
  alias: 'My.CustomSave',
  name: 'My Custom Save',
  overwrites: [
    'Umb.WorkspaceAction.Document.SaveAndPreview',
    'Umb.WorkspaceAction.Document.Save'
  ],
  // ... rest of manifest
};

umbExtensionsRegistry.register(manifest);

入口点注册

// entrypoint.ts
import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

export const onInit = (host: UmbEntryPointOnInitArgs) => {
  // Exclude default dashboard
  umbExtensionsRegistry.exclude('Umb.Dashboard.UmbracoNews');

  // Register custom dashboard
  umbExtensionsRegistry.register({
    type: 'dashboard',
    alias: 'My.CustomDashboard',
    name: 'Custom Dashboard',
    element: () => import('./custom-dashboard.element.js'),
    meta: {
      label: 'Welcome',
      pathname: 'welcome'
    },
    conditions: [
      {
        alias: 'Umb.Condition.SectionAlias',
        match: 'Umb.Section.Content'
      }
    ]
  });
};

根据服务器数据动态注册

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

async function registerDynamicDashboards() {
  // Fetch configuration from server
  const response = await fetch('/api/dashboard-config');
  const dashboards = await response.json();

  // Register each dashboard dynamically
  dashboards.forEach(config => {
    umbExtensionsRegistry.register({
      type: 'dashboard',
      alias: config.alias,
      name: config.name,
      element: () => import(config.elementPath),
      meta: {
        label: config.label,
        pathname: config.pathname
      }
    });
  });
}

条件注册

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

// Register extension only if condition is met
if (userIsAdmin) {
  umbExtensionsRegistry.register({
    type: 'dashboard',
    alias: 'My.AdminDashboard',
    name: 'Admin Dashboard',
    element: () => import('./admin-dashboard.element.js'),
    meta: {
      label: 'Admin',
      pathname: 'admin'
    }
  });
}

批量操作

import { umbExtensionsRegistry } from '@umbraco-cms/backoffice/extension-registry';

// Exclude multiple extensions
const extensionsToHide = [
  'Umb.Dashboard.UmbracoNews',
  'Umb.Dashboard.RedirectManagement',
];

extensionsToHide.forEach(alias => {
  umbExtensionsRegistry.exclude(alias);
});

// Register multiple extensions
const myExtensions = [
  { type: 'dashboard', alias: 'My.Dashboard1', /* ... */ },
  { type: 'dashboard', alias: 'My.Dashboard2', /* ... */ },
];

myExtensions.forEach(manifest => {
  umbExtensionsRegistry.register(manifest);
});

查看已注册的扩展

在后台中导航至：设置 > 扩展洞察，即可查看所有已注册的扩展。

核心概念

umbExtensionsRegistry：用于管理扩展的中央注册表

register()：在运行时添加新扩展

exclude()：永久隐藏扩展（永不显示）

unregister()：从注册表中移除扩展（之后可以重新注册）

overwrites：使用自定义实现替换现有扩展

运行时与静态：

• 静态：大多数扩展使用 umbraco-package.json
• 运行时：使用 umbExtensionsRegistry 进行动态/条件注册

入口点：在启动期间执行注册表操作的常用位置

扩展洞察：在“设置 > 扩展洞察”中查看所有已注册的扩展

使用场景：

• 隐藏 Umbraco 默认功能
• 根据服务器数据注册扩展
• 使用自定义逻辑替换内置操作
• 有条件地启用功能
• 动态注册仪表板

来源

• 扩展注册表 | Umbraco CMS
• 注册扩展 | Umbraco CMS
• 替换、排除或取消注册 | Umbraco CMS

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