Back to Details

admin-theme-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Admin Theme Development

管理后台主题开发

Overview

概述

Admin theme development in Bagisto involves creating custom admin panel themes packaged as Laravel packages. The end result is a self-contained package that can be distributed and maintained independently.
Bagisto 中的管理后台主题开发指的是将自定义管理后台主题封装为 Laravel 包的开发过程，最终产出的是可独立分发、独立维护的自包含包。

When to Apply

适用场景

Activate this skill when:
  • Creating custom admin themes as packages
  • Building admin theme packages for distribution
  • Customizing admin panel styling
  • Overriding default admin templates
在以下场景中启用本技能：
  • 创建打包为独立包的自定义管理后台主题
  • 构建可分发的后台主题包
  • 定制管理后台样式
  • 覆盖默认后台模板

Bagisto Admin Theme Architecture

Bagisto 管理后台主题架构

Core Components

核心组件

ComponentPurposeLocation
Theme ConfigurationDefines available admin themes
config/themes.php
Views PathBlade template filesDefined in theme config
Assets PathCSS, JS, imagesDefined in theme config
Admin Service ProviderLoads views and components
packages/Webkul/Admin/src/Providers/AdminServiceProvider.php
组件用途路径
主题配置定义可用的管理后台主题
config/themes.php
视图路径Blade 模板文件在主题配置中定义
资源路径CSS、JS、图片在主题配置中定义
管理后台服务提供者加载视图与组件
packages/Webkul/Admin/src/Providers/AdminServiceProvider.php

Key Configuration Properties

核心配置属性

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',
        ],
    ],
],
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',
        ],
    ],
],

Creating Admin Theme Package

创建管理后台主题包

Goal: Complete Self-Contained Package

目标：完整的独立包

The end result should be a complete package with:
  • All views inside the package
  • All assets inside the package
  • Service provider for publishing
  • Vite configuration for asset compilation
最终产出的完整包应当包含：
  • 包内包含所有视图文件
  • 包内包含所有静态资源
  • 用于资源发布的服务提供者
  • 用于资源编译的 Vite 配置

Step 1: Create Package Structure

步骤1：创建包结构

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

Step 2: Copy Complete Admin Assets

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

Copy all admin assets to your package to have full control:
bash
undefined
将所有后台资源复制到你的包中，实现完全可控：
bash
undefined

Copy complete admin assets folder

复制完整的后台资源文件夹

