扫描版PDF没有目录导航？KOReader 3步帮你打开智能章节目录-平芜编程栈

扫描版PDF没有目录导航？KOReader 3步帮你打开智能章节目录

【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreader

很多老书打开就是这种体验：几百页连续排版，页面上找不到任何"第几章"的标记，想翻到某一节只能一页一页滑。这不是格式问题——同样是 PDF，有目录和没目录的体验天差地别。KOReader（支持 PDF、DjVu、EPUB、FB2 等格式的电子书阅读器）针对这个痛点做了两层设计：文档自带目录就直接用；没有的话就自动生成一份，并且把乱序、缺页的目录条目自动修正。整套逻辑集中在 readertoc.lua 这一个阅读器模块里。

为什么你的文档打开没有目录

先把问题拆开看，目录缺失通常分三种情况，对应不同的处理结果：

文档本身就没有导航结构。扫描版 PDF 是最典型的例子：内容只是页面图像，不存在"章节"数据。
目录数据存在但质量差。某些引擎解析出的条目页码倒序、深度错乱，阅读器直接拿这种目录没法用。
目录存在但粒度太粗。只有一级标题，翻长书时定位仍然费力。

KOReader 对前两种情况的回应是：文档无法提供可用目录时，打开阶段会生成一份替代目录（alternative TOC）；拿到目录后先做一次校验修复，把页码不递增的"坏条目"批量拉回合理位置，条目旁会同时保留原始页码方便对照。

目录从哪里来：自带优先，自动补齐

打开一本书时，模块内部按这个顺序取数：

先看文档能不能提供目录，能就直接读取；
不能则尝试构建替代目录，且构建结果会随缓存保存，下次打开不用重复计算；
无论来源如何，统一过一遍validateAndFixToc()，修正顺序后再交给界面。

所以目录标题后面有时会跟一个小图标，它就是在提示你：当前这份目录不是文档原生的，而是 KOReader 生成的。看到它不必担心，只是来源标记。

3步打开并使用章节目录

第1步：打开目录视图

两个入口任选：

阅读器主菜单里的"Table of contents"；
快捷键（由 hotkeys 插件接管）：T或Shift + Up。

打开后是一个可滚动的菜单列表，层级关系通过缩进体现，深层节点默认折叠到第 2 级，点行首的展开/收起图标即可调整。

第2步：搜索定位，而不是手动滚动

长文档里翻目录列表很累，KOReader 内置了目录过滤：在目录界面触发搜索（菜单项 showTocDialog / 搜索框），输入关键词后列表只显示命中条目及其父级；输入*则还原完整目录。没命中时会给出"无结果"提示，而不是静默空白。

第3步：跳转与章节进度

点任意条目直接跳到对应页；
模块同时维护了"当前页属于哪一章"的状态，提供上一章/下一章的取位接口，以及本章总页数、剩余页数、已完成页数这几项计算，供页脚和进度组件消费；
配合阅读设置里的"章节边界强制刷新"，翻页跨章时会触发 e-ink 全刷，减少残影。

可调的显示参数

目录界面有几个独立于文件浏览器的设置，都按当前设备全局保存：

每页条目数（toc_items_per_page，默认 14）；
条目字号（toc_items_font_size，首次会从文件浏览器的字号迁移过来）；
是否显示章节长度：开启后每个条目尾部追加该章页数，判断"这一章大概多厚"很实用；
目录项之间的点线连接（toc_items_with_dots）。

进阶技巧与避坑

长书优先用搜索定位，列表滚动在条目上千时体验明显变差；
折叠策略：默认只展开到第 2 级，层级很深的技术书可以先整体折叠，再按需逐层展开，减少每屏噪音；
章节长度依赖页码差值计算，如果目录里混入了非线性页面（如附录流），显示的页数以主流程为准，属正常现象;
改了排版设置后目录会自动重建，不需要手动刷新，重新打开目录视图即可看到新结果；
目录乱序不用自己修，validateAndFixToc()会按"改动最少"原则把坏条目页码对齐到相邻正常条目，并在界面上标注原始页码。

小结

对没有导航结构的文档，KOReader 的处理路径很直接：能读则读，读不到就生成，拿到手先修复再用，再用搜索和折叠把浏览成本压下来。整套行为（填充、校验、章节长度计算、展开状态、搜索过滤）都集中在 frontend/apps/reader/modules/readertoc.lua 一个模块内，想确认某个行为的具体规则，看这一个文件就够了。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考