文集 / 把博客搬回家

第 15 篇·共 17 篇

卷五 · 网站小结

小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾

2026年10月31日 ·查看目录

小结写完的第二天,清单上的条目开始自己往下走。

小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾

写完《网站开发里程碑小结》时,我在文末留了几个"可选方向,都不急":文章内浮动导航、把书导出 PDF、给合集篇目补单独书摘。两天之后回头看,它们大半已经落地。这篇记录小结之后的这一段打磨——整本合集导出 PDF、阅读页的动态悬浮目录,以及后台编辑体验的收尾;顺手提到的每个坑,都是当时真踩进去又爬出来的。

本文是《网站开发里程碑小结:siliu.online 的架构与特点》的续篇。数据快照更新到 2026-10-31:230 篇文章(198 篇已发布)、28 个分类、98 个标签、3 本合集(67 条篇目)、60 条评论。


一、把整本书导出成 PDF

1.1 选型:ReportLab,而不是 WeasyPrint

需求很简单:合集页面右下角放一个"导出 PDF",作者本人点一下,拿到一本能打印、能存档的书。难点全在中文字体和服务端生成的稳定性上。

两条路的取舍:

方案 优点 现实
WeasyPrint HTML/CSS 直接成 PDF,样式复用最省事 要一堆系统依赖;容器是 python:3.10-slim,apt 装 libgdk-pixbuf2.0-0 偏偏在 trixie 里改了名,还遇上 dpkg 锁卡住
ReportLab(选这个) 纯 pip,无系统依赖;中文有现成的 Adobe CID 字体 版式要自己用流对象搭,没有 CSS 可抄

中文这道坎,ReportLab 自带就够用:

from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.cidfonts import UnicodeCIDFont

pdfmetrics.registerFont(UnicodeCIDFont('STSong-Light'))

注册一次,通篇中文可用。代价是不嵌入字体文件(GB1 字符集交给阅读器),换来的是镜像不用塞十几 MB 的思源黑体,也避开了嵌入中文字体的授权问题。

1.2 正文的来源:仍是"只引用,不复制"

PDF 走的是 Post.rendered_body,也就是前台详情页渲染出的同一份 HTML——文章改了,导出的 PDF 跟着改;文章撤回,PDF 里也不会留下它的位置。这和文集板块的约束是同一条:永远只有一个正文,导出只是它的第三种视图(网页 / RSS / PDF)。

剩下的工作就是把 HTML 翻译成 ReportLab 的流对象:p → Paragraph,h1~h4 → 各级标题样式,img → Image,table → Table,blockquote → 左边线 + 浅底的表格,pre>code → 灰底代码块。

1.3 图片:那些"看不见的图"

第一版导出出来的 PDF 是能看的,但几乎没有图——48 篇文章,只嵌进去 2 张。

根因很典型:站点早年的富文本里,图片几乎都写成 <p><img src="..."></p>,而我把 <p> 当纯文本块处理,只从它的行内子节点里掏文字,于是整张图连同它所在的段落一起被丢掉。

改法是把块级遍历做成递归,任意层级出现 <img> 都抓,不管它套在 <figure>、<div> 还是 <a> 里;GIF 和带透明通道的 PNG 先用 PIL 转成 RGB 再嵌入(ReportLab 的 Image 对 RGBA/GIF 模式会直接报错);按版心宽度等比缩放并限高,title/alt 作为居中的图注写在图下方;同一个 URL 建缓存,一本书里重复出现的配图只下载一次。

改完之后:48 篇嵌了 179 个图片对象,整本约 16MB。这个体积不算小(PDF 里同一张图出现在不同页时会重复写),但对"打印一本自己的书"这件事来说可以接受。

1.4 代码块:左右为难之后选择半手工

网页端之前已经刻意去掉了服务端着色,全站统一用 highlight.js。而 PDF 里没有 JS,只能服务端上色——于是 Pygments 又被装了回来,但只用在这一条导出路径上,网页的配色不被它影响。

过程中撞到两处:

  1. Preformatted(ReportLab 的等宽原样输出)不解析 <font> 富文本标记,Pygments 的颜色直接原样印成了字符串。改为逐行 Paragraph,把行首空格换成 &nbsp; 保留缩进,再整体包进一个灰底的多行 Table——这样既给代码块加了底纹,又能跨页拆分(KeepTogether 会让长代码块整块溢出到页外)。
  2. Pygments 的 HTML 输出已经做过转义,如果再过一遍自己的 escape(),页面上就会印出 &amp;gt; 这样的残字。转义只做一次,一次就够。

