Back to Details

umbraco-entity-actions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Entity Actions

Umbraco 实体操作

What is it?

什么是实体操作？

Entity Actions perform an action on a specific item in Umbraco. They provide a generic extension point for secondary functionality associated with entity types like documents, media, or custom entities. These actions appear in context menus throughout the backoffice and can be controlled by user permissions.
实体操作用于对Umbraco中的特定项执行操作，为文档、媒体或自定义实体等实体类型关联的二次功能提供通用扩展点。这些操作会出现在后台各处的上下文菜单中，并且可通过用户权限进行控制。

Documentation

文档

Always fetch the latest docs before implementing:
在开始实现前，请务必获取最新的官方文档：

Reference Examples

参考示例

The Umbraco source includes working examples:
Permission Manipulation: 
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/manipulate-document-property-value-permissions/
This example demonstrates entity actions that manipulate document property permissions.
User Permissions: 
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/user-permission/
This example shows entity actions integrated with user permission controls.
Umbraco源码中包含可用的示例：
权限操作：
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/manipulate-document-property-value-permissions/
该示例展示了如何实现用于操作文档属性权限的实体操作。
用户权限：
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/user-permission/
该示例展示了与用户权限控制集成的实体操作。

Related Foundation Skills

相关基础技能

  • Repository Pattern: When implementing actions that need data operations
    • Reference skill: 
      umbraco-repository-pattern
  • Context API: When accessing workspace or other contexts from actions
    • Reference skill: 
      umbraco-context-api
  • Conditions: When controlling action visibility based on permissions or state
    • Reference skill: 
      umbraco-conditions
  • 仓储模式：当实现需要进行数据操作的功能时
    • 参考技能：
      umbraco-repository-pattern
  • Context API：当需要从操作中访问工作区或其他上下文时
    • 参考技能：
      umbraco-context-api
  • 条件判断：当需要根据权限或状态控制操作可见性时
    • 参考技能：
      umbraco-conditions

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - What entity type? What action to perform? Permissions needed?
  3. Generate files - Create manifest + action class based on latest docs
  4. Explain - Show what was created and how to test
  1. 获取文档 - 使用WebFetch访问上述URL获取最新文档
  2. 明确问题 - 确定实体类型？要执行什么操作？需要哪些权限？
  3. 生成文件 - 根据最新文档创建清单文件（manifest）和操作类
  4. 解释说明 - 展示创建的内容以及测试方法

Minimal Examples

最简示例

Manifest (manifests.ts)

清单文件 (manifests.ts)

typescript
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];
typescript
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];

Action Implementation (my-entity-action.ts)

操作实现 (my-entity-action.ts)

typescript
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}`);
  }
}
typescript
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 包含实体的唯一标识符
    console.log('Executing action on:', this.unique);

    // 在此处执行你的操作
    alert(`Action executed on ${this.unique}`);
  }
}

Action with Repository

带仓储的操作

typescript
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);
  }
}
typescript
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() {
    // 通过 this.repository 访问仓储
    await this.repository?.myCustomMethod(this.unique);
  }
}

Link-based Action (using getHref)

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

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

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

  async execute() {
    // 使用getHref时无需实现此方法
  }
}

Common Entity Types

常见实体类型

  • document
    - Content nodes
  • media
    - Media items
  • member
    - Members
  • data-type
    - Data types
  • document-type
    - Document types
  • media-type
    - Media types
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
  • document
    - 内容节点
  • media
    - 媒体项
  • member
    - 会员
  • data-type
    - 数据类型
  • document-type
    - 文档类型
  • media-type
    - 媒体类型
就是这样！请始终获取最新文档，保持示例简洁，生成完整可运行的代码。