feat: EPUB 阅读器搜索、选中注释、书签 chrome 状态及大量重构优化

- 新增 RDEPUBReaderSearchCoordinator 与 RDEPUBSelectionState 管理搜索和选中状态 - 新增 BookmarkChromeStateTests、NavigationBackwardTests、SelectionAnnotateTests 等 UI 测试 - 新增多个边界测试 epub 样本（损坏结构、空归档、缺失文件、流式外链验证） - 重构阅读器 chrome 状态管理，统一 tool bar 与 search bar 交互 - 优化大书分页缓存策略（RDEPUBChapterSummaryDiskCache、RDEPUBPageCountCache） - 移除废弃的 RDEPUBLocationConverter 和 RDEPUBPageBreakPolicy - 更新 epub-bridge.js 与 JS bridge 通信协议 - 全面更新现有 UI 测试以适配新的 helper 和状态管理
2026-06-13 22:48:56 +08:00
parent 27e9b85ddb
commit 6f75b083f7
83 changed files with 4824 additions and 1879 deletions
@@ -51,6 +51,21 @@ final class RDEPUBReaderSearchCoordinator {
        advanceSearch(by: -1)
    }

+    /// 跳转到指定索引的搜索匹配项
+    @discardableResult
+    func selectSearchMatch(at index: Int) -> Bool {
+        guard let controller else { return false }
+        guard var searchState = controller.searchState,
+              searchState.matches.indices.contains(index) else {
+            return false
+        }
+
+        searchState.currentMatchIndex = index
+        controller.searchState = searchState
+        notifySearchStateChanged()
+        return navigateToCurrentSearchMatch(animated: true)
+    }
+
    /// 清除搜索状态并刷新当前可见内容
    func clearSearch() {
        guard let controller else { return }
@@ -109,12 +124,109 @@ final class RDEPUBReaderSearchCoordinator {
            }
            return RDEPUBTextSearchEngine.searchWithoutPublication(textBook: textBook, keyword: keyword)
        }
+        if controller.readerContext.bookPageMap != nil, controller.publication != nil {
+            return resolvedOnDemandSearchMatches(for: keyword)
+        }
        if let parser = controller.parser, let publication = controller.publication {
            return RDEPUBHTMLSearchEngine(parser: parser, publication: publication).search(keyword: keyword)
        }
        return []
    }

