Joplin 插件模板开发指南从 manifest 到 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 的插件系统允许开发者通过 Yeoman 生成器yo joplin快速搭建一个标准工程本指南以仓库中packages/app-cli/tests/support/plugins/editor_context_menu这一模板型示例插件为骨架系统讲解插件目录结构、清单配置、基于 Webpack 的构建打包流程、框架更新机制并结合示例源码演示如何在编辑器右键菜单中挂载自定义命令。读完本文你将掌握从零创建一个可分发 Joplin 插件JPL 归档的完整链路并能独立为笔记编辑器扩展右键菜单等 UI 入口。插件模板整体结构与核心文件Joplin 插件模板的核心职责非常聚焦源码入口 插件清单 构建配置。以 editor_context_menu 插件目录 为例模板中最需要关注的两个文件是/src/index.ts插件源码的入口点所有插件逻辑从这里注册/src/manifest.json插件清单声明插件的名称、版本、作者等元信息。模板目录下还包含配套的工程化文件package.json脚本与依赖、webpack.config.js构建配置、tsconfig.jsonTypeScript 编译配置、plugin.config.json外部脚本声明、api/Joplin 插件 API 的类型声明供开发期提供类型提示以及GENERATOR_DOC.md生成器附带的使用文档。入口文件 src/index.ts示例插件 src/index.ts 展示了 Joplin 插件 API 的最小用法import joplin from api; import { MenuItemLocation } from api/types; joplin.plugins.register({ onStart: async function() { await joplin.commands.register({ name: sayHi, label: Say Hi, execute: async () { await joplin.commands.execute(replaceSelection, hi!); }, }); await joplin.views.menuItems.create(myContextMenuItem, sayHi, MenuItemLocation.EditorContextMenu); }, });这段代码的执行链分三步joplin.plugins.register({ onStart })注册插件生命周期回调Joplin 在应用启动时调用onStartjoplin.commands.register(...)注册一个名为sayHi的自定义命令label为菜单中显示的文案joplin.views.menuItems.create(myContextMenuItem, sayHi, MenuItemLocation.EditorContextMenu)把该命令以菜单项形式挂到编辑器右键菜单EditorContextMenu下。命令体内调用的replaceSelection是 Joplin 的内置命令用于将文本插入/替换当前编辑器选中区域。在桌面端它贯穿于 CodeMirror 与 TinyMCE 两种编辑器实现例如 packages/app-desktop/commands/replaceMisspelling.ts 中便通过CommandService.instance().execute(replaceSelection, suggestion)在拼写修正场景下替换选区文本CodeMirror 编辑器封装 则将其映射到editorRef.current.replaceSelection(value)。也就是说本示例在右键菜单点击后会在光标处插入字符串hi!。插件清单 manifest.jsonsrc/manifest.json 是插件的信息中枢{ id: org.joplinapp.plugins.EditorContextMenuDemo, manifest_version: 1, app_min_version: 1.4, name: Editor Context Menu Demo, description: , version: 1.0.0, author: , homepage_url: }各字段含义id插件唯一标识构建产物.jpl 归档与 .json 信息文件以该 id 命名manifest_version清单协议版本当前模板为1app_min_version运行该插件所需的最低 Joplin 版本此处为1.4name/description/author/homepage_url展示用元信息version插件版本号遵循语义化版本。构建插件Webpack 管线与 JPL 归档模板使用 Webpack 完成构建构建结果分为两部分编译产物TypeScript 源码被编译输出到dist/目录分发归档在插件根目录生成 JPLJoplin Plugin Library归档文件该归档即可用于分发、安装。构建命令非常简洁npm run dist对应 package.json 中的脚本定义dist: webpack --joplin-plugin-config buildMain webpack --joplin-plugin-config buildExtraScripts webpack --joplin-plugin-config createArchivenpm run dist实际串行执行三个阶段的 Webpack 构建--joplin-plugin-config参数指定运行哪个配置阶段这一设计在 webpack.config.js 的main()中清晰可见buildMain编译./src/index.ts入口并把src/下其余资源CSS、脚本、静态文件等复制到dist/该阶段启动时会先清理并重建dist/与publish/目录buildExtraScripts按plugin.config.json中extraScripts声明的外部脚本逐个编译见下文JavaScript 文件若无需编译则直接复制到dist/需要编译的则被编译产物覆盖createArchive以dist/index.js为入口通过 createPluginArchive 将dist/全部文件用 tar 打包为publish/manifest.id.jpl同时生成附带_publish_hashSHA-256与_publish_commitGit 分支与提交号的id.json信息文件。模板默认采用 TypeScript 工程配置见 tsconfig.json但通过调整构建配置也可改用纯 JavaScript 开发灵活度留给开发者自行决定。注册命令与菜单挂载点MenuItemLocation 全览本模板插件的主题是“编辑器右键菜单”其 API 支持将命令挂载到多个内置菜单位置。MenuItemLocation枚举定义在 api/types.ts完整取值包括枚举值挂载位置命令接收的上下文参数File/Edit/View/Note/Tools/Help应用顶部对应主菜单无NoteListContextMenu笔记列表右键菜单noteIds: string[]被右键选中的笔记 IDEditorContextMenu编辑器右键菜单无FolderContextMenu文件夹右键菜单folderId: stringTagContextMenu标签右键菜单tagId: stringContext已废弃与NoteListContextMenu等价同NoteListContextMenu对应的创建 API 为joplin.views.menuItems.create(id, commandName, location?, options?)其中options目前支持accelerator快捷键字段见 JoplinViewsMenuItems.d.ts。桌面端特有的菜单能力platform-desktop可进一步参考 JoplinViewsMenus.d.ts 中create(id, label, menuItems, location?)的用法它允许把一组菜单项作为子菜单挂到应用内置菜单下。外部脚本extraScriptscontent script 与 webview 脚本的编译默认构建只编译src/index.ts及其 import 的模块其余文件会被原样复制进插件包。但以下两种场景需要额外编译详见模板附带的 GENERATOR_DOC.md脚本本身是 TypeScript 文件必须编译为 JavaScript脚本引用了package.json中新增的第三方依赖必须打包进 JPL 才能随插件分发。解决方案是在 plugin.config.json 中声明{ extraScripts: [] }例如将src/webviews/index.ts加入extraScripts数组时路径需相对src/书写为webviews/index.ts编译后产物固定以.js结尾即插件包内路径为webviews/index.js引用时使用该路径。resolveExtraScriptPathwebpack.config.js会为每个外部脚本单独生成一个以commonjs为库目标、导出default的编译配置。更新插件框架yo joplin --update与版本控制建议插件模板由generator-joplin生成更新框架使用yo joplin --update模板package.json中也提供了等价的npm run update脚本先npm install -g generator-joplin再执行上述命令。更新操作的关键行为与注意事项会覆盖src/目录之外的所有框架相关文件如package.json、.gitignore、webpack.config.js源码不受影响因此若改过框架文件务必先纳入版本控制如 Git更新后通过 diff 检查并重新应用自己的改动最佳实践是尽量不改动框架文件若要扩展 Webpack 配置建议新建独立 JS 文件并在webpack.config.js中通过require引入这样更新时只需恢复引入的那一行即可。webpack.config.js文件头部也以注释形式给出了同样的建议见 webpack.config.js 注释从源码层面印证了这一约定。插件发布到官方仓库的三大条件如需将插件发布到 Joplin 插件仓库通过npm publish提交到 npm 后由官方脚本自动收录GENERATOR_DOC.md 明确了必须同时满足的三个条件package.json的name以joplin-plugin-开头如joplin-plugin-tocpackage.json的keywords中包含joplin-pluginpublish/目录下存在由npm run dist生成的.jpl与.json文件。webpack.config.js中的validatePackageJson()第 37-50 行会在打包时对前两项做校验并给出黄色警告包名不符合joplin-plugin-前缀、keywords缺少joplin-plugin都会触发提示。插件生成器默认已配置好这些字段若发布后发现仓库中未出现自己的插件可对照上述三点逐一排查。小结通过本模板一条完整的 Joplin 插件生产链路已经清晰src/index.ts注册命令与 UI 入口 →manifest.json声明元信息 →npm run dist经三段 Webpack 构建产出dist/编译产物与publish/*.jpl分发归档 → 插件包可安装到 Joplin 桌面端或按三项约定发布到官方插件仓库。本文示例的editor_context_menu恰好覆盖了其中最常用的一环——把自定义命令挂载到笔记编辑器的右键菜单配合replaceSelection内置命令即可快速实现“选中文本 → 自定义操作”的交互扩展是理解 Joplin 插件 API 命令与菜单体系的理想起点。值得深入探索的相关资料editor_context_menu 插件完整目录插件 API 类型声明目录 api/生成器附带的完整使用文档 GENERATOR_DOC.md桌面端 replaceSelection 命令的实际调用【免费下载链接】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），仅供参考
