Typecho PHP 模板 API 完整参考

while ($this->have()) {
    // 循环内容
}

while ($this->have()) {
    $this->next();
    // 处理当前项
}

$this->title();                          // 完整标题
$this->title(50, '...');                 // 截取标题

$this->content();                        // 完整内容
$this->content('阅读全文');              // 带 more 标签截取

$this->excerpt();                        // 默认 100 字
$this->excerpt(200, '——');              // 自定义截取

$this->date();                           // 使用后台设置格式
$this->date('Y-m-d H:i:s');             // 自定义格式

$this->category();                       // 逗号分隔，带链接
$this->category(' / ', false);           // 斜线分隔，无链接
$this->category(',', true, '未分类');    // 带默认值

$this->tags();                           // 逗号分隔，带链接
$this->tags(' ', false);                 // 空格分隔，纯文本

$this->directory(' > ');              // 输出完整分类路径

$this->author();                         // 昵称
$this->author('url');                    // 作者主页
$this->author('mail');                   // 作者邮箱

$this->commentsNum();                    // 直接输出数字
$this->commentsNum('%d 评论');           // 带单位
$this->commentsNum('暂无评论', '1 条评论', '%d 条评论');  // 复数处理

\(comments = \)this->comments();
while ($comments->have()) {
    $comments->next();
    // 处理评论
}

\(pings = \)this->pings();

$this->pageNav('« 上一页', '下一页 »', 3, '...');

$this->pageLink('« 上一页', 'prev');     // 上一页
$this->pageLink('下一页 »', 'next');     // 下一页

$this->theNext('<a href="%s">下一篇: %s</a>', '没有下一篇了');

$this->thePrev('<a href="%s">上一篇: %s</a>', '没有上一篇了');

// 获取相关文章
\(related = \)this->related(5);            // 默认按标签
\(related = \)this->related(5, 'author');  // 按作者
while ($related->have()) {
    $related->next();
    // 处理相关文章
}

$this->is('index');                      // 首页
$this->is('single');                     // 单篇文章/页面
$this->is('post');                       // 文章
$this->is('page');                       // 独立页面
$this->is('category');                   // 分类页
$this->is('category', 'default');        // 指定分类
$this->is('tag');                        // 标签页
$this->is('search');                     // 搜索页
$this->is('archive');                    // 归档页
$this->is('author');                     // 作者页
$this->is('feed');                       // 订阅输出

$this->need('header.php');               // 加载头部
$this->need('sidebar.php');              // 加载侧边栏
$this->need('footer.php');               // 加载底部

$this->header();                         // 输出默认头部
$this->header('keywords=&description=');  // 自定义输出项

$this->footer();                         // 输出页脚（支持插件扩展）

$this->archiveTitle();                   // 默认格式
$this->archiveTitle([
    'category' => '分类 %s 下的文章',
    'search'   => '搜索: %s',
    'tag'      => '标签: %s',
    'author'   => '作者: %s'
], ' - ');

$this->keywords();                       // 逗号分隔
$this->keywords(' ', '默认关键词');       // 自定义分隔符

$this->remember('author');               // 记忆的作者名
$this->remember('mail');                 // 记忆的邮箱
$this->remember('url');                  // 记忆的网址

\(attachments = \)this->attachments();
while ($attachments->have()) {
    $attachments->next();
    echo $attachments->url;
}

$this->cid;              // 内容 ID
$this->title;            // 标题
$this->slug;             // 缩略名
$this->created;          // 创建时间戳
$this->modified;         // 修改时间戳
$this->text;             // 原始内容
$this->order;            // 排序
$this->authorId;         // 作者 ID
$this->template;         // 自定义模板
$this->type;             // 类型（post/page/attachment）
$this->status;           // 状态
$this->password;         // 密码保护
$this->commentsNum;      // 评论数
$this->allowComment;     // 允许评论
$this->allowPing;        // 允许引用
$this->allowFeed;        // 允许 Feed
$this->parent;           // 父级 ID

$this->permalink;        // 永久链接
$this->url;              // URL（同 permalink）
$this->path;             // 路径
$this->feedUrl;          // RSS 2.0
$this->feedRssUrl;       // RSS 1.0
$this->feedAtomUrl;      // Atom 1.0
$this->theId;            // 锚点 ID（type-cid）
$this->respondId;        // 回复框 ID
$this->commentUrl;       // 评论提交地址
$this->trackbackUrl;     // Trackback 地址
$this->responseUrl;      // 回复地址

$this->content;          // 解析后的内容
$this->excerpt;          // 摘要（带 more 标签处理）
$this->plainExcerpt;     // 纯文本摘要
$this->summary;          // 第一段摘要
$this->fields;           // 自定义字段对象
$this->attachment;       // 附件信息（仅 attachment 类型）

$this->date;             // Date 对象
$this->dateWord;         // 词义化日期（如"3小时前"）
$this->year;             // 年份
$this->month;            // 月份
$this->day;              // 日期

