Umbraco CMS 内容选择器自定义查询步骤的实现方法

在Umbraco CMS开发过程中，内容选择器(Content Picker)是一个常用的组件，它允许编辑者在后台选择特定的内容节点。Umbraco 15版本提供了扩展内容选择器功能的能力，特别是可以添加自定义的动态根查询步骤(Dynamic Root Query Step)。本文将详细介绍如何正确实现这一功能。

核心概念

动态根查询步骤是内容选择器中的一个重要功能，它允许开发者定义特定的内容节点查询逻辑。系统默认提供了一些基础步骤，如"祖先"、"后代"等，但有时我们需要根据业务需求实现自定义的查询逻辑。

实现步骤

1. 服务端实现

首先需要创建一个实现IDynamicRootQueryStep接口的类：

using Umbraco.Cms.Core.DynamicRoot.QuerySteps;
using Umbraco.Cms.Core;

public class MyCustomDynamicRootQueryStep : IDynamicRootQueryStep
{
    public virtual string SupportedDirectionAlias { get; set; } = "MyCustomStep";

    public async Task<Attempt<ICollection<Guid>>> ExecuteAsync(
        ICollection<Guid> origins, 
        DynamicRootQueryStep filter)
    {
        if (filter.Alias != SupportedDirectionAlias)
        {
            return Attempt<ICollection<Guid>>.Fail();
        }

        if (origins.Any() is false)
        {
            return Attempt<ICollection<Guid>>.Succeed(Array.Empty<Guid>());
        }

        // 这里实现自定义查询逻辑
        var dummyResult = Guid.NewGuid();
        ICollection<Guid> result = new List<Guid> { dummyResult };

        return Attempt<ICollection<Guid>>.Succeed(result);
    }
}

2. 注册服务端组件

通过Composer将自定义步骤注册到系统中：

using Umbraco.Cms.Core.Composing;
using Umbraco.Cms.Core.DependencyInjection;

public class MyComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DynamicRootSteps().Append<MyCustomDynamicRootQueryStep>();
    }
}

3. 客户端实现

这是关键但容易被忽略的一步。需要在App_Plugins目录下创建一个包扩展：

{
  "$schema": "../../umbraco-package-schema.json",
  "name": "My.Test.Extension",
  "version": "0.1.0",
  "extensions": [
    {
      "type": "dynamicRootQueryStep",
      "alias": "Umb.DynamicRootQueryStep.MyCustomStep",
      "name": "Dynamic Root Query Step: My Custom Step",
      "meta": {
        "queryStepAlias": "MyCustomStep",
        "label": "My Custom Step",
        "description": "自定义步骤的描述信息",
        "icon": "icon-coffee"
      },
      "weight": 60
    }
  ]
}

实现要点

1. 别名一致性：服务端的SupportedDirectionAlias必须与客户端配置中的queryStepAlias完全匹配。

2. 权重设置：weight属性决定了步骤在UI中的显示顺序，数值越大排序越靠后。

3. 图标选择：可以使用Umbraco内置的图标类名，如示例中的"icon-coffee"。

4. 错误处理：服务端实现中应包含适当的错误处理逻辑，确保在无效输入时返回正确的响应。

常见问题解决

如果在实现后发现自定义步骤没有出现在内容选择器中，请检查：

1. 服务端和客户端的别名是否完全一致
2. 包扩展文件是否放置在正确的目录(App_Plugins)
3. 服务端组件是否已正确注册
4. 是否有任何编译错误或运行时错误

通过以上步骤，开发者可以成功扩展Umbraco CMS的内容选择器功能，实现符合特定业务需求的节点查询逻辑。这种扩展方式既保持了系统的灵活性，又遵循了Umbraco的扩展规范，是推荐的做法。