umbraco-extension-registry

Umbraco Extension Registry

これは何ですか？

Extension Registry は、すべての Umbraco バックオフィス UI 要素を管理する中核システムです。バックオフィス内のほぼすべての UI は、Extension Registry によって管理される拡張機能です。このレジストリにより、開発者は 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);
});

登録された拡張機能の表示

バックオフィスで Settings > Extensions Insights に移動すると、登録されているすべての拡張機能を確認できます。

主要な概念

umbExtensionsRegistry: 拡張機能を管理するための中央レジストリ

register(): 実行時に新しい拡張機能を追加します

exclude(): 拡張機能を完全に非表示にします（表示されることはありません）

unregister(): レジストリから拡張機能を削除します（再登録が可能です）

overwrites: 既存の拡張機能をカスタム実装で置き換えます

実行時 vs 静的:

• 静的: ほとんどの拡張機能には umbraco-package.json を使用します
• 実行時: 動的または条件付きの登録には umbExtensionsRegistry を使用します

エントリポイント: 起動時にレジストリ操作を実行するための一般的な場所

Extension Insights: Settings > Extensions Insights で登録されているすべての拡張機能を表示します

ユースケース:

• デフォルトの Umbraco 機能を非表示にする
• サーバーデータに基づいて拡張機能を登録する
• 組み込みのアクションをカスタムロジックで置き換える
• 機能を条件付きで有効にする
• 動的なダッシュボード登録

出典

• Extension Registry | Umbraco CMS
• Register an Extension | Umbraco CMS
• Replace, Exclude or Unregister | Umbraco CMS

以上です！ 常に最新のドキュメントを取得し、例は最小限に保ち、完全に動作するコードを生成してください。