$this->categories;       // 分类数组
$this->tags;             // 标签数组
$this->directory;        // 多级目录数组

$this->author;           // 作者对象（Widget\Users\Author）
$this->author->uid;      // 作者 ID
$this->author->screenName;  // 昵称
$this->author->url;      // 作者主页
$this->author->mail;     // 作者邮箱

$this->allow('comment');   // 允许评论
$this->allow('ping');      // 允许引用
$this->allow('feed');      // 允许 Feed
$this->allow('edit');      // 允许编辑
$this->allow('comment', 'edit');  // 多个权限

if ($this->isMarkdown) {
    // 是 Markdown 格式
}

if ($this->hidden) {
    // 内容被密码保护
}

$this->coid;             // 评论 ID
$this->cid;              // 所属内容 ID
$this->created;          // 创建时间戳
$this->author;           // 作者名
$this->authorId;         // 作者 ID（注册用户）
$this->ownerId;          // 内容作者 ID
$this->mail;             // 邮箱
$this->url;              // 网址
$this->ip;               // IP 地址
$this->agent;            // User Agent
$this->text;             // 评论内容
$this->type;             // 类型（comment/pingback/trackback）
$this->status;           // 状态
$this->parent;           // 父评论 ID
$this->commentPage;      // 所在评论页

$this->date;             // Date 对象
$this->dateWord;         // 词义化日期
$this->theId;            // 锚点 ID（type-coid）
$this->permalink;        // 评论链接
$this->title;            // 所属内容标题
$this->content;          // 解析后的评论内容
$this->parentContent;    // 所属内容对象

$this->date();                           // 默认格式
$this->date('Y-m-d H:i:s');             // 自定义格式

$this->author();                         // 默认带链接
$this->author(false);                    // 不带链接
$this->author(true, true);               // 带 nofollow

$this->gravatar();                       // 默认 32px
$this->gravatar(64);                     // 64px
$this->gravatar(64, 'mm', true);         // 高分辨率支持

$this->excerpt();                        // 默认 100 字
$this->excerpt(50);                      // 50 字

$this->mail();                           // 纯邮箱
$this->mail(true);                       // mailto: 链接

$this->options->siteUrl();               // http://example.com
$this->options->siteUrl('about/');       // http://example.com/about/

$this->options->index();                 // 网站首页

$this->options->themeUrl();              // 当前主题 URL
$this->options->themeUrl('style.css');   // 主题文件
$this->options->themeUrl(null, 'default');  // 指定主题

$this->options->pluginUrl();             // 插件目录
$this->options->pluginUrl('MyPlugin/');  // 指定插件

$this->options->adminUrl();              // 后台首页
$this->options->adminUrl('write-post.php');  // 写文章页
\(url = \)this->options->adminUrl('manage-posts.php', true);  // 返回不输出

$this->options->feedUrl;                 // RSS 2.0
$this->options->feedRssUrl;              // RSS 1.0
$this->options->feedAtomUrl;             // Atom 1.0
$this->options->commentsFeedUrl;         // 评论 RSS 2.0
$this->options->commentsFeedRssUrl;      // 评论 RSS 1.0
$this->options->commentsFeedAtomUrl;     // 评论 Atom 1.0

$this->options->title;                   // 网站标题
$this->options->description;             // 网站描述
$this->options->keywords;                // 网站关键词
$this->options->theme;                   // 当前主题
$this->options->siteUrl;                 // 网站地址
$this->options->siteDomain;              // 网站域名

$this->options->pageSize;                // 每页文章数
$this->options->postDateFormat;          // 文章日期格式
$this->options->commentDateFormat;       // 评论日期格式
$this->options->frontPage;               // 首页显示（recent/page:X/file:X）
$this->options->frontArchive;            // 归档作为首页

$this->options->commentsListSize;        // 每页评论数
$this->options->commentsPageSize;        // 评论分页大小
$this->options->commentsShowCommentOnly; // 只显示评论
$this->options->commentsThreaded;        // 启用嵌套评论
$this->options->commentsOrder;           // 评论排序（ASC/DESC）
$this->options->commentsMarkdown;        // 支持 Markdown
$this->options->commentsShowUrl;         // 显示评论者网址
$this->options->commentsUrlNofollow;     // 添加 nofollow
$this->options->commentsAvatar;          // 显示头像
$this->options->commentsAvatarRating;    // 头像评级
$this->options->commentsPageBreak;       // 评论分页
$this->options->commentsHTMLTagAllowed;  // 允许的 HTML 标签
$this->options->commentsAntiSpam;        // 反垃圾评论
$this->options->commentsAutoClose;       // 自动关闭评论
$this->options->commentsPostTimeout;     // 关闭评论天数
$this->options->commentsMaxNestingLevels;// 最大嵌套层数