另外还补了一条语言标签(vbscript/python/csharp…),让读者知道自己在看什么。

1.5 列表编号:尊重作者当年写下的 start

测试稿里的有序列表全线都以 1. 开头——每一条都是 1.。

查下去发现:老文章常常把一条有序列表拆成多个 <ol>,靠 start="2"、start="3" 续上编号(富文本编辑器里回车断段容易写成这样)。而我当时的实现不管 start,一律从 1 数起。

修法分两层:① 读 <ol start="N"> 的 start 属性作为起始编号;② 保留一层兜底——把"没有 start、且相邻的只含单个 <li> 的同型列表"合并处理,对付另一种拆写习惯。编号这才对齐了原文。

1.6 从"干等十四秒"到进度条 + 下载

最初导出是同步的:点按钮,浏览器白转十几秒,然后突然蹦出一个下载。中间发生了什么,用户一无所知。

切成三段式:

POST /books/<slug>/export/start/        → 校验权限,起后台线程,立即返回 {task_id, total}
GET  /books/<slug>/export/progress/<id>/ → 轮询进度 {status, current, total, label, error}
GET  /books/<slug>/export/download/<id>/ → 流式返回 PDF(支持 Range)
  • 服务器/线程:后台用一个 daemon 线程跑 build_collection_pdf,任务登记在模块级字典里带锁。这条成立的前提是 gunicorn 单 worker——后台线程和轮询请求在同一个进程、同一份内存里。哪天真扩成多 worker,任务登记就必须挪到 Redis 或文件存储。
  • 进度粒度:篇数 + 正文图片数(一次导出 total=159,即 48 篇 + 111 张图),每篇、每张图、最后排版打包各走一步。
  • 前端:遮罩 + 进度条 + "不含图片(更快)"选项;完成后自动下载。

1.7 下载被迅雷接管后报错

进度条跑满、下载框跳出,迅雷却报了一个错。三个原因叠在一起:

  1. 任务被一次性消费:下载视图里当初写的是 _TASKS.pop(task_id)。迅雷这类工具会重发请求、还会多线程分段探测,第二次请求时任务已经被弹掉,于是返回 409。改成 .get() 不消费,改由统一的时间戳清理(超过 1 小时的 temp 文件和任务一起回收,顺带裁剪字典防止内存无限涨)。
  2. 缺少断点续传响应头:补 Range 支持(返回 206 + Content-Range + Accept-Ranges: bytes,越界给 416),再补 ETag(<task 前 12 位>-<size>)、Last-Modified(文件 mtime)、Cache-Control: public, max-age=3600,让下载工具判定这是一个正规的可续传文件。
  3. 前端交出了下载权:原来是 window.location.href = downloadUrl,浏览器转手就把这次附件下载交给了系统下载器。改成 fetch 取 blob → URL.createObjectURL → 程序化点击 <a download>,下载器压根没机会介入;blob 失败才退回直接跳转。

顺带一个容易忘的实现细节:支持 Range 必须用 StreamingHttpResponse。HttpResponse(一个生成器) 并不能流式输出,它没有 streaming_content,按字节切区间会出错。

1.8 权限:只有作者能导出

导出的是"整本书"而不是单独一篇文章,所以权限比阅读更严:_can_export() 判断作者本人,或在作者为空时允许超级管理员。匿名请求 302 跳登录,其他登录用户 403。导出按钮在详情页也只对作者显示。


二、阅读页的动态悬浮目录

这个功能的参照物是我自己最喜欢的那种交互:屏幕右缘平时只有几条安静的小横线,鼠标靠近,它们才从右往左滑开,变成本书的篇目表。

2.1 第一版做错了方向

初版按常规做法:一个 overflow:hidden 的外壳 + 一个整体 translateX 的面板。效果出来一看——横线停在了距离屏幕右缘 290px 的地方。因为整体左移的是整个面板,可见的那条带跟着面板一起跑到了中间,压根没贴边。

2.2 每一行自己做抽屉

推翻重来的思路是:每一行自己就是一个抽屉。

.bc-floattoc__item {          /* 折叠:只剩右缘的一条小横线 */
  width: 34px;
  height: 28px;
  display: flex;
  justify-content: flex-end;  /* 内容永远贴右缘 */
  overflow: hidden;           /* 左边多出来的部分裁掉 */
  box-sizing: border-box;     /* 必须:bootstrap 的全局 border-box 会让这里漂移 */
  pointer-events: auto;
}
.bc-floattoc.is-all-open .bc-floattoc__item { width: 320px; }

