feat(epub): complete wxread parity scope

2026-05-26 09:19:37 +08:00
parent 23182e8b5a
commit 0e7d952fe5
31 changed files with 2619 additions and 1533 deletions
@@ -76,6 +76,10 @@ public struct RDEPUBTextBook {
    public var pages: [RDEPUBTextPage]
    /// 全局索引表：fileIndex/row/column → 绝对字符偏移量
    public let indexTable: RDEPUBTextIndexTable
+    /// 对标 WXRead 的位置转换器（文件位置 <-> 全书字符位置 <-> 页码）
+    public var positionConverter: RDEPUBTextPositionConverter {
+        RDEPUBTextPositionConverter(book: self)
+    }

    public init(chapters: [RDEPUBTextChapter], pages: [RDEPUBTextPage]) {
        self.chapters = chapters
@@ -93,12 +97,47 @@ public struct RDEPUBTextBook {
        return RDEPUBChapterData(chapter: chapter, indexTable: indexTable)
    }

+    /// 按 spine 索引获取章节的数据访问层。
+    public func chapterData(forSpineIndex spineIndex: Int) -> RDEPUBChapterData? {
+        guard let chapter = chapters.first(where: { $0.spineIndex == spineIndex }) else { return nil }
+        return RDEPUBChapterData(chapter: chapter, indexTable: indexTable)
+    }
+
    /// 按章节序号获取章节的数据访问层
    public func chapterData(atChapterIndex index: Int) -> RDEPUBChapterData? {
        guard chapters.indices.contains(index) else { return nil }
        return RDEPUBChapterData(chapter: chapters[index], indexTable: indexTable)
    }

+    /// 按绝对页码（从 1 开始）获取章节的数据访问层。
+    public func chapterData(forPageNumber pageNumber: Int) -> RDEPUBChapterData? {
+        guard let page = page(at: pageNumber) else { return nil }
+        return chapterData(forSpineIndex: page.spineIndex)
+    }
+
+    /// 根据持久化位置解析所属章节的数据访问层。
+    public func chapterData(
+        for location: RDEPUBLocation,
+        resolver: RDEPUBResourceResolver,
+        bookIdentifier: String?
+    ) -> RDEPUBChapterData? {
+        guard let normalizedLocation = resolver.normalizedLocation(location, bookIdentifier: bookIdentifier) else {
+            return nil
+        }
+        return chapterData(for: normalizedLocation.href)
+    }
+
+    /// 全书章节信息快照；对标 WXRead 由章节模型直接提供章节元数据。
+    public var chapterInfos: [EPUBChapterInfo] {
+        chapters.map { chapter in
+            EPUBChapterInfo(
+                spineIndex: chapter.spineIndex,
+                title: chapter.title,
+                pageCount: chapter.pages.count
+            )
+        }
+    }
+
    /// 按页码（从 1 开始）获取对应页面
    public func page(at pageNumber: Int) -> RDEPUBTextPage? {
        guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else {
@@ -115,51 +154,30 @@ public struct RDEPUBTextBook {
    /// 3. navigationProgression 进度百分比回退
    public func pageNumber(for location: RDEPUBLocation, resolver: RDEPUBResourceResolver, bookIdentifier: String?) -> Int? {
        guard let normalizedLocation = resolver.normalizedLocation(location, bookIdentifier: bookIdentifier),
-              let chapter = chapters.first(where: { $0.href == normalizedLocation.href }) else {
+              let chapterData = chapterData(for: normalizedLocation.href) else {
            return nil
        }

        if let anchor = normalizedLocation.rangeAnchor?.start,
-           let page = indexTable.pageNumber(for: anchor, in: self) {
-            return page + 1
+           let page = positionConverter.pageNumber(for: anchor) {
+            return page
        }

-        let targetOffset: Int
-        if let fragment = normalizedLocation.fragment, let fragmentOffset = chapter.fragmentOffsets[fragment] {
-            targetOffset = fragmentOffset
-        } else {
-            let lastOffset = max(chapter.attributedContent.length - 1, 0)
-            targetOffset = min(lastOffset, max(0, Int(round(Double(lastOffset) * normalizedLocation.navigationProgression))))
+        if let anchor = indexTable.anchor(for: normalizedLocation),
+           let page = positionConverter.pageNumber(for: anchor) {
+            return page
        }

-        if let page = chapter.pages.first(where: { targetOffset >= $0.pageStartOffset && targetOffset <= $0.pageEndOffset }) {
-            return page.absolutePageIndex + 1
-        }
-
-        return chapter.pages.last.map { $0.absolutePageIndex + 1 }
+        return chapterData.pageNumber(for: normalizedLocation)
    }

    /// 根据页码生成持久化位置（RDEPUBLocation），包含起止锚点
    public func location(forPageNumber pageNumber: Int, bookIdentifier: String?) -> RDEPUBLocation? {
-        guard let page = page(at: pageNumber),
-              let chapter = chapters.first(where: { $0.chapterIndex == page.chapterIndex }) else {
+        guard let chapterData = chapterData(forPageNumber: pageNumber),
+              let page = page(at: pageNumber) else {
            return nil
        }
-
-        let totalLength = max(chapter.attributedContent.length - 1, 1)
-
-        let startAnchor = indexTable.anchor(forAbsoluteIndex: page.pageStartOffset, in: chapter)
-        let endAnchor = indexTable.anchor(forAbsoluteIndex: page.pageEndOffset, in: chapter)
-        let rangeAnchor = RDEPUBTextRangeAnchor(start: startAnchor, end: endAnchor)
-
-        return RDEPUBLocation(
-            bookIdentifier: bookIdentifier,
-            href: page.href,
-            progression: Double(page.pageStartOffset) / Double(totalLength),
-            lastProgression: Double(page.pageEndOffset) / Double(totalLength),
-            fragment: nil,
-            rangeAnchor: rangeAnchor
-        )
+        return chapterData.location(forPage: page, bookIdentifier: bookIdentifier)
    }
 }