之前写更新日志,都是「今天改了什么」的流水账。这次换个角度:把主题仓库里 tag 之间的提交全部拉出来,按版本重新读一遍,看看这五个版本到底在解决什么。
从 10-11 首版到 10-19 的 v1.4.0,一共 5 个版本、24 个提交,累计 49 个文件、+4212 / −610 行。有意思的是,主线并不是「功能越堆越多」,而是一条不断把站点层补丁收回主题本体的线。
一、五个版本一览
| 版本 | 日期 | 提交 | 改动规模 | 这一版的主线 |
|---|---|---|---|---|
| v1.0.0 | 10-11 | 7 | 33 文件 · +2819 / −206 | 从零立起三模式骨架,响应式改自适应 |
| v1.1.0 | 10-12 | 3 | 19 文件 · +560 / −95 | 一次收编站点层规避的 9 个缺陷 |
| v1.2.0 | 10-13 | 4 | 23 文件 · +1221 / −18 | 中英切换与 AdSense 广告位 |
| v1.3.0 | 10-14 | 5 | 12 文件 · +223 / −39 | 手机端抽屉按钮归零、悬浮按钮组 |
| v1.4.0 | 10-19 | 5 | 13 文件 · +873 / −112 | 导航栏升为多级菜单 |
一套代码同时产出 blog / notes / docs 三种形态,响应式改为三档自适应。
侧栏折叠、选项卡、笔记过滤、分页、挂件栏等 9 个缺陷回归主题本体。
导航栏中英切换、运行期界面语言替换、Google AdSense 广告位。
抽屉档菜单按钮被 flex 压成 0 宽的问题原生修复,新增悬浮按钮组。
导航栏支持三级菜单,新增 nav 配置节;顺手修掉档位规则与版权占位符。
二、v1.0.0 · 先立骨架
首版只做一件事:让一套模板同时撑起三种形态。layout.ejs 按 page.mode || theme.mode 分发,blog 走列表 + 挂件栏,notes 走左侧笔记树,docs 走三栏文档布局。
真正费工夫的是自适应。之前的写法是媒体查询里逐条改样式,档位一多就互相打架;这版改成三档独立令牌——手机 / 平板 / 桌面各自一套尺寸、间距、字号变量,细节规则按档位分别生成,而不是在一份样式上不断覆盖。
同版还收掉了三个小问题:语言占位符没替换、文档翻页到最后一页时出现空白翻页条、笔记侧栏的当前分类重复出现两次。
三、v1.1.0 · 把补丁收回本体
这是五个版本里含金量最高的一版。背景很具体:站点为了能上线,在主题外面写了 overrides、scripts、custom.css 一堆规避文件,主题一升级,补丁全废。与其维护这层壳,不如把能力补回主题。
| 站点补丁 | 收编后在主题里的形态 |
|---|---|
| P1 文档侧栏不能折叠 | has-children 两列栅格 + 纯 CSS 收起态,expanded / auto_expand / toggle_label 三个配置真正生效 |
| P2 选项卡点不动 | 模板只产出了 DOM 和样式、没有切换逻辑,补上按钮与面板联动、方向键导航、aria-selected 同步 |
| P3 笔记侧栏收录混乱 | 新增 note_categories / note_tags 过滤(同时配置取交集),group_by: none 支持平铺,collapsed 从死配置变活 |
| P4 首页与末页页码偏移 | 翻页组件始终输出「上一页 / 下一页」,不可用时给禁用态占位,不再左右跳位 |
| P5 挂件被裁掉 | 去掉挂件栏的 max-height / overflow-y,不再出现侧栏自己的滚动条把下方挂件切掉 |
| C7 无标题页右侧空栏 | 目录栏增加「页面真有 h2–h4 标题」判定,没有就整栏不渲染 |
| C2 Waline v2 不认配置 | 评论区把 snake_case 选项归一成驼峰(server_url → serverURL 等),v2 才认 |
一次提交、17 个文件、+490 / −93,站点的自定义目录当天就清空了。事后看,这版定下了一条规矩:能在上游修的,绝不留在站点层。
四、v1.2.0 · 双语与广告
两个新能力,都是「配置即用」型:
- 界面语言:导航栏加中英切换,运行期替换界面文案,不用重载页面。
- AdSense:支持挂 AdSense 广告,广告位可在配置里声明位置与尺寸。
改动量不小(+1221 行),因为语言包要按主题里所有文案逐条抽出来。不过它也埋了个雷:语言选项的属性写法误命中了页面根元素,导致全站链接点不动——下一版就修这个。
五、v1.3.0 · 手机端那个「消失」的按钮
症状是手机端导航栏左侧的汉堡按钮既看不见也点不动。DOM 在、图标在、事件也在,display 和 visibility 都正常,但它的宽度算出来是 0。
根因在头部 flex 布局:品牌区与工具区都设了不收缩,唯一允许收缩的菜单按钮成了溢出量的「垃圾桶」,38px 被压到 0。
这版的原生修复做得比站点临时补丁更全:按钮固定不收缩、品牌区可收缩并带 min-width 保底、logo 不参与压缩,顺带把悬浮按钮从 inline-grid 改成 inline-flex(此前图标和文字被排成两行)。
同期还有两件事:修掉上版遗留的全站链接失效问题(属性误命中根元素),以及新增右下角悬浮按钮组——回到顶部、深浅色切换,文档页多一个「文档目录」按钮,手机上尤其实用。
六、v1.4.0 · 导航栏长出了第三层
本站正好是这版的重度用户:现在顶部是「文档 → 教程 → TypeScript」三级菜单。之前菜单只能平铺,多出来的层级只能挤进一个页面里的锚点。
v1.4.0 给菜单加了 children 嵌套,并配了一个 nav 配置节:
| 配置项 | 默认值 | 作用 |
|---|---|---|
depth |
3 |
最多渲染几级:1 只有一级,2 一级 + 下拉,3 下拉里再往右飞一层 |
trigger |
hover |
桌面展开方式,hover 悬停展开、click 点箭头才展开(触屏一律走点击) |
hover_delay |
120 |
悬停移出后的收起延迟,单位毫秒,0 为立即收起 |
submenu_width |
190 |
子菜单最小宽度,二级下拉与三级右飞共用 |
drawer_accordion |
true |
窄屏抽屉里的形态:true 可折叠分组、false 全部拉平按层级缩进 |
菜单项的写法有两种语义,容易搞混:
- 只写
children不写path—— 这一项本身就是展开按钮,点了不跳转; path与children都写 —— 点击跳转,右侧的箭头单独负责展开。
本站的三级菜单就是这么写的:
1 | 文档: |
教程 只当分组用(没有 path),点击只展开不跳转;TypeScript 才是真正的链接。层级超过 nav.depth 的部分会被截断,所以改结构时记得对一眼这个值。
同版还夹了两个修复。一个是版权声明里的 {link} 占位符:替换结果是一段链接标签,原先用转义输出,页面上直接显示成字面代码,改成原样输出才对。另一个是自适应档位规则的老毛病——细节样式直接拼在选择器前面,一段逗号列表里只有第一个选择器带了档位前缀,后面的全变成全局规则。比如一条本该只作用于手机档的三列网格规则,把桌面端的友链也压成了一列。修法是按顶层逗号拆分(括号里的逗号不动),逐个选择器补前缀;顺手给手机档加了分页降级,390px 下只保留上一页 / 下一页,不再被一长串页码撑破布局。
七、升级要注意什么
主题既可以 npm 装,也可以像本站这样用 git submodule 锁版本(当前锁在 ccb49a7 = v1.4.0)。从旧版本升上来的话,只有三处值得留意:
- v1.1.0 之后:之前写在站点层的 overrides / scripts / custom.css 该逐条删掉了,能力已经在主题里,留着反而互相覆盖。
- v1.2.0 之后:
Waline的配置键用驼峰写法(serverURL/requiredMeta/pageSize),旧写法虽然兼容,但会让人误以为是新版不认配置。 - v1.4.0 之后:既有菜单不用改,不写
nav节就走默认值;要做多级才加children,注意depth与drawer_accordion的搭配。
判断「这个需求该不该进主题」的两条土办法:一看它是否需要站点重复写同样的规避代码,二看它是否属于主题自身的渲染职责。两条中一条成立,就该往上收,而不是在站点层打补丁。
八、写在最后
五个版本看下来,代码量涨得不快(+4212 行里还有一大半是语言包和文档),但站点层的自定义文件从十几个变成了零。这件事比多加几个功能更值——主题升级不再意味着重新对一遍补丁,锁个版本、拉一下 submodule 就能跑。
下个版本想做的还是这个方向:把配置里那些「必须读源码才知道怎么写」的地方,都变成带注释的默认值。
评论