Reorganize docs and update reader search flows

Sources/RDReaderView/EPUBUI/RDEPUBReaderController.swift

@@ -310,27 +310,13 @@ public final class RDEPUBReaderController: UIViewController {
 
     // MARK: - 搜索栏管理
 
-    /// 显示搜索栏，将其添加到 readerView 并滑入动画
+    /// 显示搜索栏。工具栏可见时立即添加到视图层级并滑入动画；否则仅标记状态，
+    /// 等待 `handleToolViewVisibilityChanged` 在工具栏显示时再安装。
     func showSearchBar() {
         guard !isSearchBarVisible else { return }
         isSearchBarVisible = true
         searchBarView.apply(theme: configuration.theme)
 
-        readerView.addSubview(searchBarView)
-        readerView.searchBarView = searchBarView
-        let topToolbarHeight: CGFloat = readerView.safeAreaInsets.top + 52
-        NSLayoutConstraint.activate([
-            searchBarView.leadingAnchor.constraint(equalTo: readerView.leadingAnchor),
-            searchBarView.trailingAnchor.constraint(equalTo: readerView.trailingAnchor),
-            searchBarView.topAnchor.constraint(equalTo: readerView.topAnchor, constant: topToolbarHeight),
-            searchBarView.heightAnchor.constraint(equalToConstant: 52)
-        ])
-
-        searchBarView.transform = CGAffineTransform(translationX: 0, y: -52)
-        UIView.animate(withDuration: 0.3) {
-            self.searchBarView.transform = .identity
-        }
-
         searchBarView.onSearchSubmit = { [weak self] keyword in
             self?.runtime.search(keyword: keyword)
             self?.updateSearchCount()
@@ -347,12 +333,36 @@ public final class RDEPUBReaderController: UIViewController {
             self?.hideSearchBar(clearSearch: true)
         }
 
+        if readerView.isShowToolView {
+            installSearchBarView()
+        }
+    }
+
+    /// 将搜索栏添加到 readerView 并执行滑入动画
+    private func installSearchBarView() {
+        guard searchBarView.superview == nil else { return }
+        searchBarView.apply(theme: configuration.theme)
+
+        readerView.addSubview(searchBarView)
+        readerView.searchBarView = searchBarView
+        let topToolbarHeight: CGFloat = readerView.safeAreaInsets.top + 52
+        NSLayoutConstraint.activate([
+            searchBarView.leadingAnchor.constraint(equalTo: readerView.leadingAnchor),
+            searchBarView.trailingAnchor.constraint(equalTo: readerView.trailingAnchor),
+            searchBarView.topAnchor.constraint(equalTo: readerView.topAnchor, constant: topToolbarHeight),
+            searchBarView.heightAnchor.constraint(equalToConstant: 52)
+        ])
+
+        searchBarView.transform = CGAffineTransform(translationX: 0, y: -52)
+        UIView.animate(withDuration: 0.3) {
+            self.searchBarView.transform = .identity
+        }
+
         if let keyword = searchState?.keyword, !keyword.isEmpty {
             searchBarView.restoreKeyword(keyword)
             updateSearchCount()
         }
 
-        // 延迟到下一帧确保视图已布局后再获取焦点
         DispatchQueue.main.async { [weak self] in
             self?.searchBarView.textField.becomeFirstResponder()
         }
@@ -379,7 +389,7 @@ public final class RDEPUBReaderController: UIViewController {
     }
 
     /// 同步搜索栏匹配计数
-    private func updateSearchCount() {
+    func updateSearchCount() {
         guard let searchState else {
             searchBarView.showNoResults()
             return
@@ -394,7 +404,9 @@ public final class RDEPUBReaderController: UIViewController {
     /// 当工具栏可见性变化时同步搜索栏（由 RDReaderView 回调调用）
     func handleToolViewVisibilityChanged(isVisible: Bool) {
         if isVisible {
-            if searchState != nil && !isSearchBarVisible {
+            if isSearchBarVisible {
+                installSearchBarView()
+            } else if searchState != nil {
                 showSearchBar()
             }
         } else {