Typecho 主题开发文档
1. 主题系统概述
Typecho 的主题系统基于 PHP 模板引擎，允许开发者通过创建模板文件来自定义博客的外观和布局。每个主题都是一个独立的目录，包含必要的模板文件和资源文件。
2. 主题目录结构
一个完整的 Typecho 主题通常包含以下文件和目录：
themes/
└── your-theme-name/
├── index.php # 首页模板
├── archive.php # 归档页模板（分类、标签、日期等）
├── post.php # 文章详情页模板
├── page.php # 独立页面模板
├── footer.php # 页脚模板
├── header.php # 页头模板
├── sidebar.php # 侧边栏模板
├── functions.php # 主题功能文件
├── style.css # 主题样式表
├── screenshot.png # 主题预览图
└── assets/ # 静态资源目录（CSS、JS、图片等）
3. 模板文件详解
3.1 index.php (首页模板)
这是主题的主要模板文件，用于显示首页的文章列表：
<?php if (!defined('__TYPECHO_ROOT_DIR__')) exit; ?>
<?php $this->need('header.php'); ?>
<div id="main">
<?php while($this->next()): ?>
<article class="post">
<h2><a href="<?php $this->permalink() ?>"><?php $this->title() ?></a></h2>
<div class="entry">
<?php $this->content() ?>
</div>
<p class="meta">发布时间: <?php $this->date('Y-m-d'); ?></p>
</article>
<?php endwhile; ?>
<?php $this->pageNav(); ?>
</div>
<?php $this->need('sidebar.php'); ?>
<?php $this->need('footer.php'); ?>
3.2 post.php (文章详情页)
用于显示单篇文章的详细内容：
<?php if (!defined('__TYPECHO_ROOT_DIR__')) exit; ?>
<?php $this->need('header.php'); ?>
<div id="main">
<article class="post">
<h1><?php $this->title() ?></h1>
<div class="entry">
<?php $this->content(); ?>
</div>
<p class="meta">发布时间: <?php $this->date('Y-m-d H:i'); ?></p>
</article>
<?php $this->need('comments.php'); ?>
</div>
<?php $this->need('sidebar.php'); ?>
<?php $this->need('footer.php'); ?>
3.3 archive.php (归档页)
用于显示分类、标签、日期等归档内容：
<?php if (!defined('__TYPECHO_ROOT_DIR__')) exit; ?>
<?php $this->need('header.php'); ?>
<div id="main">
<h2><?php $this->archiveTitle(); ?></h2>
<?php if ($this->have()): ?>
<?php while($this->next()): ?>
<article class="post">
<h3><a href="<?php $this->permalink() ?>"><?php $this->title() ?></a></h3>
<div class="entry">
<?php $this->excerpt(200); ?>
</div>
</article>
<?php endwhile; ?>
<?php else: ?>
<article class="post">
<h2>没有找到内容</h2>
<p>抱歉，没有找到相关内容。</p>
</article>
<?php endif; ?>
<?php $this->pageNav(); ?>
</div>
<?php $this->need('sidebar.php'); ?>
<?php $this->need('footer.php'); ?>
4. 主题功能文件 (functions.php)
functions.php 文件用于为主题添加额外的功能，如主题配置、自定义函数等：
<?php
if (!defined('__TYPECHO_ROOT_DIR__')) exit;
/**
* 主题配置函数
*/
function themeConfig($form) {
// 添加Logo URL配置
$logoUrl = new \Typecho\Widget\Helper\Form\Element\Text(
'logoUrl',
null,
null,
_t('站点LOGO地址'),
_t('在这里填入一个图片URL地址, 以在网站标题前加上一个LOGO')
);
$form->addInput($logoUrl->addRule('url', _t('请填写一个合法的URL地址')));
// 添加侧边栏显示选项
$sidebarBlock = new \Typecho\Widget\Helper\Form\Element\Checkbox(
'sidebarBlock',
[
'ShowRecentPosts' => _t('显示最新文章'),
'ShowRecentComments' => _t('显示最近回复'),
'ShowCategory' => _t('显示分类'),
'ShowArchive' => _t('显示归档'),
'ShowOther' => _t('显示其它杂项')
],
['ShowRecentPosts', 'ShowRecentComments', 'ShowCategory', 'ShowArchive', 'ShowOther'],
_t('侧边栏显示')
);
$form->addInput($sidebarBlock->multiMode());
}
/**
* 自定义文章元信息显示函数
*/
function postMeta($archive) {
?>
<ul class="post-meta">
<li>作者: <?php $archive->author(); ?></li>
<li>时间: <?php $archive->date('Y-m-d'); ?></li>
<li>分类: <?php $archive->category(','); ?></li>
<li>评论: <?php $archive->commentsNum('暂无评论', '1 条评论', '%d 条评论'); ?></li>
</ul>
<?php
}
/**
* 自定义字段添加函数
*/
function themeFields($layout) {
$logoUrl = new \Typecho\Widget\Helper\Form\Element\Text(
'logoUrl',
null,
null,
_t('自定义LOGO地址'),
_t('为这篇文章设置一个特殊的LOGO')
);
$layout->addItem($logoUrl);
}
5. 模板标签参考
5.1 基础标签
$this->title()- 显示文章标题$this->permalink()- 显示文章固定链接$this->content()- 显示文章全文$this->excerpt()- 显示文章摘要$this->date()- 显示文章发布日期$this->author()- 显示文章作者$this->category()- 显示文章分类$this->tags()- 显示文章标签
5.2 系统标签
$this->options->title()- 显示站点标题$this->options->siteUrl()- 显示站点URL$this->options->themeUrl()- 显示当前主题URL$this->options->description()- 显示站点描述$this->options->keywords()- 显示站点关键词
5.3 分页标签
$this->pageNav()- 显示分页导航$this->have()- 检查是否有内容$this->next()- 循环遍历内容
6. 主题配置
主题可以通过 functions.php 中的 themeConfig 函数提供配置界面：
function themeConfig($form) {
// 文本输入框
$textInput = new \Typecho\Widget\Helper\Form\Element\Text(
'textInput', null, '默认值', '标签文字', '描述文字'
);
$form->addInput($textInput);
// 复选框
$checkbox = new \Typecho\Widget\Helper\Form\Element\Checkbox(
'checkbox',
['option1' => '选项1', 'option2' => '选项2'],
['option1'],
'复选框标题'
);
$form->addInput($checkbox->multiMode());
// 下拉选择框
$select = new \Typecho\Widget\Helper\Form\Element\Select(
'select',
['value1' => '显示文字1', 'value2' => '显示文字2'],
'value1',
'下拉框标题'
);
$form->addInput($select);
}
7. 主题开发最佳实践
7.1 安全性
- 始终使用
<?php if (!defined('__TYPECHO_ROOT_DIR__')) exit; ?>保护模板文件 - 输出用户内容时使用
htmlspecialchars()进行转义 - 验证和过滤用户输入
7.2 性能优化
- 合理使用
$this->need()加载模板片段 - 避免在模板中执行复杂计算
- 压缩和合并CSS/JS文件
7.3 兼容性
- 遵循Typecho的模板规范
- 测试不同浏览器的兼容性
- 保持向后兼容
8. 主题发布
发布主题前需要确保：
- 主题预览图 (
screenshot.png) 存在且尺寸合适 - 主题信息在
functions.php或index.php中正确声明 - 主题在不同设备上正常显示
- 遵循Typecho的开源协议