Typecho主题完整API文档

default/
├── 404.php              # 404错误页面
├── comments.php         # 评论模块
├── footer.php           # 页脚模块
├── functions.php        # 主题配置与自定义函数
├── header.php           # 页头模块
├── index.php            # 首页/文章列表
├── page.php             # 独立页面
├── post.php             # 文章详情页
├── sidebar.php          # 侧边栏
├── style.css            # 主题样式
├── grid.css             # 网格布局样式
├── normalize.css        # CSS重置样式
├── screenshot.png       # 主题缩略图
└── img/                 # 图片资源目录

<?php if ($this->is('post')): ?>
    <!-- 文章单页内容 -->
<?php elseif ($this->is('page')): ?>
    <!-- 独立页面内容 -->
<?php elseif ($this->is('category', 'default')): ?>
    <!-- 默认分类内容 -->
<?php endif; ?>

<?php if ($this->have()): ?>
    <?php while ($this->next()): ?>
        <!-- 文章内容 -->
        <h2><?php $this->title() ?></h2>
        <div><?php $this->content() ?></div>
    <?php endwhile; ?>
<?php else: ?>
    <h2>没有找到内容</h2>
<?php endif; ?>

$archive->author();              // 输出作者名
$archive->author->permalink();   // 输出作者链接

// 显示全部（默认）
\(this->comments()->to(\)comments);

// 只显示评论
\(this->comments('comment')->to(\)comments);

// 只显示引用通告
\(this->comments('trackback')->to(\)trackbacks);

// 只显示引用通知
\(this->comments('pingback')->to(\)pingbacks);

// 默认：站点名称 » 页面标题
<?php \(this->options->title(); ?><?php \)this->archiveTitle(); ?>

// 自定义：页面标题 - 站点名称
<?php \(this->archiveTitle('', '', ' - '); ?><?php \)this->options->title(); ?>

<?php \(this->related(5)->to(\)relatedPosts); ?>
<ul>
    <?php while ($relatedPosts->next()): ?>
    <li><a href="<?php \(relatedPosts->permalink(); ?>" title="<?php \)relatedPosts->title(); ?>">
        <?php $relatedPosts->title(); ?>
    </a></li>
    <?php endwhile; ?>
</ul>

<?php function threadedComments(\(comments, \)options) {
    $commentClass = '';
    if ($comments->authorId) {
        if (\(comments->authorId == \)comments->ownerId) {
            $commentClass .= ' comment-by-author';  // 文章作者的评论
        } else {
            $commentClass .= ' comment-by-user';     // 已登录用户的评论
        }
    }
    \(commentLevelClass = \)comments->levels > 0 ? ' comment-child' : ' comment-parent';
?>

<li id="li-<?php $comments->theId(); ?>" class="comment-body<?php 
if ($comments->levels > 0) {
    echo ' comment-child';
    $comments->levelsAlt(' comment-level-odd', ' comment-level-even');
} else {
    echo ' comment-parent';
}
$comments->alt(' comment-odd', ' comment-even');
echo $commentClass;
?>">
    <div id="<?php $comments->theId(); ?>">
        <div class="comment-author">
            <?php $comments->gravatar('40', ''); ?>
            <cite class="fn"><?php $comments->author(); ?></cite>
        </div>
        <div class="comment-meta">
            <a href="<?php \(comments->permalink(); ?>"><?php \)comments->date('Y-m-d H:i'); ?></a>
            <span class="comment-reply"><?php $comments->reply(); ?></span>
        </div>
        <?php $comments->content(); ?>
    </div>
<?php if ($comments->children) { ?>
    <div class="comment-children">
        <?php \(comments->threadedComments(\)options); ?>
    </div>
<?php } ?>
</li>
<?php } ?>

<nav id="nav-menu" class="clearfix" role="navigation">
    <a<?php if ($this->is('index')): ?> class="current"<?php endif; ?>
        href="<?php $this->options->siteUrl(); ?>">首页</a>
    <?php \Widget\Contents\Page\Rows::alloc()->to($pages); ?>
    <?php while ($pages->next()): ?>
        <a<?php if (\(this->is('page', \)pages->slug)): ?> class="current"<?php endif; ?>
            href="<?php $pages->permalink(); ?>"
            title="<?php \(pages->title(); ?>"><?php \)pages->title(); ?></a>
    <?php endwhile; ?>
</nav>

