话接上回,准备用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.png | 404、使用说明、主题截图 |
三、后台设置项(id → 默认值)
| id | 默认 | 说明 |
|---|---|---|
excerptLength | 120 | 列表摘要字数,0 = 不截取 |
showMeta | 1 | 日期/分类/评论数显示开关 |
defaultThumb | 空 | 默认缩略图地址(封面第三级兜底) |
showCover | 1 | 文章封面图总开关 |
logoUrl | 空 | 站点 Logo(留空显示站名文字) |
logoDarkUrl | 空 | 深色模式专用 Logo |
logoHeight | 36 | Logo 高度(0→36、>120→120 自动保护) |
logoWithText | 1 | Logo 右侧是否带站点名 |
showBanner | 1 | 首屏 Banner 图组开关 |
bannerHeight | 300 | Banner 桌面高度(仅数字,超出 0–720 回落 300) |
banner1Img/1Title/1Url | 空 | 左侧大图(图片/标题/链接) |
banner2Img/2Title/2Url | 空 | 右上小图 |
banner3Img/3Title/3Url | 空 | 右下小图 |
showIntro | 1 | 首页引言开关 |
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()->authorId | authorId == 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
五、开发与验证工作流
- 改 PHP → 用
php-parser做语法校验(无 php CLI):/tmp/phpcheck下node check.js,逐文件输出 OK/FAIL,10 个模板全部通过 - 改 CSS/PHP 结构 → 复制最新样式到样机:
cp lightline/style.css /tmp/llmock/style.css - 真实渲染验证 → playwright + chromium:
executable_path="/usr/local/bin/chromium", args=["--no-sandbox"]device_scale_factor=2,桌面 800×*、手机 390×844 - 断言 → 用
getBoundingClientRect量尺寸/重叠/溢出,不靠肉眼 - 合成预览图 → PIL 左右拼浅色/深色(必要时加手机端),存为
preview-*.png - 打包 → 项目根
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 | 首页引言 |
七、可继续的方向
- Banner 自动抓取最新 3 篇文章的封面 + 标题(现在是纯手动配置)
- 卡片「顶部通栏大图」杂志风布局,或封面比例可配(16:9 / 4:3)
- 首页引言居中排版,或支持引用出处链接
- 归档页分页样式、面包屑、文章目录(TOC)
- 主题截图更新为当前首页(含引言 + Banner)
暂无评论