umbraco-routing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Umbraco Routing

Umbraco 路由

What is it?

什么是Umbraco路由？

Routing in Umbraco's backoffice enables navigation between sections, dashboards, and workspaces using pathname-based URLs. Sections serve as primary organizational dividers with entry points via section views, dashboards, or custom elements. Custom routing can be built using

umb-router-slot

with route definitions that support parameters and redirects.

Umbraco后台中的路由支持通过基于路径名的URL在不同板块、仪表板和工作区之间导航。板块是主要的组织划分单元，可通过板块视图、仪表板或自定义元素作为入口点。可以使用

umb-router-slot

构建自定义路由，其路由定义支持参数和重定向。

Documentation

文档

Always fetch the latest docs before implementing:

Main docs: https://docs.umbraco.com/umbraco-cms/customizing/foundation/routes
Sections: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/sections/section
Dashboards: https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/dashboard
Foundation: https://docs.umbraco.com/umbraco-cms/customizing/foundation

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

主文档：https://docs.umbraco.com/umbraco-cms/customizing/foundation/routes
板块：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/sections/section
仪表板：https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types/dashboard
基础概念：https://docs.umbraco.com/umbraco-cms/customizing/foundation

Reference Example

参考示例

The Umbraco source includes a working example:

Location:

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

This example demonstrates routed modals with URL-based navigation and deep-linking support. Study this for complex routing patterns.

Umbraco源码中包含一个可用示例：

位置：

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

该示例展示了支持基于URL导航和深度链接的路由模态框。如需了解复杂路由模式，可参考此示例。

Workflow

工作流程

Fetch docs - Use WebFetch on the URLs above
Ask questions - Custom routes? Section navigation? Parameters needed?
Generate code - Implement routing based on latest docs
Explain - Show what was created and how navigation works

获取文档 - 使用WebFetch访问上述URL
提出问题 - 是否需要自定义路由？板块导航？参数配置？
生成代码 - 根据最新文档实现路由
解释说明 - 展示创建的内容以及导航的工作原理

Minimal Examples

极简示例

Section with Pathname

带路径名的板块

json

{
  "type": "section",
  "alias": "My.Section",
  "name": "My Section",
  "meta": {
    "label": "My Section",
    "pathname": "my-section"
  }
}

URL:

/section/my-section

json

{
  "type": "section",
  "alias": "My.Section",
  "name": "My Section",
  "meta": {
    "label": "My Section",
    "pathname": "my-section"
  }
}

URL:

/section/my-section

Dashboard with Pathname

带路径名的仪表板

json

{
  "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

json

{
  "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

Custom Router with Routes

带路由的自定义路由器

typescript

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>
    `;
  }
}

typescript

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>
    `;
  }
}

Route with Parameters

带参数的路由

typescript

{
  path: 'edit/:id',
  component: () => import('./edit.element.js'),
  setup: (component, info) => {
    const id = info.match.params.id;
    component.itemId = id;
  },
}

typescript

{
  path: 'edit/:id',
  component: () => import('./edit.element.js'),
  setup: (component, info) => {
    const id = info.match.params.id;
    component.itemId = id;
  },
}

Route with Redirect

带重定向的路由

typescript

{
  path: '',
  redirectTo: 'overview',
}

typescript

{
  path: '',
  redirectTo: 'overview',
}

Multiple Routes Example

多路由示例

typescript

@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',
  },
];

typescript

@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',
  },
];

Navigation Links

导航链接

typescript

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>
  `;
}

typescript

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>
  `;
}

Section View with Pathname

带路径名的板块视图

json

{
  "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

json

{
  "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

Nested Routes

嵌套路由

typescript

// 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'),
  },
];

typescript

// 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'),
  },
];

Route Setup Function

路由设置函数

typescript

{
  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);
  },
}

typescript

{
  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);
  },
}

Key Concepts

核心概念

pathname: URL segment for sections/dashboards/views

umb-router-slot: Component that renders matched route

UmbRoute: Route definition with path, component, setup

Route Order: First match wins - order matters!

Parameters: Use

:paramName

in path (e.g.,

item/:id

)

Redirects: Use

redirectTo

to redirect to another path

setup Function: Called when route matches, receives component and route info

URL Structure:

Section:
```
/section/my-section
```
Dashboard:
```
/section/content/dashboard/welcome
```
Section View:
```
/section/my-section/organization
```
Custom:
```
/section/my-section/people/person/123
```

Entry Points:

Section Views (with tabs/icons)
Dashboards (with tabs/icons)
Workspaces (entity editing)
Custom Elements (full control)

That's it! Always fetch fresh docs, keep examples minimal, generate complete working code.

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
```

入口点：

板块视图（带标签页/图标）
仪表板（带标签页/图标）
工作区（实体编辑）
自定义元素（完全控制）

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