企业官网建设流程全解析

KOReader目录：3步给EPUB无目录补上章节导航

【免费下载链接】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

KOReader 的目录功能可以从 EPUB 的 H1–H6 标题自动生成多级目录，也能把页码错乱的旧目录修复成有序状态。三步操作后，一本完全没有导航的书就拥有了章节跳转、剩余页码统计和进度条刻度。

一、先说问题：它到底解决什么痛点

早年出版或扫描转换的 EPUB，经常没有 TOC 字段，点开"目录"菜单是一串空白，想翻到某一章只能靠滑动翻页和全文搜索慢慢找。更糟的情况是文件里有目录但页码顺序混乱，章节跳转落到错误位置，进度条刻度也跟着错位。用之前，"找到第三章"要翻几百页；用之后，点一次条目就到位，页脚还能顺带显示当前章节还剩几页。

二、三步快速上手

1. 在阅读页轻触屏幕顶边唤出主菜单，"导航"列第一项就是"目录"。如果这本书自带 TOC，这里会直接列出章节。

上图为 KOReader 的触屏分区示意，顶边 TOP MENU 区域唤出主菜单后进入目录入口

2. 书没有目录时，在"导航"下的"设置"子菜单里勾选"Alternative table of contents"。KOReader 会重新解析 EPUB，按 H1–H6 标题层级构建一份新目录；若全书连标题都没有，它退而按每个 HTML 文件的起始位置划分章节。
3. 目录列表出现后，点任意条目直接跳转，逐级展开/折叠层级，还能用列表顶部的搜索框按章节名过滤，页脚同步显示当前章节的剩余页数。

三、参数与显示配置一览

以上选项都挂在"导航 → 设置"子菜单里，改动即时生效并写入G_reader_settings：

四、真实场景实战

1. 自建教材 EPUB 没有 TOC

场景是典型的纯文本流文档，nav 字段完全缺失。替代目录功能扫描全文标题标签后，教材里"第 1 章"是一级、"1.1"是二级，生成的目录直接呈现两层结构。效果是章节跳转立即可用，页脚进度条按章节分段，读到哪章、还剩多少页一目了然。

2. 页码错乱的长 PDF

场景是扫描版 PDF，引擎给出的目录页码出现回退。加载时validateAndFixToc()会对整个 TOC 做一遍扫描，发现页码倒序就修复涉及范围最小的一批条目，让页码保持递增。若引擎根本给不出目录，改用"Custom table of contents"手动标记各章起始页。修复后，三千页的文档也能稳定按章节跳转。

3. 层级过密的小说目录

小说带章、节、幕多级标题时，进度条刻度会被挤成一团。通过"Progress bars: N ticks"勾选可忽略某一层级在进度条中的显示，还可以把章节导航绑定到保留的刻度上。界面清爽了，跳转和页脚章节名仍照常工作。

五、进阶技巧与常见疑问

• 问：替代目录生成出来偏粗糙怎么办？ 答：在"风格微调 → 杂项"里配置 Alternative ToC hints，可以把非标题元素指定为目录项，也可忽略指定层级的标题。这对标题用得随意的 EPUB 最有用。

• 问：切到替代目录后想恢复原目录？ 答：再次切换同一菜单项即可。KOReader 弹出确认后删除alternative_toc标记并重新加载文档，恢复出厂自带的目录。

• 问：为什么 PDF 里看不到"Alternative table of contents"？ 答：该选项只在 CRE 流式文档（EPUB 等）中出现。PDF 的可行路径是用"Custom table of contents"手工标记章节起始页，一次标记长期有效。

六、实现速览

目录主模块是frontend/apps/reader/modules/readertoc.lua（1534 行），负责加载、修复、展示与跳转；替代目录的构建入口在frontend/document/credocument.lua的buildAlternativeToc()，自定义目录在frontend/apps/reader/modules/readerhandmade.lua。修复逻辑的核心是一次页码递增扫描：

-- 来自 readertoc.lua 的 validateAndFixToc() local cur_page = 0 for i = 1, #toc do local page = toc[i].page if page >= cur_page then cur_page = page -- 页码递增，目录健康 else -- 检测到页码回退，按最小改动范围修复该条目 end end

修复结果写回toc[i].page，原始页码保留在orig_page里仅用于展示，所以坏目录不会在界面上留下痕迹。

七、写在最后

对没有目录的书，KOReader 不改动文档本身，就能给出一份可用的章节结构，且同一份 TOC 被页脚、进度条和 Book Map 复用。拿那本一直没加书签的 EPUB 试一次：顶边轻触 → 导航 → 设置 → 替代目录，当天就能用上。

【免费下载链接】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