M-DOC-FULL P2 | EPUB3 NAV 解析支持 #100

New Issue

wangdl · 2026-06-07T21:49:07+08:00

wangdl commented

2026-06-07 21:49:07 +08:00

问题

epub.rs 当前仅解析 NCX TOC（EPUB2 标准）。EPUB3 使用 <nav epub:type="toc"> 元素在内容文件中定义 TOC，不使用 NCX。

影响

打开 EPUB3-only 文件时，read_ncx_toc 返回空 → 章节标题回退到 "Chapter N" → 用户看到的是 "Chapter 1" 而非真实章节标题。

建议

在 NCX 未找到时，查找 OPF manifest 中 properties="nav" 的 item，读取该 XHTML 文件，解析 <nav epub:type="toc"> 中的 <a> 元素提取章节标题和路径。

代码位置

crates/zx_document_core/src/epub.rs:196-216 (read_ncx_toc)

审计来源

#71-#74 批审查发现。

## 问题 `epub.rs` 当前仅解析 NCX TOC（EPUB2 标准）。EPUB3 使用 `<nav epub:type="toc">` 元素在内容文件中定义 TOC，不使用 NCX。 ## 影响打开 EPUB3-only 文件时，`read_ncx_toc` 返回空 → 章节标题回退到 "Chapter N" → 用户看到的是 "Chapter 1" 而非真实章节标题。 ## 建议在 NCX 未找到时，查找 OPF manifest 中 `properties="nav"` 的 item，读取该 XHTML 文件，解析 `<nav epub:type="toc">` 中的 `<a>` 元素提取章节标题和路径。 ## 代码位置 `crates/zx_document_core/src/epub.rs:196-216 (read_ncx_toc)` ## 审计来源 #71-#74 批审查发现。

wangdl referenced this issue

2026-06-07 21:49:40 +08:00

DOC-FULL-015 P1 | PDF metadata / text / search 【status:todo】 #71

wangdl referenced this issue

2026-06-07 21:49:40 +08:00

DOC-FULL-016 P1 | EPUB metadata / spine / toc / chapter 【status:todo】 #72

wangdl commented

2026-06-08 19:52:18 +08:00

实现完成

改动

epub.rs — EPUB3 NAV 解析支持：

1. TOC 读取重构

read_toc() — 统一入口：先尝试 NCX (EPUB2)，失败后回退到 NAV (EPUB3)
read_ncx_toc() — 原有 NCX 解析不变
read_nav_toc() — 新增 EPUB3 NAV 解析

2. NAV 解析

find_nav_item() — 从 OPF manifest 查找 properties="nav" 的 item
parse_nav_links() — 从 NAV XHTML 解析 <a href="...">title</a> 链接
find_nav_href_in_opf() — 获取 NAV 文件路径

3. Spine 过滤

parse_opf 构建 spine 时自动跳过 NAV 项（通过 find_nav_item 检测并排除）

4. 测试

minimal_epub3() — 生成不含 NCX 的 EPUB3 文件（含 NAV XHTML）
test_epub3_nav_fallback — 验证 NAV 回退：3 章节标题正确解析

验证

cargo test epub — 13 passed (含 EPUB3 NAV 测试)
cargo test --all — 164 passed, 0 failed

## 实现完成 ### 改动 `epub.rs` — EPUB3 NAV 解析支持： **1. TOC 读取重构** - `read_toc()` — 统一入口：先尝试 NCX (EPUB2)，失败后回退到 NAV (EPUB3) - `read_ncx_toc()` — 原有 NCX 解析不变 - `read_nav_toc()` — 新增 EPUB3 NAV 解析 **2. NAV 解析** - `find_nav_item()` — 从 OPF manifest 查找 `properties="nav"` 的 item - `parse_nav_links()` — 从 NAV XHTML 解析 `<a href="...">title</a>` 链接 - `find_nav_href_in_opf()` — 获取 NAV 文件路径 **3. Spine 过滤** - `parse_opf` 构建 spine 时自动跳过 NAV 项（通过 `find_nav_item` 检测并排除） **4. 测试** - `minimal_epub3()` — 生成不含 NCX 的 EPUB3 文件（含 NAV XHTML） - `test_epub3_nav_fallback` — 验证 NAV 回退：3 章节标题正确解析 ### 验证 ``` cargo test epub — 13 passed (含 EPUB3 NAV 测试) cargo test --all — 164 passed, 0 failed ```

wangdl closed this issue

2026-06-08 19:52:18 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#100