行宽从 34px 长到 320px,因为内容右对齐、溢出在左侧被裁掉,视觉上就是"从右往左滑出来",而横线本身始终钉在右边缘。容器 .bc-floattoc 设成 pointer-events: none,只有每一行自己 auto——折叠时除了那 34px,屏幕其他地方完全不挡正文。

这里还藏着两个不把数值量出来就发现不了的坑:

  • --bc-* 调色板原本写在 .bc-hero 的作用域里。悬浮目录不在那个元素内部,var(--bc-ink) 全部解析为空,于是"当前篇"那条该是墨色的横线,实际背景是透明。整套变量挪到 :root 才正常。这类"变量作用域"的问题,肉眼验收很难发现,得用 getComputedStyle 探针打出来。
  • box-sizing 漂移:bootstrap 设了全局 border-box,而单独引入的 anthology.css 在某些加载顺序下是 content-box,同一句 width:34px 会变成 34 + 26(内边距) = 60px,横线就不再居中了。

2.3 让它像波浪一样荡开

只展开当前悬停的那一行还不够——我希望鼠标靠近时,最近的行先动,然后像水波一样扩散,最后整块目录全部铺开。

做法:JS 以指针所在行下标为中心,给容器的所有直接子项(卷名行和篇目行交错混排,一共 54 个)写入各自的延迟,CSS 用这个延迟做过渡:

var STEP = 18;    // 每远一行的延迟增量
var MAX  = 420;   // 延迟上限,避免最远的行等太久

function spread(origin) {
  var home = cells.indexOf(origin);
  cells.forEach(function (el, i) {
    el.style.setProperty('--bc-delay', Math.min(Math.abs(i - home) * STEP, MAX) + 'ms');
  });
}
toc.classList.add('is-all-open');   // 先排好延迟,再统一放开宽度
.bc-floattoc__item { transition-delay: var(--bc-delay, 0ms); }

于是离指针近的先展开,远的晚一步:延迟以指针为中心对称(36/18/0/18/36ms),最终在约 560ms 时全部铺平。卷名行也一起参与延迟,否则分组那一段会断层。已经铺开之后不再重排波浪,避免在面板里上下移动时被反复从头荡一遍。

2.4 鼠标明明在里面,为什么立刻收起

铺开之后一移动鼠标,目录就闪烁着退回去了。两个原因:

  1. 卷名行不可命中:容器是 pointer-events:none(折叠时不能挡正文),只有篇目行恢复了 auto,而 6 个卷名行各占 26px 高、依然是 none。鼠标在目录里上下移动必然穿过卷名行,那一瞬命中测试落到 body → 容器 mouseleave 立即触发 → 整块收起;落到下一行又重新荡一遍波浪。
  2. mouseleave 零宽限:任何擦边、手抖、从首尾行的圆角斜着掠出去,都立刻收。

修法两条:

.bc-floattoc.is-all-open { pointer-events: auto; }   /* 铺开后整块接管,面板内无缝隙可逃 */
var GRACE = 320;   // 移开后的宽限期
function closeLater() {
  clearTimeout(timer);
  timer = setTimeout(function () { /* 真正收起 */ }, GRACE);
}

关键在于:一旦铺开,容器整块接管事件,面板内部(含卷名行、行列之间的缝)再也命中不到 body;而折叠态仍然保持 none,照样不挡正文。再给收起加 320ms 宽限,期间任何一次行内 mouseover(哪怕落在面板空白处)都会取消收起。

验证用的是 elementFromPoint 扫描:折叠态只有右缘 34px 那条带命中目录,左侧 320px 完全透传给正文;展开态在右缘、中部、左缘各取 x 采样,26 行全部命中目录内部,落空 0。

验收小结:判断"某个样式有没有生效"别靠肉眼看截图,用 --dump-dom + 内联探针打印 getComputedStyle;截图只用来看整体版式。另外,--virtual-time-budget 下 CSS 过渡是不推进的(采样永远是初始值),负 transition-delay 冻结中间帧在无头下也无效——想验动画,得用同一条 cubic-bezier 在 JS 里算出各时刻的理论宽度再静态渲染。这条坑让我一度误判过两次。


三、后台的收尾:48 行的编辑表不再横向滚动

