10 分钟做出你的第一个 KOReader 插件：从零到可用的完整指南

10 分钟做出你的第一个 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如果你刚开始做 KOReader 插件开发最卡人的往往不是 Lua 语法而是不清楚 KOReader 靠什么机制找到你的代码。想给阅读器加个菜单项、绑个快捷键却不知道往哪写——这是每个新手都会撞上的墙。这篇 KOReader 插件教程按最短路径带你过一遍两个文件、十几行 Lua你就能做出第一个可用的插件重启后菜单入口直接出现。KOReader 如何发现你的插件先说结论插件加载器只扫描 plugins/ 目录把名字以.koplugin结尾的子目录当作插件。这个规则写死在 frontend/pluginloader.lua 里目录必须以.koplugin结尾插件名就是前缀部分例如mytool.koplugin对应插件名mytool目录里必须同时有main.lua和_meta.lua加载器先执行前者、再读取后者除内置插件外你可以通过extra_plugin_paths设置再挂一个自定义插件目录不必改动仓库本身。哪两个文件不能少_meta.lua声明身份它返回一张表字段会被合并到插件模块上。你只需要四样东西fullname菜单里显示的名字、description、version、author。注意不要再在_meta.lua里写name字段——加载器会忽略它并打印警告name由目录名决定。return { fullname My Tool, version 1.0.0, author you, description 我的第一个 KOReader 插件, }main.lua承载行为惯例做法是让插件继承WidgetContainer在init里挂到主菜单参考 plugins/hello.koplugin/main.lua 的做法local WidgetContainer require(ui/widget/container/widgetcontainer) local MyTool WidgetContainer:extend{ name mytool, } function MyTool:init() self.ui.menu:registerToMainMenu(self) end -- ... 功能方法 return MyTool把插件放进菜单注册方法与组件选型菜单入口由插件自己的addToMainMenu方法提供加载器把它注册进主菜单后menu_items表会传进来你往表里加一项即可function MyTool:addToMainMenu(menu_items) menu_items.my_tool { text My Tool, sorting_hint more_tools, callback function() self:showInfo() end, } endtext决定菜单里显示的文字callback是点击后的动作sorting_hint控制它落在哪个分组例如more_tools会进“更多工具”。弹窗方面直接复用frontend/ui/widget/下的现成组件就够了InfoMessage轻量提示、ButtonDialog按钮对话框、InputDialog文本输入。以提示为例local InfoMessage require(ui/widget/infomessage) local UIManager require(ui/uimanager) function MyTool:showInfo() UIManager:show(InfoMessage:new{ text 你好KOReader 插件 }) end让插件对操作做出反应三类事件加载器对插件里所有以on开头的函数做了沙箱包裹事件触发时如果抛错不会拖垮阅读器错误会写进日志。你只需要知道三类入口手势事件点按、滑动区域对应阅读器屏幕上的固定触摸区如下图所示按键事件物理按键与键盘组合键可结合Dispatcher:registerAction注册自定义动作全局事件以on开头的函数名对应 UI 事件或你自注册的事件比如onReaderReady、onFileAdded这类生命周期钩子。自注册事件的最小写法local Dispatcher require(dispatcher) function MyTool:onInit() Dispatcher:registerAction(mytool_action, { category none, event MyToolEvent, title My Tool, }) end function MyTool:onMyToolEvent() self:showInfo() end拓展能力文件系统与网络服务插件运行在 KOReader 进程内因此可以读写设备文件系统——做备份、导出、文件管理这类功能都是同一套 Lua 逻辑。涉及网络时用 frontend/httpclient.lua 发起请求参考 plugins/httpinspector.koplugin 能看到完整的网络调试实现plugins/calibre.koplugin 则是与外部服务Calibre 的无线传输组件通信的现成范例。先读这两份源码比自己造轮子省事得多。发布前的验证与常见坑验证顺序很简单对照仓库内置的 plugins/hello.koplugin 检查自己的两个文件——它就是最小可运行插件完整重启 KOReader不是关窗口再开加载器只在启动时扫描插件目录打开菜单确认入口出现点一遍回调没反应时查日志错误会被加载器写进koreader.log打开调试开关还能看到完整堆栈。最常见的三个坑目录名漏掉.koplugin后缀直接不被发现改了代码没重启改动不生效在_meta.lua里写了name字段被忽略并告警。下一步先照 plugins/hello.koplugin 抄一个最小插件让菜单里出现一条弹消息的入口再往上加功能。想继续深入就从 plugins/ 目录里挑一个功能最接近你目标的插件读源码——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），仅供参考