Zsens Admin前端主题模板开发教程及注意事项~

张先生主理

社区管理

置顶精华Ⅰ 部署教程 176 浏览 1 回复

本文说明如何为 Zsens Admin（社区前台）开发 模板主题。模板主题与「应用插件」、社区自带「配色」是三层不同的东西，请勿混用。

1. 概念区分

类型	是什么	放哪里	后台入口
应用插件	功能扩展（消息、封禁、积分商城等）	`plugins/插件名/`	应用中心 → 应用插件
模板主题	前台皮肤：HTML + CSS + JS	`themes/主题名/`	应用中心 → 模板主题
配色	ink / blue 等 CSS 变量色板	community 配置	非主题包

要点：

主题包 plugin.json 必须 type: "theme"，否则会被当成普通插件。
主题安装后默认 不启用，需在「模板主题」页手动启用。
同一宿主（目前为 community）同时只能启用一套主题。
未启用主题时，前台使用社区插件自带视图。

2. 目录规范

主题必须放在站点根目录的 themes/ 下，不要放进 plugins/。

themes/
└── my-theme/                 # 目录名 = plugin.json 的 name
    ├── plugin.json           # 必填：包元数据
    ├── theme.json            # 推荐：资源与覆盖说明
    ├── ThemePlugin.php       # 必填：入口类（entry）
    ├── icon.svg              # 推荐：后台列表图标
    ├── preview.png           # 推荐：后台预览图（也可用 jpg/webp）
    ├── static/
    │   ├── theme.css         # 前台样式（可在 theme.json 改名）
    │   └── theme.js          # 前台脚本
    └── view/
        └── front/            # 只放需要覆盖的模板
            ├── index.html
            ├── topic.html
            ├── member.html
            └── …

打包上传 / 上架市场时：将 my-theme/ 目录打成 zip（zip 根下可以是一层目录，内含 plugin.json）。

3. plugin.json（必填）

{
  "name": "my-theme",
  "title": "我的主题",
  "version": "1.0.0",
  "author": "你的名字",
  "description": "一句话介绍",
  "icon": "mdi-palette",
  "tag": "主题",
  "type": "theme",
  "host": "community",
  "namespace": "plugins\\mytheme",
  "require": {
    "community": ">=1.0.0"
  },
  "entry": "ThemePlugin"
}

字段	说明
`name`	包标识，须与目录名一致，仅 `a-zA-Z0-9_-`
`type`	`必须是 theme`
`host`	宿主应用，目前固定 `community`
`require.community`	依赖社区插件；未安装/未启用社区时主题无法启用
`namespace`	PHP 命名空间。目录名含 `-` 时必须手写（连字符不能当命名空间）
`entry`	入口类名，对应根目录 `ThemePlugin.php`

常见错误：

忘记写 "type": "theme" → 会出现在应用插件里，或安装到错误目录。
name 与文件夹名不一致 → 安装/启用失败。
只有 namespace: "plugins\\theme-xxx"（含 -）→ 类无法加载。

4. theme.json（推荐）

{
  "host": "community",
  "compatible_community": ">=1.0.0",
  "css": "theme.css",
  "js": "theme.js",
  "disable_color_picker": true,
  "covers": [
    "index.html",
    "topic.html",
    "member.html"
  ]
}

字段	说明
`css` / `js`	相对 `static/` 的文件名，启用后注入前台
`disablecolorpicker`	`true` 时建议隐藏社区配色切换（完整皮肤自管颜色）
`covers`	文档用：列出本主题覆盖了哪些前台模板（便于维护）

静态资源安装后会出现在：/static/{主题名}/theme.css、theme.js（带版本号缓存参数）。

5. 入口类 ThemePlugin.php

最小实现示例：

<?php
declare(strict_types=1);

namespace plugins\mytheme;

use app\service\PluginService;

class ThemePlugin
{
    public function name(): string
    {
        return 'my-theme';
    }

    public function install(): void
    {
        PluginService::copyStaticAssets('my-theme');
    }

    public function uninstall(): void
    {
        PluginService::removeStaticAssets('my-theme');
    }
}

说明：

namespace 必须与 plugin.json 一致。
install / uninstall 负责静态资源复制与清理。
可选：实现 renderAssets() 在启用时追加额外 HTML/脚本（见 theme-aurora）。

6. 视图覆盖机制（最重要）

启用主题后，系统会：

复制宿主 plugins/community/view/front/ 全量到运行时目录

runtime/theme_front/{主题名}/

