Joplin 插件开发实战基于官方模板工程构建自定义设置Settings插件【免费下载链接】joplinJoplin - the privacy-focused note taking app with sync capabilities for Windows, macOS, Linux, Android and iOS.项目地址: https://gitcode.com/GitHub_Trending/jo/joplinJoplin 插件系统允许第三方开发者通过 JavaScript/TypeScript 扩展这款隐私优先的笔记应用。本文以仓库内官方自带的设置插件示例Settings Demo为骨架完整讲解如何从模板工程起步理解目录结构、构建 JPL 插件包、注册自定义设置分区与设置项、读写设置值以及如何安全地升级插件框架。读完本文你将能够独立开发一个带有配置界面、可被用户在“配置”屏幕中直接编辑设置的 Joplin 插件。一、模板工程官方插件脚手架的核心文件本示例插件位于 packages/app-cli/tests/support/plugins/settings它既是一个可直接运行的演示插件演示joplin.settings各项能力也是 generator-joplin 生成器产出模板的标准形态。其 README.md 明确指出插件模板中最重要的两个文件是文件作用src/index.ts插件源码的入口点所有注册逻辑设置、命令、视图等都在这里完成src/manifest.json插件清单包含插件名称、版本号、作者等元信息除此之外模板工程还包含以下配套文件均在示例目录下可查到package.jsonnpm 包定义其中scripts.dist定义了构建命令链webpack.config.jsWebpack 构建脚本负责编译 TypeScript、产出dist/目录与 JPL 归档plugin.config.json插件配置用于声明需要额外编译的脚本extraScripts默认为空数组tsconfig.jsonTypeScript 编译配置target: es2015、module: commonjs、outDir: ./dist/api/目录随模板自带的 Joplin 插件 API 类型声明.d.ts为编辑器提供完整的智能提示与类型检查。manifest.json插件身份信息示例的 src/manifest.json 内容如下{ id: org.joplinapp.plugins.SettingsDemo, manifest_version: 1, app_min_version: 1.4, name: Setting Demo, description: Demo to register new settings, version: 1.0.0, author: Laurent Cozic, homepage_url: https://joplinapp.org }关键字段说明id插件的全局唯一标识同时也是打包产物.jpl文件的命名依据见 webpack.config.js 中pluginArchiveFilePath publish/${manifest.id}.jplmanifest_version清单格式版本当前为 1app_min_version运行该插件所需的最低 Joplin 版本示例要求1.4及以上name/description/version/author展示在插件管理器中的基本信息。二、构建插件一条命令产出可分发产物模板采用 Webpack 构建。根据 README 与 package.json 中的脚本定义npm run dist该命令实际会按顺序执行三段 Webpack 构建见 webpack.config.js 中的configs映射buildMain以./src/index.ts为入口编译主逻辑并把src/下其余资源CSS、脚本、静态文件等复制到dist/buildExtraScripts根据plugin.config.json的extraScripts数组逐个编译需要额外处理的脚本如内容脚本、Webview 脚本编译产物固定输出为.js文件会覆盖同名拷贝文件——这是刻意设计不需要编译的 JS 直接拷贝需要编译的则被正确替换createArchive把dist/下所有文件用 tar 打包成.jpl归档并生成配套的.json插件信息文件。构建完成后的产物布局dist/编译后的插件代码目录publish/分发目录包含plugin-id.jpl可安装的插件归档与plugin-id.json插件信息其中通过createPluginInfo注入_publish_hash与_publish_commit字段用于发布校验。模板默认使用 TypeScript但 README 也说明可以修改配置改回纯 JavaScript 开发。此外package.json中定义了prepare: npm run dist这意味着npm install或npm publish前会自动执行构建保证发布产物始终是最新的。三、自定义设置注册分区与设置项本示例插件最核心的价值是演示了 Joplin 插件设置 APIjoplin.settings的完整用法。入口代码位于 src/index.ts在joplin.plugins.register的onStart回调中完成全部注册。3.1 注册自定义设置分区await joplin.settings.registerSection(myCustomSection, { label: My Custom Section, iconName: fas fa-music, });registerSection(name, section)用于创建一个新的设置分区。根据 JoplinSettings.d.ts 与 types.ts 中的SettingSection接口分区支持以下属性属性说明label分区在配置屏幕中显示的标题必填iconName分区图标使用 Font Awesome 类名如fas fa-musicdescription分区的描述文字name分区名称分区注册是动态的它只存在于本次 Joplin 运行期间每次应用启动后插件都必须重新注册通常在onStart中完成。但设置值本身会跨启动持久保留即使某次插件启动失败已保存的设置值也不会丢失。3.2 注册各类设置项示例通过一次registerSettings调用批量注册了 7 个设置项覆盖了最常见的配置形态await joplin.settings.registerSettings({ myCustomSetting: { value: 123, type: SettingItemType.Int, section: myCustomSection, public: true, label: My Custom Setting, }, multiOptionTest: { value: en, type: SettingItemType.String, section: myCustomSection, isEnum: true, public: true, label: Multi-options test, options: { en: English, fr: French, es: Spanish, }, }, mySecureSetting: { value: hunter2, type: SettingItemType.String, section: myCustomSection, public: true, secure: true, label: My Secure Setting, }, myFileSetting: { value: abcd, type: SettingItemType.String, section: myCustomSection, public: true, label: My file setting, description: This setting will be saved to settings.json, [storage as any]: 2, // Should be storage: SettingStorage.File }, myFilePathAndArgs: { value: , type: SettingItemType.String, subType: SettingItemSubType.FilePathAndArgs, section: myCustomSection, public: true, label: File path and args, }, myFilePathOnly: { value: , type: SettingItemType.String, subType: SettingItemSubType.FilePath, section: myCustomSection, public: true, label: File path, }, myDirectory: { value: , type: SettingItemType.String, subType: SettingItemSubType.DirectoryPath, section: myCustomSection, public: true, label: Directory path, }, });3.3 SettingItem 字段全解根据 api/types.ts 中的SettingItem接口一个设置项可用的属性如下属性必填说明value是设置的默认/当前值type是设置类型见下方SettingItemType枚举label是在配置屏幕中显示的标签description否设置项的描述文字public是为true时设置会出现在配置屏幕并允许用户修改为false时为私有设置不暴露给用户只能程序化读写适合存储不想公开的内部值section否归属的分区名通常指向registerSection创建的自定义分区subType否子类型当前仅用于显示文件/目录选择器使用时type必须为SettingItemType.StringisEnum否设为true时该设置渲染为下拉列表options条件必填isEnum为true时必填为value label的映射表secure否设为true时该设置被视为安全数据如密码存储在系统钥匙串keychain中advanced否设为true时该设置归入配置屏幕的“Advanced高级”按钮下minimum/maximum/step否限定Int类型设置的取值范围与步进appTypes否预留属性目前未使用storage否存储位置SettingStorage.Database默认存数据库或SettingStorage.File存 settings.jsonSettingItemType枚举的取值按数值大小值名称用途1Int整数2String字符串3Bool布尔值4Array数组5Object对象6Button按钮SettingItemSubType用于文件/目录选择场景值说明FilePathAndArgs文件路径 命令行参数选择器FilePath文件路径选择器移动端不支持DirectoryPath目录路径选择器移动端不支持SettingStorageDatabase 1默认、File 2。示例中myFileSetting通过[storage as any]: 2指定存储到settings.json代码注释建议正式写法为storage: SettingStorage.File。这一存储行为的正确性在仓库测试中有对应验证——Setting.test.ts 针对SettingStorage.Database与SettingStorage.File两种存储分别断言“未立即注册/未在重启前注册的自定义设置不应被清除”底层实现 Setting.ts 也区分了keyStorage()为 File 时的读写分支。注意JoplinSettings.d.ts明确说明该 API无法访问 Joplin 内置设置这是刻意设计——允许插件修改内置设置可能产生不可预期的结果。四、读写设置值value / setValue / values / globalValue / onChange示例同时演示了设置值的读写 API方法签名与说明同样来自 JoplinSettings.d.ts方法说明values(keys: string[] \| string)批量获取自己注册的设置值返回Recordstring, unknownvalue(key)获取单个设置值已废弃推荐改用values()setValue(key, value)设置单个设置值globalValue(key)获取全局设置值包括应用自身设置及其他插件设置的项可用键列表参见源码packages/lib/models/Setting.tsonChange(handler)监听自己插件设置的变化事件对象为ChangeEvent含keys: string[]字段出于性能考虑该事件是延迟触发的且只接收本插件设置的变化事件在示例的incValue命令中读写流程非常直观execute: async () { const value await joplin.settings.value(myCustomSetting); console.info(Got value, value); await joplin.settings.setValue(myCustomSetting, value 1); },checkValue命令则演示了一次读取多个不同类型的设置execute: async () { const value await joplin.settings.value(myCustomSetting); console.info(Current value is: value); const secureValue await joplin.settings.value(mySecureSetting); console.info(Secure value is: secureValue); const fileValue await joplin.settings.value(myFileSetting); console.info(Setting in file is: fileValue); },可以看到无论设置存储于数据库、系统钥匙串还是settings.json对插件来说读取方式完全一致——存储细节由 Joplin 内核透明处理。五、将设置与命令、工具栏按钮联动注册好设置后示例进一步演示了“设置 ↔ 命令 ↔ 工具栏按钮”的完整链路await joplin.commands.register({ name: incValue, label: Increment custom setting value, iconName: fas fa-music, execute: async () { /* 读取并递增 myCustomSetting */ }, }); await joplin.commands.register({ name: checkValue, label: Check custom setting value, iconName: fas fa-drum, execute: async () { /* 打印各设置值 */ }, }); await joplin.views.toolbarButtons.create(incValueButton, incValue, ToolbarButtonLocation.NoteToolbar); await joplin.views.toolbarButtons.create(checkValueButton, checkValue, ToolbarButtonLocation.NoteToolbar);其中joplin.commands.register注册可执行命令name需全局唯一label用于菜单项与快捷键编辑器展示joplin.views.toolbarButtons.create(id, commandName, location)把命令绑定到工具栏按钮ToolbarButtonLocation.NoteToolbar表示出现在笔记工具栏右上角另有EditorToolbar文本编辑器上方只作用于笔记正文可选二者定义见 types.ts。这样用户既可以在配置屏幕修改设置值也可以通过工具栏按钮一键触发对设置的读写构成一个完整可交互的插件示例。六、更新插件框架yo joplin --update 的正确姿势模板工程由generator-joplinYeoman 生成器产出。README 中给出的更新命令为yo joplin --update在模板的package.json中则封装为npm run update该命令实际执行npm install -g generator-joplin yo joplin --update见 package.json。必须牢记的警告更新操作会覆盖src/目录之外所有框架相关文件如package.json、.gitignore、webpack.config.js你的业务源码不会被动到。因此修改过框架文件时务必先纳入版本控制更新后通过 diff 检查并重新应用自己的改动原则上尽量避免改动框架文件确需修改时采用“最小改动”策略。一个官方推荐的实践如果你想改 Webpack 配置不要直接编辑webpack.config.js而是新建一个独立的 JavaScript 文件并在webpack.config.js中引入它webpack.config.js头部注释也明确建议这一做法这样更新时只需恢复那一条引入语句。GENERATOR_DOC.md模板自带的生成器说明位于示例目录下还补充更新命令会尝试合并package.json和.gitignore的变更而非直接覆盖并且会保留/src与README.md不动真正的风险点集中在webpack.config.js的覆盖上。七、发布插件进入官方插件仓库的条件GENERATOR_DOC.md说明了插件发布到 Joplin 官方插件仓库需要满足的条件package.json中的包名以joplin-plugin-开头如joplin-plugin-tocpackage.json的keywords中包含joplin-pluginpublish/目录中存在.jpl与.json文件由npm run dist构建产生。以上条件一般由生成器自动设置但排查插件未出现在仓库时可按此清单复核。webpack.config.js中的validatePackageJson()函数会在每次构建时检查前两条若不满足会打印黄色警告若package.json中存在postinstall脚本也会警告建议改用prepare脚本以便在发布前执行。.json插件信息文件还会写入_publish_hashJPL 文件的 SHA-256 摘要与_publish_commit当前 Git 分支与提交供仓库侧校验产物一致性。八、本地体验与进一步阅读想亲手运行这个示例可以按以下方式查看与测试阅读完整演示源码src/index.ts对照 API 声明逐方法学习api/JoplinSettings.d.ts 与 api/types.ts在示例目录执行npm install后运行npm run dist即可在publish/得到可安装的.jpl文件将构建出的.jpl通过 Joplin 的“工具 → 选项 → 插件 → 安装插件”载入即可在配置屏幕看到 “My Custom Section” 分区及其 7 个设置项并可通过两个工具栏按钮体验设置读写若需要底层行为佐证可查阅 Setting.ts设置模型的存储与校验实现与 Setting.test.ts对数据库/文件两种存储方式的测试覆盖。简而言之这个设置插件示例完整展示了 Joplin 插件中“注册配置界面 → 持久化设置值 → 通过命令与工具栏交互”的标准开发路径配合官方生成器yo 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），仅供参考