主题 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	已启用评论

社区

变量	类型	描述
$_subscriptionsEnabled	bool	频道订阅已开启且主题支持
$_subscriptionsUnseen	int	自会员上次访问以来其订阅频道的新视频数（游客为 0）
$_memberUploadsEnabled	bool	会员上传已开启且主题支持
$_pwaEnabled	bool	可安装应用已开启

模板专有变量

除全局变量外，每个模板还会接收各自的数据。

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
$subscriptionsOn	bool — 是否显示订阅按钮（设置已开启且主题支持）
$channelSubscribed, $channelSubscribers	bool, int — 观看者的订阅状态，以及视频第一个频道的订阅数
$ownerPreview	bool — 上传者正在查看自己尚未发布的视频
$uploader	array|null — 上传该视频的会员

category.php / tag.php / performer.php / channel.php

变量	类型
$category / $tag / $performer / $channel	array — 实体
$videos	array — 视频行
$pagination	Pagination 对象
$sort	string
$subscriptionsOn, $isSubscribed, $subscriberCount	bool, bool, int — 仅限 channel.php

列表模板

模板	主要变量
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

upload.php

变量	类型
$uploadGate	array — ok，或会员无法上传的原因（已停用、未登录、达到每日上限）
$uploadConfig	array — 上传脚本所需信息：接口地址、CSRF 令牌、大小与分片限制、支持的格式
$uploadCategories, $uploadTypes	array — 会员可选择的分类和视频类型
$uploadGuidelines, $uploadModerated	string, bool — 您的上传规则，以及上传是否需要审核

auth/profile.php

变量	类型
$subscriptionsTab, $uploadsTab	bool — 是否显示订阅和我的上传标签页
$subChannels, $subVideos, $subNewSince	array, array, string|null — 已订阅的频道、其最新视频，以及“新”徽标的截止时间
$uploadItems	array — 会员的上传，各自附带状态

辅助类

这些静态辅助类在每个模板中均可用。

类	主要方法
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) 的快捷方式

渲染流程

1. 控制器调用渲染器。 ThemeRenderer::render('home', ['videos' => $videos, …])。
2. 注入全局变量。 添加带 $_ 前缀的站点、外观、语言区域和卡片/播放变量。
3. 插件可修改数据。 HookSystem::applyFilter('theme.template_data', $data, $templateName) 运行。
4. 模板渲染。 您的模板文件被缓冲至 $content。
5. 布局加载。 layout.php 接收 $content 以及所有变量。
6. 展示量刷新。 ImpressionTracker::flush() 发送批量展示更新（CTR）。
7. Cron 运行。 CronManager::run() 执行所有到期的计划任务。

layout.php 要求

主题的 layout.php 必须完成以下所有操作：

1. 输出完整的 HTML 框架（<!DOCTYPE html> … </html>）。
2. 在 <head> 中包含 <?= ThemeRenderer::renderCSS() ?>。
3. 在 <head> 中包含 <?= $_colorOverrides ?>。
4. 在 <main> 内输出 $content。
5. 在 </body> 前包含 <?= ThemeRenderer::renderJS() ?>。
6. 在 </body> 前调用 <?php ImpressionTracker::flush(); ?>（用于 CTR）。
7. 在 <head> 中调用 <?php HookSystem::doAction('head.meta'); ?>。
8. 在 </body> 前调用 <?php HookSystem::doAction('footer.scripts'); ?>。

模板回退

如果活动主题缺少某个模板，TubePress 将回退到捆绑的 Simply 主题。因此，自定义主题只需覆盖实际需要更改的模板——从一个模板开始，逐步扩展。

后续步骤