话接上回,准备用AI写一个typecho主题,说干就干,从上线到不断打磨,前后修改了不下30多次,目前还在不断完善中。

AI修改起来太方便了,不需要懂太多的语法,有问题可以马上修正,唯一不足的是它在运作时需要反复加载仓库内核,工作用时久了一点。

单栏、简约、浅色系的 Typecho 主题。记录每一次功能迭代的设计决策、后台设置项、验证结果与交付信息,方便下次继续。
  • 主题源码:lightline/(与本文档同级)
  • 安装包:lightline.zip(解压后得到 lightline 文件夹,上传至 usr/themes/)
  • 技术基线:Typecho 1.3.0,PHP 7.4–8.x
  • 预览图:lightline/screenshot.png(1200×701,浅色/深色列表页对比)

一、设计基线

项目取值
内容最大宽度720px
圆角14px(卡片)/ 10–12px(图片)
字体系统无衬线栈,正文 16px / 行高 1.85
浅色配色bg #f7f7f4、card #ffffff、text #2b2b28、text-light #7a7a72、line #ececea、accent #5b7a6b、accent-2 #93b3a4、accent-soft #eef3f0、code-bg #2b2b28
深色配色bg #15171a、card #1d2024、text #e6e4df、text-light #96968f、line #2c2f34、accent #8fb3a2、accent-2 #b7cfc2、accent-soft #222a26、code-bg #101114

深色模式通过 <html data-theme="dark"> 切换,全部配色走 CSS 变量,新增组件只要用变量就自动兼容两套主题。


二、文件结构(14 个)

文件职责
index.php首页:引言 → Banner 图组 → 文章卡片列表
archive.php分类/标签/作者归档列表
search.php搜索结果列表
post.php文章页:阅读进度条、封面大图、正文、翻页、评论
page.php独立页面(无评论、有进度条)
comments.php评论表单 + 评论列表容器
header.php<head>、防白闪脚本、Logo、导航、深浅色切换按钮
footer.php页脚、回到顶部按钮与滚动逻辑
functions.php后台设置项、threadedComments() 评论回调、lightlineThumb() 封面、lightlineBanner()
style.css全部样式(含深色变量组、移动端媒体查询)
404.php / README.txt / screenshot.png404、使用说明、主题截图

三、后台设置项(id → 默认值)

id默认说明
excerptLength120列表摘要字数,0 = 不截取
showMeta1日期/分类/评论数显示开关
defaultThumb空默认缩略图地址(封面第三级兜底)
showCover1文章封面图总开关
logoUrl空站点 Logo(留空显示站名文字)
logoDarkUrl空深色模式专用 Logo
logoHeight36Logo 高度(0→36、>120→120 自动保护)
logoWithText1Logo 右侧是否带站点名
showBanner1首屏 Banner 图组开关
bannerHeight300Banner 桌面高度(仅数字,超出 0–720 回落 300)
banner1Img/1Title/1Url空左侧大图(图片/标题/链接)
banner2Img/2Title/2Url空右上小图
banner3Img/3Title/3Url空右下小图
showIntro1首页引言开关
introText空引言内容(支持多行,nl2br 处理换行)
introAuthor空引言署名

通用原则:留空就不输出,绝不出现空占位或错位。


四、已实现功能

1. 基础主题

13 → 14 个模板文件,单栏卡片式列表,浅米白 + 墨绿点缀。

2. 深色模式 + 回到顶部

  • <head> 内联脚本先读 localStorage('lightline-theme'),没有则跟随 prefers-color-scheme,避免白闪
  • 页头圆形按钮(浅色显示月亮、深色显示太阳,内联 SVG)
  • 回顶:滚动 300px 后浮现,requestAnimationFrame 缓动,尊重 prefers-reduced-motion

3. 阅读进度条

  • 仅在 post.php / page.php 输出 .reading-progress + #reading-progress-bar
  • 按文章自身长度计算(getBoundingClientRect().top + scrollY 到文章底部减视口高度)
  • 文章短于视口时不显示;3px 渐变细线
  • 实测:45% 滚动 → 44.93%、60% → 60.01%、到底 → 100%