cp -r packages/Webkul/Admin/src/Resources/assets/* packages/Webkul/CustomAdminTheme/src/Resources/assets/
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/
cp -r packages/Webkul/Admin/src/Resources/views/* packages/Webkul/CustomAdminTheme/src/Resources/views/

Copy admin package.json for dependencies

复制后台的 package.json 依赖文件

cp packages/Webkul/Admin/package.json packages/Webkul/CustomAdminTheme/

This gives you:
- Complete CSS foundation with Tailwind
- All JavaScript functionality
- Admin components and layouts
- Images, fonts, and static assets
- Complete Blade template structure
- Dependencies for asset compilation
cp packages/Webkul/Admin/package.json packages/Webkul/CustomAdminTheme/

执行后你将获得：
- 基于 Tailwind 的完整 CSS 基础框架
- 所有 JavaScript 功能逻辑
- 后台组件与布局
- 图片、字体与静态资源
- 完整的 Blade 模板结构
- 资源编译所需的依赖

Step 3: Add Custom Dashboard Page (Boilerplate)

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

After copying, create a custom dashboard page to show it's a new theme:
File: 
packages/Webkul/CustomAdminTheme/src/Resources/views/dashboard/index.blade.php
blade
<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>
复制完成后，创建自定义仪表盘页面，验证新主题生效：
文件： 
packages/Webkul/CustomAdminTheme/src/Resources/views/dashboard/index.blade.php
blade
<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">
            自定义主题仪表盘
        </h1>

        <div class="flex gap-x-2.5 items-center">
            <button class="secondary-button">
                重置为默认
            </button>
            
            <button class="primary-button">
                保存设置
            </button>
        </div>
    </div>

    {{-- 仪表盘内容 --}}
    <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">
            欢迎使用自定义管理后台主题
        </h1>
        
        <p class="text-lg text-gray-600 dark:text-gray-300 mb-8">
            你的定制化 Bagisto 管理后台！
        </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">
                    数据分析
                </h3>
                <p class="text-blue-600">
                    增强版仪表盘分析与报表功能
                </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">
                    订单管理
                </h3>
                <p class="text-green-600">
                    精简高效的订单管理界面
                </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">
                    客户管理
                </h3>
                <p class="text-purple-600">
                    增强型客户管理工具
                </p>
            </div>
        </div>
    </div>
</x-admin::layouts>

Step 4: Create Custom Layout (Optional)

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

Create your own master layout for complete control:
File: 
packages/Webkul/CustomAdminTheme/src/Resources/views/layouts/master.blade.php
blade
<!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/Resources/views/layouts/master.blade.php
blade
<!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>
    
    {{-- 自定义布局需要手动加载资源 --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body class="dark:bg-gray-900">
    {{-- 自定义侧边栏 --}}
    @include('custom-admin-theme::layouts.sidebar')
    
    <div class="flex">
        {{-- 主内容区域 --}}
        <main class="flex-1 p-6">
            {{ $slot }}
        </main>
    </div>
</body>
</html>

Step 5: Create Service Provider

步骤5：创建服务提供者

File: 
packages/Webkul/CustomAdminTheme/src/Providers/CustomAdminThemeServiceProvider.php
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');
    }
}
文件： 
packages/Webkul/CustomAdminTheme/src/Providers/CustomAdminThemeServiceProvider.php
php
<?php

namespace Webkul\CustomAdminTheme\Providers;

use Illuminate\Support\ServiceProvider;

class CustomAdminThemeServiceProvider extends ServiceProvider
{
    /**
     * 注册服务
     */
    public function register(): void
    {
        //
    }

    /**
     * 启动服务
     */
    public function boot(): void
    {
        // 发布视图到 resources/admin-themes/custom-admin-theme/views
        $this->publishes([
            __DIR__ . '/../Resources/views' => resource_path('admin-themes/custom-admin-theme/views'),
        ], 'custom-admin-theme-views');
    }
}

Step 6: Configure Autoloading

步骤6：配置自动加载

Update 
composer.json
:
json
"autoload": {
    "psr-4": {
        "Webkul\\CustomAdminTheme\\": "packages/Webkul/CustomAdminTheme/src"
    }
}
Run: 
composer dump-autoload
更新 
composer.json
：
json
"autoload": {
    "psr-4": {
        "Webkul\\CustomAdminTheme\\": "packages/Webkul/CustomAdminTheme/src"
    }
}
执行命令：
composer dump-autoload

Step 7: Register Service Provider

步骤7：注册服务提供者

Add to 
bootstrap/providers.php
:
php
Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider::class,
添加到 
bootstrap/providers.php
：
php
Webkul\CustomAdminTheme\Providers\CustomAdminThemeServiceProvider::class,

Step 8: Update Theme Configuration

步骤8：更新主题配置

File: 
config/themes.php
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',
        ],
    ],
],
文件： 
config/themes.php
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',
        ],
    ],
],

Step 9: Publish Views

步骤9：发布视图

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

Step 10: Clear Cache

步骤10：清除缓存

bash
php artisan optimize:clear
bash
php artisan optimize:clear

Step 11: Build Assets

步骤11：编译资源

bash
undefined
bash
undefined

Navigate to package

进入包目录

cd packages/Webkul/CustomAdminTheme
cd packages/Webkul/CustomAdminTheme

Install dependencies

安装依赖

npm install
npm install

Build assets for production

编译生产环境资源

npm run build

This will compile your admin theme assets and create the build directory. After building, your custom admin theme will be ready to use with the custom dashboard you created.
npm run build

这将编译你的后台主题资源并生成构建目录。编译完成后，你的自定义管理后台主题就可以使用了，你创建的自定义仪表盘也会生效。

Vite-Powered Assets

Vite 驱动的资源管理

Step 1: Create Asset Configuration Files

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

