admin-theme-development

管理后台主题开发

概述

在 Bagisto 中，管理后台主题开发涉及创建自定义管理后台主题，并将其打包为 Laravel 包。最终成果是一个独立的包，可单独分发和维护。

适用场景

在以下情况下使用此技能：

• 将自定义管理后台主题创建为包
• 构建用于分发的管理后台主题包
• 自定义管理后台样式
• 覆盖默认管理后台模板

Bagisto 管理后台主题架构

核心组件

组件	用途	位置
主题配置	定义可用的管理后台主题	config/themes.php
视图路径	Blade 模板文件	在主题配置中定义
资源路径	CSS、JS、图片	在主题配置中定义
管理后台服务提供者	加载视图和组件	packages/Webkul/Admin/src/Providers/AdminServiceProvider.php

关键配置属性

// config/themes.php
'admin-default' => 'default',

'admin' => [
    'default' => [
        'name' => 'Default',
        'assets_path' => 'public/themes/admin/default',
        'views_path' => 'resources/admin-themes/default/views',
        'vite' => [
            'hot_file' => 'admin-default-vite.hot',
            'build_directory' => 'themes/admin/default/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
],

创建管理后台主题包

目标：完整的独立包

最终成果应是一个完整的包，其中包含：

• 包内的所有视图
• 包内的所有资源
• 用于发布的服务提供者
• 用于编译资源的 Vite 配置

步骤 1：创建包结构

mkdir -p packages/Webkul/CustomAdminTheme/src/{Providers,Resources/views}

步骤 2：复制完整的管理后台资源

将所有管理后台资源复制到你的包中，以便完全掌控：

# Copy complete admin assets folder
cp -r packages/Webkul/Admin/src/Resources/assets/* packages/Webkul/CustomAdminTheme/src/Resources/assets/

# Copy complete admin views folder
cp -r packages/Webkul/Admin/src/Resources/views/* packages/Webkul/CustomAdminTheme/src/Resources/views/

# Copy admin package.json for dependencies
cp packages/Webkul/Admin/package.json packages/Webkul/CustomAdminTheme/

这样你将获得：

• 基于 Tailwind 的完整 CSS 基础
• 所有 JavaScript 功能
• 管理后台组件和布局
• 图片、字体和静态资源
• 完整的 Blade 模板结构
• 用于资源编译的依赖项

步骤 3：添加自定义仪表板页面（样板）

复制完成后，创建一个自定义仪表板页面，以展示这是一个新主题：

文件： packages/Webkul/CustomAdminTheme/src/Resources/views/dashboard/index.blade.php

<x-admin::layouts>
    <x-slot:title>
        Custom Admin Dashboard
    </x-slot>

    <div class="flex gap-4 justify-between max-sm:flex-wrap">
        <h1 class="py-[11px] text-xl text-gray-800 dark:text-white font-bold">
            Custom Theme Dashboard
        </h1>

        <div class="flex gap-x-2.5 items-center">
            <button class="secondary-button">
                Reset to Defaults
            </button>
            
            <button class="primary-button">
                Save Settings
            </button>
        </div>
    </div>

    {{-- Dashboard Content --}}
    <div class="mt-8 bg-white dark:bg-gray-900 rounded-lg shadow p-6">
        <h1 class="text-3xl font-bold text-gray-800 dark:text-white mb-6">
            Welcome to Custom Admin Theme
        </h1>
        
        <p class="text-lg text-gray-600 dark:text-gray-300 mb-8">
            Your customized Bagisto admin panel!
        </p>
        
        <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
            <div class="bg-blue-50 p-4 rounded-lg border border-blue-200">
                <h3 class="text-xl font-semibold text-blue-800 mb-2">
                    Analytics
                </h3>
                <p class="text-blue-600">
                    Enhanced dashboard analytics and reporting
                </p>
            </div>
            
            <div class="bg-green-50 p-4 rounded-lg border border-green-200">
                <h3 class="text-xl font-semibold text-green-800 mb-2">
                    Orders
                </h3>
                <p class="text-green-600">
                    Streamlined order management interface
                </p>
            </div>
            
            <div class="bg-purple-50 p-4 rounded-lg border border-purple-200">
                <h3 class="text-xl font-semibold text-purple-800 mb-2">
                    Customers
                </h3>
                <p class="text-purple-600">
                    Enhanced customer management tools
                </p>
            </div>
        </div>
    </div>
</x-admin::layouts>

步骤 4：创建自定义布局（可选）

创建自己的主布局，以便完全掌控：

文件： packages/Webkul/CustomAdminTheme/src/Resources/views/layouts/master.blade.php

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ $title ?? config('app.name') }}</title>
    
    {{-- Load assets manually for custom layouts --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body class="dark:bg-gray-900">
    {{-- Custom sidebar --}}
    @include('custom-admin-theme::layouts.sidebar')
    
    <div class="flex">
        {{-- Main content area --}}
        <main class="flex-1 p-6">
            {{ $slot }}
        </main>
    </div>
</body>
</html>

步骤 5：创建服务提供者

文件： packages/Webkul/CustomAdminTheme/src/Providers/CustomAdminThemeServiceProvider.php

<?php

namespace Webkul\CustomAdminTheme\Providers;

use Illuminate\Support\ServiceProvider;

class CustomAdminThemeServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register(): void
    {
        //
    }

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        // Publish views to resources/admin-themes/custom-admin-theme/views
        $this->publishes([
            __DIR__ . '/../Resources/views' => resource_path('admin-themes/custom-admin-theme/views'),
        ], 'custom-admin-theme-views');
    }
}

步骤 6：配置自动加载

更新 composer.json：

"autoload": {
    "psr-4": {
        "Webkul\\CustomAdminTheme\\": "packages/Webkul/CustomAdminTheme/src"
    }
}

运行：composer dump-autoload

步骤 7：注册服务提供者

添加到 bootstrap/providers.php：

Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider::class,

步骤 8：更新主题配置

文件： config/themes.php

'admin-default' => 'custom-admin-theme',

'admin' => [
    'default' => [
        'name' => 'Default',
        'assets_path' => 'public/themes/admin/default',
        'views_path' => 'resources/admin-themes/default/views',
        'vite' => [
            'hot_file' => 'admin-default-vite.hot',
            'build_directory' => 'themes/admin/default/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
    'custom-admin-theme' => [
        'name' => 'Custom Admin Theme',
        'assets_path' => 'public/themes/admin/custom-admin-theme',
        'views_path' => 'resources/admin-themes/custom-admin-theme/views',
        'vite' => [
            'hot_file' => 'admin-custom-vite.hot',
            'build_directory' => 'themes/admin/custom-admin/build',
            'package_assets_directory' => 'src/Resources/assets',
        ],
    ],
],

步骤 9：发布视图

php artisan vendor:publish --provider="Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider"

步骤 10：清除缓存

php artisan optimize:clear

步骤 11：构建资源

# Navigate to package
cd packages/Webkul/CustomAdminTheme

# Install dependencies
npm install

# Build assets for production
npm run build

这将编译你的管理后台主题资源并创建构建目录。构建完成后，你的自定义管理后台主题即可使用，其中包含你创建的自定义仪表板。

Vite 驱动的资源

步骤 1：创建资源配置文件

在包根目录中创建：

文件： package.json

{
    "name": "custom-admin-theme",
    "private": true,
    "description": "Custom Admin Theme Package for Bagisto",
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    },
    "devDependencies": {
        "autoprefixer": "^10.4.14",
        "axios": "^1.1.2",
        "laravel-vite-plugin": "^0.7.2",
        "postcss": "^8.4.23",
        "tailwindcss": "^3.3.2",
        "vite": "^4.0.0"
    }
}

文件： vite.config.js

import { defineConfig, loadEnv } from "vite";
import laravel from "laravel-vite-plugin";
import path from "path";

export default defineConfig(({ mode }) => {
    const envDir = "../../../";

    Object.assign(process.env, loadEnv(mode, envDir));

    return {
        build: {
            emptyOutDir: true,
        },
        envDir,
        server: {
            host: process.env.VITE_HOST || "localhost",
            port: process.env.VITE_ADMIN_PORT || 5174,
            cors: true,
        },
        plugins: [
            laravel({
                hotFile: "../../../public/admin-custom-vite.hot",
                publicDirectory: "../../../public",
                buildDirectory: "themes/admin/custom-admin/build",
                input: [
                    "src/Resources/assets/css/app.css",
                    "src/Resources/assets/js/app.js",
                ],
                refresh: true,
            }),
        ],
    };
});

文件： tailwind.config.js

module.exports = {
    content: [
        "./src/Resources/**/*.blade.php",
        "../../../resources/admin-themes/custom-admin-theme/**/*.blade.php"
    ],
    theme: {
        extend: {
            colors: {
                navyBlue: "#060C3B",
            },
        },
    },
    plugins: [],
};