+    private func resolvedOnDemandSearchMatches(for keyword: String) -> [RDEPUBSearchMatch] {
+        guard let controller,
+              let publication = controller.publication else {
+            return []
+        }
+
+        let normalizedKeyword = keyword.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedKeyword.isEmpty else {
+            return []
+        }
+
+        let buildableSpineIndices = publication.spine.indices.filter { index in
+            let item = publication.spine[index]
+            return item.linear && (item.mediaType.contains("html") || item.mediaType.contains("xhtml"))
+        }
+
+        var matches: [RDEPUBSearchMatch] = []
+        for spineIndex in buildableSpineIndices {
+            guard let chapter = try? controller.runtime.chapterLoader.loadChapterSynchronouslyForMigration(
+                spineIndex: spineIndex,
+                store: controller.runtime.chapterRuntimeStore
+            ) else {
+                continue
+            }
+
+            let chapterData = makeChapterData(from: chapter, chapterIndex: chapter.pages.first?.chapterIndex ?? 0)
+            let source = chapter.typesetAttributedString.string as NSString
+            let fullLength = source.length
+            guard fullLength > 0 else { continue }
+
+            let normalizedHref = publication.resourceResolver.normalizedHref(chapter.href) ?? chapter.href
+            var localMatchIndex = 0
+            var searchRange = NSRange(location: 0, length: fullLength)
+
+            while searchRange.length > 0 {
+                let foundRange = source.range(of: normalizedKeyword, options: [.caseInsensitive], range: searchRange)
+                guard foundRange.location != NSNotFound else {
+                    break
+                }
+
+                let progressionDenominator = max(fullLength - 1, 1)
+                let progression = Double(foundRange.location) / Double(progressionDenominator)
+                matches.append(
+                    RDEPUBSearchMatch(
+                        href: normalizedHref,
+                        progression: progression,
+                        previewText: previewText(in: source, matchRange: foundRange),
+                        localMatchIndex: localMatchIndex,
+                        rangeLocation: foundRange.location,
+                        rangeLength: foundRange.length,
+                        rangeAnchor: chapterData.rangeAnchor(for: foundRange)
+                    )
+                )
+
+                localMatchIndex += 1
+                let nextLocation = foundRange.location + max(foundRange.length, 1)
+                if nextLocation >= fullLength {
+                    break
+                }
+                searchRange = NSRange(location: nextLocation, length: fullLength - nextLocation)
+            }
+        }
+
+        return matches
+    }
+
+    private func makeChapterData(
+        from runtimeChapter: RDEPUBRuntimeChapter,
+        chapterIndex: Int
+    ) -> RDEPUBChapterData {
+        let textChapter = RDEPUBTextChapter(
+            chapterIndex: chapterIndex,
+            spineIndex: runtimeChapter.spineIndex,
+            href: runtimeChapter.href,
+            title: runtimeChapter.title,
+            attributedContent: runtimeChapter.typesetAttributedString,
+            fragmentOffsets: runtimeChapter.chapterOffsetMap.fragmentOffsets,
+            pageBreakReasons: runtimeChapter.pages.map(\.metadata.breakReason),
+            pages: runtimeChapter.pages
+        )
+        return RDEPUBChapterData(
+            chapter: textChapter,
+            indexTable: RDEPUBTextIndexTable(chapters: [textChapter])
+        )
+    }
+
+    private func previewText(in text: NSString, matchRange: NSRange) -> String {
+        let previewRadius = 12
+        let start = max(matchRange.location - previewRadius, 0)
+        let end = min(matchRange.location + matchRange.length + previewRadius, text.length)
+        let range = NSRange(location: start, length: max(end - start, 0))
+        return text.substring(with: range).trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
    private func advanceSearch(by delta: Int) -> Bool {
        guard let controller else { return false }
        guard var searchState = controller.searchState, !searchState.matches.isEmpty else {
@@ -162,6 +274,14 @@ final class RDEPUBReaderSearchCoordinator {
    private func pageNumber(for searchMatch: RDEPUBSearchMatch) -> Int? {
        guard let controller else { return nil }
        if let chapterData = controller.textChapterData(forNormalizedHref: searchMatch.href) {
+            if let exactPageNumber = exactPageNumber(
+                for: searchMatch,
+                in: chapterData,
+                keyword: controller.searchState?.keyword
+            ) {
+                return exactPageNumber
+            }
+
            if let pageNumber = chapterData.pageNumber(for: searchMatch) {
                return pageNumber
            }
@@ -194,4 +314,39 @@ final class RDEPUBReaderSearchCoordinator {
            bookIdentifier: controller.currentBookIdentifier
        ).map { $0 + 1 }
    }
+
+    private func exactPageNumber(
+        for searchMatch: RDEPUBSearchMatch,
+        in chapterData: RDEPUBChapterData,
+        keyword: String?
+    ) -> Int? {
+        let normalizedKeyword = keyword?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !normalizedKeyword.isEmpty else { return nil }
+
+        let source = chapterData.attributedContent.string as NSString
+        let fullLength = source.length
+        guard fullLength > 0 else { return nil }
+
+        var localMatchIndex = 0
+        var searchRange = NSRange(location: 0, length: fullLength)
+
+        while searchRange.length > 0 {
+            let foundRange = source.range(of: normalizedKeyword, options: [.caseInsensitive], range: searchRange)
+            guard foundRange.location != NSNotFound else { break }
+
+            if localMatchIndex == searchMatch.localMatchIndex,
+               let page = chapterData.page(containing: foundRange.location) {
+                return page.absolutePageIndex + 1
+            }
+
+            localMatchIndex += 1
+            let nextLocation = foundRange.location + max(foundRange.length, 1)
+            if nextLocation >= fullLength {
+                break
+            }
+            searchRange = NSRange(location: nextLocation, length: fullLength - nextLocation)
+        }
+
+        return nil
+    }
 }