开发者参考
主题 API 参考
TubePress 主题 API 参考：在构建或自定义视频站点主题时可用的每一个全局模板变量、辅助函数与类。
本页是主题可用内容的完整参考：注入每个模板的全局变量、各模板专有变量以及主题代码中可用的辅助类。若您正在构建或自定义主题，请将本页与 主题开发 一同参阅。
每个模板均由 ThemeRenderer::render($template, $data) 渲染。渲染器注入一组带 $_ 前缀的全局变量，合并模板专有的 $data，运行 theme.template_data 过滤器，将模板缓冲至 $content，然后加载 layout.php。
全局变量
这些变量在每个模板和 layout.php 中均可用。
站点
| 变量 | 类型 | 描述 |
|---|
$_template | string | 当前模板名称（例如 'home'、'video'） |
$_siteName | string | 来自设置的站点名称 |
$_siteDescription | string | 站点描述 |
$_siteUrl | string | 站点 URL |
$_videosPerRow | int | 网格列数（4、5 或 6） |
$_user | array\|null | 已登录用户，或 null |
$_footerPages | array | 标记为页脚的静态页面 |
$_registrationEnabled | bool | 注册开关 |
$_ctrEnabled | bool | CTR 排名开关 |
外观
| 变量 | 类型 | 描述 |
|---|
$_siteLogo | string | Logo 文件名（位于 /uploads/branding/） |
$_siteFavicon | string | Favicon 文件名 |
$_siteBackground | string | 背景图片文件名 |
$_siteBackgroundMode | string | 'cover'、'contain' 或 'repeat' |
$_colorOverrides | string | 包含 CSS 自定义属性的 <style> 块 |
$_menuSearch | bool | 显示搜索栏 |
$_menuItems | array | 导航项（key、label、url、enabled、templates） |
语言区域
| 变量 | 类型 | 描述 |
|---|
$_locale | string | 当前语言区域代码（例如 'en'） |
$_direction | string | 'ltr' 或 'rtl' |
$_isRtl | bool | 从右到左语言 |
$_availableLangs | array | 可用语言 |
$_langPrefix | string | URL 前缀（例如 '/fr' 或 ''） |
视频卡片设置
| 变量 | 类型 | 描述 |
|---|
$_cardShowDuration | bool | 显示时长徽章 |
$_cardShowTitle | bool | 显示视频标题 |
$_cardMetaLeft | string | 左侧元信息：'views'、'likes'、'time'、'none' |
$_cardMetaRight | string | 右侧元信息（相同选项） |
$_cardGridGap | int | 以像素为单位的网格间距 |
$_cardBorderRadius | int | 以像素为单位的卡片圆角半径 |
$_cardThumbnailHover | bool | 缩略图悬停效果 |
$_cardTitleLines | int | 标题行数（1 或 2） |
播放页面设置
| 变量 | 类型 | 描述 |
|---|
$_watchShowViews | bool | 显示观看次数 |
$_watchShowDuration | bool | 显示时长 |
$_watchShowDate | bool | 显示发布日期 |
$_watchShowLikes | bool | 显示点赞/踩 |
$_watchShowFavorites | bool | 显示收藏按钮 |
$_watchShowPornstars | bool | 显示表演者 |
$_watchShowChannels | bool | 显示频道 |
$_watchShowCategories | bool | 显示分类 |
$_watchShowTags | bool | 显示标签 |
$_commentsEnabled | bool | 已启用评论 |
这些是设置，而非魔法。 每个
$_card* 和
$_watch* 的值均直接来自管理员
外观 界面，因此站点所有者无需修改代码即可重新设置主题样式——只要您读取这些变量而非硬编码即可。
模板专有变量
除全局变量外，每个模板还会接收各自的数据。
home.php
| 变量 | 类型 |
|---|
$videos | array — 视频行 |
$pagination | Pagination 对象 |
$sort | string — 当前排序键 |
video.php
| 变量 | 类型 |
|---|
$video | array — 包含分类、标签、表演者和频道的完整视频 |
$categories、$tags、$performers | array |
$comments | array |
$similar | array — 相似视频 |
$recommended | array — 推荐视频 |
$userVote | string\|null — 'like'、'dislike' 或 null |
$isFavorited | bool |
category.php / tag.php / performer.php / channel.php
| 变量 | 类型 |
|---|
$category / $tag / $performer / $channel | array — 实体 |
$videos | array — 视频行 |
$pagination | Pagination 对象 |
$sort | string |
列表模板
| 模板 | 主要变量 |
|---|
categories.php | $categories — 每个包含 video_count；CTR 开启时，包含 best_video_thumbnail |
performers.php | $performers — video_count；CTR 开启时，包含 best_video_thumbnail、total_ctr，按 CTR 排序；$pagination |
channels.php | 结构与 performers 相同 |
search.php | $query、$videos、$pagination |
辅助类
这些静态辅助类在每个模板中均可用。
| 类 | 主要方法 |
|---|
ThemeRenderer | ::enqueueCSS($url, $priority)、::enqueueJS($url, $priority)、::partial($name, $data)、::bodyClass()、::renderCSS()、::renderJS() |
ThemeManager | ::assetUrl($path)、::themePath()、::templatePath($t)、::active()、::info($key) |
ImpressionTracker | ::collect($videoId)、::flush()、::isBot() |
Format | ::number($n)、::duration($seconds)、::timeAgo($datetime)、::fileSize($bytes) |
Pagination | ->total、->page、->totalPages、->offset、->hasPrev()、->hasNext()、->pages()、->prevUrl()、->nextUrl() |
Router | ::url($path)、::csrfField()、::csrfToken()、::langPrefix() |
HookSystem | ::doAction($event, ...$args)、::applyFilter($filter, $value, ...$args) |
Auth | ::check()、::user()、::id() |
Setting | ::get($key, $default) |
__($key, $replacements) | 翻译辅助函数 |
url($path) | Router::url($path) 的快捷方式 |
渲染流程
- 控制器调用渲染器。
ThemeRenderer::render('home', ['videos' => $videos, …])。
- 注入全局变量。 添加带
$_ 前缀的站点、外观、语言区域和卡片/播放变量。
- 插件可修改数据。
HookSystem::applyFilter('theme.template_data', $data, $templateName) 运行。
- 模板渲染。 您的模板文件被缓冲至
$content。
- 布局加载。
layout.php 接收 $content 以及所有变量。
- 展示量刷新。
ImpressionTracker::flush() 发送批量展示更新（CTR）。
- Cron 运行。
CronManager::run() 执行所有到期的计划任务。
layout.php 要求
主题的 layout.php 必须完成以下所有操作：
- 输出完整的 HTML 框架（
<!DOCTYPE html> … </html>）。
- 在
<head> 中包含 <?= ThemeRenderer::renderCSS() ?>。
- 在
<head> 中包含 <?= $_colorOverrides ?>。
- 在
<main> 内输出 $content。
- 在
</body> 前包含 <?= ThemeRenderer::renderJS() ?>。
- 在
</body> 前调用 <?php ImpressionTracker::flush(); ?>（用于 CTR）。
- 在
<head> 中调用 <?php HookSystem::doAction('head.meta'); ?>。
- 在
</body> 前调用 <?php HookSystem::doAction('footer.scripts'); ?>。
模板回退
如果活动主题缺少某个模板，TubePress 将回退到捆绑的 Simply 主题。因此，自定义主题只需覆盖实际需要更改的模板——从一个模板开始，逐步扩展。
后续步骤
