mcpField
U
umbraco-routing

umbraco-routing

github.com/umbraco开发27393 次安装6 周前更新
代码仓库

关于 umbraco-routing

用于实现 Umbraco 后台扩展路径导航的技能，涵盖区块、仪表板和自定义路由，并指导配置参数与重定向。

主要功能

  1. 01区块、仪表板和视图路径
  2. 02带参数的自定义路由
  3. 03路由重定向与 setup 函数
  4. 04提示查阅最新文档

适用场景

  1. 01为后台区块添加导航
  2. 02构建支持深度链接的路由模态框
  3. 03向组件传递路由参数

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/umbraco/umbraco-cms-backoffice-skills --skill umbraco-routing

安装后在 Claude Code 中输入/umbraco-routing确认已加载。

详细介绍

Umbraco 路由

这是什么？

Umbraco 后台中的路由通过基于路径名的 URL，实现各个区块、仪表板和工作区之间的导航。区块是主要的组织划分，可通过区块视图、仪表板或自定义元素进入。可以使用 umb-router-slot 和支持参数及重定向的路由定义来构建自定义路由。

文档

实现前务必获取最新文档：

参考示例

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

位置：/Umbraco-CMS/src/Umbraco.Web.UI.Client/examples/modal-routed/

此示例演示了带有基于 URL 的导航和深层链接支持的路由模态框。复杂路由模式可参考此示例。

工作流程

  1. 获取文档 - 对上述 URL 使用 WebFetch
  2. 提出问题 - 需要自定义路由、区块导航或参数吗？
  3. 生成代码 - 根据最新文档实现路由
  4. 说明 - 展示创建的内容以及导航的工作方式

最小示例

带路径名的区块
{
  "type": "section",
  "alias": "My.Section",
  "name": "My Section",
  "meta": {
    "label": "My Section",
    "pathname": "my-section"
  }
}

URL：/section/my-section

带路径名的仪表板
{
  "type": "dashboard",
  "alias": "My.Dashboard",
  "name": "My Dashboard",
  "meta": {
    "label": "Welcome",
    "pathname": "welcome-dashboard"
  },
  "conditions": [
    {
      "alias": "Umb.Condition.SectionAlias",
      "match": "Umb.Section.Content"
    }
  ]
}

URL：/section/content/dashboard/welcome-dashboard

带路由的自定义路由器
import { html, customElement, state } from '@umbraco-cms/backoffice/external/lit';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import type { UmbRoute } from '@umbraco-cms/backoffice/router';

@customElement('my-routed-element')
export class MyRoutedElement extends UmbLitElement {
  @state()
  private _routes: UmbRoute[] = [
    {
      path: 'person/:personId',
      component: () => import('./person.element.js'),
      setup: (_component, info) => {
        console.log('personId:', info.match.params.personId);
      },
    },
    {
      path: 'people',
      component: () => import('./people.element.js'),
    },
    {
      path: '',
      redirectTo: 'people',
    },
  ];

  render() {
    return html`
      <umb-router-slot .routes=${this._routes}></umb-router-slot>
    `;
  }
}
带参数的路由
{
  path: 'edit/:id',
  component: () => import('./edit.element.js'),
  setup: (component, info) => {
    const id = info.match.params.id;
    component.itemId = id;
  },
}
带重定向的路由
{
  path: '',
  redirectTo: 'overview',
}
多个路由示例
@state()
private _routes: UmbRoute[] = [
  {
    path: 'overview',
    component: () => import('./overview.element.js'),
  },
  {
    path: 'settings',
    component: () => import('./settings.element.js'),
  },
  {
    path: 'item/:id',
    component: () => import('./item-detail.element.js'),
    setup: (component, info) => {
      component.itemId = info.match.params.id;
    },
  },
  {
    path: '',
    redirectTo: 'overview',
  },
];
导航链接
render() {
  return html`
    <nav>
      <a href="/section/my-section/overview">Overview</a>
      <a href="/section/my-section/settings">Settings</a>
      <a href="/section/my-section/item/123">Item 123</a>
    </nav>
    <umb-router-slot .routes=${this._routes}></umb-router-slot>
  `;
}
带路径名的区块视图
{
  "type": "sectionView",
  "alias": "My.SectionView",
  "name": "My Section View",
  "element": "/App_Plugins/MyExtension/section-view.js",
  "meta": {
    "label": "Organization",
    "pathname": "organization",
    "icon": "icon-users"
  },
  "conditions": [
    {
      "alias": "Umb.Condition.SectionAlias",
      "match": "My.Section"
    }
  ]
}

URL：/section/my-section/organization

嵌套路由
// Parent element
@state()
private _routes: UmbRoute[] = [
  {
    path: 'admin',
    component: () => import('./admin-layout.element.js'),
  },
  {
    path: 'users',
    component: () => import('./users-layout.element.js'),
  },
];

// Admin layout element can have its own nested routes
@state()
private _adminRoutes: UmbRoute[] = [
  {
    path: 'dashboard',
    component: () => import('./admin-dashboard.element.js'),
  },
  {
    path: 'settings',
    component: () => import('./admin-settings.element.js'),
  },
];
路由设置函数
{
  path: 'edit/:documentId',
  component: () => import('./document-editor.element.js'),
  setup: (component, info) => {
    // Access route parameters
    const documentId = info.match.params.documentId;

    // Pass to component
    component.documentId = documentId;

    // Can also access query params, etc.
    console.log('Route info:', info);
  },
}

核心概念

pathname：区块、仪表板和视图的 URL 路径段

umb-router-slot：用于渲染匹配路由的组件

UmbRoute：包含路径、组件和设置的路由定义

路由顺序：优先匹配第一个路由——顺序很重要！

参数：在路径中使用 :paramName（例如 item/:id）

重定向：使用 redirectTo 重定向到另一个路径

setup 函数：路由匹配时调用，接收组件和路由信息

URL 结构：

  • 区块：/section/my-section
  • 仪表板：/section/content/dashboard/welcome
  • 区块视图：/section/my-section/organization
  • 自定义：/section/my-section/people/person/123

入口点：

  • 区块视图（带选项卡和图标）
  • 仪表板（带选项卡和图标）
  • 工作区（实体编辑）
  • 自定义元素（完全控制）

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

评论

支持 Markdown