KOReader插件开发教程30分钟从Hello菜单到事件监听【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreaderKOReader的阅读功能足够多但工作方式未必合你心意你想用三指滑动打开书签或者在读到某页时快速把批注导出来。KOReader插件开发解决的就是这类问题——不用fork整个主项目几十行Lua就能实现。读完这篇文章你能自己写一个被系统识别的插件完成菜单注册、弹窗和阅读事件拦截三件事。搞懂插件加载机制一个U盘式的心智模型把插件想成U盘目录放进指定位置就被插上系统扫到即生效从插件管理里关掉它等于拔下文件本身不动。启动时加载器扫描plugins/目录凡是名字以.koplugin结尾的子目录都视为插件执行其中的main.lua加载成功后它出现在设置 → 插件管理里可以随时开关。核心逻辑在 插件加载器 中不需要你修改。最小目录结构长这样plugins/myplugin.koplugin/ ├── _meta.lua # 声明名称与描述供插件管理列表展示 └── main.lua # 全部插件逻辑_meta.lua只返回一个表return { fullname MyPlugin, description 它能做什么 }。三步跑通第一个插件在plugins/下建目录myplugin.koplugin后缀必须精确少一个字母都不行。写入上面那句_meta.lua。把下面内容存为main.lua重启 KOReader——主菜单里会多出一个打个招呼条目点它弹出提示框local WidgetContainer require(ui/widget/container/widgetcontainer) local InfoMessage require(ui/widget/infomessage) local UIManager require(ui/uimanager) local Hello WidgetContainer:extend{ name hello, is_doc_only false } function Hello:init() self.ui.menu:registerToMainMenu(self) end function Hello:addToMainMenu(menu_items) menu_items.hello { text 打个招呼, callback function() UIManager:show(InfoMessage:new{ text Hello, KOReader! }) end } end return Hello三行require拿到容器基类、提示框组件和界面管理器init()在插件加载时执行一次负责把自己挂进主菜单addToMainMenu返回菜单项表callback是点击后的动作。掌握菜单、弹窗与事件三个扩展点菜单注册一行代码挂进主菜单原理插件类在init()里调用self.ui.menu:registerToMainMenu(self)主菜单就会回头调用你的addToMainMenu拿条目。一个坑is_doc_only默认为true插件只出现在文件管理器侧。想让它在阅读界面也生效在类定义里写is_doc_only false示例里已带上。弹窗组件所有界面都是Widget原理UIManager:show(widget)把组件压进界面栈顶事件优先发给它。InfoMessage几秒后自动消失ButtonDialog、ConfirmBox这类对话框需要你显式收尾。一个坑还没UIManager:close旧对话框就弹出新的旧窗口留在栈顶拦截事件新界面看起来像卡死。先关旧再开新。事件监听以 on 开头的函数自动生效原理加载器会把所有on开头的函数包进沙箱系统派发同名事件时自动调用无需手动注册。自定义事件则先用Dispatcher:registerAction声明再实现对应的onActionName处理函数。function Hello:onDocumentReady() self.doc self.doc -- 打开文档后拿到文档对象 end function Hello:onReaderReady() -- 进入阅读界面后触发可在此弹出自己的入口 end function Hello:onCloseDocument() return true -- 返回 true 阻止事件继续向上派发 end一个坑处理器不返回true事件会继续向更上层组件传播可能出现我明明处理了别人也响应了的重叠行为。想独占事件就返回true。排查插件没反应的四个常见问题现象目录已放好插件管理列表里却空荡荡。原因目录名没以.koplugin结尾或main.lua语法错误导致加载失败。解决核对目录名查日志里的 Error when loading 定位报错行。现象插件加载了菜单却没有入口。原因init()里漏调self.ui.menu:registerToMainMenu(self)。解决补上这一行并重启。现象文件管理器里菜单正常进书后消失。原因is_doc_only默认为true阅读界面不加载它。解决类定义中设is_doc_only false。现象事件处理器报错界面只是无反应没有提示。原因on*处理器被 pcall 沙箱包住异常只写进日志。解决打开 koreader 日志文件看完整堆栈或开启调试模式获取 traceback。先动手跑通再决定进阶方向一句话总结KOReader 插件 放对目录 返回一个类 复用现成的 Widget 与事件系统。进阶可以从三处入手拆解 插件入口目录 里 gestures、hotkeys 等官方样本的写法读 事件文档 弄清事件传播与return true的边界翻一遍 插件加载器 确认加载与禁用细节。现在就去建一个*.koplugin目录把上面的 hello 样例原样落盘——重启后看到菜单里多出那一项你就完成了 KOReader 插件开发的第一公里。【免费下载链接】koreaderAn ebook reader application supporting PDF, DjVu, EPUB, FB2 and many more formats, running on Cervantes, Kindle, Kobo, PocketBook and Android devices项目地址: https://gitcode.com/GitHub_Trending/ko/koreader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考