umbraco-entity-actions

Umbraco 实体操作

这是什么？

实体操作会对 Umbraco 中的特定项目执行操作。它们为与文档、媒体或自定义实体等实体类型相关的辅助功能提供通用扩展点。这些操作会显示在后台的上下文菜单中，并可由用户权限控制。

文档

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

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/entity-actions
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

参考示例

Umbraco 源代码中包含可运行的示例：

权限操作：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/manipulate-document-property-value-permissions/

此示例演示如何通过实体操作管理文档属性权限。

用户权限：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/user-permission/

此示例展示了与用户权限控制集成的实体操作。

相关基础技能

• 仓储模式：实现需要执行数据操作的操作时

  • 参考技能：umbraco-repository-pattern

• 上下文 API：从操作中访问工作区或其他上下文时

  • 参考技能：umbraco-context-api

• 条件：根据权限或状态控制操作的可见性时

  • 参考技能：umbraco-conditions

工作流

1. 获取文档 - 对上方的 URL 使用 WebFetch
2. 提出问题 - 实体类型是什么？要执行什么操作？需要哪些权限？
3. 生成文件 - 根据最新文档创建清单 + 操作类
4. 说明 - 展示创建的内容以及如何测试

最简示例

清单（manifests.ts）

import type { ManifestEntityAction } from '@umbraco-cms/backoffice/extension-registry';
import { MyEntityAction } from './my-entity-action.js';

const manifest: ManifestEntityAction = {
  type: 'entityAction',
  alias: 'My.EntityAction',
  name: 'My Entity Action',
  weight: 10,
  api: MyEntityAction,
  forEntityTypes: ['document'],
  meta: {
    icon: 'icon-alarm-clock',
    label: 'My Action',
  },
};

export const manifests = [manifest];

操作实现（my-entity-action.ts）

import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class MyEntityAction extends UmbEntityActionBase<never> {
  constructor(host: UmbControllerHost, args: { unique: string; entityType: string }) {
    super(host, args);
  }

  async execute() {
    // this.unique contains the entity's unique identifier
    console.log('Executing action on:', this.unique);

    // Perform your action here
    alert(`Action executed on ${this.unique}`);
  }
}

使用仓储的操作

import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action';

export class MyEntityAction extends UmbEntityActionBase<MyRepository> {
  constructor(host: UmbControllerHost, args: { unique: string; entityType: string; repositoryAlias: string }) {
    super(host, args);
  }

  async execute() {
    // Access repository via this.repository
    await this.repository?.myCustomMethod(this.unique);
  }
}

基于链接的操作（使用 getHref）

export class MyLinkAction extends UmbEntityActionBase<never> {
  async getHref() {
    return `/some/path/${this.unique}`;
  }

  async execute() {
    // Not needed when using getHref
  }
}

常见实体类型

• document - 内容节点
• media - 媒体项目
• member - 成员
• data-type - 数据类型
• document-type - 文档类型
• media-type - 媒体类型

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