<ul>
    <?php \Widget\Comments\Recent::alloc()->to($comments); ?>
    <?php while ($comments->next()): ?>
        <li>
            <a href="<?php \(comments->permalink(); ?>"><?php \)comments->author(false); ?></a>: 
            <?php $comments->excerpt(35, '...'); ?>
        </li>
    <?php endwhile; ?>
</ul>

// 方法一：使用listCategories
<?php \Widget\Metas\Category\Rows::alloc()->listCategories('wrapClass=widget-list'); ?>

// 方法二：使用parse（带描述）
<?php \Widget\Metas\Category\Rows::alloc()
    ->parse('<li><a href="{permalink}" title="{description}">{name}</a> ({count})</li>'); ?>

// 方法三：获取分类描述
<?php echo $this->getDescription(); ?>

<?php 
\(this->widget('Widget_Archive@myCustomCategory', 'type=category', 'mid=1')->to(\)categoryPosts); 
if ($categoryPosts->have()):
    while ($categoryPosts->next()): 
        // 显示文章
        <a href="<?php \(categoryPosts->permalink(); ?>"><?php \)categoryPosts->title(); ?></a>
    endwhile;
endif;
?>

function themeInit($archive) {
    if ($archive->is('category', 'jobs')) {
        $archive->parameter->pageSize = 10;  // 自定义分类文章显示条数
    }
}

new \Typecho\Widget\Helper\Form\Element\Text(
    'name',           // 字段名
    null,             // 值
    null,             // 默认值
    _t('标题'),       // 标签
    _t('描述')        // 说明
)

$logoUrl = new \Typecho\Widget\Helper\Form\Element\Text(
    'logoUrl',
    null,
    null,
    _t('站点 LOGO 地址'),
    _t('在这里填入一个图片 URL 地址, 以在网站标题前加上一个 LOGO')
);
\(form->addInput(\)logoUrl->addRule('url', _t('请填写一个合法的URL地址')));

new \Typecho\Widget\Helper\Form\Element\Checkbox(
    'name',           // 字段名
    [                 // 选项
        'ShowRecentPosts'    => _t('显示最新文章'),
        'ShowRecentComments' => _t('显示最近回复'),
        'ShowCategory'       => _t('显示分类'),
        'ShowArchive'        => _t('显示归档'),
        'ShowOther'          => _t('显示其它杂项')
    ],
    ['ShowRecentPosts', 'ShowRecentComments'], // 默认选中
    _t('侧边栏显示')  // 标签
)

$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());

<?php
if (!defined('__TYPECHO_ROOT_DIR__')) exit;

function themeConfig($form)
{
    // Logo设置
    $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());
}
?>

<?php
/**
 * 自定义首页模板
 *
 * @package index
 */
?>

<?php
/**
 * 自定义页面模板
 *
 * @package custom
 */
?>

<?php if ($this->is('category', 'default')): ?>
    <!-- 默认分类模板 -->
<?php endif; ?>
<?php if ($this->is('category', 'category2')): ?>
    <!-- 分类2模板 -->
<?php endif; ?>

<div class="crumbs_patch">
    <a href="<?php $this->options->siteUrl(); ?>">首页</a> &raquo;
    <?php if ($this->is('index')): ?>
        最新文章
    <?php elseif ($this->is('post')): ?>
        <?php \(this->category(); ?> &raquo; <?php \)this->title() ?>
    <?php else: ?>
        <?php $this->archiveTitle(' &raquo; ', '', ''); ?>
    <?php endif; ?>
</div>

<?php \(this->related(5)->to(\)relatedPosts); ?>
<ul>
    <?php while ($relatedPosts->next()): ?>
    <li><a href="<?php \(relatedPosts->permalink(); ?>" title="<?php \)relatedPosts->title(); ?>">
        <?php $relatedPosts->title(); ?>
    </a></li>
    <?php endwhile; ?>
</ul>

<!-- 只显示评论 -->
<?php \(this->comments('comment')->to(\)comments); ?>
<?php if ($comments->have()): ?>
    <h3>评论</h3>
    <ol>
        <?php while ($comments->next()): ?>
        <li id="<?php $comments->theId() ?>">
            <div class="comment_data">
                <?php $comments->gravatar(32, '', '', 'avatar'); ?>
                <span><?php $comments->author() ?></span> 说:<br />
                <?php \(comments->date('F jS, Y'); ?> at <?php \)comments->date('h:i a'); ?>
            </div>
            <div class="comment_text"><?php $comments->content() ?></div>
        </li>
        <?php endwhile; ?>
    </ol>
