umbraco-tree-item

Umbraco 树项目

这是什么？

树项目定义了如何在 Umbraco 后台的树形结构中呈现实例。它们控制侧边栏和导航树中项目的视觉呈现和行为。树项目与实体类型相关联，并且可以进行自定义，以便为特定实体类型显示其他信息、图标或自定义呈现效果。

文档

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

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/tree
• 基础：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/foundation
• 扩展注册表：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-registry

何时使用自定义树项目上下文

大多数树项目使用 kind: 'default'，不需要自定义上下文。仅在以下情况创建自定义上下文：

• 自定义图标逻辑 - 根据项目状态动态显示图标
• 自定义标签或徽标 - 添加其他视觉信息
• 特殊呈现 - 为特定实体类型提供独特行为
• 其他项目行为 - 点击处理程序、拖放等

如果只需要标准树项目，请使用 kind: 'default'，无需自定义上下文。

相关基础技能

• 树：树项目在树形结构中工作

  • 参考技能：umbraco-tree
  • IMPORTANT：树存储在 Umbraco 14 中已弃用，并在 Umbraco 18 中移除，详情请参阅该技能

• 仓储模式：加载树数据时使用

  • 参考技能：umbraco-repository-pattern

• 上下文 API：访问树上下文时使用

  • 参考技能：umbraco-context-api

工作流

1. 获取文档 - 对上述 URL 使用 WebFetch
2. 提出问题 - 有哪些实体类型？需要什么自定义呈现？
3. 生成文件 - 创建清单 + 可选的元素/上下文
4. 说明 - 展示创建了什么以及如何测试

最简示例

基本清单 (manifests.ts)

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'treeItem',
    kind: 'default',
    alias: 'My.TreeItem',
    name: 'My Tree Item',
    forEntityTypes: ['my-entity-type'],
  },
];

带上下文的自定义树项目

import { MY_ENTITY_TYPE, MY_ROOT_ENTITY_TYPE } from '../entity.js';

export const manifests: Array<UmbExtensionManifest> = [
  {
    type: 'treeItem',
    kind: 'default',
    alias: 'My.TreeItem.Custom',
    name: 'My Custom Tree Item',
    forEntityTypes: [MY_ENTITY_TYPE, MY_ROOT_ENTITY_TYPE],
    api: () => import('./my-tree-item.context.js'),
  },
];

树项目上下文 (my-tree-item.context.ts)

import { UmbDefaultTreeItemContext } from '@umbraco-cms/backoffice/tree';
import type { UmbControllerHost } from '@umbraco-cms/backoffice/controller-api';
import type { UmbTreeItemModel, UmbTreeRootModel } from '@umbraco-cms/backoffice/tree';

export class MyTreeItemContext extends UmbDefaultTreeItemContext<
  UmbTreeItemModel,
  UmbTreeRootModel
> {
  constructor(host: UmbControllerHost) {
    super(host);
  }

  // Override to customize icon
  override async getIcon() {
    const item = this.getTreeItem();
    if (item?.hasChildren) {
      return 'icon-folder';
    }
    return 'icon-document';
  }

  // Override to add custom labels/badges
  override async getLabel() {
    const item = this.getTreeItem();
    return item?.name ?? 'Unknown';
  }
}

export { MyTreeItemContext as api };

包含树项目的完整树

import { MY_ENTITY_TYPE, MY_ROOT_ENTITY_TYPE } from './entity.js';
import { MY_TREE_ALIAS, MY_TREE_REPOSITORY_ALIAS } from './constants.js';

export const manifests: Array<UmbExtensionManifest> = [
  // Tree definition
  {
    type: 'tree',
    kind: 'default',
    alias: MY_TREE_ALIAS,
    name: 'My Tree',
    meta: {
      repositoryAlias: MY_TREE_REPOSITORY_ALIAS,
    },
  },
  // Tree item for the entities
  {
    type: 'treeItem',
    kind: 'default',
    alias: 'My.TreeItem',
    name: 'My Tree Item',
    forEntityTypes: [MY_ROOT_ENTITY_TYPE, MY_ENTITY_TYPE],
  },
];

接口参考

interface ManifestTreeItem extends ManifestElementAndApi<UmbControllerHostElement, UmbTreeItemContext> {
  type: 'treeItem';
  forEntityTypes: Array<string>;  // Entity types this tree item renders
}

常见实体类型

具有树项目的内置实体类型：

• document - 内容节点
• document-root - 内容根节点
• media - 媒体项目
• media-root - 媒体根节点
• member - 成员
• data-type - 数据类型
• document-type - 文档类型
• template - 模板

种类

kind: 'default' 使用标准树项目呈现方式。可以创建自定义种类以实现专门的呈现效果。

最佳实践

• 为不同实体类型使用合适的图标
• 考虑异步数据的加载状态
• 保持树项目轻量，以提升性能
• 使用实体类型常量确保类型安全

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