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

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

重點摘要

  • 功能：資料夾顯示自訂或來源於書籍的封面；遞迴搜尋子資料夾。
  • 來源：修改自 sebdelsol/KOReader.patches 的 2-browser-folder-cover.lua，新增遞迴搜尋與 .cover 支援、以及簡單快取與 UI 選項。

為什麼會需要這個 patch

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

主要功能

  • 支援自訂封面檔案：將自訂圖片放在資料夾內，檔名前綴為 .cover 並附上副檔名（範例：.cover.jpg、.cover.png）。
  • 自動從書籍封面取代：若沒有 .cover，會在資料夾內尋找第一本有效的書籍封面並使用。
  • 遞迴搜尋子資料夾：若資料夾本身沒有可用封面，會往下搜尋子資料夾（預設深度 3）以找到合適的書籍封面。
  • 顯示調整：資料夾名稱字型自動縮放以符合可用空間，並提供是否置中與顯示名稱的選項。
  • 性能優化：做簡單快取，減少重複建立的成本。

與上游（原作者）差異

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

  • 新增對自訂 .cover 檔案的偵測與使用。
  • 新增遞迴搜尋子資料夾以尋找書籍封面（避免空資料夾顯示預設圖示）。
  • 在 FileChooser:getListItem 加入簡單快取機制以降低 UI 建構成本。

安裝與使用

  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）：
      • Crop folder custom image（裁切自訂封面）
      • Folder name centered（資料夾名稱置中）
      • Show folder name（顯示資料夾名稱）

注意事項與建議

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

授權與來源

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

  • sebdelsol/KOReader.patches： https://github.com/sebdelsol/KOReader.patches

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