Obsidian 插件：Tag Wrangler

概述

从标签面板重命名、合并、切换和搜索标签。

Readme(翻译）

下面是 tag-wrangler 插件的自述翻译

Obsidian 标签管理插件

该插件为 Obsidian.md 标签窗格添加了一个上下文菜单，提供以下操作：

• 打开或创建 标签页面（0.5.0 版本新增）
• 重命名标签（以及其所有子标签）
• 开始对该标签进行新的搜索（类似于普通点击）
• 将标签添加为当前搜索的要求（tag:#whatever）
• 将标签添加为当前搜索的排除项（-tag:#whatever）
• 打开具有该标签的随机笔记（如果您已安装并启用了 Smart Random Note 插件）
• 折叠标签窗格中同一级别的所有标签
• 展开标签窗格中同一级别的所有标签

根据搜索和标签窗格的当前状态，某些操作可能不可用（例如，只有在标签窗格显示层次结构标签时才可用展开和折叠）。

请注意：重命名标签可能是一个不可逆的操作：在开始重命名之前，您可能希望备份您的数据。有关更多信息，请参阅下面的 重命名标签 部分。

安装

在 Obsidian 的社区插件界面中搜索“tag wrangler”，或者 点击这里 在最近使用的 vault 中打开它。（然后选择“安装”和“启用”。）

此外，请确保您已经在 vault 的配置的“核心插件”部分启用了“Tag Pane”插件。该插件会为该插件提供的面板添加上下文菜单，并且没有自己的用户界面。

标签页面

人们经常辩论使用标签还是页面链接来组织笔记的优点。通过标签页面，您可以兼具标签的可见性和流畅输入以及页面的集中内容和外部链接。

要创建标签页面，只需右键单击标签窗格中的任何标签，然后选择“创建标签页面”。将创建一个带有所选标签别名的新笔记。您可以重命名笔记或将其移动到存储库中的任何位置，只要保留别名将其链接到标签即可。（重命名与标签页面关联的标签（参见下文的“重命名标签”）将自动更新别名。）

要打开现有标签页面，可以在标签窗格或任何笔记中使用 Alt + 单击，无论是在编辑视图还是阅读视图中。Ctrl / Cmd + 单击或中键单击将在新窗格中打开标签页面。（注意：如果不存在标签页面，则将应用全局搜索标签的正常单击行为。）

或者，您可以在 Obsidian 的“快速切换器”中输入标签的名称（默认热键：Ctrl / Cmd-O）以从键盘打开页面。您还可以在标签窗格或任何 Markdown 视图中悬停预览任何标签，以弹出标签页面的预览。

（如果您不熟悉悬停预览，基本思想是在 Obsidian 中，通过按住 Ctrl / Cmd 键并将鼠标指针移动到 Obsidian 中的项目上，通常会弹出一个带有相关页面小版本的弹出窗口。如果您喜欢只悬停而不使用 Ctrl / Cmd 键，您还可以进入内置的“页面预览”插件的设置，并选择性地禁用使用 Ctrl / Cmd 键的需求。Tag Wrangler 尊重您在编辑器和预览视图中悬停链接的现有设置，并为“标签窗格”添加了一个额外的设置，用于控制在标签窗格中悬停标签时是否需要 Ctrl / Cmd 键。）

Tag Wrangler 目前不支持自动将标签引用转换为页面链接或反之亦然，但在将来的版本中可能会支持。然而，在此期间，您可以使用 Obsidian 的反向链接来查找并更改标签页面中的此类引用。具体来说，查看标签页面的“未链接提及”将显示使用该标签的所有位置以及您可以使用的“链接”按钮将它们转换为页面链接。（将页面链接转换为标签需要手动编辑。）

手动创建和管理标签页面

您不必使用“创建标签页面”菜单命令来创建标签页面：只要页面具有标签作为有效的 Obsidian 别名，任何页面（甚至看板或 Excalidraw 绘图）都可以成为标签页面。您可以通过以下两种方式验证特定页面是否具有有效的别名：

• 打开 Obsidian 快速切换器（默认为 Ctrl/Cmd-O），然后输入 # 后跟标签名称：页面应该显示出标签作为别名
• 将笔记切换到预览模式，并查看元数据框顶部的“别名”是否包含标签的形状（前面带有箭头和 #）

如果它在上述任何位置都没有显示出来，那么很可能您的笔记元数据在某种方式上存在语法错误。Obsidian 识别名为 Alias 或 Aliases（不区分大小写）的第一个字段，并期望它是一个由逗号分隔的别名字符串或字符串的 YAML 列表。为了被识别为标签别名，字符串或字符串必须被引用。以下是一些包含标签的别名或别名字段的有效示例，每个示例都会导致该笔记被视为 #some/tag 的标签页面：

---
Alias: "#some/tag"
---
Aliases: [ "#some/tag", "another alias" ]
---
alias:
  - some alias
  - "#some/tag"
  - another alias
---
aliases: "some alias, #some/tag, another alias"
---

请注意，每个项目都必须被引用并且位于有效的 YAML 列表（[ ] 或带有 - 的行）中，或者整个别名集合应该被引用并用逗号分隔。标签别名也不能包含任何空格或其他文本。

当标签被重命名时，标签管理器将自动更新别名。您还可以手动编辑或删除别名以断开标签页面的连接，添加其他标签（以防您希望多个标签共享同一页），或更改页面所属的标签。

最后，请注意，您可以将相同的别名添加到多个笔记中，但在这种情况下，标签管理器将从可用选项中随机选择标签页面。要解决此问题，请使用快速切换器搜索具有该别名的笔记（即通过键入 # 和标签名称），然后从不想用作标签页面的笔记中删除别名（或别名）。

重命名标签

与重命名笔记类似，重命名标签涉及对所有引用它们的文件进行替换。为了确保只有实际的标签被重命名，Tag Wrangler 使用 Obsidian 自己的解析数据来识别标签的位置。这样，如果你有一个类似 [foo](#bar) 的 Markdown 链接，它不会将 #bar 视为 #bar 标签的一个实例。

因为标签只存在于包含它们的文件中，某些重命名操作是不可逆转的。例如，如果你将 #foo 重命名为 #bar，而你已经有一个 #bar 标签，那么之后将无法确定哪些文件最初包含 #foo，哪些包含 #bar，除非查看备份或某种形式的修订控制。

因此，Tag Wrangler 会提前检查是否以一种将任何标签与现有标签合并的方式重命名标签，并要求额外的确认，警告缺乏撤销功能。（并不是说任何重命名都是可撤销的，只是如果没有发生合并，你通常可以将标签重新命名为旧名称！）

如果你正在使用某种类型的后台同步（例如 Dropbox、GDrive、Resilio 等），并且在 Tag Wrangler 进行重命名时导致任何文件发生更改，Tag Wrangler 可能会跳过已更改的文件，导致部分重命名。通常，重复相同的重命名选项应该可以完成进程，但在合并的情况下，你可能需要更加小心。（最好确保在开始任何重命名操作之前，确保所有同步操作已完成。）

如果需要更改的文件很多，或者重命名过程进行得很慢，将显示一个进度对话框，让你选择中止重命名过程。这不会撤销之前所做的更改，只会停止进一步的更改。

带有子标签的标签

Obsidian 允许使用 #x/y/z 形式的层次标签。当您重命名父标签（如 #x/y）时，所有子标签也将被重命名。

例如，如果您将 #x/y 重命名为 #a/b，那么之前命名为 #x/y/z 的标签将被重命名为 #a/b/z。（除了逐个重命名所有子标签以将它们移动到另一个父标签下之外，没有办法仅重命名父标签。）

如果您想重构标签层次结构，请注意您可以将标签及其子标签重命名为具有更多或更少路径部分。也就是说，您可以将 #x/y 重命名为 #x，然后您的 #x/y/z 标签将变为 #x/z。或者相反，您可以将 #x/y 重命名为 #letters/x/y，这将使 #x/y/z 移动到 #letters/x/y/z。

有许多可能性可供重构标签。在开始之前，请务必备份，跟踪您所做的更改，并在同步或提交更改之前检查结果。

元数据/前置内容

Obsidian 允许通过 YAML 前置内容将标签指定为笔记的元数据的一部分。Tag Wrangler 将尝试重命名这些标签以及在笔记正文中找到的标签。

在大多数情况下，这不会引起任何问题。然而，如果您使用高级 YAML 功能来指定标签（YAML 别名或块标量），则有两点需要注意。

首先，如果您使用 YAML 块标量 (< 或 |) 来指定标签，重命名标签可能会影响标签字段的缩进、间距或换行。其次，如果您在标签列表中使用 YAML 别名 (*)，重命名别名标签将会在原地展开别名，而不是更改定义别名的锚点。

缩进问题已经报告给上游库，希望将来能有某种解决方案。对于别名，当前行为是有意选择的，以避免更改元数据中的非标签值。因此，如果您使用这些更高级的 YAML 功能之一，您应该在进行全库重命名之前在一个临时笔记中尝试一些虚假标签。

大小写不敏感

Tag Wrangler 在匹配要更改的标签和检查冲突时使用与 Obsidian 相同的大小写不敏感比较。但请注意，由于 Obsidian 使用标签的第一个出现来确定在标签窗格中如何显示它，因此重命名标签时如果没有一致的大小写使用，可能会导致标签窗格中“其他”标签名称的表面更改。

假设您有一个名为 #foo/bar 的标签，并将 #foo 重命名为 #Bar/baz。但与此同时，您已经有一个名为 #bar/bell 的标签。这可能会导致您现在在标签窗格中看到该标签显示为 #Bar/bell，即使 Tag Wrangler 实际上没有替换任何现有的 #bar/bell 标签！（如果您搜索它们，您将看到这一点。）

相反，如果 #Bar/baz 标签是 Obsidian 在生成标签窗格时遇到的以 bar 某种变体开头的第一个标签，就会发生这种情况。Obsidian 只使用特定大小写的第一个遇到的字符串作为标签的“显示名称”，然后将所有后续出现视为相同的标签。

这只是 Obsidian 标签的工作方式，而不是 Tag Wrangler 可以解决的问题。但是，您可以通过将任何以“错误”大小写命名的内容重命名为“正确”大小写来轻松解决此问题。这意味着（与 Obsidian 中已经存在的情况相同），您不能在标签窗格中显示同一标签名称的多个大小写，并且现在您可以根据需要轻松重命名标签以保持一致的大小写。

开发者笔记

Tag Wrangler 在 app.workspace 上触发以下事件，这些事件可能对与其他插件的集成有用：

tag-wrangler:contextmenu

该事件允许其他插件向标签管理器上下文菜单中添加菜单项。您可以像这样注册回调函数：

type menuInfo = {
  query?: string           // 当前的全局搜索查询
  isHierarchy: boolean     // 如果标签是标签面板中的子标签（按层次排序），则为true
  tagPage: TFile|undefined // 笔记的标签页面（如果存在）
};

this.registerEvent(
  app.workspace.on("tag-wrangler:contextmenu", (menu: Menu, tagName: string, info: menuInfo) => {
    // 在这里向菜单添加项目
  })
);

tag-page:will-create

该事件允许其他插件接管标签页面的创建。您可以像这样注册一个回调函数：

type tagPageEvent = {
  tag: string
  file?: TFile | Promise<TFile>
}

this.registerEvent(app.workspace.on("tag-page:will-create", (evt: tagPageEvent) => {
  if (!evt.file) {
    // 在此处创建文件，然后将其保存在事件中
    evt.file = someAsynFunctionReturningaTFilePromise();
  }
}));

您可以将文件设置为调用异步函数的结果（如上所示），但是事件处理程序本身不能是异步的，也不应该等待任何东西。如果它是异步的，那么很可能会创建多个文件，因为 Tag Wrangler 和该事件的任何其他事件处理程序都会认为没有其他插件创建了文件。

请注意，如果 evt.file 不是 undefined，则您的回调函数不能执行任何操作，因为文件已经被创建或正在被创建过程中。如果您想修改已经创建的标签页面文件，请改用 tag-page:did-create 事件。（见下文。）

对于使用 Quickadd 和其他允许用户定义 Javascript 的插件的用户，请注意 this.registerEvent() 调用可能需要替换为类似 app.plugins.plugins['quickadd'].registerEvent() 的内容。您还应该仅在插件初始化时运行此代码一次，而不是作为命令或模板的一部分。

tag-page:did-create

该事件允许其他插件修改或重命名新创建的标签页面。它具有与 tag-page:will-create 相同的回调签名，只是 file 字段将始终包含一个 TFile。（由 Tag Wrangler 创建或通过对 tag-page:will-create 的回调创建的文件。）您应该使用 app.vault.process() 方法进行任何更改，以防止意外文件覆盖和数据丢失。（将其更名或更改其名称或位置也应该是安全的 app.vault.rename()。）

与 will-create 的事件处理程序不同，did-create 的处理程序可以是异步的。