<?php endif; ?>

<!-- 只显示Pingback -->
<?php \(this->comments('pingback')->to(\)pingbacks); ?>
<?php if ($pingbacks->have()): ?>
    <h3>Pingbacks</h3>
    <ol>
        <?php while ($pingbacks->next()): ?>
            <li id="<?php $pingbacks->theId() ?>">
                <?php \(pingbacks->author() ?> <?php \)pingbacks->date('F jS, Y'); ?>
            </li>
        <?php endwhile; ?>
    </ol>
<?php endif; ?>

<div class="post-meta">
    <li>作者: <a href="<?php \(archive->author->permalink(); ?>"><?php \)archive->author(); ?></a></li>
    <li>时间: <time datetime="<?php \(archive->date('c'); ?>"><?php \)archive->date(); ?></time></li>
    <li>分类: <?php $archive->category(','); ?></li>
    <li>评论: <a href="<?php \(archive->permalink() ?>#comments"><?php \)archive->commentsNum(_t('暂无评论'), _t('1 条评论'), _t('%d 条评论')); ?></a></li>
</div>

<!-- 最新文章 -->
<section class="widget">
    <h3 class="widget-title">最新文章</h3>
    <ul class="widget-list">
        <?php \Widget\Contents\Post\Recent::alloc()
            ->parse('<li><a href="{permalink}">{title}</a></li>'); ?>
    </ul>
</section>

<!-- 最近评论 -->
<section class="widget">
    <h3 class="widget-title">最近回复</h3>
    <ul class="widget-list">
        <?php \Widget\Comments\Recent::alloc()->to($comments); ?>
        <?php while ($comments->next()): ?>
            <li>
                <a href="<?php \(comments->permalink(); ?>"><?php \)comments->author(false); ?></a>: 
                <?php $comments->excerpt(35, '...'); ?>
            </li>
        <?php endwhile; ?>
    </ul>
</section>

<!-- 分类列表 -->
<section class="widget">
    <h3 class="widget-title">分类</h3>
    <?php \Widget\Metas\Category\Rows::alloc()->listCategories('wrapClass=widget-list'); ?>
</section>

<!-- 归档 -->
<section class="widget">
    <h3 class="widget-title">归档</h3>
    <ul class="widget-list">
        <?php \Widget\Contents\Post\Date::alloc('type=month&format=F Y')
            ->parse('<li><a href="{permalink}">{date}</a></li>'); ?>
    </ul>
</section>

<?php if ($this->allow('comment')): ?>
    <div id="<?php $this->respondId(); ?>" class="respond">
        <div class="cancel-comment-reply">
            <?php $comments->cancelReply(); ?>
        </div>

        <h3 id="response">添加新评论</h3>
        <form method="post" action="<?php $this->commentUrl() ?>" id="comment-form" role="form">
            <?php if ($this->user->hasLogin()): ?>
                <p>登录身份: <a href="<?php $this->options->profileUrl(); ?>">
                    <?php $this->user->screenName(); ?>
                </a>. 
                <a href="<?php $this->options->logoutUrl(); ?>" title="Logout">退出 &raquo;</a></p>
            <?php else: ?>
                <p>
                    <label for="author" class="required">称呼</label>
                    <input type="text" name="author" id="author" class="text"
                           value="<?php $this->remember('author'); ?>" required/>
                </p>
                <p>
                    <label for="mail" class="required">Email</label>
                    <input type="email" name="mail" id="mail" class="text"
                           value="<?php \(this->remember('mail'); ?>"<?php if (\)this->options->commentsRequireMail): ?> required<?php endif; ?> />
                </p>
                <p>
                    <label for="url">网站</label>
                    <input type="url" name="url" id="url" class="text" placeholder="http://"
                           value="<?php \(this->remember('url'); ?>"<?php if (\)this->options->commentsRequireUrl): ?> required<?php endif; ?> />
                </p>
            <?php endif; ?>
            <p>
                <label for="textarea" class="required">内容</label>
                <textarea rows="8" cols="50" name="text" id="textarea" class="textarea"
                          required><?php $this->remember('text'); ?></textarea>
            </p>
            <p>
                <button type="submit" class="submit">提交评论</button>
            </p>
        </form>
    </div>
<?php else: ?>
    <h3>评论已关闭</h3>
<?php endif; ?>