插件开发补充

什么是插件？

插件是一种第三方应用程序，可让您根据自己的喜好扩展或修改 Obsidian。 通过构建插件，您可以：

• 扩展或修改用户界面。
• 中编辑文件和文件夹 在您的Vault 。
• 改进 编辑器 以获得更好的笔记体验。

要查看插件的外观，请查看 插入链接 示例。

插件生命周期

• onload()每当用户开始使用 Obsidian 中的插件时运行。 您将在此处配置插件的大部分功能。
• onunload()当插件被禁用时运行。 您的插件正在使用的任何资源都必须在此处释放，以避免在您的插件被禁用后影响 Obsidian 的性能。

命令 addCommand

import { Plugin } from "obsidian";

export default class ExamplePlugin extends Plugin {
  async onload() {
    this.addCommand({
      id: "print-greeting-to-console",
      name: "Print greeting to console",
      callback: () => {
        console.log("Hey, you!");
      },
    });
  }
}

条件命令 checkCallback

如果您的命令只能在特定条件下运行，请考虑使用 checkCallback反而。

这 checkCallback运行两次。 首先，执行初步检查以确定命令是否可以运行。 二是执行动作。

由于两次运行之间可能会经过时间，因此您需要在两次调用期间执行检查。

要确定回调是否应执行初步检查或操作，一个 checking参数传递给回调。

• 如果 checking被设置为 true, 进行初步检查。
• 如果 checking被设置为 false, 执行一个动作。

以下示例中的命令取决于所需的值。 在两次运行中，回调检查值是否存在，但仅在以下情况下执行操作 checking是 false.

this.addCommand({
  id: 'example-command',
  name: 'Example command',
  checkCallback: (checking: boolean) => {
    const value = getRequiredValue();

    if (value) {
      if (!checking) {
        doCommand(value);
      }

      return true
    }

    return false;
  },
});

Editor命令

如果您的命令需要访问编辑器，您还可以使用 editorCallback，它提供活动编辑器及其视图作为参数

this.addCommand({
  id: 'example-command',
  name: 'Example command',
  editorCallback: (editor: Editor, view: MarkdownView) => {
    const sel = editor.getSelection()

    console.log(`You have selected: ${sel}`);
  },
}

热键

在此示例中，用户可以通过同时按住 Ctrl（或 Mac 上的 Cmd）和 Shift，然后按下字母来运行命令 a在他们的键盘上。

this.addCommand({
  id: 'example-command',
  name: 'Example command',
  hotkeys: [{ modifiers: ["Mod", "Shift"], key: "a" }],
  callback: () => {
    console.log('Hey, you!');
  },
});

库 vault

官方文档 来自有关使用多个 Vault ：

Obsidian 中的每个笔记集合都称为 Vault。 保管库由一个文件夹和其中的所有子文件夹组成。

虽然您的插件可以像任何其他 Node.js 应用程序一样访问文件系统，但 Vault模块旨在使在 Vault 中处理文件和文件夹变得更加容易。

以下示例递归打印 Vault 中所有 Markdown 文件的路径：

const files = this.app.vault.getMarkdownFiles()

for (let i = 0; i < files.length; i++) {
  console.log(files[i].path);
}

TIPS

如果要列出 所有 文件，而不仅仅是 Markdown 文档，请使用 getFiles()反而。

读取文件

读取文件内容有两种方法： read()和 cachedRead().

• 如果只想向用户显示内容，则使用 cachedRead()避免多次从磁盘读取文件。
• 如果要读取内容，更改它，然后将其写回磁盘，则使用 read()以避免可能用陈旧的副本覆盖文件。

信息

之间的唯一区别 cachedRead()和 read()是在插件读取文件之前在 Obsidian 外部修改文件的时间。 一旦文件系统通知黑曜石文件已从外部更改， cachedRead()行为 完全 一样 read(). 同样，如果您将文件保存在 Obsidian 中，读取缓存也会被刷新。

以下示例读取 Vault 中所有 Markdown 文件的内容并返回平均文档大小：

执行顺序

执行顺序（从上到下依次执行）

// async onload() {}
// async onload() {} > this.app.workspace.onLayoutReady(() => {});
// ViewPlugin.fromClass(class {constructor(view: EditorView) {}}) // 执行多次，每个已经被打开的文档都会执行一次
// ...
// onunload() {}