主题开发

一套主题 = 一个目录 + 一份 theme.json + 若干 PHP 视图。内核不编译模板、不引入模板引擎,视图就是普通 PHP 文件,服务端直接输出 HTML。

本页导航

目录结构

themes/<id>/
  theme.json          # 元数据 + 后台可调设置(必需)
  style.css           # 主题样式
  views/
    layout.php        # 整页外壳(必需)
    landing.php       # 门户首页(home.landing=1 时启用)
    landing-en.php    # 英文首页(/en/ 优先)
    landing-cms.php   # 门户首页共用取数与版式(可选)
    404.php
    partials/         # list / post / page / search / archives / sidebar / toc-side …
  logo.png / favicon.png

内置 34 套主题(yecha、teadoc、xinglan、wenshu…)都是可直接照抄的范例;主题广场可逐套查看。

theme.json

字段说明
name / version / description后台与/theme展示的名称、版本、简介
requires_core依赖内核版本(如 1.2.5)
author / license作者与许可
home设为 landing 时首页走门户版式
settings后台可调项数组:key / type(select、color、number、checkbox) / label / def / opts

后台「主题设置」只收集这里声明过的键,写入 ye_options.theme.options(JSON);模板里用 theme_opt('key', '默认值') 读。

最小可用主题

themes/hello/theme.json:

{
  "name": "Hello",
  "version": "0.1.0",
  "requires_core": "1.2.5",
  "description": "最小示例主题",
  "settings": [
    { "key": "accent", "type": "color", "label": "主色", "def": "#b3541e" }
  ]
}

themes/hello/views/layout.php:

<!DOCTYPE html>
<html lang="<?= e($htmlLang ?? 'zh-CN') ?>">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title><?= e($title) ?></title>
<link rel="stylesheet" href="<?= e(View::asset('style.css')) ?>">
</head>
<body>
<header><?php foreach (Nav::list('top', Lang::short()) as $n): ?>
<a href="<?= e($n['href']) ?>"<?= $n['active'] ? ' class="active"' : '' ?>><?= e($n['label']) ?></a>
<?php endforeach; ?></header>
<main><?= $main ?></main>
<aside><?= $side ?></aside>
</body>
</html>

放进 themes/ 后后台「主题」即可见并切换。

视图与变量

变量含义
$title / $htmlLang页面标题、<html lang>
$main / $side正文 HTML、侧栏 HTML(内核已渲染好,直接输出)
$posts / $post / $toc列表数据、当前内容、目录条目(按页面类型提供)

常用函数:

函数用途
e()HTML 转义,所有动态文本必须过一遍
__()语言包取值(如 __('nav.docs'))
site_label() / site_name()站点名(含英文回落)
theme_opt()读主题设置
`Nav::list('top'\'foot')`导航项(已带语言前缀与 active)
Poly::termUrl() / Poly::termName()多语术语链接与名称
View::asset('style.css')带 ?v=<mtime> 的资源 URL,改样式不必手工改版本号

正文由 core/Markdown.php 渲染:标题自动生成锚点与右栏目录,显式 {#id} 可自定义锚点,```lang 围栏代码块带语言角标。

首页版式

home.landing=1 时,首页走 views/landing.php(中文)/ views/landing-en.php(英文)。官网默认主题把取数与结构抽到 partials/landing-cms.php:主题/插件数来自目录扫描、安装包数来自 download/pkg/index.json、更新条目来自 /changelog 内容页、版本来自 core/version.php——数字不写死,避免文档与展示脱节。

自己做首页时建议沿用这个约定;纯文章列表首页(home.landing=0)由内核 Front::home() 提供数据,视图只负责排版。

样式与暗色

  • 主题色用 CSS 变量,默认主题为茶褐 --accent:#b3541e,另有 --line、--soft、--bg、--fg。
  • 暗色模式挂在 html.dark 上,所有面板/代码块/表格都要写深色分支,文字对比度要够。
  • 响应式:768px 以下单列,侧栏落到正文下方;390px 窄屏检查导航折叠。
  • 代码样式复用 pre/code;pre[data-lang]::before 显示语言角标(1.2.5 起所有内容页通用)。

调试与回落

  1. 逐文件 php -l,切换主题后清页缓存/区块缓存、重建首页静态件(见运维:缓存)。
  2. 缺模板时内核回落到默认主题 yecha,并在 var/log/php-error.log 留记录,不静默失败。
  3. 模板里不要输出未转义的 $_GET / 数据库字段;不要依赖 JS 渲染主体内容(无 JS 也要能看全)。
  4. 多语检查:中文页与 /en/ 页都要跑一遍,别把中文硬编码进英文视图。

发布清单

  • [ ] theme.json 字段齐全,requires_core 与实测版本一致
  • [ ] 所有 PHP 文件 php -l 通过
  • [ ] layout.php、landing.php(如声明)、404.php 齐全
  • [ ] 中文 / 英文 / 暗色 / 窄屏四种组合目检
  • [ ] 区块缓存、首页静态件、页缓存清理后复测
  • [ ] 打包到云市场前校验 SHA-256,包内不含密钥、缓存、上传目录