umbraco-conditions

Umbraco 条件

这是什么？

扩展条件允许开发者声明扩展在后台中可用前必须满足的要求。它们充当门控机制，根据区块、工作区、用户权限或内容类型等上下文控制扩展的显示时间和位置。多个条件采用 AND 逻辑——所有条件都必须通过，扩展才会显示。

文档

实现前请始终获取最新文档：

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-conditions
• 扩展类型：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types
• Foundation：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

参考示例

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

位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/entity-content-type-condition/

此示例演示了一个用于检查实体内容类型的自定义条件。请参考它，了解创建自定义条件的模式。

工作流

1. 获取文档 - 对以上 URL 使用 WebFetch
2. 提出问题 - 有哪些因素会限制可见性？区块？工作区？用户？内容类型？
3. 生成代码 - 根据最新文档将条件添加到清单中
4. 说明 - 展示创建的内容，以及扩展会在何时显示

最小示例

区块条件

{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "conditions": [
    {
      "alias": "Umb.Condition.SectionAlias",
      "match": "Umb.Section.Content"
    }
  ]
}

工作区条件

{
  "type": "workspaceView",
  "alias": "My.WorkspaceView",
  "name": "My Workspace View",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceAlias",
      "match": "Umb.Workspace.Document"
    }
  ]
}

多个条件（AND 逻辑）

const manifest = {
  type: 'workspaceAction',
  alias: 'My.WorkspaceAction',
  name: 'My Action',
  conditions: [
    {
      alias: 'Umb.Condition.SectionAlias',
      match: 'Umb.Section.Content'
    },
    {
      alias: 'Umb.Condition.WorkspaceAlias',
      match: 'Umb.Workspace.Document'
    },
    {
      alias: 'Umb.Condition.WorkspaceContentTypeAlias',
      match: 'blogPost'
    }
  ]
};

用户权限条件

{
  "type": "entityAction",
  "alias": "My.DeleteAction",
  "name": "Delete Document",
  "conditions": [
    {
      "alias": "Umb.Condition.UserPermission.Document",
      "match": "Umb.UserPermission.Document.Delete"
    }
  ]
}

区块用户权限

{
  "type": "dashboard",
  "alias": "My.AdminDashboard",
  "name": "Admin Dashboard",
  "conditions": [
    {
      "alias": "Umb.Condition.SectionUserPermission",
      "match": "Umb.Section.Settings"
    }
  ]
}

工作区实体类型

{
  "type": "workspaceView",
  "alias": "My.View",
  "name": "My View",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceEntityType",
      "match": "document"
    }
  ]
}

内容类型条件

{
  "type": "workspaceView",
  "alias": "My.BlogView",
  "name": "Blog Post View",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceContentTypeAlias",
      "match": "blogPost"
    }
  ]
}

工作区包含集合

{
  "type": "workspaceAction",
  "alias": "My.CollectionAction",
  "name": "Collection Action",
  "conditions": [
    {
      "alias": "Umb.Condition.WorkspaceHasCollection",
      "match": true
    }
  ]
}

自定义条件实现

import { UmbConditionBase } from '@umbraco-cms/backoffice/extension-api';
import { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';

export class MyCustomCondition extends UmbConditionBase<MyConditionConfig> {
  constructor(host: UmbControllerHost, args: MyConditionConfig) {
    super(host, args);

    // Observe some context or state
    this.consumeContext(SOME_CONTEXT, (context) => {
      this.observe(context.someObservable, (value) => {
        // Update permitted state based on value
        this.permitted = value === this.args.expectedValue;
      });
    });
  }
}

interface MyConditionConfig {
  expectedValue: string;
}

注册自定义条件

export const manifests = [
  {
    type: 'condition',
    name: 'My Custom Condition',
    alias: 'My.Condition.Custom',
    api: MyCustomCondition,
  },
];

使用自定义条件

{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "conditions": [
    {
      "alias": "My.Condition.Custom",
      "expectedValue": "someValue"
    }
  ]
}

内置条件

区块条件：

• Umb.Condition.SectionAlias - 匹配当前区块
• Umb.Condition.SectionUserPermission - 用户拥有区块访问权限

工作区条件：

• Umb.Condition.WorkspaceAlias - 匹配当前工作区
• Umb.Condition.WorkspaceEntityType - 匹配实体类型（文档、媒体等）
• Umb.Condition.WorkspaceContentTypeAlias - 匹配内容类型别名
• Umb.Condition.WorkspaceHasCollection - 工作区包含集合

用户权限条件：

• Umb.Condition.UserPermission.Document - 文档权限
• Umb.Condition.CurrentUser.IsAdmin - 用户是管理员
• Umb.Condition.CurrentUser.GroupId - 用户属于指定组

核心概念

门控：条件控制扩展是否可用

AND 逻辑：所有条件都必须通过，扩展才会显示

匹配属性：用于比较的值（别名、实体类型等）

允许状态：表示条件是否通过的布尔值

自定义条件：实现 UmbConditionBase 并设置 this.permitted

使用场景：

• 仅在 Content 区块中显示仪表板
• 仅对特定内容类型显示操作
• 限制管理员用户使用功能
• 仅在文档工作区中显示视图
• 根据权限启用操作

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