书里的篇目一旦多达几十条,编辑页就成了灾难:横向滚动条左右拖,改一段书摘要要来回拖滚动条。查下去是三层原因叠的:

  1. admin 自己有定额宽度:单行输入 20em、textarea 48em,一篇目五个字段(排序 / 卷 / 篇名 / 书摘 / 文章)摊开就是 5em + 20em + 20em + 48em + 20em ≈ 1800px。
  2. .related-widget-wrapper 默认 float: left(文章外键那一格:下拉框 + 三个操作图标),浮动盒按内容算宽,不受表格单元格约束,直接顶到表格外面。
  3. 我一开始的"修复"制造了新问题:给 select 加 width:100% !important,会把 select2 藏起来的原生 <select>(.select2-hidden-accessible,position:absolute; width:1px)按视口解析成整表宽,反而多出几百 px 溢出。凡是给 admin 里的 select 设宽度,必须用 :not(.select2-hidden-accessible) 排除这个替身。

最终方案:表格改 table-layout: fixed + 表头按百分比定列宽(排序 7 / 卷 12 / 篇名 21 / 书摘 26 / 文章 28 / 删除 6),所有控件一律撑满自己那一格;.related-widget-wrapper 取消浮动改成 flex(图标固定、下拉吃掉剩余宽度,width:auto !important 覆盖 select2 写死的内联宽度,低于 120px 就让图标换行)。

效果:1440px 宽度下横向溢出 697px → 0,在 1600 / 1440 / 1366 / 1280 / 1024 五档下都为 0,表格宽度恒等于父容器可用宽度。


四、顺带:内容侧的一次重编

《结构技术文萃》在建库后经历了一次改组:把"基础 / 管桩"从散落的分类里单独拎成一卷,剔除一级注册结构考试那几篇纯报名参考文,书名定成《结构设计笔记》,最后又把"结构插件"独立成卷。结果是六卷 48 篇——原本按分类散落的技术文章,被排成了一条"先设计、再工具、再基础、最后回到计算与理念"的阅读线。

这件事本身没写新代码,但它验证了一件事:目录结构一旦能自由编排,"把散篇变成书"这件事才开始真正产生价值。


五、现在的样子

回头看小结之后这两天做的事情,几乎没有一件是"新增功能",全是把已有的东西向"真的好用"推进:

  • PDF 导出从一个"能吐文件"的接口,走到了同款封面、高亮代码、179 张配图、带进度、不会被下载器搞砸;
  • 悬浮目录从一个"整体滑出的面板",走到了每行一个抽屉、波浪扩散、进去以后赶都赶不走;
  • 后台篇目表从一个"必带横向滚动条的地方",走到了任何屏幕宽度都不溢出。

它们的共同点是:第一版都能跑,但都不是"我用起来舒服"的状态。而做到这一点,靠的基本是同一个动作——不要相信肉眼,去测真实的数值:PDF 里的图片对象数、getComputedStyle 算出的样式值、表格横向溢出的像素、elementFromPoint 的命中数、铺开后的标题行数。测得越具体,改得越准。

《网站开发里程碑小结》里留下的"可选方向",现在划掉了浮动导航与导出 PDF 两条。剩下的选项(书籍 RSS、按卷导出、逐篇补单独书摘)还在清单上——不急,但大概也不会等太久。

定稿于 2026.10.31

本书目录
  1. 01 把网站从云服务器搬回家里:Django + Docker + IPv6 DDNS 迁移实录
  2. 02 评论功能迁移完善:把四处 site-packages 补丁收拢为 sitecomments 自定义 app
  3. 03 为什么 AAAA 记录指向家里的 IPv6 地址,外网就能直接访问
  4. 04 外网打不开、本机却正常:一次 IPv6 静默断网三小时的完整复盘
  5. 05 用 Markdown 写博客:一篇示例,也是本站的格式说明
  6. 06 给博客加上 Markdown:一个字段、两套渲染层,和一堆必须小心的地方
  7. 07 把编辑器打磨顺手:去掉多余确认、对齐宽度,让评论也用上 Markdown
  8. 08 收尾两件事:评论只剩 Markdown,代码高亮只剩一套
  9. 09 编辑栏合并成一套,顺手补上撤销重做
  10. 10 博客媒体全面上云:CDN 域名统一与纯云存储改造
  11. 11 把博客升级到 Django 4.2 LTS:一次低风险、却有意外收获的升级
  12. 12 网站优化记录:存储后端本地化与 Markdown 编辑器统一
  13. 13 把文章编成书:给博客加一个「文集」板块
  14. 14 网站开发里程碑小结:siliu.online 的架构与特点
  15. 15 小结之后的继续打磨:PDF 导出、悬浮目录与后台收尾
  16. 16 本站功能与使用指南:siliu.online 一览
  17. 17 外网也能传:用 Docker SFTP 把静态站点直推到家宽服务器