Joplin 插件系统深度指南从 v1.4 起步到 JPL 打包与插件开发实战【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 是一个注重隐私的笔记应用支持 Windows、macOS、Linux、Android 和 iOS 多平台同步。插件系统自 v1.4 版本起逐步成熟官方在 2020 年 11 月宣布插件支持接近生产可用并大幅扩展了插件 API。本文基于仓库内新闻公告readme/news/20201130-145937.md结合当前仓库中插件 API 文档与源码实现系统讲解 Joplin 插件体系的能力边界、JPL 打包格式、配置管理以及如何从零开发一个可安装的插件。读完本文你将掌握 Joplin 插件的注册流程、API 调用方式、manifest 编写规范与打包安装全链路。插件系统走向生产就绪v1.4 的里程碑插件系统在 Joplin v1.3 中已经作为基础能力出现但当时仍不够稳定。v1.4 是插件系统走向生产可用状态的关键版本其核心变化在于插件 API 大幅扩展依据开发者反馈API 覆盖了更多插件类型论坛上也因此开始出现各类插件原型JPL 格式与配置界面落地插件配置界面支持导入 JPLJoplinPLugin格式并支持启用/禁用以及卸载插件从能写到能分发的过渡插件创建、打包JPL、安装的完整链路已经打通唯一缺失的是在线包管理机制详见下文在线插件仓库的构想一节。这份里程碑公告对应的完整 API 能力清单与当前仓库的 readme/api/index.md 中 Plugin API 部分的描述完全一致可以作为我们深入解读插件开发的基础。插件 API 能力全景v1.4 能做什么根据官方公告与 readme/api/index.mdJoplin 插件 API 在 v1.4 起支持以下核心能力能力说明数据访问通过数据 API 读写笔记、文件夹notebooks等数据自定义视图使用 HTML/CSS/JS 添加视图展示自定义数据对话框创建对话框展示信息并接收用户输入命令系统创建新命令并关联工具栏按钮或菜单项当前笔记操作获取正在编辑的笔记并修改其内容事件监听监听各种事件并在事件发生时执行代码行为定制挂钩到应用中以设置额外选项、定制 Joplin 行为导入/导出创建模块用于向 Joplin 导入或导出数据设置扩展定义新的设置和设置分组并可在插件中读写Markdown 渲染插件创建新的 Markdown 插件以渲染自定义标记编辑器插件修改 Markdown 编辑器CodeMirror的底层行为数据 API 与插件 API 的分工Joplin 对外提供两个主要扩展点理解它们的区别对选型至关重要数据 APIData API通过标准 HTTP 调用创建、修改、删除笔记、笔记本、标签等数据也可以给笔记附加文件并取回。Web Clipper 就是通过它和 Joplin 通信的典型例子。适用于外部应用需要访问 Joplin 数据的场景详见 readme/api/references/rest_api.md。插件 APIPlugin API直接在应用内部添加新功能、修改 Joplin 本身是上文表格中全部能力的来源入门文档见 readme/api/get_started/plugins.md。JPL 打包格式与插件配置界面公告中特别强调了JPLJoplin PLugin格式这是 Joplin 插件的标准打包格式插件配置界面配置 插件支持导入 JPL 文件、启用/禁用以及卸载插件。源码中的 JPL 加载实现从源码层面看JPL 就是一个 TAR 归档包其中必须包含manifest.json和index.js。核心加载逻辑位于 packages/lib/services/plugins/PluginService.tsloadPluginFromPath约 L389-L421按路径后缀分发.js按纯 JS bundle 加载.jpl走loadPluginFromPackage否则按目录自动探测dist/子目录加载loadPluginFromPackage约 L321-L376将.jpl解包到缓存目录读取manifest.json与index.js为提高启动性能源码用文件大小 mtime判断.jpl是否变化避免每次启动都对整个文件做 MD5 哈希解包状态size、timestamp会持久化缓存有效时直接复用已解包结果installPlugin约 L678-L705把.jpl复制到pluginDir目录下命名为pluginId.jpl完成安装uninstallPlugin约 L727-L735按插件 ID 找到路径并移除实现卸载。插件加载规则Joplin 从配置文件的plugins目录加载插件时会按以下顺序查找见 readme/api/references/plugin_loading_rules.mdplugins/PLUGIN_ID.jsplugins/PLUGIN_ID/index.jsplugins/PLUGIN_ID/dist/index.js任何以_开头的目录或文件都会被排除——这可以用于不删除插件但暂时禁用它。PLUGIN_ID可以是任意字符串但必须唯一。从零开发一个插件环境搭建与 Hello World环境准备开发 Joplin 插件需要Node.js 与 git安装好的 Joplin 应用全局安装 Yeomannpm install -g yo generator-joplin在计划开发插件的目录中运行生成器yo joplin生成器会创建插件的基本脚手架根目录是一系列通常无需修改的配置文件src/目录存放你的代码。项目默认使用 TypeScript但也可以用纯 JavaScript——最终都会被编译为纯 JS。src/下还包含 manifest.json保存了生成时填写的插件信息名称、主页 URL 等。注意发布后再编辑 manifest 可能导致用户需要重新下载插件。运行开发模式测试插件时建议使用开发模式readme/api/references/development_mode.mdJoplin 会用另一个独立的 profile 运行包含测试笔记和笔记本你可以放心实验不会误改或误删真实数据。启用方式帮助 将开发模式命令复制到剪贴板然后把复制的命令粘贴到 shell/终端中运行即可启动开发版本的应用。Hello World 插件脚手架中的src/index.ts已经包含一个 Hello World 插件核心要点调用joplin.plugins.register注册插件——所有插件都必须通过它向应用注册提供onStart()事件处理函数——插件启动时被调用。import joplin from api; joplin.plugins.register({ onStart: async function() { console.info(Hello world. Test plugin started!); }, });编译插件npm run dist这会把所有文件编译到dist/目录——这也是 Joplin 加载插件的位置。安装打开 Joplin配置 插件在高级设置下的Development plugins文本框中填入插件根目录路径即path/to/your/root/plugin/directory重启开发模式应用。如果一切正常插件控制台会输出 Hello world. Test plugin started!同时设置 插件中可以看到 manifest 中的插件信息。仓库内的真实插件示例仓库自带一个可直接参考的插件实现packages/plugins/ToggleSidebarsNote list and sidebar toggle buttons为笔记列表和侧边栏添加切换按钮。其src/index.ts展示了工具栏按钮的创建方式import joplin from api; import { ToolbarButtonLocation } from api/types; joplin.plugins.register({ onStart: async function() { await joplin.views.toolbarButtons.create(toggleSideBarButton, toggleSideBar, ToolbarButtonLocation.NoteToolbar); await joplin.views.toolbarButtons.create(toggleNoteListButton, toggleNoteList, ToolbarButtonLocation.NoteToolbar); }, });这段代码展示了三个 API 要素joplin.plugins.register注册插件、joplin.views.toolbarButtons.create创建工具栏按钮、ToolbarButtonLocation.NoteToolbar指定按钮位置。插件根目录下还提供了完整的 TypeScript 声明文件packages/plugins/ToggleSidebars/api 下的Joplin*.d.ts是查阅 API 签名的一手资料。manifest 清单插件元数据规范插件的 manifest 是一个 JSON 文件描述插件的各项属性。使用 Yeoman 生成器时会根据你的回答自动生成。完整字段规范见 readme/api/references/plugin_manifest.md名称类型必填说明manifest_versionnumber是目前始终为1namestring是插件名称面向用户展示versionstring是版本号如1.0.0app_min_versionstring是插件兼容的最低 Joplin 版本通常取开发所用的版本app_min_version_mobilestring否移动端最低版本与app_min_version不同时填写platformsstring[]否支持的平台如[desktop, mobile]descriptionstring否插件详细描述authorstring否作者名keywordsstring[]否关键词用于搜索homepage_urlstring否主页 URL也可以是 GitHub 仓库链接repository_urlstring否插件源码托管仓库 URLcategoriesstring[]否功能分类见下表screenshotsImage[]否截图用于 Joplin 插件网站展示iconsIcons否图标至少提供一个主图标建议 48x48 PNG未提供则使用默认插件图标promo_tileImage否插件网站的推广图440x280 JPEG/PNG无 alpha平台platforms可包含desktop和/或mobile缺省时多数插件默认为[ desktop ]。分类categoriesappearance外观、developer tools开发者工具、editor编辑器增强、files文件处理如导入导出备份、integrations第三方集成、personal knowledge management个人知识管理、productivity生产力、search搜索增强、tags标签、themes主题、viewer笔记渲染增强。截图与图标路径src若为路径需相对于仓库根目录如screenshots/a.png。注意若src是路径而非 URL则repository_url或homepage_url必须指向 GitHub 仓库截图才能在 Joplin 插件网站上显示。完整 manifest 示例{ manifest_version: 1, name: Joplin Simple Plugin, description: To test loading and running a plugin, version: 1.0.0, author: John Smith, app_min_version: 1.4, app_min_version_mobile: 3.0.3, platforms: [mobile, desktop], homepage_url: https://joplinapp.org, screenshots: [ { src: images/screenshot.png, label: An example of the plugin being used }, { src: https://example.com/images/screenshot.png, label: The plugin loading screen } ], icons: { 16: images/icon16.png, 32: images/icon32.png, 48: images/icon48.png, 128: images/icon128.png }, promo_tile: { src: images/promo_tile.png, label: A logo of a plugin on a clear background } }仓库内 ToggleSidebars 插件的实际 manifestpackages/plugins/ToggleSidebars/src/manifest.json展示了最小可用形态manifest_version: 1、id: org.joplinapp.plugins.ToggleSidebars、app_min_version: 1.6、version: 1.0.3等可作对照参考。插件开发实战用 TOC 教程理解核心 API 模式仓库中的 readme/api/tutorials/toc_plugin.md 是一份完整的目录Table of Contents插件教程它系统演示了插件 API 的三种核心模式注册、获取当前笔记、创建 webview 视图。模式一注册与事件处理所有插件必须先注册自己并声明可处理的事件。由于插件采用多进程架构应始终假设所有函数调用和事件处理器都是异步的import joplin from api; joplin.plugins.register({ onStart: async function() { console.info(TOC plugin started!); }, });模式二workspace API 与事件监听生成目录需要访问当前选中笔记的内容并在每次笔记变化时刷新。这通过 workspace API 完成joplin.plugins.register({ onStart: async function() { async function updateTocView() { const note await joplin.workspace.selectedNote(); // 注意没有选中任何笔记时它可能是 null if (note) { console.info(Note content has changed! New note is:, note); } else { console.info(No note is selected); } } // 用户切换到不同笔记时触发 await joplin.workspace.onNoteSelectionChange(() { updateTocView(); }); // 笔记内容变化时触发 await joplin.workspace.onNoteChange(() { updateTocView(); }); // 插件启动时也刷新一次 updateTocView(); }, });关键点joplin.workspace.selectedNote()可能返回null务必判空onNoteSelectionChange与onNoteChange分别覆盖切换笔记和内容变更两类刷新时机启动时主动调用一次保证初始状态正确。模式三注册命令与事件驱动的视图刷新教程中插件通过joplin.commands.register注册scrollToHash命令让点击目录标题可以滚动到笔记对应章节并在 webview 与主应用之间通过 postMessage 通信joplin.commands.execute(scrollToHash, message.hash)这展示了插件 API 的完整调用链webview 捕获点击 → 发送消息 → 插件执行已注册命令 → 命令操纵当前编辑器视图。打包、安装与分发从 JPL 到在线仓库的演进打包与安装链路v1.4 里程碑意味着以下链路全部打通创建用yo joplin生成脚手架并编写插件代码打包把插件编译产物manifest.jsonindex.js打包为 JPL 文件安装在插件配置界面导入 JPL即可启用/禁用或卸载。从源码实现看packages/lib/services/plugins/PluginService.tsinstallPlugin把 JPL 复制到pluginDir/pluginId.jpl启动时loadPluginFromPackage将其解包到缓存目录cacheDir并加载——这就是导入即安装的底层机制。在线插件仓库的构想公告明确指出当时缺失的最后一块拼图是插件的发现与分享机制即在线包管理器。当时的设想是建立一个 GitHub 仓库任何人都可以提交或更新插件应用连接该仓库即可便捷安装新插件。这一构想当时仅是提议官方也欢迎大家提出其他方案相关讨论在论坛的 plugin repository 主题中展开。从当前仓库看这一构想已经落地为插件仓库基础设施仓库中已包含 packages/plugin-repo-cli插件仓库命令行工具包含installPluginFromRepo等仓库 API 支持以及 packages/lib/services/plugins/RepositoryApi.ts 等实现文件说明应用连接仓库安装插件的机制已在源码中成为现实。注意这套仓库工具属于后续版本演进v1.4 时代它们尚不存在使用时需以更高版本 Joplin 为前提。结语从 v1.4 的里程碑公告可以看出Joplin 插件系统的设计从一开始就追求完整闭环丰富的 API 能力覆盖数据、视图、命令、事件、设置、渲染器等方方面面JPL 统一打包格式配合配置界面简化了安装管理而在线仓库的构想则最终催生了今天的插件分发基础设施。对于想要扩展 Joplin 的开发者推荐的进阶路径是阅读 readme/api/get_started/plugins.md 完成 Hello World跟随 readme/api/tutorials/toc_plugin.md 走一遍真实插件开发流程以 packages/plugins/ToggleSidebars 为最小范例对照实现查阅 readme/api/references/plugin_manifest.md 规范化元数据结合 packages/lib/services/plugins/PluginService.ts 理解加载、安装、卸载的底层机制从而写出更健壮的插件。【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考