企业官网建设流程全解析

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

项目目录结构全景一览

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

其他文件：_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_cover_cache.lua（封面缓存）、sui_streak.lua（阅读连续天数）、sui_updater.lua（更新）、sui_aa_paint.lua（抗锯齿绘制）。

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

engines/：渲染引擎层（可复用的"零件"）

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

• sui_screen_engine.lua（4,071 行）——主页模块布局引擎，负责模块排序、缩放、分节标签；
• sui_window.lua（3,565 行）——通用窗口容器，全仓库被引用最多次的基础件；
• sui_book_grid.lua（2,107 行）——书封网格，"在读/最近/书库"等多个模块共用；
• sui_tab_strip.lua、sui_heatmap_data.lua、sui_library_scan.lua 等。

screens/：全屏页面层（"用户看到什么"）

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

• sui_homescreen.lua——主页，SimpleUI 的核心；
• sui_bottombar.lua（1,968 行）与 sui_topbar.lua——底部导航栏、顶部状态栏；
• sui_titlebar.lua（1,857 行）——重做的书库标题栏；
• sui_menu.lua（4,896 行）、sui_stats_windows.lua（3,949 行）——主菜单注入与统计窗口；
• sui_settings_window.lua——SUI 设置窗口；sui_onboarding.lua——首次运行的欢迎引导。

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 个实用切入点

• 🧭想改界面文字？不用碰 Lua：翻译在 locale/zh_CN.po 等 25 个.po文件里，字符串提取由 scripts/extract_strings.py 生成模板；
• 📦想理解"插件如何接入 KOReader"？看 _meta.lua（元数据）+ main.lua（init入口）+ infra/sui_patches.lua（对原生界面的打点替换）；
• 📦想知道发布包怎么打？scripts/Makefile 一条make build生成simpleui.koplugin.zip，并自动排除文档与开发脚本。

总结

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