Joplin 插件开发实战解读 events 示例插件的构建流程与事件监听 API【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin本文以 Joplin 仓库内置的 events 演示插件为切入点系统讲解 Joplin 插件工程的标准结构、npm run dist构建与 JPL 打包流程并逐行解析joplin.workspace事件监听 API闹钟触发、同步开始/完成等的实际用法。读完本文你将掌握从零搭建、编译、分发一个 Joplin 插件以及利用事件钩子实现自动化功能的完整套路。背景events 插件是什么events是 Joplin 官方为插件开发者准备的示例插件之一位于 packages/app-cli/tests/support/plugins/events。它的manifest.json中的描述写得很直白——Demonstrate how to listen to various events演示如何监听各类事件。也就是说这个插件本身不提供任何界面功能它的全部价值在于示范如何注册插件、如何挂接工作区事件回调是学习 Joplin 插件 API 的最佳入门样例。它同时也是一个由 Yeoman 生成器generator-joplin生成的标准插件模板目录下的 README.md 即模板自带的工程说明文档描述了所有 Joplin 插件通用的结构、构建与更新方式。因此本文将以该 README 为骨架以 events 示例源码为血肉展开讲解。插件项目的目录结构README 明确指出一个 Joplin 插件项目里最值得关注的是两个文件/src/index.ts插件的入口文件所有插件逻辑的起点/src/manifest.json插件清单声明插件名称、版本、最低兼容的应用版本等信息。以 events 示例为例实际目录结构如下位于仓库 packages/app-cli/tests/support/plugins/eventsevents/ ├── src/ │ ├── index.ts # 插件入口注册插件并挂接事件 │ └── manifest.json # 插件清单 ├── api/ # 插件 API 的 TypeScript 类型声明 │ ├── Joplin.d.ts │ ├── JoplinData.d.ts │ ├── JoplinWorkspace.d.ts │ └── ... ├── webpack.config.js # 构建配置模板自动生成 ├── plugin.config.json # 插件附加配置如 extraScripts ├── package.json # npm 脚本与依赖 ├── tsconfig.json # TypeScript 编译配置 └── README.md # 模板工程说明其中api/目录是模板自动附带、由 Joplin 插件 API 类型定义生成的声明文件集合开发时 IDE 会基于它们提供完整的自动补全与类型检查项目根目录下的api/index.ts导出一个全局的joplin单例对象插件代码通过import joplin from api引入它。入口文件 src/index.tsevents 插件的 src/index.ts 完整代码如下import joplin from api; joplin.plugins.register({ onStart: async function() { joplin.workspace.onNoteAlarmTrigger(async (event:any) { const note await joplin.data.get([notes, event.noteId]); console.info(Alarm was triggered for note: , note); }); joplin.workspace.onSyncStart(async (event:any) { console.info(Sync has started...); }); joplin.workspace.onSyncComplete(async (event:any) { console.info(Sync has completed); console.info(With errors:, event.withErrors); }); }, });这段代码展示了一个 Joplin 插件的最小完整形态通过joplin.plugins.register({...})注册插件在onStart生命周期回调中初始化业务逻辑通过joplin.workspace.xxx系列方法订阅工作区事件。插件清单 manifest.jsonsrc/manifest.json 的内容{ id: org.joplinapp.plugins.EventsDemo, manifest_version: 1, app_min_version: 1.4, name: Event demo, description: Demonstrate how to listen to various events, version: 1.0.0, author: Laurent Cozic, homepage_url: https://joplinapp.org }各字段含义如下字段说明示例值id插件的全局唯一标识通常采用反向域名风格它同时决定了 JPL 安装包的命名org.joplinapp.plugins.EventsDemomanifest_version清单格式版本目前为11app_min_version运行该插件所需的最低 Joplin 版本低于此版本的应用不会加载插件1.4name插件显示名称Event demodescription插件描述Demonstrate how to listen to various eventsversion插件版本号语义化版本1.0.0author作者名Laurent Cozichomepage_url插件主页https://joplinapp.org从构建脚本 webpack.config.js 可以看到manifest.json中的id会被读取并用于生成publish/{id}.jpl与publish/{id}.json两个分发产物同时readManifest还会校验categories字段是否属于预定义的分类集合如productivity、themes、editor等如果类别重复或非法会直接抛出构建错误。事件监听 API 详解events 插件示范了三个最常用的工作区事件它们的定义与完整事件族可以在 api/JoplinWorkspace.d.ts 中查到。onNoteAlarmTrigger待办闹钟触发joplin.workspace.onNoteAlarmTrigger(async (event:any) { const note await joplin.data.get([notes, event.noteId]); console.info(Alarm was triggered for note: , note); });当与某个待办事项to-do关联的闹钟被触发时Joplin 会调用该回调。事件对象event携带noteId字段类型定义见 JoplinWorkspace.d.ts随后示例通过数据 API 的joplin.data.get([notes, noteId])按 ID 拉取完整的笔记对象——这演示了事件回调与数据 API 的组合用法事件只给最小上下文具体数据需要用joplin.data主动获取。joplin.data的方法签名与 REST 语义一一对应GET/POST/PUT/DELETE其path参数是一个数组形如[notes, :id, link]详见 api/JoplinData.d.ts。由于插件运行在 Joplin 应用进程内部调用该 API无需鉴权 token。onSyncStart / onSyncComplete同步生命周期joplin.workspace.onSyncStart(async (event:any) { console.info(Sync has started...); }); joplin.workspace.onSyncComplete(async (event:any) { console.info(Sync has completed); console.info(With errors:, event.withErrors); });onSyncStart同步过程开始时触发回调不带事件参数类型定义为SyncStartHandler () voidonSyncComplete同步结束后触发事件对象带有withErrors: boolean字段见 JoplinWorkspace.d.ts用于判断本次同步是否出现错误。这两个钩子非常适合做同步状态的日志记录、桌面通知或是在同步完成后再触发自定义的数据刷新逻辑。更多可用事件api/JoplinWorkspace.d.ts 还定义了 events 示例之外的一批常用事件均可在插件中直接使用API触发时机事件参数onNoteSelectionChange当前选中的笔记发生变化value: string[]笔记 ID 数组onNoteChange笔记内容或任意属性变化推荐取代已废弃的onNoteContentChange{ id, event }event取值为Create/Update/DeleteonResourceChange资源附件被修改新增/删除不触发{ id }onNoteAlarmTrigger待办闹钟触发{ noteId }onSyncStart同步开始无onSyncComplete同步完成{ withErrors: boolean }filterEditorContextMenu编辑器右键菜单弹出前仅桌面端允许向菜单注入条目菜单过滤对象值得留意的是onNoteSelectionChange、onNoteChange、onNoteAlarmTrigger、onSyncStart、onSyncComplete等订阅方法的返回类型是PromiseDisposable——订阅后返回一个可销毁句柄插件卸载时用于反注册回调避免内存泄漏。构建插件npm run distREADME 明确指出构建命令只有一条npm run dist该命令来自 package.json 中的scripts配置实际展开是三个依次执行的 Webpack 构建步骤dist: webpack --joplin-plugin-config buildMain webpack --joplin-plugin-config buildExtraScripts webpack --joplin-plugin-config createArchive对应的三阶段逻辑定义在 webpack.config.jsbuildMain编译入口./src/index.ts用ts-loader将 TypeScript 编译为 CommonJS 模块target 为 ES2015配置见 tsconfig.json并把src/下其余非 TS 资源CSS、JSON 等复制到dist/。此阶段开始时还会先清空dist/与publish/目录buildExtraScripts按plugin.config.json中的extraScripts列表逐一编译附加脚本默认events示例为空数组createArchive把dist/目录内的全部文件打包成.jpl归档并生成配套的.json信息文件。构建产物构建完成后项目根目录会生成两个目录/产物dist/编译后的中间产物插件主代码index.js及复制过来的静态资源publish/{pluginId}.jplJPL 插件安装包是最终用于分发的文件publish/{pluginId}.json则记录了插件元信息并在打包时自动追加_publish_hashJPL 文件的 SHA-256 校验值与_publish_commitgit 分支与提交号见 webpack.config.js。把生成的.jpl文件放进 Joplin 的插件目录或在应用内通过工具 → 选项 → 插件界面手动安装即可加载。类型与语言选择README 还特别说明模板默认使用 TypeScript但你也可以把工程改成纯 JavaScript——只要保证webpack.config.js中ts-loader的规则与入口文件匹配即可。tsconfig.json中的allowJs: true也表明混用 JS 是被允许的。更新插件框架yo joplin --update当 Joplin 插件框架升级后模板工程可以通过生成器一键更新yo joplin --update等价地package.json 中预置了npm run update脚本先全局安装generator-joplin再执行yo joplin --update。README 给出了两条非常重要的使用提醒src/目录内的源码不会被覆盖被覆盖的只是框架相关文件如package.json、.gitignore、webpack.config.js等但若你曾修改过这些框架文件务必先提交到版本控制以便更新后比对 diff 并重新应用你的改动尽量避免改动框架文件。如果必须改例如要扩展 Webpack 配置正确做法是新建一个独立的 JS 文件然后在webpack.config.js中用一行require引入它——这样升级框架时只需要恢复这一行自定义逻辑不会丢失。这条少改动、外置文件的策略与 GENERATOR_DOC.md 的说明一致更新命令会尽量合并package.json与.gitignore的差异且保留src/与README.md不动唯独webpack.config.js会被整体覆盖因此它是最需要隔离自定义改动的文件。进阶附加脚本extraScripts与插件发布虽然 events 示例本身没有用到但模板配套的 GENERATOR_DOC.md 与 plugin.config.json 还覆盖了两个实用主题一并说明以保证文档完整性。编译附加脚本默认情况下 Webpack 只编译src/index.ts及其 import 链其余文件仅被复制。但在两种场景下你需要把其他脚本也纳入编译脚本是 TypeScript 文件必须编译成 JS 才能运行脚本require了package.json中新增的第三方模块必须打包进 JPL 才能随插件分发。做法是在 plugin.config.json 的extraScripts数组中加入相对src/的路径例如文件位于src/webviews/index.ts就写webviews/index.ts。编译后的产物固定使用.js扩展名插件代码中应引用编译后的路径如webviews/index.js详见 webpack.config.js 中resolveExtraScriptPath的实现。发布到插件仓库模板的发布流程也很清晰先构建再执行npm publish把插件发布到 npm。后续 Joplin 的自动脚本会将其收录进官方插件仓库前提是满足三个条件GENERATOR_DOC.mdpackage.json的name以joplin-plugin-开头例如joplin-plugin-tocpackage.json的keywords包含joplin-pluginpublish/目录下存在构建生成的.jpl与.json文件。webpack.config.js中的validatePackageJson函数会在每次打包时自动检查前两条并给出黄色警告webpack.config.js帮你在发布前及早发现问题。小结以 events 示例插件为镜可以梳理出 Joplin 插件开发的完整心智模型工程骨架src/index.ts入口src/manifest.json清单api/类型声明三件套生命周期在joplin.plugins.register的onStart中完成一切初始化事件驱动通过joplin.workspace.onXxx订阅闹钟、同步、笔记选择等事件配合joplin.data数据 API 实现自动化构建分发npm run dist走完编译主入口 → 编译附加脚本 → 打包 JPL三阶段产物落在publish/框架升级yo joplin --update把自定义 Webpack 逻辑外置为独立文件以最小化升级冲突。对于想要深入的同学仓库里还提供了大量同类示例插件位于 packages/app-cli/tests/support/plugins 目录如settings、register_command、dialog等以及完整的插件 API 类型定义可供查阅Yeoman 生成器源码则在 packages/generator-joplin 中可以对照模板了解每个文件是如何生成的。【免费下载链接】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），仅供参考 Joplin 插件开发实战：解读 events 示例插件的构建流程与事件监听 API
Joplin 插件开发实战解读 events 示例插件的构建流程与事件监听 API【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplin本文以 Joplin 仓库内置的 events 演示插件为切入点系统讲解 Joplin 插件工程的标准结构、npm run dist构建与 JPL 打包流程并逐行解析joplin.workspace事件监听 API闹钟触发、同步开始/完成等的实际用法。读完本文你将掌握从零搭建、编译、分发一个 Joplin 插件以及利用事件钩子实现自动化功能的完整套路。背景events 插件是什么events是 Joplin 官方为插件开发者准备的示例插件之一位于 packages/app-cli/tests/support/plugins/events。它的manifest.json中的描述写得很直白——Demonstrate how to listen to various events演示如何监听各类事件。也就是说这个插件本身不提供任何界面功能它的全部价值在于示范如何注册插件、如何挂接工作区事件回调是学习 Joplin 插件 API 的最佳入门样例。它同时也是一个由 Yeoman 生成器generator-joplin生成的标准插件模板目录下的 README.md 即模板自带的工程说明文档描述了所有 Joplin 插件通用的结构、构建与更新方式。因此本文将以该 README 为骨架以 events 示例源码为血肉展开讲解。插件项目的目录结构README 明确指出一个 Joplin 插件项目里最值得关注的是两个文件/src/index.ts插件的入口文件所有插件逻辑的起点/src/manifest.json插件清单声明插件名称、版本、最低兼容的应用版本等信息。以 events 示例为例实际目录结构如下位于仓库 packages/app-cli/tests/support/plugins/eventsevents/ ├── src/ │ ├── index.ts # 插件入口注册插件并挂接事件 │ └── manifest.json # 插件清单 ├── api/ # 插件 API 的 TypeScript 类型声明 │ ├── Joplin.d.ts │ ├── JoplinData.d.ts │ ├── JoplinWorkspace.d.ts │ └── ... ├── webpack.config.js # 构建配置模板自动生成 ├── plugin.config.json # 插件附加配置如 extraScripts ├── package.json # npm 脚本与依赖 ├── tsconfig.json # TypeScript 编译配置 └── README.md # 模板工程说明其中api/目录是模板自动附带、由 Joplin 插件 API 类型定义生成的声明文件集合开发时 IDE 会基于它们提供完整的自动补全与类型检查项目根目录下的api/index.ts导出一个全局的joplin单例对象插件代码通过import joplin from api引入它。入口文件 src/index.tsevents 插件的 src/index.ts 完整代码如下import joplin from api; joplin.plugins.register({ onStart: async function() { joplin.workspace.onNoteAlarmTrigger(async (event:any) { const note await joplin.data.get([notes, event.noteId]); console.info(Alarm was triggered for note: , note); }); joplin.workspace.onSyncStart(async (event:any) { console.info(Sync has started...); }); joplin.workspace.onSyncComplete(async (event:any) { console.info(Sync has completed); console.info(With errors:, event.withErrors); }); }, });这段代码展示了一个 Joplin 插件的最小完整形态通过joplin.plugins.register({...})注册插件在onStart生命周期回调中初始化业务逻辑通过joplin.workspace.xxx系列方法订阅工作区事件。插件清单 manifest.jsonsrc/manifest.json 的内容{ id: org.joplinapp.plugins.EventsDemo, manifest_version: 1, app_min_version: 1.4, name: Event demo, description: Demonstrate how to listen to various events, version: 1.0.0, author: Laurent Cozic, homepage_url: https://joplinapp.org }各字段含义如下字段说明示例值id插件的全局唯一标识通常采用反向域名风格它同时决定了 JPL 安装包的命名org.joplinapp.plugins.EventsDemomanifest_version清单格式版本目前为11app_min_version运行该插件所需的最低 Joplin 版本低于此版本的应用不会加载插件1.4name插件显示名称Event demodescription插件描述Demonstrate how to listen to various eventsversion插件版本号语义化版本1.0.0author作者名Laurent Cozichomepage_url插件主页https://joplinapp.org从构建脚本 webpack.config.js 可以看到manifest.json中的id会被读取并用于生成publish/{id}.jpl与publish/{id}.json两个分发产物同时readManifest还会校验categories字段是否属于预定义的分类集合如productivity、themes、editor等如果类别重复或非法会直接抛出构建错误。事件监听 API 详解events 插件示范了三个最常用的工作区事件它们的定义与完整事件族可以在 api/JoplinWorkspace.d.ts 中查到。onNoteAlarmTrigger待办闹钟触发joplin.workspace.onNoteAlarmTrigger(async (event:any) { const note await joplin.data.get([notes, event.noteId]); console.info(Alarm was triggered for note: , note); });当与某个待办事项to-do关联的闹钟被触发时Joplin 会调用该回调。事件对象event携带noteId字段类型定义见 JoplinWorkspace.d.ts随后示例通过数据 API 的joplin.data.get([notes, noteId])按 ID 拉取完整的笔记对象——这演示了事件回调与数据 API 的组合用法事件只给最小上下文具体数据需要用joplin.data主动获取。joplin.data的方法签名与 REST 语义一一对应GET/POST/PUT/DELETE其path参数是一个数组形如[notes, :id, link]详见 api/JoplinData.d.ts。由于插件运行在 Joplin 应用进程内部调用该 API无需鉴权 token。onSyncStart / onSyncComplete同步生命周期joplin.workspace.onSyncStart(async (event:any) { console.info(Sync has started...); }); joplin.workspace.onSyncComplete(async (event:any) { console.info(Sync has completed); console.info(With errors:, event.withErrors); });onSyncStart同步过程开始时触发回调不带事件参数类型定义为SyncStartHandler () voidonSyncComplete同步结束后触发事件对象带有withErrors: boolean字段见 JoplinWorkspace.d.ts用于判断本次同步是否出现错误。这两个钩子非常适合做同步状态的日志记录、桌面通知或是在同步完成后再触发自定义的数据刷新逻辑。更多可用事件api/JoplinWorkspace.d.ts 还定义了 events 示例之外的一批常用事件均可在插件中直接使用API触发时机事件参数onNoteSelectionChange当前选中的笔记发生变化value: string[]笔记 ID 数组onNoteChange笔记内容或任意属性变化推荐取代已废弃的onNoteContentChange{ id, event }event取值为Create/Update/DeleteonResourceChange资源附件被修改新增/删除不触发{ id }onNoteAlarmTrigger待办闹钟触发{ noteId }onSyncStart同步开始无onSyncComplete同步完成{ withErrors: boolean }filterEditorContextMenu编辑器右键菜单弹出前仅桌面端允许向菜单注入条目菜单过滤对象值得留意的是onNoteSelectionChange、onNoteChange、onNoteAlarmTrigger、onSyncStart、onSyncComplete等订阅方法的返回类型是PromiseDisposable——订阅后返回一个可销毁句柄插件卸载时用于反注册回调避免内存泄漏。构建插件npm run distREADME 明确指出构建命令只有一条npm run dist该命令来自 package.json 中的scripts配置实际展开是三个依次执行的 Webpack 构建步骤dist: webpack --joplin-plugin-config buildMain webpack --joplin-plugin-config buildExtraScripts webpack --joplin-plugin-config createArchive对应的三阶段逻辑定义在 webpack.config.jsbuildMain编译入口./src/index.ts用ts-loader将 TypeScript 编译为 CommonJS 模块target 为 ES2015配置见 tsconfig.json并把src/下其余非 TS 资源CSS、JSON 等复制到dist/。此阶段开始时还会先清空dist/与publish/目录buildExtraScripts按plugin.config.json中的extraScripts列表逐一编译附加脚本默认events示例为空数组createArchive把dist/目录内的全部文件打包成.jpl归档并生成配套的.json信息文件。构建产物构建完成后项目根目录会生成两个目录/产物dist/编译后的中间产物插件主代码index.js及复制过来的静态资源publish/{pluginId}.jplJPL 插件安装包是最终用于分发的文件publish/{pluginId}.json则记录了插件元信息并在打包时自动追加_publish_hashJPL 文件的 SHA-256 校验值与_publish_commitgit 分支与提交号见 webpack.config.js。把生成的.jpl文件放进 Joplin 的插件目录或在应用内通过工具 → 选项 → 插件界面手动安装即可加载。类型与语言选择README 还特别说明模板默认使用 TypeScript但你也可以把工程改成纯 JavaScript——只要保证webpack.config.js中ts-loader的规则与入口文件匹配即可。tsconfig.json中的allowJs: true也表明混用 JS 是被允许的。更新插件框架yo joplin --update当 Joplin 插件框架升级后模板工程可以通过生成器一键更新yo joplin --update等价地package.json 中预置了npm run update脚本先全局安装generator-joplin再执行yo joplin --update。README 给出了两条非常重要的使用提醒src/目录内的源码不会被覆盖被覆盖的只是框架相关文件如package.json、.gitignore、webpack.config.js等但若你曾修改过这些框架文件务必先提交到版本控制以便更新后比对 diff 并重新应用你的改动尽量避免改动框架文件。如果必须改例如要扩展 Webpack 配置正确做法是新建一个独立的 JS 文件然后在webpack.config.js中用一行require引入它——这样升级框架时只需要恢复这一行自定义逻辑不会丢失。这条少改动、外置文件的策略与 GENERATOR_DOC.md 的说明一致更新命令会尽量合并package.json与.gitignore的差异且保留src/与README.md不动唯独webpack.config.js会被整体覆盖因此它是最需要隔离自定义改动的文件。进阶附加脚本extraScripts与插件发布虽然 events 示例本身没有用到但模板配套的 GENERATOR_DOC.md 与 plugin.config.json 还覆盖了两个实用主题一并说明以保证文档完整性。编译附加脚本默认情况下 Webpack 只编译src/index.ts及其 import 链其余文件仅被复制。但在两种场景下你需要把其他脚本也纳入编译脚本是 TypeScript 文件必须编译成 JS 才能运行脚本require了package.json中新增的第三方模块必须打包进 JPL 才能随插件分发。做法是在 plugin.config.json 的extraScripts数组中加入相对src/的路径例如文件位于src/webviews/index.ts就写webviews/index.ts。编译后的产物固定使用.js扩展名插件代码中应引用编译后的路径如webviews/index.js详见 webpack.config.js 中resolveExtraScriptPath的实现。发布到插件仓库模板的发布流程也很清晰先构建再执行npm publish把插件发布到 npm。后续 Joplin 的自动脚本会将其收录进官方插件仓库前提是满足三个条件GENERATOR_DOC.mdpackage.json的name以joplin-plugin-开头例如joplin-plugin-tocpackage.json的keywords包含joplin-pluginpublish/目录下存在构建生成的.jpl与.json文件。webpack.config.js中的validatePackageJson函数会在每次打包时自动检查前两条并给出黄色警告webpack.config.js帮你在发布前及早发现问题。小结以 events 示例插件为镜可以梳理出 Joplin 插件开发的完整心智模型工程骨架src/index.ts入口src/manifest.json清单api/类型声明三件套生命周期在joplin.plugins.register的onStart中完成一切初始化事件驱动通过joplin.workspace.onXxx订阅闹钟、同步、笔记选择等事件配合joplin.data数据 API 实现自动化构建分发npm run dist走完编译主入口 → 编译附加脚本 → 打包 JPL三阶段产物落在publish/框架升级yo joplin --update把自定义 Webpack 逻辑外置为独立文件以最小化升级冲突。对于想要深入的同学仓库里还提供了大量同类示例插件位于 packages/app-cli/tests/support/plugins 目录如settings、register_command、dialog等以及完整的插件 API 类型定义可供查阅Yeoman 生成器源码则在 packages/generator-joplin 中可以对照模板了解每个文件是如何生成的。【免费下载链接】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），仅供参考