文件： postcss.config.js

module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
}

步骤 2：添加到 Bagisto Vite 配置

文件： config/bagisto-vite.php

'admin-custom-theme' => [
    'hot_file' => 'admin-custom-vite.hot',
    'build_directory' => 'themes/admin/custom-admin/build',
    'package_assets_directory' => 'src/Resources/assets',
],

开发命令

# Navigate to package
cd packages/Webkul/CustomAdminTheme

# Install dependencies
npm install

# Start dev server with hot reload
npm run dev

# Build for production
npm run build

开发工作流

选项 A：符号链接（推荐）

创建符号链接，以便实时开发，无需重新发布：

# Remove published views
rm -rf resources/admin-themes/custom-admin-theme/views

# Create symlink from package to resources
ln -s $(pwd)/packages/Webkul/CustomAdminTheme/src/Resources/views resources/admin-themes/custom-admin-theme/views

选项 B：直接开发包

直接在包中开发，并在需要时重新发布：

# After making changes
php artisan vendor:publish --provider="Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider" --force

管理后台布局

要编写 Blade 本身？ blade-conventions 技能包含标记规则 — : 与 :: 属性绑定、匿名组件与 Vue 驱动组件、缩进、注释 风格，以及翻译和 view_render_event 钩子的放置位置。

