Back to Details

umbraco-menu-items

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Umbraco Menu Items

Umbraco 菜单项

What is it?

什么是菜单项？

Menu items are extension components that appear throughout the Umbraco backoffice in sidebars, button flyouts, and other locations. They work alongside Menu extensions to provide navigational and action-based functionality. Menu items come in different kinds (link, action, tree) and can use default components or custom elements.
菜单项是在Umbraco后台的侧边栏、按钮下拉菜单等各处出现的扩展组件。它们与菜单扩展配合使用，提供导航和基于操作的功能。菜单项分为不同类型（链接、操作、树形），可使用默认组件或自定义元素。

Documentation

文档

Always fetch the latest docs before implementing:
在实现前请务必获取最新文档：

Reference Example

参考示例

The Umbraco source includes a working example:
Location: 
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/menu-item/
This example demonstrates custom menu items with different kinds. Study this for production patterns.
Umbraco源码中包含一个可运行的示例：
位置：
/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/menu-item/
该示例展示了不同类型的自定义菜单项。可参考此示例中的生产级实现模式。

Related Foundation Skills

相关基础技能

If you need to explain these foundational concepts when implementing menu items, reference these skills:
  • Umbraco Element: When implementing custom menu item elements, explaining UmbLitElement, or creating menu item components
    • Reference skill: 
      umbraco-umbraco-element
  • Controllers: When implementing UmbMenuItemAction, action logic, execute methods, or menu item behavior
    • Reference skill: 
      umbraco-controllers
  • Context API: When implementing context access or service consumption from menu item actions
    • Reference skill: 
      umbraco-context-api
在实现菜单项时，若需要解释以下基础概念，可参考对应的技能：
  • Umbraco Element：当实现自定义菜单项元素、解释UmbLitElement或创建菜单项组件时
    • 参考技能：
      umbraco-umbraco-element
  • 控制器：当实现UmbMenuItemAction、操作逻辑、执行方法或菜单项行为时
    • 参考技能：
      umbraco-controllers
  • Context API：当实现从菜单项操作中访问上下文或调用服务时
    • 参考技能：
      umbraco-context-api

Workflow

工作流程

  1. Fetch docs - Use WebFetch on the URLs above
  2. Ask questions - What kind? Which menu? Link, action, or tree? Custom element needed?
  3. Generate files - Create manifest + element (if custom) based on latest docs
  4. Explain - Show what was created and how to test
  1. 获取文档 - 使用WebFetch获取上述URL中的文档
  2. 确认需求 - 确定菜单项类型？要添加到哪个菜单？链接、操作还是树形？是否需要自定义元素？
  3. 生成文件 - 根据最新文档创建清单文件（manifest）+ 元素（如果需要自定义）
  4. 说明解释 - 展示创建的内容以及测试方法

Minimal Examples

最简示例

Link Menu Item (manifest.ts)

链接型菜单项（manifest.ts）

typescript
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"
    }
  }
];
typescript
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"
    }
  }
];

Action Menu Item (manifest.ts)

操作型菜单项（manifest.ts）

typescript
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"]
    }
  }
];
typescript
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"]
    }
  }
];

Action Implementation (menu-item-action.ts)

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

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

Tree Menu Item (manifest.ts)

树形菜单项（manifest.ts）

typescript
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"
    }
  }
];
typescript
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"
    }
  }
];

Custom Element Menu Item (menu-item.element.ts)

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

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

Menu Item Kinds

菜单项类型

  1. Link - Navigate to external URLs (
    href
    property)
  2. Action - Execute custom logic on click (requires 
    api
    implementation)
  3. Tree - Display submenu from tree structure (
    treeAlias
    property)
  1. 链接型 - 导航到外部URL（使用
    href
    属性）
  2. 操作型 - 点击时执行自定义逻辑（需要实现
    api
    ）
  3. 树形 - 从树形结构显示子菜单（使用
    treeAlias
    属性）

Key Properties

关键属性

  • type: Always 
    "menuItem"
  • kind: Type of menu item (
    "link"
    , 
    "action"
    , 
    "tree"
    )
  • alias: Unique identifier
  • meta.label: Display text
  • meta.icon: Icon identifier
  • meta.menus: Array of menu aliases to appear in
  • weight: Controls ordering (higher = later in list)
  • element: Path to custom element (optional)
  • api: Action implementation (for kind: "action")
That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.
  • type：固定为
    "menuItem"
  • kind：菜单项类型（
    "link"
    、
    "action"
    、
    "tree"
    ）
  • alias：唯一标识符
  • meta.label：显示文本
  • meta.icon：图标标识符
  • meta.menus：菜单项所属的菜单别名数组
  • weight：控制排序（值越大，在列表中越靠后）
  • element：自定义元素的路径（可选）
  • api：操作逻辑的实现（适用于类型为"action"的菜单项）
就是这样！请务必获取最新文档，保持示例最简，生成完整可运行的代码。