4. 后台 Logo(含双 Logo 修复)

  • 用户曾反馈「浅色和深色 Logo 都填时会并排显示」,根因是两张图只靠 CSS display:none 互斥,旧缓存下 .logo-img{display:block} 把深色图也放出来
  • 修复三重保险:深色图去掉 .logo-img 类只留 .logo-img-dark、加原生 hidden 属性、CSS 顺序与权重兜底
  • 另加防呆:两栏填同一地址时只输出一张

5. 评论列表修复

原代码 5 处错误(已对照 Typecho 官方源码核实):

错误正确
$comments->has()$comments->have()
手写 while + threadedComments($comments)$comments->listComments()
$comments->children()$comments->threadedComments()
$comments->parent()->authorIdauthorId == ownerId
id="comment-xxx"id="<?php $this->respondId(); ?>"(实际为 respond-post-{cid})

6. 评论头像

  • $comments->gravatar(40, null, true):第三个参数输出 2x/3x srcset
  • 尊重后台「启用评论头像」与 __TYPECHO_GRAVATAR_PREFIX__ 镜像常量
  • 布局:左头像 + 右正文 flex,头像 40px 圆形(手机 34px)
  • 后台关闭头像时 gravatar() 输出空 → .comment-avatar:empty{display:none} 自动收起,实测空档 0px

7. 文章封面图(三级回退)

优先级:自定义字段 cover → 正文首张 <img> → 主题设置 defaultThumb → 不输出

  • 列表:左缩略图 168×116 + 右文字;无封面回退纯文字卡片,不留白
  • 文章页:标题上方整幅大图,最大高度 420px,圆角 12px
  • 手机端:封面改为通栏 16:9、文字在下(早期 112×84 左缩略图方案会挤压正文,已废弃)

8. 首屏 Banner 图组

  • 位置:首页引言下方、列表上方
  • 桌面:1.06fr / 1fr 两列两行,左图跨两行,高度由 bannerHeight 控制
  • 手机上:大图通栏 16:9,两小图并排各半
  • 智能降级:3 张 = 大+两小、2 张 = 平分、1 张 = 通栏、0 张 = 整块不显示
  • 图上白色标题底部居中 + 渐变遮罩(浅色 .58 / 深色 .72),object-fit: cover 不变形,悬停 1.045 倍缓动

9. 首页引言

  • 前置浅绿引号 “(伪元素,Georgia 字体),小号灰字 + 可选署名
  • 支持多行(nl2br),手机端 13px

五、开发与验证工作流

  1. 改 PHP → 用 php-parser 做语法校验(无 php CLI):
    /tmp/phpcheck 下 node check.js,逐文件输出 OK/FAIL,10 个模板全部通过
  2. 改 CSS/PHP 结构 → 复制最新样式到样机:cp lightline/style.css /tmp/llmock/style.css
  3. 真实渲染验证 → playwright + chromium:
    executable_path="/usr/local/bin/chromium", args=["--no-sandbox"]
    device_scale_factor=2,桌面 800×*、手机 390×844
  4. 断言 → 用 getBoundingClientRect 量尺寸/重叠/溢出,不靠肉眼
  5. 合成预览图 → PIL 左右拼浅色/深色(必要时加手机端),存为 preview-*.png
  6. 打包 → 项目根 zip -r lightline.zip lightline -x "*.DS_Store",present_files 交付

踩过的坑

  • 样机必须每次 cp 最新 style.css,否则验证到的是旧样式(进度条那次就误判成「没渲染」)
  • Typecho 1.3 没有 has() / children() 这类调用式,别凭印象写
  • 评论头像关闭时 gravatar() 输出空字符串,必须 :empty 兜底
  • 双 Logo 只靠 CSS 互斥在旧缓存下会露馅,要有原生属性兜底

六、交付记录

版本内容地址
v1主题初版
v2深色模式 + 回到顶部
v3阅读进度条
v4后台 Logo 设置
v5评论列表修复
v6评论头像
v7文章封面图
v8首屏 Banner 图组
v9首页引言

七、可继续的方向

  1. Banner 自动抓取最新 3 篇文章的封面 + 标题(现在是纯手动配置)
  2. 卡片「顶部通栏大图」杂志风布局,或封面比例可配(16:9 / 4:3)
  3. 首页引言居中排版,或支持引用出处链接
  4. 归档页分页样式、面包屑、文章目录(TOC)
  5. 主题截图更新为当前首页(含引言 + Banner)