主题开发
文件结构（主题）
以下基于通过「创建应用」生成的初始文件：
/path/zb_users/theme/demoTheme
│ screenshot.png [必需]缩略图 320*240像素, 横向；
│ theme.xml [必需]自述文件；
│ main.php [可选]应用内置管理页，在创建主题时填写才会生成；
│ include.php [可选]应用嵌入页，在创建主题时填写才会生成；
│
├─compile [废弃]旧版 z-blog 用于放置模板编译文件，可直接删除；
├─include [可选]主题自带「文件模块」，使用{module:abc}「嵌入调用」该目录下的abc.php文件；
├─script [可选]JS目录；
├─style [必需]样式目录, 内存样式表及所需图片；
│ style.css [必需]不限于这个文件名，一套主题也可以拥有多个样式（各自独立使用）；
│
├─css [可选]并不会自动创建，用于不应该放在style文件夹中的样式内容；
└─template 用于存放模板文件；建议优先确立以下 6 个模板文件及内容；
index.php 首页及列表页
single.php 文章页(单页)
search.php 搜索结果页，不存在时使用index.php
header.php 公共头部文件
footer.php 公共尾部文件
404.php 建议设置主入口模板
默认情况下，系统只会尝试直接调用index.php、single.php、search.php、404.php四个模板文件（如果存在的话）；
其他模板则通过「嵌入调用」组合其自身内容到「主模板」之中；
示例
理论上可以直接使用如下示例作为四个「主模板」文件的基础结构；「
Your Code部分除外」；{template:header}{template:footer}{template:sidebar}为「Z-BlogPHP 体系内」常用模板，{template:hero}则可自由命名，用于拆分相应位置的代码；「模板书写 - 嵌入调用」关于「模板描述信息」「嵌入调用」「变量输出标签」等部分的详情，参见：「模板书写」
{* Template Name: 首页及列表页 * Template Type: index|list *}
<!-- ↑ 「模板描述信息」，包括适配的「页面类型」，放在模板文件第一行 -->
<!DOCTYPE html>
<html lang="{$language}"><!-- {$language} 为「变量输出标签」 -->
<head>
{template:header}<!-- 公共头部文件 -->
</head>
<body class="{$type}"><!-- 同为「变量输出标签」，对应上方 Template Type -->
{template:hero}
<!-- ↓Your Code↓ -->
<!-- ↓Your Code↓ -->
<div id="divNavBar">
<!-- 导航「模块」调用 -->
<ul>{module:navbar}</ul>
</div>
<div id="divMiddle">
<div id="divMain">列表索引或正文内容</div>
<!-- 「侧栏」调用 -->
<div id="divSidebar">{template:sidebar}</div>
</div>
<!-- ↑Your Code↑ -->
<!-- ↑Your Code↑ -->
{template:footer}<!-- 公共尾部文件 -->
</body>
</html>模板文件及缺省机制
因为「保留模板」机制，当主题未提供某一模板文件时，系统会从
zb_system/defend/default中读取使用；「在线查看」因此可以缺省部分不需要自定义内容结构的模板文件，尤其是「侧栏模块相关」的部分；
页面公共模板文件
| 模板文件 | 说明 |
|---|---|
| header.php | 公共头部文件 |
| footer.php | 公共尾部文件 |
首页与列表页相关模板
| 模板文件 | 说明 |
|---|---|
| index.php | 首页及列表页主模板文件 |
| post-multi.php | 摘要文章模板 |
| post-istop.php | 置顶文章模板 |
| pagebar.php | 页码模板 |
日志/独立页相关模板
post-single.php
| 模板文件 | 说明 |
|---|---|
| single.php | 文章页(单页)主模板文件 |
| 日志页文章模板 | |
| post-page.php | 独立页面模板 |
| comments.php | 评论区模板 |
| comment.php | 每条评论内容显示模板 |
| commentpost.php | 评论发送表单模板 |
| commentpost-verify.php | 评论验证码模板（1.5 新增） |
侧栏模块相关模板
模块展现外框架模板
| 模板文件 | 说明 |
|---|---|
| sidebar.php | 默认侧栏模板，可自定义 sidebar2.php~`sidebar9.php` 用于后续侧栏调用 |
| module.php | 模块显示模板，可定义模块标题等格式，模块具体内容格式由下列细节模板决定 |
模块内容细节模板（1.5 版本及以上）
| 模板文件 | 说明 | 备注（默认列表行数） |
|---|---|---|
| module-archives.php | 文章归档模块 | 没有限制 |
| module-authors.php | 作者列表模块 | 没有限制 |
| module-calendar.php | 日历模块 | 没有限制 |
| module-catalog.php | 分类列表模块 | 没有限制 |
| module-navbar.php | 导航条模块 | 没有限制 |
| module-statistics.php | 站点信息模块 | 没有限制 |
| module-comments.php | 最近评论列表模块 | 10条 |
| module-previous.php | 最近文章列表模块 | 10条 |
| module-tags.php | 标签列表模块 | 25条 |
模板书写
描述信息（可选）
模板内注释语法（推荐）
放在模板文件第一行：
{* Template Name:「模板用途描述」 *}可以同时声明模板类型（针对「主入口模板」）：
{* Template Name: 首页及列表页 * Template Type: index|list *}注：「描述信息」和「类型声明」的必要性仅体现在
同一「页面类型」有多个「入口模板」可供用户选择时的选项输出，或者针对不同「页面类型」细化建立了不同的模板文件。对于后者需要自行实现判断调用，或引导用户选择设置。重要：在
{}内部，*与其他内容之间要有空格；- index 首页 - list 列表页 - author - category - date - tag - single 单页面（含文章与页面） - article - page - search 搜索 - 404 404 - none 显示设置隐藏
1.7.0 以后支持 template.json 配置
template.json示例：（点击展开）
{ "id": "主题ID", "templates": [ { "filename": "index", "type": "list", "name": "列表自动模板" }, { "filename": "single", "type": "single", "name": "文章/单页自动模板" } ] }
嵌入调用
嵌入模板文件
{template:hearder}- 嵌入模板文件 hearder.php 的文件内容。「嵌入调用示例」
嵌入模块内容
{module:navbar}- 嵌入「导航栏模块」注：除
include文件夹内的「文件模块」外其他模块其实是存在数据库的，另外不建议使用「文件模块」，主题更新时用户修改的内容会被覆盖。「模块」或者说「侧栏模块」，一般是指 「后台管理」→
模块管理中列出的项目；navbar为「导航栏模块」的「filename(文件名)」，其他「模块」同理；
模板标签
在「模板文件示例」示例中使用了{$language}和{$type}两个语法标签，称为「变量输出标签」或「模板标签」，实际会编译为<?php echo $language;?>和<?php echo $type;?>来输出对应变量的值；
在 Z-BlogPHP 模板中，可通过{$var}、{$obj.a}来输出「文本或数字类型」的「变量或对象属性」，其中后者会编译为<?php echo $obj->a;?>；
注：
部分标签只能在特定的页面类型（
$type取值）或上下文中才能使用；{module:navbar}可视为{$modules["navbar"].Content}的简写语法；除系统标签外，可通过「接口机制」或「原生 PHP 语法①」自定义或修改作为标签输出的变量；
模板内使用 PHP
在相应内容输出前，可以使用如下语法额外对数据进行处理；
{php}
// 这里可以写原生 PHP；
$myVar = "变量值";
{/php}
<p>输出一个自定义变量：{$myVar}</p>
<p>当前 Z-BlogPHP 版本是：{$version}</p>
//还可以用<?php ?>符号在{php}{/php}里以实现代码高亮
{php}<?php
//原生php代码
?>{/php}有用吗？
2025-10-09 14:07:45