拆解 KOReader 插件架构:SimpleUI 如何组织 7.8 万行 Lua 代码(目录结构与模块依赖完全指南)

原创2026-10-10 13:50:221,863 阅读

拆解 KOReader 插件架构:SimpleUI 如何组织 7.8 万行 Lua 代码(目录结构与模块依赖完全指南)

SimpleUI(simpleui.koplugin)是 KOReader 的一款高可定制 UI 插件:它用纯 Lua 实现主页、底部导航栏、顶部状态栏和桌面模块,整个仓库共约 78,618 行 Lua 代码。本文带你完整拆解它的目录结构与模块依赖关系——即使你不写代码,也能看懂这套"地基→引擎→屏幕→模块"的分层思想是如何让近 8 万行代码保持清晰的。

项目目录结构全景一览

先看仓库顶层,每个目录都有明确职责:

目录 行数 文件数 职责(一句话)
main.lua 2,530 1 插件入口,注册插件、分发到各模块
infra/ 12,609 12 基础设施:配置、存储、补丁、i18n
engines/ 12,113 10 渲染引擎:窗口、书封网格、热力图
screens/ 16,797 10 全屏页面:主页、导航栏、设置窗口
modules/ 17,128 20 主页模块:时钟、在读、书封轮播等
features/ 17,432 20 功能层:快捷操作、样式、壁纸、书库
locale/ — 26 25 种语言的翻译文件(.po)
icons/ — 21 内置 SVG 图标
scripts/ — 2 打包与翻译提取脚本

其他文件:_meta.lua 是插件元数据(名称 simpleui、版本 2.7.5),KOReader 靠它识别插件;README.md 是功能文档;CONTRIBUTING.md 是贡献指南。

入口 main.lua:一个 2530 行的"调度台"

main.lua 是唯一必须全量加载的文件。它开头只做几件事:

  1. 按需 require 核心依赖——i18n、配置、核心 UI、底部栏、顶部栏、快捷设置栏、补丁、设置存储等,集中在 main.lua 的头部;
  2. 兼容检查:调用 infra/sui_compat_check.lua 检测冲突插件,有冲突则直接放弃初始化;
  3. 生命周期钩子:SimpleUIPlugin:init() 里依次完成数据目录创建、版本热更新检测、用户数据迁移(把旧版写在插件目录里的图标/引文搬到 DataStorage/simpleui/),再构建各栏。

💡 值得新手学习的一点:init() 里几乎所有步骤都包在 pcall 中——任何一步出错都不会拖垮整个插件,错误只记入日志。这是 KOReader 插件里非常稳健的防御式写法。

六大目录逐个拆解

infra/:地基层(其他一切都站在它上面)

文件 作用
sui_patches.lua 全仓库最大文件(5,672 行),monkey-patch KOReader 原生界面
sui_config.lua 配置读取与菜单项构建(2,757 行)
sui_store.lua 独立设置存储,统一写入 DataStorage/simpleui/sui_settings.lua,键名带 simpleui_ / navbar_ 前缀
sui_i18n.lua 翻译代理,每个模块拿到自己的翻译函数,避免改写全局 gettext
sui_core.lua 公共 UI 工具(通知、弹窗等)
sui_custom_screens.lua 自定义屏幕的注册与快捷操作重建
sui_paths.lua 用户数据路径(壁纸、引文、预设、备份)

还有 sui_cover_cache.lua(封面缓存)、sui_streak.lua(阅读连续天数)、sui_updater.lua(更新)、sui_aa_paint.lua(抗锯齿绘制)。

📌 关键设计:代码与数据分离。插件更新只覆盖代码目录,你的壁纸、引文、预设、备份都存放在 KOReader 设置目录下的 simpleui/,升级永不丢失。

engines/:渲染引擎层(可复用的"零件")

引擎不关心"在哪个页面",只负责"怎么画":

screens/:全屏页面层("用户看到什么")

每个文件对应一个完整的屏幕或栏:

modules/:主页模块层("可以拖动的积木")

这是新手最容易上手的目录。moduleregistry.lua 是一个静态注册表,内置 16 个模块按序列出:时钟、每日引文、当前在读、最近阅读、新书、TBR、书封轮播、合集、阅读目标、阅读统计、热力图、快捷操作行、操作列表、空白间距……

🔧 添加一个新模块只需要在列表里追加一行,无需改动其他代码。每个模块还需遵守 moduleregistry.lua 顶部写明的"契约":M.id、M.build(w, ctx)、M.getHeight(ctx)、M.getMenuItems(ctx_menu) 等。

更妙的是注册表的 4 条为慢速设备优化的设计(moduleregistry.lua 的注释):静态列表不做磁盘扫描、模块文件懒加载(首次渲染才 require)、加载后缓存在内存、注册表本身零业务逻辑。它还开放了 Registry.register() 接口,允许第三方插件注册外部模块。

features/:功能层(跨页面的"业务能力")

功能层介于引擎和屏幕之间:sui_quickactions.lua(3,592 行)管理快捷操作按钮;sui_style.lua(2,366 行)管理字体/图标/主题样式;sui_wallpaper.lua、sui_presets.lua、sui_backup.lua 分别负责壁纸、布局预设和一键备份。

其中 features/library/ 是书库功能子包(14 个文件):sui_library_browse.lua(浏览视图)、sui_foldercovers.lua(文件夹封面)、sui_library_search.lua(搜索)、sui_metadata_source.lua(元数据)等——把"书库"这一大块能力独立封装,便于单独维护。

模块依赖方向:谁站在谁上面

统计各目录内部的 require 调用后,依赖关系呈现清晰的单向分层(上层依赖下层,几乎不反向引用):

  1. infra 是底层:被 modules(16 次引用 sui_store)、screens(19 次引用 sui_core)、features 大量依赖,自己几乎不依赖别人;
  2. engines 承接 infra:sui_window 是全局最热门的基础件——screens 引用 24 次、modules 引用 16 次;
  3. modules 不依赖 screens:模块只依赖引擎和基础设施,所以主页、自定义屏幕能复用同一套模块;
  4. main.lua 在顶层:只负责装配 screens + infra + features,业务细节全部委托出去。

一句话总结:数据/路径/文本(infra)→ 绘制能力(engines)→ 完整页面(screens)→ 可组合积木(modules)→ 业务功能(features)→ 装配(main.lua)。找 bug 时,从你看到的"界面"出发,就能沿这条链快速定位到对应目录。

给新手的 3 个实用切入点

总结

SimpleUI 用一套教科书式的分层把 7.8 万行 Lua 代码切成 6 个职责单一的目录:infra 管数据、engines 管绘制、screens 管页面、modules 管积木、features 管业务、main.lua 管装配。配合"设置集中存储 + 键名命名空间 + 模块懒加载 + 全程 pcall 防御"四个工程习惯,它既保证了 8 万行规模下的可维护性,也让第三方开发者可以只写一个模块文件就接入整个主页体系——这正是 KOReader 插件架构拆解中最值得借鉴的部分。

登录后查看全文
simpleui.koplugin