umbraco-dynamic-root

Umbraco 动态根

这是什么？

动态根允许内容选择器使用动态确定的起始点（原点），而不是固定节点。它包含两种扩展类型：

• 动态根原点：定义选择器的起点（例如，当前页面、站点根节点、最近的指定类型祖先）
• 动态根查询步骤：定义从原点开始的导航步骤（例如，查找最近的祖先、获取指定类型的子节点）

借助这些扩展，可以灵活配置内容选择器，使其根据上下文进行调整。

文档

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

• 扩展类型：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types
• 内容选择器：https://docs.umbraco.com/umbraco-cms/model-your-content/property-editors/built-in-umbraco-property-editors/content-picker
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提问 - 起始点逻辑是什么？需要哪些查询步骤？
3. 生成文件 - 根据最新文档创建清单
4. 说明 - 展示创建的内容以及测试方法

最小示例

动态根原点清单

import type { ManifestDynamicRootOrigin } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestDynamicRootOrigin = {
  type: 'dynamicRootOrigin',
  alias: 'My.DynamicRootOrigin.SiteRoot',
  name: 'Site Root Origin',
  meta: {
    originAlias: 'SiteRoot',
    label: 'Site Root',
    description: 'Start from the root of the current site',
    icon: 'icon-home',
  },
};

export const manifests = [manifest];

动态根查询步骤清单

import type { ManifestDynamicRootQueryStep } from '@umbraco-cms/backoffice/extension-registry';

const manifest: ManifestDynamicRootQueryStep = {
  type: 'dynamicRootQueryStep',
  alias: 'My.DynamicRootQueryStep.NearestBlog',
  name: 'Nearest Blog Query Step',
  meta: {
    queryStepAlias: 'NearestBlog',
    label: 'Nearest Blog',
    description: 'Find the nearest blog ancestor',
    icon: 'icon-article',
  },
};

export const manifests = [manifest];

多个原点和步骤

import type { ManifestDynamicRootOrigin, ManifestDynamicRootQueryStep } from '@umbraco-cms/backoffice/extension-registry';

const originManifests: ManifestDynamicRootOrigin[] = [
  {
    type: 'dynamicRootOrigin',
    alias: 'My.DynamicRootOrigin.CurrentPage',
    name: 'Current Page Origin',
    meta: {
      originAlias: 'CurrentPage',
      label: 'Current Page',
      description: 'Start from the page being edited',
      icon: 'icon-document',
    },
  },
  {
    type: 'dynamicRootOrigin',
    alias: 'My.DynamicRootOrigin.Parent',
    name: 'Parent Page Origin',
    meta: {
      originAlias: 'Parent',
      label: 'Parent Page',
      description: 'Start from the parent of current page',
      icon: 'icon-arrow-up',
    },
  },
];

const queryStepManifests: ManifestDynamicRootQueryStep[] = [
  {
    type: 'dynamicRootQueryStep',
    alias: 'My.DynamicRootQueryStep.Children',
    name: 'Children Query Step',
    meta: {
      queryStepAlias: 'Children',
      label: 'Children',
      description: 'Get all child pages',
      icon: 'icon-tree',
    },
  },
  {
    type: 'dynamicRootQueryStep',
    alias: 'My.DynamicRootQueryStep.Ancestors',
    name: 'Ancestors Query Step',
    meta: {
      queryStepAlias: 'Ancestors',
      label: 'Ancestors',
      description: 'Get ancestor pages',
      icon: 'icon-navigation-up',
    },
  },
];

export const manifests = [...originManifests, ...queryStepManifests];

需要后端实现

动态根需要通过后端 C# 实现来处理实际的查询逻辑：

// Example C# implementation for a custom origin
public class SiteRootDynamicRootOrigin : IDynamicRootOrigin
{
    public string OriginAlias => "SiteRoot";

    public Task<Guid?> GetOriginAsync(Guid contentKey, string? entityType)
    {
        // Return the site root GUID based on the content's position
        // Implementation depends on your site structure
        return Task.FromResult<Guid?>(GetSiteRootForContent(contentKey));
    }
}

// Example C# implementation for a custom query step
public class NearestBlogQueryStep : IDynamicRootQueryStep
{
    public string QueryStepAlias => "NearestBlog";

    public Task<IEnumerable<Guid>> ExecuteAsync(Guid originKey, string? entityType)
    {
        // Find nearest blog ancestor from the origin
        // Return matching content GUIDs
        return Task.FromResult(FindNearestBlogAncestors(originKey));
    }
}

// Register in Composer
public class DynamicRootComposer : IComposer
{
    public void Compose(IUmbracoBuilder builder)
    {
        builder.DynamicRootSteps()
            .AddOrigin<SiteRootDynamicRootOrigin>()
            .AddQueryStep<NearestBlogQueryStep>();
    }
}

原点元属性

属性	说明
originAlias	与后端实现匹配的唯一标识符
label	选择器配置中的显示名称
description	说明原点的帮助文本
icon	配置界面中显示的图标

查询步骤元属性

属性	说明
queryStepAlias	与后端实现匹配的唯一标识符
label	选择器配置中的显示名称
description	说明查询步骤的帮助文本
icon	配置界面中显示的图标

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