主题开发：入门
Last updated on Jun 23, 2026 16:56
PolyCMS 使用高度灵活的、基于 Blade 的主题引擎。虽然管理面板是 Vue 3 SPA，但面向公众的前端默认依赖于传统的超快服务器端渲染 (SSR) 刀片模板（尽管它也完全支持无头 API 驱动的前端）。
本指南介绍了 PolyCMS 主题的架构以及如何从头开始构建主题。
1.目录结构
所有主题都位于“themes/”目录中。
让我们看一下标准主题的结构，例如核心“flexiwhite”蓝图：
themes/
└── flexiwhite/
├── theme.json # The Theme Manifest
├── screenshot.png # 800x600 preview image for the Admin panel
├── functions.php # Optional: PHP logic, Hook registration
├── resources/
│ └── views/ # Blade templates
│ ├── layouts/
│ │ └── app.blade.php # The master wrapper
│ ├── partials/
│ └── templates/ # Specialized block templates (Landing pages, etc.)
└── public/ # Compiled CSS/JS and Images
2. 主题清单 (theme.json)
要向系统注册主题，您必须定义“theme.json”文件。 ThemeManager 使用它来识别主题并将其可用模板公开给管理 UI。
{
"name": "FlexiWhite",
"slug": "flexiwhite",
"version": "1.0.0",
"author": "Polyx Team",
"description": "A clean, whitespace-heavy corporate theme.",
"role": "main",
"templates": {
"posts": {
"full-width": "Full Width No Sidebar",
"gallery": "Gallery Focus Layout"
},
"pages": {
"landing": "Marketing Landing Page",
"contact": "Contact Form Layout"
}
}
}
主主题与子主题
注意 "role": "main" 键。 PolyCMS 实现了多主题架构：
主要主题（role: main）： 提供全局布局（app.blade.php）和站点范围的 CSS。一次只能有一个人处于活动状态。
子主题（角色：子）： 提供专门的模板（例如独特的结账流程或黑色星期五登陆页面）。您可以同时激活多个子主题。当分配给特定的帖子或页面时，他们的模板将覆盖主题。
3. 主布局 (app.blade.php)
每个主主题必须有一个位于“resources/views/layouts/app.blade.php”的主布局文件。该文件定义了 HTML 框架。
关键要求：为了确保模块和插件可以注入必要的 CSS 和 JavaScript（例如 Cookie 同意横幅或分析脚本），您的布局必须包含“@stack”指令。
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Render SEO Meta Tags dynamically -->
<title>@yield('meta_title', config('app.name'))</title>
<!-- Include Theme CSS -->
<link rel="stylesheet" href="{{ theme_asset('css/style.css') }}">
<!-- CRITICAL: Allow modules to inject CSS -->
@stack('theme-styles')
</head>
<body>
@include('theme::partials.header')
<main>
<!-- Render the specific page/post content here -->
@yield('content')
</main>
@include('theme::partials.footer')
<!-- CRITICAL: Allow modules to inject JS -->
@stack('theme-scripts')
</body>
</html>
4. theme_asset() 助手
当链接到主题的“public/”目录中存储的 CSS、JS 或图像时，始终使用“theme_asset()”辅助函数，而不是 Laravel 的标准“asset()”。
<!-- CORRECT -->
<img src="{{ theme_asset('images/logo.svg') }}" alt="Logo">
<!-- INCORRECT -->
<img src="{{ asset('themes/flexiwhite/public/images/logo.svg') }}" alt="Logo">
theme_asset() 根据当前活动主题自动解析正确的路径并处理缓存。
后续步骤
清单和布局完成后，现在可以从管理面板的外观 > 主题下激活您的主题。