better-staridc-MNBT
1---
2title: 主题系统总览
3description: MNBT 前端主题系统快速说明:目录结构、主题切换、架构一览与核心 API
4---
5
6# MNBT 前端主题系统
7
8MNBT 支持用户端(控制面板)与管理端(后台)独立切换主题。
9业务逻辑仍在 `user/*.php` / `admin/*.php`,**外观与页面 HTML 在 `templates/` 下**。
10
11- 本文档:快速说明、目录、切换方式
12- [主题开发手册](./guide.md):**主题开发完整手册**(新建主题、页面清单、API、约定)
13
14---
15
16## 目录结构
17
18```
19templates/
20├── active_user_theme # 当前用户端主题目录名(纯文本)
21├── active_admin_theme # 当前管理端主题目录名(纯文本)
22└── default/ # 官方默认主题
23 ├── theme.json # 主题元信息
24 ├── user/ # 用户控制面板视图
25 │ ├── head.php
26 │ ├── login.php
27 │ ├── index.php
28 │ ├── sy.php
29 │ ├── set.php
30 │ ├── ...
31 │ └── assets/ # 主题私有 CSS/JS/图片
32 └── admin/ # 管理后台视图
33 ├── head.php
34 ├── login.php
35 ├── index.php
36 ├── set.php
37 ├── ...
38 └── assets/
39```
40
41自定义主题示例:
42
43```
44templates/my_skin/
45├── theme.json
46├── user/ # 可只放要覆盖的页面
47│ └── login.php
48└── admin/
49 └── login.php
50```
51
52官方扩展主题:
53
54| 主题 | 说明 |
55|------|------|
56| `default` | 默认(jQuery + Bootstrap) |
57
58未提供的页面会**自动回退**到 `templates/default/` 同名文件。
59
60---
61
62## 切换主题
63
64### 1. 后台界面(推荐)
65
66管理后台 → **系统管理** → **前端模板** → 选择用户端 / 管理端主题 → 保存
67
68对应页面:`admin/set.php?gn=theme`
69
70### 2. 配置文件
71
72编辑(内容仅为主题目录名,如 `default`):
73
74- `templates/active_user_theme`
75- `templates/active_admin_theme`
76
77### 3. 数据库(可选)
78
79若 `MN_config` 表存在字段 `usertheme` / `admintheme`,则**优先于文件**读取。
80保存主题时会尝试写入这两个字段(字段不存在则忽略,不影响文件切换)。
81
82### 优先级
83
84```
85MN_config.usertheme / admintheme
86 → active_user_theme / active_admin_theme
87 → default
88```
89
90---
91
92## 架构一览
93
94```
95浏览器请求 user/sy.php
96 │
97 ▼
98user/sy.php(控制器)
99 · include MPHX/common.php
100 · 登录校验 / 取数据
101 · mnbt_render('sy')
102 │
103 ▼
104MPHX/theme.php
105 · 解析当前主题 + fallback
106 │
107 ▼
108templates/{theme}/user/sy.php(视图)
109 · mnbt_theme_include('head')
110 · HTML / CSS / JS
111```
112
113管理端同理,使用 `mnbt_admin_render()` / `mnbt_admin_include()`。
114
115---
116
117## 核心 API(`MPHX/theme.php`)
118
119| 函数 | 用途 |
120|------|------|
121| `mnbt_render($view, $vars=[], $exit=true, $scope='user')` | 渲染视图 |
122| `mnbt_admin_render($view, ...)` | 渲染管理端视图 |
123| `mnbt_theme_include($view, $vars=[], $scope='user')` | 引入局部模板(如 head) |
124| `mnbt_admin_include($view, ...)` | 管理端局部模板 |
125| `mnbt_theme_url($path, $scope)` | 主题内静态资源 URL(缺文件回退 default) |
126| `mnbt_theme_asset($path, $scope)` | 主题 `assets/` 快捷 URL |
127| `mnbt_asset_url($path)` | 公共资源 `imsetes/` URL(不随主题切换) |
128| `mnbt_theme_list($scope)` | 扫描已安装主题 |
129| `mnbt_theme_set_active($scope, $name)` | 切换当前主题 |
130| `mnbt_theme_name($scope)` | 当前主题名 |
131
132详细参数与示例见 [主题开发手册](./guide.md)。
133
134---
135
136## 权限与安全
137
138- 主题目录名仅允许:`a-z A-Z 0-9 _ -`
139- 禁止路径穿越(`..`)
140- 主题内 PHP 与站点同权限运行,**不要**安装不可信第三方主题
141- 建议仅站长上传主题包;`templates/` 目录需可写(用于 `active_*` 文件)
142
143---
144
145## 相关代码位置
146
147| 路径 | 说明 |
148|------|------|
149| `MPHX/theme.php` | 主题引擎 |
150| `MPHX/common.php` | 自动加载 theme.php |
151| `user/*.php` / `admin/*.php` | 控制器入口 |
152| `admin/api/setting.php` | `settheme` 保存接口 |
153| `imsetes/` | 公共前端静态资源(Bootstrap 等) |