umbraco-conditions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umbraco Conditions

Umbraco 条件

What is it?

什么是Umbraco条件？

Extension Conditions enable developers to declare requirements that must be met before an extension becomes available in the backoffice. They function as gatekeeping mechanisms controlling when and where extensions appear based on context like section, workspace, user permissions, or content type. Multiple conditions use AND logic—all must pass for the extension to display.

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

Documentation

文档资料

Always fetch the latest docs before implementing:

Main docs: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-conditions
Extension Types: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation

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

主文档：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-conditions
扩展类型：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types
基础内容：https://docs.umbraco.com/umbraco-cms/customizing/foundation

Reference Example

参考示例

The Umbraco source includes a working example:

Location:

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

This example demonstrates a custom condition that checks entity content type. Study this for patterns on creating custom conditions.

Umbraco源码中包含一个可用示例：

位置：

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

该示例演示了一个检查实体内容类型的自定义条件。可以参考其中的模式来创建自定义条件。

Workflow

工作流程

Fetch docs - Use WebFetch on the URLs above
Ask questions - What restricts visibility? Section? Workspace? User? Content type?
Generate code - Add conditions to manifest based on latest docs
Explain - Show what was created and when extension appears

获取文档 - 通过WebFetch访问上述URL获取文档
明确需求 - 需要限制哪些可见性？板块？工作区？用户？内容类型？
生成代码 - 根据最新文档在清单中添加条件
说明解释 - 展示创建的内容以及扩展的显示场景

Minimal Examples

极简示例

Section Condition

板块条件

json

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

json

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

Workspace Condition

工作区条件

json

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

json

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

Multiple Conditions (AND Logic)

多条件（AND逻辑）

typescript

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'
    }
  ]
};

typescript

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'
    }
  ]
};

User Permission Condition

用户权限条件

json

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

json

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

Section User Permission

板块用户权限

json

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

json

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

Workspace Entity Type

工作区实体类型

json

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

json

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

Content Type Condition

内容类型条件

json

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

json

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

Workspace Has Collection

工作区是否包含集合

json

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

json

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

Custom Condition Implementation

自定义条件实现

typescript

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;
}

typescript

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;
}

Register Custom Condition

注册自定义条件

typescript

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

typescript

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

Use Custom Condition

使用自定义条件

json

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

json

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

Built-in Conditions

内置条件

Section Conditions:

```
Umb.Condition.SectionAlias
```
- Match current section
```
Umb.Condition.SectionUserPermission
```
- User has section access

Workspace Conditions:

```
Umb.Condition.WorkspaceAlias
```
- Match current workspace
```
Umb.Condition.WorkspaceEntityType
```
- Match entity type (document, media, etc.)
```
Umb.Condition.WorkspaceContentTypeAlias
```
- Match content type alias
```
Umb.Condition.WorkspaceHasCollection
```
- Workspace has collection

User Permission Conditions:

```
Umb.Condition.UserPermission.Document
```
- Document permissions
```
Umb.Condition.CurrentUser.IsAdmin
```
- User is admin
```
Umb.Condition.CurrentUser.GroupId
```
- User in specific group

板块条件：

```
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
```
- 用户属于指定用户组

Key Concepts

核心概念

Gatekeeping: Conditions control extension availability

AND Logic: All conditions must pass for extension to appear

Match Property: Value to compare against (alias, entity type, etc.)

Permitted State: Boolean indicating if condition passes

Custom Conditions: Implement

UmbConditionBase

and set

this.permitted

Use Cases:

Show dashboard only in Content section
Display action only for specific content types
Restrict features to admin users
Show view only in document workspace
Enable actions based on permissions

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

管控机制：条件控制扩展的可用性

AND逻辑：所有条件必须满足，扩展才会显示

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

允许状态：表示条件是否满足的布尔值

自定义条件：实现

UmbConditionBase

并设置

this.permitted

使用场景：

仅在内容板块显示仪表盘
仅为特定内容类型显示操作按钮
限制功能仅对管理员开放
仅在文档工作区显示视图
根据权限启用操作

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