$this->options->allowRegister;           // 允许注册
$this->options->allowXmlRpc;             // XML-RPC 支持
$this->options->feedFullText;            // Feed 输出全文
$this->options->time;                    // 当前时间戳
$this->options->timezone;                // 时区
$this->options->serverTimezone;          // 服务器时区
$this->options->generator;               // Generator 信息
$this->options->version;                 // 版本号
$this->options->software;                // 软件名称

\(config = \)this->options->plugin('HelloWorld');
echo $config->word;                      // 访问配置项

\(config = \)this->options->personalPlugin('HelloWorld');

\(path = \)this->options->themeFile('default', 'index.php');

\(dir = \)this->options->pluginDir('HelloWorld');

$this->options->adminStaticUrl('css', 'style.css');

use Utils\Helper;

Helper::addRoute(
    'myplugin-api',                      // 路由名称
    '/api/myplugin/[action:alpha]',     // 路由路径
    'MyPlugin_Action',                   // 处理 Widget
    'api',                               // 动作方法
    'post'                               // 在 post 路由之后
);

Helper::removeRoute('myplugin-api');

Helper::addAction('my-action', 'MyPlugin_Action');
// 访问: /action/my-action

Helper::removeAction('my-action');

$menuIndex = Helper::addMenu('MyPlugin');
// 返回菜单索引，用于添加子面板

$menuIndex = Helper::removeMenu('MyPlugin');

$menuIndex = Helper::addMenu('MyPlugin');
Helper::addPanel(
    $menuIndex,                          // 菜单索引
    'panel.php',                         // 面板文件
    '插件设置',                          // 标题
    '配置插件参数',                      // 副标题
    'administrator',                     // 权限
    false,                               // 是否隐藏
    '新增数据'                           // 新增链接
);

$menuIndex = Helper::removeMenu('MyPlugin');
Helper::removePanel($menuIndex, 'panel.php');

$options = Helper::options();
echo $options->title;

$security = Helper::security();
\(token = \)security->getToken($url);

$url = Helper::url('panel.php');
// 输出: /admin/extending.php?panel=panel.php

$post = Helper::widgetById('contents', 1);
$comment = Helper::widgetById('comments', 1);
$category = Helper::widgetById('metas', 1);
$user = Helper::widgetById('users', 1);

Helper::setOption('plugin:MyPlugin', ['key' => 'value']);

Helper::configPlugin('MyPlugin', [
    'option1' => 'value1',
    'option2' => 'value2'
]);

Helper::removePlugin('MyPlugin');

Helper::replyLink('comment-123', 456, '回复');

Helper::cancelCommentReplyLink('取消回复');

Helper::threadedCommentsScript();

Helper::requestService('methodName', \(param1, \)param2);

Helper::lang('MyPlugin');

// 注册
\Typecho\Plugin::factory('Widget\Archive')->___readTime = [Plugin::class, 'getReadTime'];

// 实现
public static function getReadTime($archive)
{
    return ceil($archive->length / 300);
}

// 模板中使用
<?php echo $this->readTime; ?>

// 注册
\Typecho\Plugin::factory('Widget\Archive')->callCustomMethod = [Plugin::class, 'handleMethod'];

// 实现
public static function handleMethod(\(archive, \)args)
{
    echo 'Custom output';
}

// 模板中调用
<?php $this->customMethod(); ?>

<?php while ($this->next()): ?>
<article>
    <h2><a href="<?php \(this->permalink(); ?>"><?php \)this->title(); ?></a></h2>
    <p class="meta">
        <?php $this->date('Y-m-d'); ?> · 
        <?php $this->author(); ?> · 
        <?php $this->commentsNum(); ?>
    </p>
    <div class="content">
        <?php $this->content('阅读全文'); ?>
    </div>
    <p class="tags">
        <?php $this->tags(' ', true, '无标签'); ?>
    </p>
</article>
<?php endwhile; ?>

<?php \(comments = \)this->comments(); ?>
<?php while ($comments->next()): ?>
<li id="<?php $comments->theId(); ?>">
    <div class="avatar">
        <?php $comments->gravatar(40); ?>
    </div>
    <div class="comment-info">
        <span class="author"><?php $comments->author(); ?></span>
        <span class="time"><?php $comments->date(); ?></span>
    </div>
    <div class="comment-content">
        <?php $comments->content(); ?>
    </div>
</li>
<?php endwhile; ?>

<?php if ($this->is('index')): ?>
    <!-- 首页内容 -->
<?php elseif ($this->is('post')): ?>
    <!-- 文章页内容 -->
<?php elseif ($this->is('page')): ?>
    <!-- 独立页内容 -->
<?php elseif ($this->is('category')): ?>
    <!-- 分类页内容 -->
<?php else: ?>
    <!-- 其他页面 -->
<?php endif; ?>

<?php
\(thumb = \)this->fields->thumb;
if (!empty($thumb)) {
    echo '<img src="' . \(thumb . '" alt="' . \)this->title . '" />';
}
?>