better-staridc-MNBT
1---
2title: 主页主题开发
3description: "主页主题(scope: home)开发说明：新建主题、自定义设置字段注册、模板读取、持久化与扩展区块"
4---
5
6# 主页主题开发(V1.84)
7
8独立主页系统是 V1.84 引入的核心功能,使主页(站点根路径 `/`)脱离插件依赖,成为可独立切换的第四主题 scope(`home`)。主页视图清单速览见 [视图清单 §3.5](./views.md#35-主页-templatesthemehomev184-新增),本文是完整开发说明。
9
10## 15.1 概述
11
12**核心机制**:
13- 主页模板:`templates/{主题}/home/index.php`(缺页回退 `default`)
14- 主题切换:后台「前端模板」→ 主页主题下拉(与用户端/管理端独立)
15- 内容配置:后台「前端模板」→ 主页内容(标题、Hero、主色、Logo 等通用设置)
16- 自定义设置:主题通过 `theme.php` 声明字段,后台自动渲染并持久化
17
18> **tdesign 主题已支持 home scope**(v0.3.0):其主页为独立 SPA 售卖前端,
19> 通过插件 API 路由(`/index.php?_r=/shop/api/*` 等)驱动 `user_info` / `balance` / `hosting_shop` 页面,
20> 另含官网内容页面(关于我们/产品/新闻/联系我们,由 `official_site` 插件 `GET /site/api/*` 驱动,
21> `boot.hasSite` 能力字段控制导航与路由可见性),详见 [TDesign 三端主题](./tdesign.md) 与 [与 PHP 的对接](./tdesign-php.md#主页入口映射home-scope)。
22
23## 15.2 新建主页主题
24
25**目录结构**:
26
27```text
28templates/
29└── my_home/
30 ├── theme.json # 主题元信息(可选)
31 ├── theme.php # 注册自定义设置字段声明
32 └── home/
33 ├── index.php # 主页落地页模板(必选)
34 └── assets/ # 静态资源(可选)
35 └── style.css
36```
37
38**最小配置**:只需 `home/index.php` 即可被识别为主页主题,在后台「前端模板 → 主页主题」下拉中显示。
39
40## 15.3 注册自定义设置(theme.php)
41
42主题通过 `mnbt_register_home_setting()` 声明设置字段,**不需要写 HTML**——渲染由当前 Admin 主题负责。
43
44```php
45<?php
46// templates/my_home/theme.php
47if (!defined('IN_CRONLITE')) exit;
48
49mnbt_register_home_setting([
50 'key' => 'bg_color',
51 'label' => '背景颜色',
52 'type' => 'color',
53 'default' => '#f0f4ff',
54 'placeholder' => '#f0f4ff',
55 'hint' => '主页 body 背景色',
56]);
57
58mnbt_register_home_setting([
59 'key' => 'hero_style',
60 'label' => '标题风格',
61 'type' => 'select',
62 'default' => 'large',
63 'options' => [
64 ['value' => 'small', 'label' => '小号'],
65 ['value' => 'medium', 'label' => '中号'],
66 ['value' => 'large', 'label' => '大号'],
67 ],
68 'hint' => 'Hero 标题字号',
69]);
70
71mnbt_register_home_setting([
72 'key' => 'show_badge',
73 'label' => '显示徽章',
74 'type' => 'switch',
75 'default' => true,
76]);
77
78mnbt_register_home_setting([
79 'key' => 'footer_msg',
80 'label' => '页脚消息',
81 'type' => 'textarea',
82 'placeholder' => '可选自定义内容',
83]);
84```
85
86**支持的字段类型**:
87
88| type | 渲染组件 | default 后台 | tdesign 后台 |
89|------|----------|-------------|-------------|
90| `text` | 文本输入框 | `<input class="form-control">` | `<t-input>` |
91| `color` | 色盘 + 文本输入 | `<input type="color">` + `<input>` | `<input type="color">` + `<t-input>` |
92| `select` | 下拉选择 | `<select class="form-control">` | `<t-select>` |
93| `switch` | 开关 | Bootstrap `.custom-switch` | `<t-switch>` |
94| `textarea` | 多行文本 | `<textarea class="form-control">` | `<t-textarea>` |
95| `number` | 数字输入 | `<input type="number">` | `<t-input type="number">` |
96
97**字段参数**:
98
99| 参数 | 必填 | 说明 |
100|------|------|------|
101| `key` | 是 | 唯一标识符,`/^[a-zA-Z_][a-zA-Z0-9_]+$/`,用于模板读取和持久化 |
102| `label` | 是 | 显示标签 |
103| `type` | 否 | 组件类型,默认 `text` |
104| `default` | 否 | 默认值(switch 默认 `false`) |
105| `placeholder` | 否 | 占位文本 |
106| `hint` | 否 | 字段下方的提示说明 |
107| `options` | select 专用 | `[['value'=>'', 'label'=>''], ...]` |
108
109## 15.4 模板中读取设置值
110
111使用 `mnbt_home_theme_setting($key, $default)` 读取已保存的主题自定义设置:
112
113```php
114<?php
115// templates/my_home/home/index.php
116$bgColor = function_exists('mnbt_home_theme_setting') ? mnbt_home_theme_setting('bg_color', '#fff') : '#fff';
117$heroStyle = function_exists('mnbt_home_theme_setting') ? mnbt_home_theme_setting('hero_style', 'large') : 'large';
118$showBadge = function_exists('mnbt_home_theme_setting') ? mnbt_home_theme_setting('show_badge', true) : true;
119$footerMsg = function_exists('mnbt_home_theme_setting') ? mnbt_home_theme_setting('footer_msg', '') : '';
120?>
121<!DOCTYPE html>
122<html>
123<head>
124 <title><?= htmlspecialchars($site_title) ?></title>
125 <style>
126 body { background: <?= htmlspecialchars($bgColor) ?>; }
127 h1 { font-size: <?= $heroStyle === 'small' ? '1.4rem' : ($heroStyle === 'medium' ? '2rem' : '2.8rem') ?>; }
128 </style>
129</head>
130<body>
131 <h1><?= htmlspecialchars($site_hero) ?></h1>
132 <?php if ($showBadge): ?><div class="badge">推荐</div><?php endif; ?>
133 <?php if ($footerMsg): ?><footer><?= htmlspecialchars($footerMsg) ?></footer><?php endif; ?>
134</body>
135</html>
136```
137
138## 15.5 持久化
139
140所有自定义字段统一保存在 `MN_config.home_theme_settings`(JSON 列),切换主题后设置保留。主题重新切回来时值仍在。
141
142## 15.6 扩展区块
143
144主页模板可通过 `$blocks` 变量渲染插件注入的扩展区块:
145
146```php
147<?php foreach ($blocks as $block): ?>
148<section class="sec">
149 <?php if (!empty($block['title'])): ?>
150 <h2><?= htmlspecialchars($block['title']) ?></h2>
151 <?php endif; ?>
152 <?= $block['html'] ?>
153</section>
154<?php endforeach; ?>
155```
156
157插件通过 `mnbt_add_filter('home.blocks', callback)` 注入区块。
158
159## 15.7 启用
160
1611. 将主题文件夹放入 `templates/`
1622. 后台 → 系统设置 → 前端模板 → 主页主题下拉 → 选择 `my_home` → 保存
1633. 主页内容区域的通用设置和主题自定义字段均可在此面板中配置
1644. 访问站点 `/` 即可看到效果
165
166## 15.8 相关文件索引
167
168| 文件 | 职责 |
169|------|------|
170| `MPHX/frontend.php` | 主页引擎(分发、数据组装、字段注册 API、default 渲染器) |
171| `MPHX/theme.php` | `home` scope 注册(`mnbt_theme_name/list/set_active`) |
172| `index.php` | 请求分发入口(`mnbt_home_dispatch` 调用点) |
173| `templates/default/home/index.php` | 内置默认主页模板 |
174| `templates/tdesign/home/index.php` | tdesign 主页入口(加载 home SPA,注入 `__TD_BOOT__`) |
175| `templates/tdesign/spa/src/home/` | tdesign home SPA 源码(路由/API/视图/样式) |
176| `templates/default/admin/set.php` | default 后台渲染器(`gn=theme`) |
177| `templates/tdesign/spa/src/admin/views/settings/ThemeView.vue` | tdesign 后台渲染器 |
178| `templates/tdesign/admin/_spa_boot.php` | tdesign boot 数据注入 |
179| `admin/api/setting.php` | `save_home_settings` / `home_upload_icon` / `settheme(hometheme)` 接口 |
180| `install/install.sql` | `MN_config.home_*` 字段定义 |
181| `update/update_v184_home.sql` | 增量升级 SQL |