使用管理后台布局

<x-admin::layouts>
    <x-slot:title>
        Page Title
    </x-slot>

    {{-- Page Header --}}
    <div class="flex gap-4 justify-between max-sm:flex-wrap">
        <p class="py-[11px] text-xl text-gray-800 dark:text-white font-bold">
            Page Heading
        </p>
        <div class="flex gap-x-2.5 items-center">
            <button class="primary-button">
                Action Button
            </button>
        </div>
    </div>

    {{-- Page content --}}
    <div class="mt-8">
        Content goes here
    </div>
</x-admin::layouts>

布局功能

管理布局会自动提供：

• 侧边栏导航：包含可折叠分区的管理菜单
• 页眉：顶部导航，包含用户菜单和通知
• 响应式设计：适配移动设备的布局
• 深色模式：内置深色模式支持
• 面包屑导航：自动生成面包屑导航

管理布局最佳实践

• 始终使用标题插槽，以优化 SEO 和用户体验
• 遵循 Bagisto 的管理界面设计模式
• 使用提供的 CSS 类（例如，primary-button、secondary-button）
• 保持布局结构清晰且语义明确

管理 Blade 组件

可用组件

组件	用法	描述
<x-admin::accordion>	可折叠分区	切换内容的显示状态
<x-admin::button>	操作按钮	支持加载状态
<x-admin::charts.bar>	柱状图	基于 Chart.js
<x-admin::charts.line>	折线图	基于 Chart.js
<x-admin::datagrid>	数据表格	排序、筛选、分页
<x-admin::drawer>	滑出面板	位置：上/下/左/右
<x-admin::dropdown>	下拉菜单	提供位置选项
<x-admin::flat-picker.date>	日期选择器	基于 Flatpickr
<x-admin::flat-picker.datetime>	日期时间选择器	基于 Flatpickr
<x-admin::media.images>	图片上传	支持多张图片
<x-admin::media.videos>	视频上传	支持视频
<x-admin::modal>	对话框	包含页眉、内容和页脚插槽
<x-admin::quantity-changer>	数量输入	+/- 按钮
<x-admin::seo>	SEO 元数据	Meta 标题和描述
<x-admin::table>	数据表格	可自定义 thead/tbody
<x-admin::tabs>	标签导航	位置：左/右/中
<x-admin::shimmer.*>	加载效果	骨架屏加载器

自定义布局

创建自定义布局

文件： packages/Webkul/CustomAdminTheme/src/Resources/views/layouts/master.blade.php

<!DOCTYPE html>
<html lang="{{ app()->getLocale() }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ $title ?? config('app.name') }}</title>
    
    {{-- Load assets manually for custom layouts --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body class="dark:bg-gray-900">
    {{-- Custom sidebar --}}
    @include('custom-admin-theme::layouts.sidebar')
    
    <div class="flex">
        {{-- Main content area --}}
        <main class="flex-1 p-6">
            {{ $slot }}
        </main>
    </div>
</body>
</html>

完整的软件包结构

packages/Webkul/CustomAdminTheme/
├── src/
│   ├── Providers/
│   │   └── CustomAdminThemeServiceProvider.php
│   └── Resources/
│       ├── assets/
│       │   ├── css/
│       │   │   └── app.css
│       │   ├── js/
│       │   │   └── app.js
│       │   ├── images/
│       │   └── fonts/
│       └── views/
│           ├── layouts/
│           │   └── master.blade.php
│           ├── dashboard/
│           │   └── index.blade.php
│           ├── components/
│           └── ...
├── package.json
├── vite.config.js
├── tailwind.config.js
└── postcss.config.js

关键文件参考

文件	用途
config/themes.php	主题配置
config/bagisto-vite.php	Vite 资源配置
packages/Webkul/Admin/src/Providers/AdminServiceProvider.php	管理软件包注册
packages/Webkul/Admin/src/Resources/views/components/*	管理组件
packages/Webkul/Theme/src/Themes.php	主题门面

常见问题

• 更改主题配置后未清除缓存
• 注册软件包后忘记运行 composer dump-autoload
• 未复制完整的管理资源（视图和资源文件）
• 使用自定义布局时未手动加载 @bagistoVite 资源
• 在已发布的文件中操作，而不是在软件包源文件中操作
• 开发工作流缺少符号链接设置

测试

通过以下步骤测试管理主题：

1. 在 config/themes.php 中设置 admin-default
2. 登录管理面板
3. 检查仪表板和各个管理页面
4. 验证响应式设计
5. 验证所有管理功能均正常运行
6. 在开发期间测试热重载