obsidian-plugin

obsidian-plugin — Obsidian 插件开发技能

关键词：obsidian plugin · create obsidian plugin · obsidian eslint · obsidian submission

构建高质量的 Obsidian 插件，力求一次通过社区审核。 涵盖 eslint-plugin-obsidianmd v0.1.9 的全部 27 条规则、样板代码生成、 vault API 模式、无障碍要求和提交验证。

何时使用此技能

• 生成全新的 Obsidian 插件项目，并使用精简的样板代码（不包含臃肿的示例代码）
• 检查并修复 eslint-plugin-obsidianmd 的 ESLint 违规项
• 为插件提交到 Obsidian 社区目录做好准备
• 应用内存安全的生命周期模式（registerEvent，不存储视图引用）
• 实现恰当的类型安全（不使用不安全的 as TFile 类型断言，也不使用 any）
• 满足无障碍要求（键盘导航、ARIA 标签、焦点管理）
• 使用 Obsidian CSS 变量，确保样式兼容主题
• 验证插件元数据（manifest.json、插件 ID/名称/描述规则）

---

指南

步骤 1：生成新的插件项目

# Interactive boilerplate generator — validates metadata against submission rules
node scripts/create-plugin.js

# Or use npx directly from the source repo
npx github:gapmiss/obsidian-plugin-skill create-plugin

生成器会创建：

• src/main.ts — 集成设置的插件类
• src/settings.ts — 设置接口和 PluginSettingTab
• manifest.json — 通过验证的插件元数据
• styles.css — 包含 Obsidian 变量注释的 CSS 框架
• tsconfig.json、package.json、esbuild.config.mjs — 构建工具链
• version-bump.mjs、versions.json — 版本管理
• LICENSE — MIT 许可证，自动填入年份和作者

步骤 2：安装 ESLint 验证工具

npm install --save-dev eslint eslint-plugin-obsidianmd

// eslint.config.mjs
import pluginObsidianmd from "eslint-plugin-obsidianmd";
export default [
  pluginObsidianmd.configs.recommended,
  // For locale string checking:
  // pluginObsidianmd.configs.recommendedWithLocalesEn,
];

运行验证：

npx eslint src/
npx eslint src/ --fix   # auto-fix where possible

步骤 3：遵循提交验证工作流

1. 运行 bash scripts/install.sh，设置开发环境
2. 根据命名规则验证插件 ID 和名称（见下文）
3. 运行 ESLint — 必须通过全部 27 条规则
4. 完成代码审查清单（参见参考资料）
5. 向 obsidianmd/obsidian-releases 提交 PR

---

插件命名规则

字段	规则
插件 ID	使用小写字母、数字以及连字符/下划线；不得包含 "obsidian"；不得以 "plugin" 为后缀
插件名称	不得包含 "Obsidian"；不得以 "Plugin" 为后缀；不得以 "Obsi" 为前缀或以 "dian" 为后缀
描述	不得包含 "Obsidian" 或 "This plugin"；必须以 ., ?, ! 或 ) 结尾

# Validate your manifest.json
node scripts/create-plugin.js --validate-only

---

ESLint 规则摘要（27 条规则）

提交与命名

规则	自动修复	描述
no-obsidian-in-id	否	插件 ID 不得包含 "obsidian"
no-plugin-suffix-in-id	否	插件 ID 不得以 "-plugin" 结尾
no-obsidian-in-name	否	插件名称不得包含 "Obsidian"
no-plugin-suffix-in-name	否	插件名称不得以 "Plugin" 结尾
valid-description	否	描述格式验证

内存与生命周期

规则	自动修复	描述
prefer-register-event	否	使用 this.registerEvent() 自动清理
no-view-reference	否	切勿存储直接的视图引用（会导致内存泄漏）

类型安全

规则	自动修复	描述
no-tfile-cast	否	避免使用 as TFile / as TFolder（改用 instanceof）

UI/UX（句首字母大写规则 — 大多可自动修复）

规则	自动修复	描述
sentence-case	是	所有 UI 文本均使用句首字母大写格式
no-plugin-name-in-command	否	命令中不得重复插件名称
no-command-in-command	否	命令中不得包含单词 "command"
no-default-hotkey	否	不要定义默认快捷键
no-manual-headings	否	设置 UI：使用 setHeading()，不要手写 HTML

API 最佳实践

规则	自动修复	描述
no-global-app	否	使用 this.app，不要使用全局 app
prefer-request-url	否	使用 requestUrl()，不要使用 fetch()
no-console-log	否	提交前移除 console.log
prefer-abstract-input-suggest	否	使用 AbstractInputSuggest 提供建议

样式

规则	自动修复	描述
no-inline-styles	否	使用 CSS 类；不要使用内联 style 属性
prefer-css-variables	否	使用 Obsidian CSS 变量，不要使用硬编码颜色
scope-plugin-styles	否	所有 CSS 都必须限定在插件 ID 选择器内

无障碍（必需）

规则	自动修复	描述
require-aria-label	否	图标按钮必须具有 aria-label
require-keyboard-nav	否	所有交互都必须支持键盘操作
require-focus-visible	否	使用 :focus-visible CSS 显示焦点指示器

---

关键代码模式

内存安全的事件注册

// ✅ Correct — auto-cleaned on plugin unload
this.registerEvent(
  this.app.vault.on('create', (file) => this.handleCreate(file))
);

// ❌ Wrong — leaks memory
this.app.vault.on('create', (file) => this.handleCreate(file));

类型安全的文件访问

// ✅ Correct — instanceof narrowing
const file = this.app.workspace.getActiveFile();
if (file instanceof TFile) {
  await this.app.vault.read(file);
}

// ❌ Wrong — unsafe cast
const file = this.app.workspace.getActiveFile() as TFile;

无障碍 — 图标按钮上的 ARIA

// ✅ Correct
const btn = containerEl.createEl('button', { cls: 'clickable-icon' });
btn.setAttribute('aria-label', 'Delete note');
setIcon(btn, 'trash');

// ❌ Wrong — no aria-label
const btn = containerEl.createEl('button', { cls: 'clickable-icon' });
setIcon(btn, 'trash');

使用 Obsidian 变量的 CSS

/* ✅ Correct — theme-compatible */
.my-plugin-button {
  background-color: var(--interactive-accent);
  color: var(--text-on-accent);
  border-radius: var(--radius-m);
}

/* ❌ Wrong — hardcoded colors */
.my-plugin-button {
  background-color: #7c3aed;
  color: white;
}

---

快速参考

任务	命令
生成样板代码	node scripts/create-plugin.js
安装 ESLint	npm install --save-dev eslint eslint-plugin-obsidianmd
运行 ESLint	npx eslint src/
自动修复 ESLint	npx eslint src/ --fix
构建插件	npm run build
开发监听模式	npm run dev
更新版本号	npm run version

---

参考资料

• 无障碍指南 — 键盘导航、ARIA、焦点管理（必需）
• 代码质量指南 — 安全性、平台兼容性、API 使用
• CSS 样式指南 — Obsidian 变量、作用域样式、深色/浅色模式
• 文件操作指南 — Vault API、编辑器与 Vault、原子操作
• 内存管理指南 — registerEvent、生命周期模式
• 提交指南 — 仓库结构、命名、提交流程
• 类型安全指南 — instanceof 类型收窄、禁止使用 any、const/let
• UI/UX 指南 — 句子大小写、命令、设置结构
• eslint-plugin-obsidianmd — 官方 ESLint 规则
• Obsidian 插件开发者文档
• 源技能仓库 — MIT 许可证