feat(@vben/layouts): support activePath breadcrumb hierarchy

.changeset/kind-cats-breadcrumb.md

@@ -0,0 +1,6 @@
+---
+'@vben-core/typings': minor
+'@vben/layouts': minor
+---
+
+feat: support using the activePath route hierarchy in breadcrumbs

docs/src/en/guide/essentials/route.md

@@ -314,6 +314,11 @@ interface RouteMeta {
    * The currently active menu, sometimes you don't want to activate the existing menu, use this to activate the parent menu
    */
   activePath?: string;
+  /**
+   * Whether to use the route hierarchy resolved from activePath in breadcrumbs
+   * @default false
+   */
+  breadcrumbUseActivePath?: boolean;
   /**
    * Whether to fix the tab
    * @default false
@@ -508,6 +513,13 @@ Used to configure the badge color of the page.
 
 Used to configure the currently active menu. Sometimes the page is not displayed in the menu, and this is used to activate the parent menu.
 
+### breadcrumbUseActivePath
+
+- Type: `boolean`
+- Default: `false`
+
+When set to `true`, the breadcrumb supplements the current route matches with the route hierarchy resolved from `activePath`. This is useful for detail pages and other routes that are not nested under the target menu route but still need to display the complete breadcrumb hierarchy.
+
 ### affixTab
 
 - Type: `boolean`

docs/src/guide/essentials/route.md

@@ -307,6 +307,11 @@ interface RouteMeta {
    * 当前激活的菜单，有时候不想激活现有菜单，需要激活父级菜单时使用
    */
   activePath?: string;
+  /**
+   * 是否使用 activePath 对应的路由层级生成面包屑
+   * @default false
+   */
+  breadcrumbUseActivePath?: boolean;
   /**
    * 是否固定标签页
    * @default false
@@ -516,6 +521,13 @@ interface RouteMeta {
 
 用于配置当前激活的菜单，有时候页面没有显示在菜单内，需要激活父级菜单时使用。
 
+### breadcrumbUseActivePath
+
+- 类型：`boolean`
+- 默认值：`false`
+
+设置为 `true` 时，面包屑会使用 `activePath` 对应的路由层级补充当前路由的匹配记录。适用于详情页等未嵌套在目标菜单路由下，但仍需要展示完整面包屑层级的页面。
+
 ### affixTab
 
 - 类型：`boolean`

packages/@core/base/typings/src/vue-router.d.ts

@@ -10,6 +10,11 @@ interface RouteMeta {
    * 当前激活的菜单，有时候不想激活现有菜单，需要激活父级菜单时使用
    */
   activePath?: string;
+  /**
+   * 是否使用 activePath 对应的路由层级生成面包屑
+   * @default false
+   */
+  breadcrumbUseActivePath?: boolean;
   /**
    * 是否固定标签页
    * @default false

packages/effects/layouts/src/widgets/__tests__/breadcrumb-routes.test.ts

@@ -0,0 +1,69 @@
+import type { RouteLocationMatched } from 'vue-router';
+
+import { describe, expect, it, vi } from 'vitest';
+
+import { resolveBreadcrumbMatches } from '../breadcrumb-routes';
+
+function createMatch(name: string, path: string): RouteLocationMatched {
+  return { name, path } as RouteLocationMatched;
+}
+
+describe('resolveBreadcrumbMatches', () => {
+  it('preserves the current matches when activePath breadcrumbs are disabled', () => {
+    const matches = [createMatch('Detail', '/detail')];
+    const resolveRoute = vi.fn();
+
+    expect(
+      resolveBreadcrumbMatches(
+        {
+          matched: matches,
+          meta: {
+            activePath: '/list',
+            breadcrumbUseActivePath: false,
+            title: 'Detail',
+          },
+        },
+        resolveRoute,
+      ),
+    ).toBe(matches);
+    expect(resolveRoute).not.toHaveBeenCalled();
+  });
+
+  it('preserves the current matches when activePath cannot be resolved', () => {
+    const matches = [createMatch('Detail', '/detail')];
+
+    expect(
+      resolveBreadcrumbMatches(
+        {
+          matched: matches,
+          meta: {
+            activePath: '/missing',
+            breadcrumbUseActivePath: true,
+            title: 'Detail',
+          },
+        },
+        () => ({ matched: [] }),
+      ),
+    ).toBe(matches);
+  });
+
+  it('prepends activePath matches and removes duplicate route records', () => {
+    const root = createMatch('Root', '/');
+    const list = createMatch('List', '/list');
+    const detail = createMatch('Detail', '/detail');
+
+    expect(
+      resolveBreadcrumbMatches(
+        {
+          matched: [root, detail],
+          meta: {
+            activePath: '/list',
+            breadcrumbUseActivePath: true,
+            title: 'Detail',
+          },
+        },
+        () => ({ matched: [root, list] }),
+      ),
+    ).toEqual([root, list, detail]);
+  });
+});

packages/effects/layouts/src/widgets/breadcrumb-routes.ts

@@ -0,0 +1,41 @@
+import type { RouteLocationNormalizedLoaded } from 'vue-router';
+
+type MatchedRoutes = RouteLocationNormalizedLoaded['matched'];
+
+interface BreadcrumbRoute {
+  matched: MatchedRoutes;
+  meta: RouteLocationNormalizedLoaded['meta'];
+}
+
+type BreadcrumbRouteResolver = (path: string) => { matched: MatchedRoutes };
+
+/**
+ * 解析用于渲染当前面包屑的路由匹配记录。
+ */
+export function resolveBreadcrumbMatches(
+  route: BreadcrumbRoute,
+  resolveRoute: BreadcrumbRouteResolver,
+): MatchedRoutes {
+  const { activePath, breadcrumbUseActivePath } = route.meta;
+
+  if (!breadcrumbUseActivePath || !activePath) {
+    return route.matched;
+  }
+
+  const activeMatches = resolveRoute(activePath).matched;
+  if (activeMatches.length === 0) {
+    return route.matched;
+  }
+
+  const seen = new Set(activeMatches.map((match) => match.name ?? match.path));
+  const currentMatches = route.matched.filter((match) => {
+    const key = match.name ?? match.path;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+
+  return [...activeMatches, ...currentMatches];
+}

packages/effects/layouts/src/widgets/breadcrumb.vue

@@ -10,6 +10,8 @@ import { $t } from '@vben/locales';
 
 import { VbenBreadcrumbView } from '@vben-core/shadcn-ui';
 
+import { resolveBreadcrumbMatches } from './breadcrumb-routes';
+
 interface Props {
   hideWhenOnlyOne?: boolean;
   showHome?: boolean;
@@ -27,7 +29,9 @@ const route = useRoute();
 const router = useRouter();
 
 const breadcrumbs = computed((): IBreadcrumb[] => {
-  const matched = route.matched;
+  const matched = resolveBreadcrumbMatches(route, (path) =>
+    router.resolve(path),
+  );
 
   const resultBreadcrumb: IBreadcrumb[] = [];