Create in your package root:
File: 
package.json
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"
    }
}
File: 
vite.config.js
javascript
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,
            }),
        ],
    };
});
File: 
tailwind.config.js
javascript
module.exports = {
    content: [
        "./src/Resources/**/*.blade.php",
        "../../../resources/admin-themes/custom-admin-theme/**/*.blade.php"
    ],
    theme: {
        extend: {
            colors: {
                navyBlue: "#060C3B",
            },
        },
    },
    plugins: [],
};
File: 
postcss.config.js
javascript
module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
}
在包根目录下创建以下文件：
文件： 
package.json
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
javascript
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
javascript
module.exports = {
    content: [
        "./src/Resources/**/*.blade.php",
        "../../../resources/admin-themes/custom-admin-theme/**/*.blade.php"
    ],
    theme: {
        extend: {
            colors: {
                navyBlue: "#060C3B",
            },
        },
    },
    plugins: [],
};
文件： 
postcss.config.js
javascript
module.exports = {
    plugins: {
        tailwindcss: {},
        autoprefixer: {},
    },
}

Step 2: Add to Bagisto Vite Config

步骤2：添加到 Bagisto Vite 配置

File: 
config/bagisto-vite.php
php
'admin-custom-theme' => [
    'hot_file' => 'admin-custom-vite.hot',
    'build_directory' => 'themes/admin/custom-admin/build',
    'package_assets_directory' => 'src/Resources/assets',
],
文件： 
config/bagisto-vite.php
php
'admin-custom-theme' => [
    'hot_file' => 'admin-custom-vite.hot',
    'build_directory' => 'themes/admin/custom-admin/build',
    'package_assets_directory' => 'src/Resources/assets',
],

Development Commands

开发命令

bash
undefined
bash
undefined

Navigate to package

进入包目录

cd packages/Webkul/CustomAdminTheme
cd packages/Webkul/CustomAdminTheme

Install dependencies

安装依赖

npm install
npm install

Start dev server with hot reload

启动热重载开发服务器

npm run dev
npm run dev

Build for production

编译生产环境版本

npm run build
undefined
npm run build
undefined

Development Workflow

开发工作流

Option A: Symlink (Recommended)

方案A：软链接（推荐）

Create symlink for real-time development without republishing:
bash
undefined
创建软链接实现实时开发，无需重复发布资源：
bash
undefined

Remove published views

删除已发布的视图

rm -rf resources/admin-themes/custom-admin-theme/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
undefined
ln -s $(pwd)/packages/Webkul/CustomAdminTheme/src/Resources/views resources/admin-themes/custom-admin-theme/views
undefined

Option B: Direct Package Development

方案B：直接包开发

Work directly in package and republish when needed:
bash
undefined
直接在包目录中开发，需要时重新发布资源：
bash
undefined

After making changes

修改代码后执行

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

Admin Layouts

后台布局

Using Admin Layout

使用后台布局

blade
<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>
blade
<x-admin::layouts>
    <x-slot:title>
        页面标题
    </x-slot>

    {{-- 页面头部 --}}
    <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">
            页面标题
        </p>
        <div class="flex gap-x-2.5 items-center">
            <button class="primary-button">
                操作按钮
            </button>
        </div>
    </div>

    {{-- 页面内容 --}}
    <div class="mt-8">
        内容区域
    </div>
</x-admin::layouts>

Layout Features

布局特性

The admin layout automatically provides:
  • Sidebar Navigation: Admin menu with collapsible sections
  • Header: Top navigation with user menu and notifications
  • Responsive Design: Mobile-friendly layout
  • Dark Mode: Built-in dark mode support
  • Breadcrumbs: Automatic breadcrumb generation
后台布局自动提供以下能力：
  • 侧边栏导航：支持折叠的管理后台菜单
  • 头部导航：包含用户菜单与通知的顶部导航
  • 响应式设计：适配移动端的布局
  • 暗黑模式：内置暗黑模式支持
  • 面包屑：自动生成面包屑导航

Admin Layout Best Practices

