Obsidian 插件开发

使用 obsidian-sample-plugin-plus 模板构建可用于生产环境的 Obsidian 插件。

快速开始：新建插件

1. 从模板创建

bash

克隆模板（或使用 GitHub 的 Use this template 按钮）

或直接克隆

2. 配置插件标识

使用插件信息更新以下文件：

manifest.json：
json
{
id: my-plugin,
name: My Plugin,
version: 0.0.1,
minAppVersion: 1.5.0,
description: 插件功能描述,
author: 你的名字,
authorUrl: https://你的网站.com,
isDesktopOnly: false
}

package.json： 更新 name、description、author、license。

README.md： 将模板内容替换为插件的文档。

3. 初始化开发环境

bash
pnpm install
pnpm obsidian-dev-skills # 初始化 AI 技能
./scripts/setup-ref-links.sh # Unix 系统

或：scripts\setup-ref-links.bat # Windows 系统

4. 清理样板代码

在 src/main.ts 中：

• - 移除示例的 ribbon 图标、状态栏、命令、模态框和 DOM 事件
• 根据需要保留或移除设置选项卡
• 将 MyPlugin 类重命名为你的插件名称

如果插件不需要自定义样式，删除 styles.css。

开发工作流

构建与测试

bash
pnpm dev # 监听模式——修改后自动重新构建
pnpm build # 生产构建
pnpm lint # 检查问题
pnpm lint:fix # 自动修复问题
pnpm test # 运行单元测试

在 Obsidian 中安装

将构建输出复制到你的 vault：
bash

Unix 系统

或创建符号链接用于开发

在 Obsidian 设置 → 社区插件中启用该插件。

使用 Hot Reload 插件实现开发过程中的自动重载。

插件架构

入口点（src/main.ts）

typescript
import { Plugin } from obsidian;

export default class MyPlugin extends Plugin {
settings: MyPluginSettings;

async onload() {
await this.loadSettings();
// 注册命令、ribbon、事件、视图
}

onunload() {
// 清理：移除事件监听器、视图、DOM 元素
}

async loadSettings() {
this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
}

async saveSettings() {
await this.saveData(this.settings);
}
}

设置模式

完整的设置 UI 模式请参见 references/settings.md。

常见模式

请参见 references/patterns.md 了解：

• - 命令（简单、编辑器、检查回调）
• Ribbon 图标
• 模态框
• 事件与生命周期
• 文件操作
• 编辑器操作

约束条件

• - 无自动 git：未经明确批准，绝不运行 git commit 或 git push
• 无 eslint-disable：正确修复 lint 问题，不要抑制它们
• 无 any 类型：使用正确的 TypeScript 类型
• 句子大小写：UI 文本使用句子大小写（ESLint 可能对此产生误报——忽略即可）

发布清单

1. 1. 更新 manifest.json 和 package.json 中的版本号
2. 使用 version: minAppVersion 更新 versions.json
3. 运行 pnpm build——零错误
4. 运行 pnpm lint——零问题
5. 创建与版本号匹配的 GitHub 发布标签（不带 v 前缀）
6. 上传：main.js、manifest.json、styles.css（如果使用）

参考资料

• - 设置 UI —— 完整的设置选项卡实现
• 常见模式 —— 命令、模态框、事件、文件操作
• Obsidian API 文档 —— 官方文档