Vendure电商平台：自定义Admin UI路由开发指南

Vendure电商平台：自定义Admin UI路由开发指南

vendure A headless GraphQL commerce platform for the modern web 项目地址: https://gitcode.com/gh_mirrors/ve/vendure

前言

在Vendure电商平台中，Admin UI是商家管理后台的核心界面。通过自定义路由功能，开发者可以扩展Admin UI的功能，创建全新的管理页面。本文将详细介绍如何在Vendure中定义自定义路由，帮助开发者快速掌握这一重要功能。

路由基础概念

在Vendure Admin UI中，路由决定了不同URL路径下应该显示哪个组件。自定义路由允许开发者：

1. 在Admin UI中创建全新的页面
2. 扩展系统默认功能
3. 集成第三方服务的管理界面

所有自定义路由都会挂载在/extensions/路径下，以避免与内置路由冲突。

开发环境准备

开始前，请确保：

1. 已安装Node.js和npm/yarn
2. 已初始化Vendure项目
3. 熟悉Angular或React框架（两者都支持）

创建自定义路由完整流程

第一步：创建插件

使用Vendure CLI工具快速创建插件：

npx vendure add

选择"Create a new Vendure plugin"，命名为"greeter"，并选择UI扩展功能。

第二步：创建路由组件

根据项目技术栈选择Angular或React组件：

Angular组件示例

import { SharedModule } from '@vendure/admin-ui/core';
import { Component } from '@angular/core';

@Component({
    selector: 'greeter',
    template: `
        <vdr-page-block>
            <h2>{{ greeting }}</h2>
        </vdr-page-block>`,
    standalone: true,
    imports: [SharedModule],
})
export class GreeterComponent {
    greeting = 'Hello!';
}

React组件示例

import React from 'react';

export function Greeter() {
    const greeting = 'Hello!';
    return (
        <div className="page-block">
            <h2>{greeting}</h2>
        </div>
    );
}

重要提示：<vdr-page-block>（Angular）或<div className="page-block">（React）是布局包装器，确保组件风格与Admin UI一致。

第三步：定义路由配置

在routes.ts文件中注册路由：

Angular路由注册

import { registerRouteComponent } from '@vendure/admin-ui/core';
import { GreeterComponent } from './components/greeter/greeter.component';

export default [
    registerRouteComponent({
        component: GreeterComponent,
        path: '',
        title: 'Greeter Page',
        breadcrumb: 'Greeter',
    }),
];

React路由注册

import { registerReactRouteComponent } from '@vendure/admin-ui/react';
import { Greeter } from './components/Greeter';

export default [
    registerReactRouteComponent({
        component: Greeter,
        path: '',
        title: 'Greeter Page',
        breadcrumb: 'Greeter',
    }),
];

第四步：配置插件UI扩展

插件会自动生成UI扩展配置：

static ui: AdminUiExtension = {
    id: 'greeter-ui',
    extensionPath: path.join(__dirname, 'ui'),
    routes: [{ route: 'greeter', filePath: 'routes.ts' }],
    providers: ['providers.ts'],
};

第五步：测试运行

启动开发服务器：

npm run dev

访问http://localhost:3000/admin/extensions/greeter即可看到自定义页面。

高级路由功能

路由参数处理

可以通过:前缀定义动态路由参数：

path: ':id'

获取参数示例（Angular）

import { ActivatedRoute } from '@angular/router';

constructor(private route: ActivatedRoute) {
    this.id = this.route.snapshot.paramMap.get('id');
}

获取参数示例（React）

import { useRouteParams } from '@vendure/admin-ui/react';

const { params } = useRouteParams();
const id = params.id;

服务注入

可以注入内置服务或自定义服务：

通知服务示例（Angular）

import { NotificationService } from '@vendure/admin-ui/core';

constructor(private notificationService: NotificationService) {}

showNotification() {
    this.notificationService.success('操作成功!');
}

通知服务示例（React）

import { useInjector } from '@vendure/admin-ui/react';
import { NotificationService } from '@vendure/admin-ui/core';

const notificationService = useInjector(NotificationService);
notificationService.success('操作成功!');

动态页面标题

路由配置中设置

title: '用户管理'

组件内动态更新（Angular）

import { PageMetadataService } from '@vendure/admin-ui/core';

constructor(private pageMetadataService: PageMetadataService) {}

updateTitle() {
    this.pageMetadataService.setTitle('新标题');
}

组件内动态更新（React）

import { usePageMetadata } from '@vendure/admin-ui/react';

const { setTitle } = usePageMetadata();
setTitle('新标题');

面包屑导航配置

支持多种配置方式：

1. 简单字符串
2. 链接-标签对象
3. 链接-标签数组
4. 动态生成函数

复杂面包屑示例

breadcrumb: [
    { label: '首页', link: '/extensions' },
    { label: '用户', link: '/extensions/users' },
    { label: '详情', link: '/extensions/users/detail' }
]

动态更新（Angular）

this.pageMetadataService.setBreadcrumb('当前位置');

动态更新（React）

const { setBreadcrumb } = usePageMetadata();
setBreadcrumb('当前位置');

最佳实践建议

1. 保持风格一致：使用Vendure提供的样式组件（如vdr-page-block）
2. 合理规划路由：考虑管理后台的导航结构
3. 错误处理：为动态路由添加适当的错误处理
4. 性能优化：懒加载大型组件
5. 测试覆盖：确保自定义路由在各种场景下正常工作

总结

通过本文，您已经掌握了在Vendure电商平台中创建自定义Admin UI路由的全过程。从基础的路由创建到高级的参数处理和服务注入，这些技能将帮助您扩展Vendure的管理功能，满足特定业务需求。

实际开发中，建议先规划好路由结构，再逐步实现各个功能模块。Vendure灵活的扩展机制为电商后台定制提供了无限可能。

vendure A headless GraphQL commerce platform for the modern web 项目地址: https://gitcode.com/gh_mirrors/ve/vendure