思源笔记插件开发指南

插件基础

欢迎来到思源笔记插件开发的世界！插件允许你扩展和定制思源笔记的功能，以满足个性化的需求或构建全新的工作流。

以下是插件开发的基础知识点：

现在你已经对思源插件的基础和加载流程有了清晰的认识，接下来我们将深入探讨核心 API 的使用。

什么是思源插件？

思源插件是使用 TypeScript (或 JavaScript) 编写的代码包，它们可以：

添加新的用户界面元素: 在顶栏、状态栏添加按钮，创建自定义菜单、设置页面、停靠栏面板，甚至全新的标签页。
注册新的命令和快捷键: 让用户可以通过命令面板或快捷键执行你的插件功能。
与思源数据交互: 读取和修改笔记内容、属性、标签，管理笔记本和文档结构。
调用思源核心功能: 利用思源提供的 API 实现如搜索、导入导出、文件处理等操作。
监听和响应应用事件: 对应用内的特定事件（如打开文档、点击块图标）作出反应。
集成外部服务: 连接其他应用程序或 Web 服务。

插件的基本结构

一个典型的思源插件项目，在开发完成后通常包含以下文件和目录：

plugin.json (必需): 插件的"身份证"，定义了插件的名称 (name)、版本 (version)、作者 (author)、描述 (description)、显示名称 (displayName)、兼容的思源最低版本 (minAppVersion)、图标 (icon) 等重要信息。思源后端服务会读取它来了解你的插件。
index.ts (或你的入口 TS 文件): 这是你编写插件功能的主要地方，通常包含一个继承自思源 Plugin 基类的类。你需要将它编译成 JavaScript。
dist/index.js (必需，编译后生成): 由你的 index.ts 编译打包而来的 JavaScript 文件。思源后端会直接读取这个文件的内容，然后发送给前端执行。
dist/index.css (可选，编译后生成): 如果你的插件需要自定义样式，将 CSS 代码打包到这里。思源后端会读取这个文件的内容 (如果存在)，然后发送给前端注入页面。
icon.png (推荐): 插件在集市或设置里显示的图标。
README.md (推荐): 详细介绍插件功能、用法和配置的文档。
i18n/ (可选): 存放多语言文件的目录 (如 zh_CN.json)。后端也会读取对应的语言文件。

关键点: 思源加载插件时，后端服务会直接读取你插件目录下的 plugin.json、dist/index.js、dist/index.css (如果存在) 以及 i18n/ 目录下的语言文件。前端并不直接访问这些文件。

json

// plugin.json 示例 (字段可能不完全准确，需参考官方文档或示例)
{
  "name": "my-cool-plugin",
  "displayName": {
    "default": "My Cool Plugin",
    "zh_CN": "我的酷炫插件"
  },
  "author": "Your Name",
  "version": "0.1.0",
  "minAppVersion": "2.10.0",
  "description": {
    "default": "This plugin does something cool.",
    "zh_CN": "这个插件能做一些很酷的事情。"
  },
  "frontend": "dist/index.js", // 通常指向编译后的 JS 入口
  "icon": "icon.png",
  "readme": "README.md",
  "i18n": [
    "en_US",
    "zh_CN"
  ]
}

插件生命周期

思源插件有明确定义的生命周期方法，你可以在你的插件类中重写它们来执行特定任务：

constructor(): 插件实例被创建时调用。通常在这里初始化插件的基本属性。
onload(): 插件被加载和启用时调用。这是执行主要初始化逻辑（如注册命令、添加 UI 元素、设置监听器）的最佳位置。
onLayoutReady(): 当思源的整体界面布局加载完成后调用。如果你需要在思源完全渲染后才能执行某些操作（比如操作特定的 DOM 元素），可以在这里进行。
onunload(): 插件被禁用或思源关闭时调用。你需要在这里清理你的插件添加的所有资源，比如移除监听器、清除定时器、移除添加的 UI 元素，以避免内存泄漏或意外行为。
uninstall(): (如果提供) 插件被卸载前调用，用于执行最后的清理工作。

开发环境准备

开发思源插件通常需要：

Node.js 和 npm/pnpm/yarn: 用于管理依赖和运行脚本。
TypeScript: 思源插件推荐使用 TypeScript 编写，提供类型安全和更好的开发体验。
打包工具: 如 esbuild, webpack 或 rollup，将你的 TypeScript 代码编译并打包成浏览器可执行的 JavaScript 文件。
思源笔记: 你需要安装思源笔记本体来进行测试。

加载与调试插件

理解插件如何被加载有助于调试：

放置插件: 将你开发和打包好的插件文件夹（确保包含 plugin.json 和 dist/ 目录及里面的 index.js、可选的 index.css）完整地复制到思源工作空间下的 data/plugins/ 目录中。
后端处理: 当思源启动或你启用插件时，前端会请求后端 API /api/petal/loadPetals。思源后端服务会执行以下操作：
- 读取 data/storage/petal/petals.json 确认哪些插件是启用的。
- 对于启用的插件，读取其目录下的 plugin.json 获取元数据。
- 直接读取 dist/index.js 文件的全部内容。
- 如果 dist/index.css 文件存在，直接读取其全部内容。
- 读取 i18n/ 下的语言文件内容。
- 将插件的元数据、完整的 JS 代码字符串、CSS 代码字符串和 i18n 数据打包，通过 API 返回给前端。
- (注意：虽然我们已确认后端会返回 JS/CSS，但链接的后端 API 文档 /kernel-api/petal/loadPetals.md 可能尚未更新以反映这一点)
前端执行: 前端接收到数据后：
- 使用 eval 执行后端传来的 JS 代码字符串。这会实例化你的插件类并调用 onload()。
- 将后端传来的 CSS 代码字符串 注入到页面样式中。
布局就绪: 当界面布局完成后，前端会调用插件的 onLayoutReady() 方法，并将之前注册的顶栏、状态栏、Dock 等 UI 元素显示出来。

调试步骤:

开启开发者模式: 在思源的设置中找到"集市"相关选项，开启"开发者模式"。
修改与重载: 修改插件代码后，你需要重新编译打包（更新 dist/ 目录下的文件），然后在思源的插件设置里禁用再重新启用你的插件，或者直接重启思源，才能加载最新的代码。
开发者工具: 在思源界面右下角找到菜单按钮 (通常是一个问号 ? 图标)，点击后选择 "开发者工具" 来打开。利用 Console 查看日志和错误，利用 Sources 设置断点调试 (需要配置好 Source Maps)。

现在你已经对思源插件的基础和加载流程有了清晰的认识，接下来我们将深入探讨核心 API 的使用。

思源笔记插件开发指南 ​

插件基础 ​

什么是思源插件？ ​

插件的基本结构 ​

插件生命周期 ​

开发环境准备 ​

加载与调试插件 ​