【免费下载链接】bookshelf.kopluginA nice looking home screen for KOReader. Lets you pick a book from your shelf and read it, with some customisation around the book preview info thats shown.项目地址https://gitcode.com/gh_mirrors/bo/bookshelf.koplugin点击查看免费下载如果你装过 Bookshelf一定见过它把 KOReader 变成一个漂亮书架主页的效果。但对很多读者来说这个 KOReader 书架插件的内部代码一直是黑盒。本文带你做一次 Bookshelf 代码架构解析从入口文件 main.lua 开始逐层拆解 lib/ 目录下两百多个模块的分层设计思路帮你快速建立这个插件到底是怎么组织起来的整体认知。一、先看目录Bookshelf 的整体骨架克隆或解压项目后顶层只有少数几个关键部分职责划分非常清晰路径职责新手关注度main.lua插件入口注册菜单、接管首页⭐⭐⭐_meta.lua插件清单名称、版本 5.4.4、描述⭐lib/全部业务模块约 200 个单职责文件⭐⭐⭐micromodules/可插拔的微模块信息卡片⭐⭐locale/16 种语言的 .po 翻译文件⭐tests/纯 Lua 单元测试不依赖 KOReader 环境⭐⭐assets/、fonts/木板纹理、阴影、字体等资源⭐一句话概括main.lua 负责接线lib/ 负责干活micromodules/ 负责扩展。二、入口层main.lua 如何接管 KOReadermain.lua 是整个 Bookshelf 的总开关它的开头main.lua#L1-L30有一段值得细读的注释解释了 KOReader 插件的 API 细节比如为什么必须 monkey-patchFileManagerMenu.getStartWithMenuTable才能把 Bookshelf 塞进启动时打开菜单。入口层主要做四件事版本闸门加载时先检查 lib/bookshelf_version_gate.luaKOReader 版本过旧时直接返回一个请升级的占位插件而不是中途崩溃。存储迁移在任何文件打开之前先运行 lib/bookshelf_storage_move.lua把老版本的扁平文件布局搬到settings/bookshelf/和cache/bookshelf/。菜单与主界面注入通过addToMainMenu注册 Bookshelf 专属菜单页见 main.lua#L680-L869并提供registerSource等对外 API让其他插件也能向书架注册内容源。冷启动接管当用户设置start_with bookshelf时在 FileManager 初始化后自动弹出书架主界面。注意一个设计亮点show()方法区分了冷创建新建 widget 并整体_rebuild和热刷新已有 widget 走轻量的softRefresh避免每次开关书都重建整棵视图树——这正是书架切换流畅的关键。三、lib/ 数据层只产数据、不碰 UI打开 lib/ 你会看到文件名都很长但这恰恰是刻意为之——每个文件只做一件事。数据层的核心契约写在 lib/bookshelf_book_repository.lua#L1-L8本模块只产出 Book 记录——没有 widget 代码、不引入 UI。这种纯数据约束带来一个直接好处数据层可以被 tests/ 里的单元测试直接用lua解释器跑起来无需 KOReader 环境。数据层的关键模块lib/bookshelf_book_repository.lua统一聚合 KOReader 的阅读历史、收藏、BookInfoManager 等来源产出标准化的 Book 记录。lib/bookshelf_filter.lua / lib/bookshelf_sort_engine.lua过滤与多键排序引擎后者是纯函数实现支持先按作者、再按系列号这样的多级排序。lib/bookshelf_settings_store.lua所有偏好都存放在独立的settings/bookshelf/settings.lua里而不是混进 KOReader 全局设置卸载时一键清理。lib/bookshelf_bim_db.lua / lib/bookshelf_book_facts_db.lua / lib/bookshelf_opds_db.lua几把 SQLite 数据库分别缓存封面元数据、每本书的小事实页数、封面取色和 OPDS 目录窗口。代码注释里甚至有实测数据把 4.7MB 的 OPDS 缓存从 Lua 文件搬进 SQLite就是为了解决启动时的读取开销。lib/bookshelf_paths.lua路径中枢定义设置目录和缓存目录的边界——备份一个文件夹就等于备份了 Bookshelf 的全部用户数据。四、lib/ 来源层一个可注册的内容源注册表这是 Bookshelf 架构中最精彩的一层。lib/bookshelf_sources.lua 的开头用了一大段注释lib/bookshelf_sources.lua#L1-L87解释以前 Kindle 书库、Kobo 书库这些非本地书架来源都是被 Bookshelf 按名字硬编码认出来的第三方插件想加自己的书架只能运行时替换函数现在所有问题都改为向注册表提问。一个来源就是一份 spec 表两种工作模式list 模式一次性交出所有书由 Bookshelf 自己过滤、排序、分页Kindle / Kobo 书库就是这样fetch 模式来源自己负责分页和钻取适合在线目录如 OPDS 站点。其他插件只需调用ui.bookshelf:registerSource(id, spec)就能挂上自己的书架详见官方文档 SOURCE_API.md。而且每次调用都被pcall包裹——一个坏来源只会降级成空书架不会拖垮整个插件。这种注册表 容错降级的写法值得做插件体系的朋友参考。五、lib/ 视图层一个大 widget 组合出整个界面视图层的顶层是 lib/bookshelf_widget.lua开头注释一句话点明组合关系顶层主界面 widget组合 HeroCard ChipBar 两行 ShelfRow 翻页页脚。也就是说你在屏幕上看到的书架是几个零件拼起来的模块屏幕上的对应物lib/bookshelf_hero_card.lua顶部的正在读详情卡封面 可编辑信息区lib/bookshelf_chip_bar.lua书架标签条Recent / Series / ★…兼作钻取面包屑lib/bookshelf_shelf_row.lua单排书脊行空槽位也保持固定宽度lib/bookshelf_spine_widget.lua竖排文字的书脊支持中英文竖排lib/bookshelf_cover_grid_cell.lua封面网格模式的单格视图层还有一组基础能力件被所有零件共享主题令牌lib/bookshelf_tokens.lua、文本自适应lib/bookshelf_text_fit.lua、颜色系统lib/bookshelf_color.lua、封面缩放缓存lib/bookshelf_scaled_cover_cache.lua 及其磁盘后端。六、扩展层micromodules/ 与插件化设计micromodules/ 目录展示了另一套轻量扩展机制每个.lua文件就是一个微模块时钟、天气、阅读目标、阅读统计……返回一张 spec 表核心是render(ctx)函数。micromodules/README.md 里有一句值得记住的原则宿主负责尺寸SIZE你只负责内容CONTENT。也就是说微模块自己不用写字体缩放循环宿主会反复以不同的scale_pct渲染它直到填满格子。共享工具函数集中在 lib/bookshelf_module_kit.luaKit.sc、Kit.face、Kit.valueCard…保证所有模块在任何格子大小下都观感一致。想做一个自己的模块照着 micromodules/clock.lua 抄一份改几个字段就能用。七、周边体系国际化、资源与测试国际化lib/bookshelf_i18n.lua 提供插件专属翻译函数先查 locale/ 里的 .po 文件再回落到 KOReader 的 gettext。加一门语言只需复制 locale/bookshelf.pot 填写译文。字体fonts/ 内置 Caveat、Inter、Roboto Condensed附完整的 CREDITS.md 许可证说明。测试tests/ 下有 300 多个_test_*.lua套件思路是在package.loaded里注入 KOReader 模块的 stub让真实业务代码在普通lua解释器里跑断言。运行方式见 tests/README.mdsh tests/run.sh。这套无依赖纯 Lua 测试是数据层分层约束的直接红利。八、新手阅读路线图建议按这个顺序读源码两小时就能建立完整印象_meta.lua → main.lua 前 500 行版本闸门 init 流程lib/bookshelf_settings_store.lua理解数据落盘lib/bookshelf_book_repository.lua理解数据契约lib/bookshelf_widget.lua理解视图组合与冷/热刷新分支lib/bookshelf_sources.lua SOURCE_API.md理解扩展点micromodules/README.md 任意一个微模块总结Bookshelf 的代码架构可以概括为三条主线入口薄、模块厚main.lua 只做接线和生命周期管理200 多个小文件各司其职数据与视图严格分离repository 层不碰 UI换来可测试性和可维护性两处精心设计的扩展点来源注册表sources让别的插件借书架微模块让信息卡片即插即用。理解了这三点再去看任何单个模块都能迅速定位它在分层设计中的位置。赞分享【免费下载链接】bookshelf.kopluginA nice looking home screen for KOReader. Lets you pick a book from your shelf and read it, with some customisation around the book preview info thats shown.项目地址https://gitcode.com/gh_mirrors/bo/bookshelf.koplugin点击查看免费下载相关推荐为什么你需要了解 Awesome Code Points提升开发效率的 Unicode 技巧为什么你需要了解 Awesome Code Points提升开发效率的 Unicode 技巧 Awesome Code Points 是一个精心策划的 Uni解构 paqet 架构从 cobra 命令到 pcap 原始包的 7 层分层设计完整解析解构 paqet 架构从 cobra 命令到 pcap 原始包的 7 层分层设计完整解析 paqet 是一个运行在 原始包raw packet层面 的透明AIHelms 架构解析FastAPI LiteLLM Vue3 四层分层设计完整指南AIHelms 架构解析FastAPI LiteLLM Vue3 四层分层设计完整指南 本文带你一文看懂 AIHelms ——一个企业级 AI 资源纳创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考