umbraco-menu-items

Umbraco 菜单项

这是什么？

菜单项是扩展组件，会出现在 Umbraco 后台的侧边栏、按钮弹出菜单和其他位置。它们与菜单扩展配合使用，提供导航和基于操作的功能。菜单项有不同类型（link、action、tree），可以使用默认组件或自定义元素。

文档

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

• 主要文档：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/menu-item
• 菜单：https://docs.umbraco.com/umbraco-cms/extend-your-project/backoffice-extensions/extending-overview/extension-types/menu
• 基础：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

参考示例

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

位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/menu-item/

此示例展示了不同类型的自定义菜单项。请参考此示例，了解适用于生产环境的模式。

相关基础技能

如果实现菜单项时需要解释以下基础概念，请参考这些技能：

• Umbraco 元素：实现自定义菜单项元素、解释 UmbLitElement 或创建菜单项组件时

  • 参考技能：umbraco-umbraco-element

• 控制器：实现 UmbMenuItemAction、操作逻辑、执行方法或菜单项行为时

  • 参考技能：umbraco-controllers

• Context API：实现菜单项操作中的上下文访问或服务使用时

  • 参考技能：umbraco-context-api

工作流

1. 获取文档 - 对以上 URL 使用 WebFetch
2. 提问 - 需要哪种类型？属于哪个菜单？是链接、操作还是树？是否需要自定义元素？
3. 生成文件 - 根据最新文档创建清单 + 元素（如果是自定义元素）
4. 说明 - 展示创建的内容和测试方法

最小示例

链接菜单项（manifest.ts）

export const manifests = [
  {
    type: "menuItem",
    kind: "link",
    alias: "My.MenuItem.Link",
    name: "My Link Menu Item",
    weight: 100,
    meta: {
      label: "External Link",
      icon: "icon-link",
      menus: ["Umb.Menu.Help"],
      href: "https://example.com"
    }
  }
];

操作菜单项（manifest.ts）

export const manifests = [
  {
    type: "menuItem",
    kind: "action",
    alias: "My.MenuItem.Action",
    name: "My Action Menu Item",
    api: () => import('./menu-item-action.js'),
    meta: {
      label: "Execute Action",
      icon: "icon-wand",
      menus: ["My.Menu"]
    }
  }
];

操作实现（menu-item-action.ts）

import { UmbMenuItemAction } from '@umbraco-cms/backoffice/menu';

export class MyMenuItemAction extends UmbMenuItemAction {
  async execute() {
    console.log('Menu item clicked!');
    // Perform custom logic here
  }
}

export default MyMenuItemAction;

树菜单项（manifest.ts）

export const manifests = [
  {
    type: "menuItem",
    kind: "tree",
    alias: "My.MenuItem.Tree",
    name: "My Tree Menu Item",
    meta: {
      label: "Tree Structure",
      icon: "icon-folder",
      menus: ["Umb.Menu.Content"],
      treeAlias: "My.Tree"
    }
  }
];

自定义元素菜单项（menu-item.element.ts）

import { html, customElement } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';

@customElement('my-menu-item')
export class MyMenuItemElement extends UmbLitElement {

  #onClick() {
    // Custom logic
  }

  render() {
    return html`
      <uui-menu-item
        label="Custom Item"
        @click="${this.#onClick}"
      >
        <uui-icon name="icon-wand"></uui-icon>
      </uui-menu-item>
    `;
  }
}

export default MyMenuItemElement;

菜单项类型

1. Link - 导航到外部 URL（href 属性）
2. Action - 点击时执行自定义逻辑（需要实现 api）
3. Tree - 根据树结构显示子菜单（treeAlias 属性）

关键属性

• type：始终为 "menuItem"
• kind：菜单项类型（"link"、"action"、"tree"）
• alias：唯一标识符
• meta.label：显示文本
• meta.icon：图标标识符
• meta.menus：要显示在其中的菜单别名数组
• weight：控制排序（数值越大，在列表中越靠后）
• element：自定义元素的路径（可选）
• api：操作实现（kind 为 "action" 时）

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