再用主题的 view/front/ 覆盖同名文件
前台 view_path 指向该合并目录

因此：

只需覆盖要改的页面，其余自动沿用社区自带模板。
主题里没有的文件（如 layout.html）会继续用社区版本。
改主题模板或启用/停用后，会重建合并目录；若前台仍旧，可清 runtime/theme_front/ 与页面缓存后再试。

常用可覆盖模板（社区）

按需覆盖，名称需与社区 view/front/ 一致，例如：

layout.html — 整站骨架（谨慎改，缺文件会回退）
index.html — 首页信息流
topic.html — 帖子详情
member.html / memberprofile.html / membertopics.html / member_coins.html — 会员中心
plazaleft.html / plazaaside.html — 首页左右栏
memberside.html — 会员侧栏
skinbanner.html — 主题横幅插槽（社区 layout 在启用主题时 include）
user.html — 用户主页（若社区有该模板）

模板引擎与社区相同（Think 模板）。变量、URL 助手、权限判断请保持与社区模板兼容，避免删掉必要钩子/插槽。

7. CSS / JS 开发建议

提高选择器优先级再改布局

社区 base.css 里的 .layout-triple 等规则会影响左栏/主栏宽度。主题应用 !important 或更高优先级覆盖，不要在 JS 里随意去掉 layout-triple，否则左栏可能被隐藏。

对齐顶栏与内容区宽度

注意社区 .xn-page 水平 padding；主题若做三栏，需统一内容最大宽度，避免「顶栏一条、内容错位」。

会员中心 / 用户页

会员页可能有 max-width 或 order 与主题网格冲突；用户主页若无 xn-grid，需在主题 CSS 中单独适配。

改 CSS/JS 后 bump 版本号

plugin.json 的 version 会拼到静态资源 ?v= 上，便于刷新缓存。

配色层

若主题已自带完整色板，建议 disablecolorpicker: true，避免与社区 ink/blue 切换打架。

8. 本地开发流程

在站点根目录创建 themes/my-theme/，按上文放好文件。
确认已安装并启用 community。
打开后台 应用中心 → 模板主题：

- 本地包显示「安装」→ 安装成功后点「启用」；或

- 使用「上传主题」选择 zip 安装。

前台强制刷新（Ctrl+F5）查看效果。
修改 view/front 后：重新启用一次主题，或删除 runtime/theme_front/my-theme/ 再访问。
修改 static/ 后：可再执行安装/启用以复制静态文件，并升高 version。

停用主题后，前台恢复社区自带皮肤；卸载会移除包记录与静态资源（请先停用再卸载）。

9. 打包与上架

本地上传

后台「模板主题」→ 上传主题（zip）。
zip 内须能读到 plugin.json，且 type=theme。
系统会解压到 themes/{name}/（不会进 plugins/）。

应用市场

购买/下载流程与插件类似，安装目录仍为 themes/。

zip 注意

支持一层目录包裹（my-theme/plugin.json）。
不要把 runtime/、.git、node_modules 打进去。
预览图文件名：preview.png / preview.jpg / preview.webp（优先于 icon.svg 作为卡片图）。

10. 注意事项清单（必看）

目录是 themes/，不是 plugins/。
type 必须为 theme，host 为 community。
目录名含 - 时必须配置合法 namespace（去掉连字符）。
安装 ≠ 启用；启用前社区插件必须可用。
同宿主只能启用一个主题；启用新主题会停用旧主题。
只覆盖需要改的 HTML；合并以宿主为底，主题覆盖其上。
慎改 layout.html；改坏可能导致整站空白，可删合并缓存回退排查。
布局冲突优先查 base.css 的 grid / layout-triple / max-width。
游客页若开了整页缓存，换肤后可能看到旧 HTML；启用/停用主题会尝试清缓存，仍异常时清 runtime 相关缓存。
不要把主题逻辑写进普通功能插件；也不要把功能插件 type 写成 theme。
客户端升级包需带上主题相关核心能力后，站点才支持 themes/；纯旧版客户端无主题入口。

11. 快速对照：从零到启用

1. 复制 themes/theme-aurora → themes/my-theme
2. 改 plugin.json：name / title / namespace / version
3. 改 ThemePlugin.php 命名空间与内部主题名字符串
4. 改 view/front、static 做出自己的视觉
5. 后台「模板主题」→ 安装 → 启用
6. 前台验收首页 / 帖子 / 会员中心 / 用户页

完成以上步骤后，即可作为本地主题使用，或打成 zip 上传 / 提交应用市场（类型选主题）。