Obsidian插件开发指南
Obsidian 插件开发环境搭建
-
首先安装 Node.js（JavaScript 运行时环境）和常用的开发工具（例如 VSCode）。为防止数据丢失，不要在主 Vault 中开发插件，应创建一个专用的空 Vault用于测试。
-
获取插件模板：可以使用 Obsidian 官方的 Sample Plugin（基于 TypeScript）作为起点，也可以使用社区提供的纯 JavaScript 模板。例如，beardicus 提供的 obsidian-simple-sample-plugin 示例无需使用 TypeScript 即可开发。克隆模板到开发目录时，建议将其放在你的 Vault 的
.obsidian/plugins/你的插件ID/目录下。 -
安装依赖：在插件项目根目录下运行
npm install以安装所需依赖。对于纯 JS 模板，不需要进行编译，也不需要npm run dev；只需将代码直接写入main.js。建议安装 Obsidian 社区插件 “Hot Reload” 来自动检测代码变化并重载插件。
提示： 插件开发时可使用
console.log()或 Obsidian 的new Notice()在开发者控制台输出调试信息，并可通过 开发者工具（Ctrl+Shift+I）查看报错日志。
插件文件结构说明
在 .obsidian/plugins/你的插件ID/ 文件夹中，至少需要以下文件：
-
manifest.json：插件清单，包含id、name、version、minAppVersion、description、author等字段。注意：本地开发时，id字段需与插件文件夹名相同，否则某些功能（如外部设置更改事件）可能无法正常触发。 -
main.js：插件主脚本，用于实现功能逻辑。纯 JavaScript 模板直接编辑此文件，无需构建步骤。 -
styles.css（可选）：用于存放插件的样式表（例如自定义侧边栏图标、弹窗样式等）。 -
其余文件：可根据需要添加，例如
data.json（存储插件配置信息）等。
示例 manifest.json 结构：
{
"id": "translate-plugin",
"name": "Text Translator",
"version": "1.0.0",
"minAppVersion": "0.9.12",
"description": "Translate selected English text to Chinese.",
"author": "Your Name",
"authorUrl": "https://your.website",
"fundingUrl": "",
"js": "main.js"
}将以上文件放在同一个名为 translate-plugin 的文件夹下，并复制到 Vault 的 .obsidian/plugins/ 目录即可。
编写插件主文件 main.js
下面给出一个示例 main.js，展示如何获取选中文本并调用翻译 API，将结果替换回编辑器。代码包含完整注释，便于理解和调试。
module.exports = class TranslatePlugin extends Plugin {
async onload() {
// 在加载时注册一个命令到命令面板，使用快捷键或命令面板触发翻译
this.addCommand({
id: 'translate-selection',
name: '翻译选中文本',
// 使用 editorCallback 以便获取当前编辑器实例
editorCallback: async (editor, view) => {
// 获取当前选中文本
const selected = editor.getSelection();
if (!selected) {
// 如果没有选中任何文本，给出提示
new Notice("请先选中文本再翻译");
return;
}
// 调用翻译 API（示例使用 LibreTranslate 的公开服务）
try {
const res = await fetch("https://translate.argosopentech.com/translate", {
method: "POST",
body: JSON.stringify({
q: selected, // 待翻译文本
source: "en", // 源语言：英文
target: "zh", // 目标语言：简体中文
format: "text"
}),
headers: { "Content-Type": "application/json" }
});
const data = await res.json();
const translated = data.translatedText;
// 将翻译结果替换掉原选中的文本:contentReference[oaicite:13]{index=13}
editor.replaceSelection(translated);
}
catch (error) {
// 出现错误时提示用户，并打印到控制台
new Notice("翻译失败：" + error.message);
console.error(error);
}
}
});
// 注册右键菜单，在编辑器中选中文本后右键可见此选项:contentReference[oaicite:14]{index=14}
this.registerEvent(this.app.workspace.on("editor-menu", (menu, editor, view) => {
menu.addItem(item => {
item
.setTitle("翻译为中文")
.onClick(async () => {
const selected = editor.getSelection();
if (!selected) {
new Notice("请先选中文本再翻译");
return;
}
try {
const res = await fetch("https://translate.argosopentech.com/translate", {
method: "POST",
body: JSON.stringify({
q: selected,
source: "en",
target: "zh",
format: "text"
}),
headers: { "Content-Type": "application/json" }
});
const data = await res.json();
const translated = data.translatedText;
editor.replaceSelection(translated);
}
catch (error) {
new Notice("翻译失败：" + error.message);
console.error(error);
}
});
});
}));
}
onunload() {
// 可在此处执行插件卸载时的清理操作（如移除事件等）
}
}代码说明： 上例使用 editor.getSelection() 获取选中文本，然后通过 fetch 请求 LibreTranslate（开源翻译 API）实现翻译。注意将 editorCallback 和菜单的回调函数都声明为 async，以便使用 await 处理异步请求。在得到翻译结果后，用 editor.replaceSelection(translated) 方法替换选中的文本。如果希望在原文后插入翻译结果而不删除原文，可改用 editor.replaceRange() 或先读取原文再拼接后插入；此处示例以直接替换为主。
插件打包与加载
完成开发后，将插件文件夹部署到你的 Vault 中：
-
打包：由于使用纯 JS，无需特殊构建步骤。确保
manifest.json和main.js（以及可选的styles.css等）位于同一文件夹下。 -
复制到 Vault：将整个插件文件夹（文件名应与
manifest.json中的id相同）复制到 Vault 根目录下的.obsidian/plugins/文件夹中。 -
加载插件：重启 Obsidian 或在设置中刷新插件页面，然后在 设置 → 社区插件 中启用你的插件。如果是克隆了官方样例仓库，可先运行
npm run dev生成最终的main.js（但对于纯 JS 模板，这一步可省略）。
提示： 如果修改了插件代码，可使用 “Hot Reload” 插件自动重载，或手动在 Obsidian 中停用再启用插件来加载最新代码。