后台布局最佳实践

  • Always use the title slot for SEO and user experience
  • Follow Bagisto's admin design patterns
  • Use provided CSS classes (e.g., 
    primary-button
    , 
    secondary-button
    )
  • Keep layout structure clean and semantic
  • 始终使用 title 插槽优化 SEO 与用户体验
  • 遵循 Bagisto 后台设计规范
  • 使用内置 CSS 类（如 
    primary-button
    、
    secondary-button
    ）
  • 保持布局结构清晰、语义化

Admin Blade Components

后台 Blade 组件

Available Components

可用组件

ComponentUsageDescription
<x-admin::accordion>
Collapsible sectionsToggle content visibility
<x-admin::button>
Action buttonsLoading states supported
<x-admin::charts.bar>
Bar chartsBased on Chart.js
<x-admin::charts.line>
Line chartsBased on Chart.js
<x-admin::datagrid>
Data tablesSorting, filtering, pagination
<x-admin::drawer>
Slide-out panelsPosition: top/bottom/left/right
<x-admin::dropdown>
Dropdown menusPosition options available
<x-admin::flat-picker.date>
Date pickerBased on Flatpickr
<x-admin::flat-picker.datetime>
Date-time pickerBased on Flatpickr
<x-admin::media.images>
Image uploadMultiple images support
<x-admin::media.videos>
Video uploadVideo support
<x-admin::modal>
Dialog boxesHeader, content, footer slots
<x-admin::quantity-changer>
Quantity input+/- buttons
<x-admin::seo>
SEO metadataMeta title and description
<x-admin::table>
Data tablesCustomizable thead/tbody
<x-admin::tabs>
Tab navigationPosition: left/right/center
<x-admin::shimmer.*>
Loading effectsSkeleton loaders
组件用法描述
<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>
数据表格支持自定义表头/表体
<x-admin::tabs>
标签导航支持左/右/居中对齐
<x-admin::shimmer.*>
加载效果骨架屏加载动画

Custom Layouts

自定义布局

Creating Custom Layout

创建自定义布局

File: 
packages/Webkul/CustomAdminTheme/src/Resources/views/layouts/master.blade.php
blade
<!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/Resources/views/layouts/master.blade.php
blade
<!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>
    
    {{-- 自定义布局需要手动加载资源 --}}
    @bagistoVite([
        'src/Resources/assets/css/app.css',
        'src/Resources/assets/js/app.js'
    ])
</head>
<body class="dark:bg-gray-900">
    {{-- 自定义侧边栏 --}}
    @include('custom-admin-theme::layouts.sidebar')
    
    <div class="flex">
        {{-- 主内容区域 --}}
        <main class="flex-1 p-6">
            {{ $slot }}
        </main>
    </div>
</body>
</html>

Complete Package Structure

完整包结构

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

Key Files Reference

关键文件参考

FilePurpose
config/themes.php
Theme configuration
config/bagisto-vite.php
Vite asset configuration
packages/Webkul/Admin/src/Providers/AdminServiceProvider.php
Admin package registration
packages/Webkul/Admin/src/Resources/views/components/*
Admin components
packages/Webkul/Theme/src/Themes.php
Theme facade
文件用途
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
主题门面

Common Pitfalls

常见问题

  • Not clearing cache after theme config changes
  • Forgetting to run composer dump-autoload after package registration
  • Not copying complete admin assets (views and assets)
  • Using custom layouts without manually loading @bagistoVite assets
  • Working in published files instead of package source files
  • Missing symlink setup for development workflow
  • 修改主题配置后未清除缓存
  • 注册包后忘记执行 composer dump-autoload
  • 未复制完整的后台资源（视图与静态资源）
  • 使用自定义布局时未手动加载 @bagistoVite 资源
  • 在已发布的文件中修改，而非包源文件
  • 开发流程中未配置软链接

Testing

测试

Test your admin theme by:
  1. Setting admin-default in config/themes.php
  2. Logging into admin panel
  3. Checking dashboard and various admin pages
  4. Verifying responsive design
  5. Verifying all admin functionality works
  6. Testing hot reload during development
通过以下步骤测试你的管理后台主题：
  1. 在 config/themes.php 中设置 admin-default 配置
  2. 登录管理后台
  3. 检查仪表盘与各类后台页面
  4. 验证响应式布局适配
  5. 确认所有后台功能正常运行
  6. 测试开发阶段的热重载功能