Joplin 插件开发实战:基于官方模板理解插件入口、manifest 与 JPL 打包构建全流程
Joplin 插件开发实战:基于官方模板理解插件入口、manifest 与 JPL 打包构建全流程
Joplin 是一款以隐私为核心、支持多端同步的笔记应用,其插件机制允许开发者通过 TypeScript/JavaScript 扩展笔记编辑器、界面视图与桌面端行为。本文以仓库内置的 toast 示例插件(packages/app-cli/tests/support/plugins/toast/README.md)所附的官方模板 README 为主线,完整讲解 Joplin 插件工程的核心骨架:src/index.ts 入口点、src/manifest.json 插件清单、基于 Webpack 的 npm run dist 构建流水线,以及 yo joplin --update 的框架升级策略。读完本文,你将能够独立搭建、构建并发布一个可用的 Joplin 插件,并掌握如何在不被升级覆盖的前提下安全定制框架配置。
模板全景:一个标准 Joplin 插件工程包含什么
官方模板是一个完整的 npm 工程,除了 README 中强调的两个核心文件,还包含构建配置、API 类型声明与打包脚本。以 toast 示例插件的实际目录为例:
packages/app-cli/tests/support/plugins/toast/
├── api/ # 官方插件 API 的 TypeScript 类型声明(Joplin.d.ts、JoplinViewsDialogs.d.ts 等)
├── src/
│ ├── index.ts # 插件源码入口点
│ └── manifest.json # 插件清单:名称、版本、ID 等元信息
├── GENERATOR_DOC.md # yeoman 生成器补充文档
├── README.md # 模板说明(本文主体)
├── package.json # npm 脚本与依赖(dist / update 等)
├── plugin.config.json # 额外脚本配置(extraScripts)
├── tsconfig.json # TypeScript 编译配置
└── webpack.config.js # 三段式构建流水线核心
README 明确指出,开发时最需要关注的两个文件是:
/src/index.ts:插件源码的入口点,所有插件逻辑从这里启动;/src/manifest.json:插件清单,承载插件名称、版本号等元信息。
两者的作用可以在 toast 示例中直接验证。入口文件 src/index.ts 通过 joplin.plugins.register({ onStart }) 注册插件生命周期回调;而 src/manifest.json 声明了插件 ID org.joplinapp.plugins.DialogDemo、最低应用版本 app_min_version: "1.4"、插件名、描述、作者与主页。其中 manifest_version 当前为 1,是 Joplin 插件清单的协议版本号。
入口点 src/index.ts:插件如何启动
Joplin 插件的入口文件统一约定为 src/index.ts。它通过全局导入的 joplin 对象访问整个插件 API——正如 api/Joplin.d.ts 所述,这是“Joplin API 的主入口点”,提供 data、views、commands、settings、workspace 等访问器。
最基础的启动模式是调用 joplin.plugins.register() 并传入一个含 onStart 回调的注册对象。toast 示例展示了最小可用形态:
import joplin from 'api';
import { ToastType } from 'api/types';
joplin.plugins.register({
onStart: async function() {
const dialogs = joplin.views.dialogs;
setTimeout(() => {
dialogs.showToast({
message: 'This is an info message',
});
}, 5000);
setTimeout(() => {
dialogs.showToast({
type: ToastType.Error,
message: 'This is an error message',
});
}, 7000);
setTimeout(() => {
dialogs.showToast({
type: ToastType.Success,
message: 'This is a success message',
});
}, 9000);
},
});
从源码结构看,该示例依次在启动后 5 秒、7 秒、9 秒触发三条不同类型的 toast 通知,用于演示 showToast 的三种展示形态。onStart 被声明为 async,意味着可以在其中执行异步初始化(读取设置、创建视图等),插件框架会等待其完成。入口点之外,api/ 目录下的 .d.ts 声明文件为整个 API 提供类型提示与编译期校验,这是模板工程默认启用 TypeScript 的最大收益。
manifest.json:插件的身份证明
清单文件是插件能否被 Joplin 正确加载与发布的关键。以 toast 示例的 manifest.json 为准,各字段含义如下:
| 字段 | 示例值 | 说明 |
|---|---|---|
id |
org.joplinapp.plugins.DialogDemo |
插件唯一 ID,构建脚本会将其用作 JPL 归档文件名(<id>.jpl) |
manifest_version |
1 |
清单协议版本号 |
app_min_version |
1.4 |
支持该插件的最低 Joplin 应用版本 |
name |
Dialog Demo |
插件显示名称 |
description |
Demonstrate how to create and use a custom dialog box |
插件简介 |
version |
1.0.0 |
插件版本号 |
author |
Laurent Cozic |
作者 |
homepage_url |
https://joplinapp.org |
主页地址(模板默认值) |
构建脚本对 manifest 有硬性校验:在 webpack.config.js 的 readManifest() 中,若 id 缺失会直接抛出错误;若声明了 categories 字段,还会逐一校验其必须位于预置类别白名单内(如 appearance、productivity、themes、integrations、editor、personal knowledge management 等),且不允许重复。因此新增类别前务必核对白名单,否则构建会失败。
构建插件:npm run dist 背后的三段式 Webpack 流水线
README 给出的构建命令极其简单:npm run dist。它由 package.json 中的 scripts 定义,实际是串联三次带 --joplin-plugin-config 参数的不同 webpack 调用:
"dist": "webpack --joplin-plugin-config buildMain && webpack --joplin-plugin-config buildExtraScripts && webpack --joplin-plugin-config createArchive"
在 webpack.config.js 中,这三步分别对应 main() 函数里三套配置,注释中说明了它们必须按顺序串行执行(webpack 并行运行无法保证产物顺序):
buildMain:以./src/index.ts为入口,用ts-loader编译 TypeScript,输出到/dist;同时通过copy-webpack-plugin把src/下非.ts/.tsx的静态资源(脚本、CSS、其他资产)一并拷入/dist。第一次执行时还会清空并重建dist/与publish/目录。buildExtraScripts:按 plugin.config.json 中extraScripts数组声明的额外脚本逐个编译,产物输出到/dist并可能覆盖上一步拷贝的原始 JS——设计意图是:不需要编译的 JS 直接拷贝,需要编译的则以编译产物为准。createArchive:通过on-build-webpack钩子在构建完成后触发onBuildCompleted(),把dist/下所有文件用tar打成 JPL 归档(publish/<manifest.id>.jpl),同时生成对应的插件信息文件publish/<manifest.id>.json(内含_publish_hash的 SHA-256 校验值与_publish_commit的 git 分支/提交信息),最后执行validatePackageJson()检查发布规范。
dist 目录存放编译产物,publish 目录存放可直接分发/安装的 JPL 归档——README 中“JPL archive 也会在根目录创建,可用于分发插件”所指即此。若 dist 目录为空,createPluginArchive() 会抛出 Plugin archive was not created because the "dist" directory is empty 并中止打包。
用示例插件验证构建链路
本文讨论的 toast 插件位于 packages/app-cli/tests/support/plugins/toast,属于 app-cli 包测试支持目录下的插件示例(packages/app-cli/tests/support/plugins/ 下还同类存放了 dialog、externalEdit 等插件样例,可用于对照学习不同 API)。验证构建时:
cd packages/app-cli/tests/support/plugins/toast
npm install
npm run dist
执行完毕后检查 dist/index.js(编译后的插件主体)与 publish/org.joplinapp.plugins.DialogDemo.jpl(可分发归档)是否生成。此外,仓库根目录还提供了一键脚手架方案 packages/generator-joplin,可用 yo joplin 生成全新插件工程,与本文模板结构完全一致。
更新插件框架:yo joplin --update 及其风险控制
插件框架(构建脚本、webpack 配置、API 类型声明等)会随 Joplin 版本迭代,官方模板的升级方式为:
yo joplin --update
该命令由 package.json 的 update 脚本包装(npm install -g generator-joplin && yo joplin --update),其实现位于 packages/generator-joplin 包中。README 特别警告了两点:
- 升级会覆盖
src/之外的所有框架相关文件——包括package.json、.gitignore、webpack.config.js等,你自己的源码不受影响。因此若曾修改过框架文件,务必先提交到版本控制,升级后再对比 diff 并重新应用改动。 - 框架文件改动越少越好:如果必须改 Webpack 配置,推荐新建一个独立 JS 文件,并在
webpack.config.js中通过require引入。这样升级时只需恢复那一行引入语句即可,其余自定义内容全部保留。
这一建议与 webpack.config.js 头部注释完全一致:“不建议编辑此文件,因为更新框架时会被覆盖;如确需修改,考虑使用外部 JS 文件并在此 require 它,以最小化改动、便于升级后恢复”。例如,把自定义 loader 或插件规则写进 my-custom-webpack.js,然后在模板配置里加一行 const custom = require('./my-custom-webpack'); 即可。
结合源码纵深:showToast API 与 Toast 参数模型
toast 示例插件是理解“入口 + 清单 + 构建”之外最有价值的 API 用例,其核心 API showToast 的完整签名位于 api/JoplinViewsDialogs.d.ts:
showToast(toast: Toast): Promise<void>;
参数类型 Toast 与枚举 ToastType 定义在 api/types.ts:
export enum ToastType {
Info = 'info',
Success = 'success',
Error = 'error',
}
export interface Toast {
message: string;
type?: ToastType;
duration?: number;
timestamp?: number;
}
各字段说明:
message(必填):toast 显示的核心文本;type(可选):通知类型,取ToastType.Info/ToastType.Success/ToastType.Error之一;示例中省略时默认为 info 风格(第一次showToast调用即未传type);duration(可选):显示时长(毫秒级数值);timestamp(可选):时间戳,用于定位通知的产生时刻。
示例插件分别在 5s/7s/9s 触发 info、error、success 三种 toast,正好覆盖了枚举的全部取值,是测试 showToast 视觉表现的最小可运行程序。若需更复杂的交互界面(模态对话框、按钮、HTML 内容),可在同一 API 面上使用 create()、setHtml()、setButtons()、open() 等方法,toast 与 dialog 共用 joplin.views.dialogs 这一视图管理器。
发布前自检清单
结合模板构建脚本的校验逻辑,发布前应逐项确认:
package.json命名:包名应以joplin-plugin-开头(否则构建仅告警不报错,但不利于发布识别);keywords:必须包含joplin-plugin;- scripts 约定:若需安装时构建,推荐使用
prepare脚本而非postinstall(脚本内已针对postinstall输出警告); - manifest 完整性:
id必填;categories若填写必须在小写白名单内且不重复; - 归档产物:确认
publish/<plugin-id>.jpl与.json均已生成,.json内含发布哈希与 git 提交信息,便于追溯版本来源; - 升级前提交:执行
yo joplin --update前,先提交所有框架文件改动到版本控制。
结语
这份官方模板 README 虽短,却勾勒出 Joplin 插件开发的最小闭环:用 src/index.ts 书写逻辑、用 manifest.json 声明身份、用 npm run dist 一键产出 JPL 归档、用 yo joplin --update 低成本跟随框架演进。结合 toast 示例的 showToast API 与 webpack 三段式构建源码,开发者可以从零开始搭建插件工程,并在后续开发中把“改框架文件”视为需要版本控制与最小化策略的高风险操作。更多 API 细节可继续研读模板自带的 api/ 类型声明目录,以及 packages/generator-joplin 下的生成器实现。