這次要介紹的是我為 KOReader 檔案瀏覽（Mosaic）所做的另一個 userpatch：2-browser-folder-cover.lua。這個 patch 可以讓資料夾在 Mosaic 檢視時顯示封面圖片，支援放置自訂 .cover 檔案，若無自訂封面則會自動從該資料夾或其子資料夾的書籍取得封面。此外還提供兩種顯示風格：單一封面或 2×2 格狀封面。

下載路徑：https://github.com/chiahsien/KOReader.Patches

重點摘要

  • 功能：資料夾顯示自訂或來源於書籍的封面；支援單一封面與 2×2 格狀兩種風格；遞迴搜尋子資料夾。
  • 來源：修改自 sebdelsol/KOReader.patches 的 2-browser-folder-cover.lua，新增格狀封面、遞迴搜尋、.cover 支援、非同步載入、e-ink 閃爍消除、LRU 快取與 UI 選項。

為什麼會需要這個 patch

KOReader 的 Mosaic 檢視本身會以書籍封面作為格子顯示；但資料夾通常只會顯示資料夾名稱或預設圖示。這個 patch 補強了資料夾的視覺表現，讓資料夾也能像書籍一樣顯示代表性的封面，改進瀏覽體驗，特別適合把資料夾當作書櫃或系列集合來管理的使用者。

主要功能

  • 支援自訂封面檔案：將自訂圖片放在資料夾內，檔名前綴為 .cover 並附上副檔名（範例：.cover.jpg、.cover.png、.cover.webp）。
  • 兩種封面風格：
    • Single cover（單一封面）：每個資料夾顯示一張書籍封面，底部對齊。
    • Grid (2×2)（格狀封面）：最多顯示四張書籍封面以 2×2 格狀排列，每格使用 aspect fill（裁切溢出以填滿格子）。支援不完整的格狀排列：2 張填滿上排、3 張多填左下角。只找到 1 張時自動退回單一封面顯示。
  • 自動從書籍封面取代：若沒有 .cover，會在資料夾內尋找有效的書籍封面並使用。
  • 遞迴搜尋子資料夾：若資料夾本身沒有可用封面，會往下搜尋子資料夾（預設深度 3）以找到合適的書籍封面。
  • 非同步封面載入：當書籍封面尚未被 KOReader 擷取時，資料夾格子會在封面就緒後自動重新整理，不需手動操作。
  • e-ink 閃爍消除：資料夾跳過預設的 original_update() 流程，避免先畫預設圖示再替換封面所產生的 e-ink 閃爍。
  • 性能優化：Per-directory LRU widget 快取（最多保留 10 個目錄）與封面來源快取，避免重複掃描目錄；settings version 追蹤機制，只在設定變更時才清除快取。

封面搜尋順序

Patch 依以下優先順序決定資料夾封面：

  1. 自訂 .cover 檔案：檢查資料夾內是否有 .cover.{jpg,jpeg,png,webp,gif}。找到即直接使用，不論目前選擇的封面風格為何，自訂封面一律以單一封面方式顯示。
  2. 封面來源快取：若該資料夾先前已解析過書籍封面路徑，直接重用，跳過目錄掃描。
  3. 掃描資料夾內的書籍：呼叫 BookInfoManager:getBookInfo() 逐一檢查檔案，收集有效封面（grid 模式最多 4 張、single 模式 1 張）。
  4. 遞迴搜尋子資料夾：若仍需更多封面，往下遞迴搜尋子資料夾（最多深度 3）以尋找額外的書籍封面。

若封面仍在背景擷取中，資料夾格子會註冊到 CoverBrowser 的 polling 機制，待封面就緒後自動重試。

與上游（原作者）差異

此版本基於 sebdelsol/KOReader.patches 的實作，但做了下列主要改動：

  • 新增 2×2 格狀封面模式（Grid mode），支援不完整排列。
  • 新增對自訂 .cover 檔案的偵測與使用。
  • 新增遞迴搜尋子資料夾以尋找書籍封面（避免空資料夾顯示預設圖示）。
  • 新增非同步封面載入，封面未就緒時自動重試。
  • 消除 e-ink 閃爍：資料夾直接設定封面，不再先畫預設圖示。
  • 改用 Per-directory LRU widget 快取（最多 10 個目錄）與封面來源快取，大幅降低 UI 建構成本。
  • 尊重 KOReader 既有的封面快取有效性檢查，避免使用過期封面。

安裝與使用

  1. 將 2-browser-folder-cover.lua 複製到 KOReader 的 patches 資料夾（通常位於 <koreader_data_dir>/patches/）。常見路徑：

    • Kobo: /mnt/onboard/.adds/koreader/patches/
    • Kindle: /mnt/us/documents/koreader/patches/
    • Android: /sdcard/koreader/patches/
    • Desktop: ~/.koreader/patches/

  2. 重新啟動 KOReader，patch 會在啟動時自動載入。

  3. 使用方法：

    • 若要使用自訂封面，於資料夾放入檔名為 .cover 並含有副檔名的圖片檔（例如 .cover.jpg）。
    • 若未放 .cover，patch 會先檢查該資料夾內的書籍封面，找不到時再往子資料夾遞迴搜尋（最多 3 層）。
    • 可於 KOReader 設定中找到新增的選項（File browser settings → Mosaic and detailed list settings）：
      • Folder cover style：子選單，可選擇 "Single cover"（預設）或 "Grid (2×2)"。
      • Crop folder custom image（裁切自訂封面，預設啟用）
      • Show folder name（顯示資料夾名稱，預設啟用）

注意事項與建議

  • .cover 的優先度高於書籍封面：一旦發現 .cover，patch 會直接使用該圖片並略過書籍封面搜尋。自訂封面一律以單一封面顯示，不受封面風格設定影響。
  • 若資料夾或子資料夾包含大量檔案或深度很深，遞迴搜尋可能帶來額外的檔案系統存取成本，建議將預設深度（目前程式內使用 3）視情況調整或僅在目標目錄使用 .cover。
  • 若發現封面顯示不正常，請先檢查 BookInfoManager 是否已正確擷取並快取了該書的封面，或在 KOReader 中重建封面快取。

授權與來源

此 patch 為我自行維護的衍生版本，原始實作與靈感來自：

若想回到上游版本或查看原始程式碼，可參考上面連結。