KOReader 目录生成指南：10 分钟给无目录的电子书补上章节导航-迪斯科星球

KOReader 目录生成指南：10 分钟给无目录的电子书补上章节导航

【免费下载链接】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、EPUB、DjVu 等格式的跨平台电子书阅读器，它的智能目录生成能力，能直接利用文档里的标题层级重建一份可用的目录。本文讲清楚这个功能是什么、三步怎么开启、背后怎么工作，以及目录乱序时该怎么调优。

功能速览：目录生成能替你省掉什么

省掉手动定位：文档没有内置目录时，KOReader 扫描正文中的 H1–H6 标题，自动生成一份"替代目录"，像给一本没印目录的书手抄一份，之后按章节直接跳。
目录乱序自动修复：像图书管理员发现上架顺序错了，先快速扫一遍，再就近纠正。目录页码错乱时，模块会自动检测并按最小组合方式修复。
章节进度随手看：页脚始终显示当前章节标题，还能算出本章已读多少页、还剩多少页。
手动微调空间：自动生成的目录不满意，可以切换到手动目录，自己逐条添加章节；也可以折叠层级、忽略过深的目录项。
适合谁：在读老书、扫描版 PDF、自建 EPUB，或目录损坏、层级混乱文档的人。

三步上手：从打开书籍到按章节跳转

第 1 步：打开那本没有目录的书

在文件浏览器里点选书籍文件。EPUB 和 PDF 都能直接打开。打开后先点顶部菜单，找到"Table of contents（目录）"一项，确认它确实是空的或不可用。

第 2 步：用文档标题生成替代目录

在目录菜单下方有一个"Use alternative table of contents"勾选项。勾选后系统会重新扫描文档标题，生成一份替代目录并立即显示出来。菜单标题旁出现一个特殊图标，说明当前展示的是替代目录而不是文档原生目录。想换回原生目录，再勾一次即可。

第 3 步：点目录项跳转，页脚跟进进度

在目录里点击任意条目，页面直接跳到对应位置。之后阅读时，页脚会显示当前章节标题，支持上一章/下一章快速切换，本章页码进度也会实时累加。

它是怎么做到的

先看效果：打开一本书，目录模块先问文档引擎"有没有自带目录"；没有的话，就标记为"用标题构建替代目录"。与此同时，拿到目录数据后它还会做一次快速校验——页码必须递增，发现乱序就自动就近修复，不需要你手动干预。

核心逻辑在 readertoc.lua 的validateAndFixToc()里，下面是它的快速扫描段：

-- 快速扫描：TOC 项的页码必须递增，否则标记为需要修复 local has_bogus, cur_page = false, 0 for i = first, last do if toc[i].page < cur_page then has_bogus = true break end cur_page = toc[i].page end if not has_bogus then self.toc_depth = max_depth; return end -- 全部递增，无需修复

这段代码做的事：从头到尾扫一遍目录，记录已见的最大页码，一旦某条目标页码比它小，就判定目录"有毛病"。扫描同时顺手算出目录最大深度和每条项在同层级的序号——序号后面给 BookMap 等组件复用。发现问题后，修复逻辑会统计"往前改几条 vs 往后改几条"，选改动最少的一组把页码拉回正确位置。

替代目录的构建由文档引擎完成：credocument.lua 把buildAlternativeToc()转给底层，从 H1 到 H6 标签逐级取标题；如果文档连标题都没有，就退化为按 HTML 文件片段定位，保证至少每章起点可点。标题的取舍规则集中在 css_tweaks.lua 的"Alternative ToC hints"小节，手动编辑目录则由 readerhandmade.lua 负责。

实战场景：三种真实用法

给扫描版 PDF 补上章节导航

问题：扫描版 PDF 通常没有原生目录，KOReader 的目录菜单是空的。操作：打开书，进目录菜单，勾选"Use alternative table of contents"。系统按 OCR 识别出的标题层级建目录，目录项指向每章首页。结果：目录页直接列出"第一章……第 N 章"，点击即跳转，不再靠拖拽翻页找章节。

目录页码错乱怎么救

问题：某些 EPUB 元数据里章节页码丢失或重复，目录一打开，顺序是乱的。操作：什么都不用做。每次打开书或重载文档，validateAndFixToc()都会跑一遍扫描，乱序项按"改动最少"原则就近修正页码。结果：你看到的目录是修好的版本；极端情况下个别条目可能停在相邻章节首页，跳转差一两页，但整体导航可用。

目录层级太深，页面显示拥挤

问题：教材类文档目录层级多，默认每页显示条数下根本放不下，页脚章节标题也显得挤。操作：调高"TOC items per page"数值（默认 14）；或在菜单里对过深的层级勾选忽略，让它不参与页脚和快速跳转栏。结果：目录界面清爽，页脚只保留你要的一级章节，阅读时不被噪音干扰。

调优与避坑

toc_items_per_page与toc_items_font_size：目录每页条数和字体大小独立可调，存在用户设置里；长目录的书适当调大条数，减少翻页。
手动目录与替代目录互斥：启用"Custom table of contents（手动目录）"后，替代目录选项自动禁用。想切回自动生成，先到手动目录里关闭，再打开替代目录，菜单里会直接提示。
标题识别不准就改 CSS 提示：在"Style tweaks → Miscellaneous → Alternative ToC hints"里，可以忽略 H1–H6 中不想要的级别，也能把特定非标题元素标记为目录项。改完后要把替代目录关一次再开一次，才会用新规则重建。
章节长度统计：目录条目后面显示的"本章还有 N 页"由 readertoc.lua 的getChapterPagesDone()等函数计算，翻页时自动刷新，无需配置。
目录完全为空的对策：文档既无原生目录也没有可识别标题（例如纯图片扫描且 OCR 质量差），替代目录建不出来。此时用手动目录：在任意页面添加一条"Custom TOC"项，逐章手工标注，虽然麻烦但保底可用。
切换替代目录后书籍重载：勾选或取消替代目录都会使当前缓存失效、重新加载文档，这是正常行为，进度不丢。

延伸：还能玩什么

BookMap：用色块图展示整书章节分布，点击色块直达章节，依赖目录里算好的层级序号。
SkimTo 快速浏览：把目录压缩成一条可拖动的进度条，扫读整本书结构。
快捷键呼出目录：hotkeys 插件默认绑定T键（Shift+Up）直接打开目录，键盘党友好。
目录搜索：目录界面自带搜索框，章节名很长时输入关键词即可定位条目。
导出与分享：exporter 插件支持把当前视图内容导出为 Markdown，配合手动目录整理个人读书笔记。

没有目录的书，现在十分钟内就能补上可用的章节导航。打开你手边那本目录为空的 PDF，按第二步勾上替代目录，看看它识别出多少章节。

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

企业官网建设流程全解析