Imagine -- Obsidian 图片综合管理插件

Imagine 是一款面向 Obsidian 的桌面端社区插件，提供从图片浏览、筛选、插入、排版、拖拽调整尺寸到全屏查看的完整工作流。插件同时支持对 Vault 中图片资源进行引用分析与批量清理，帮助用户高效管理数量庞大的图片附件。

本项目部分功能参考插件 Image Toolkit 与 AttachFlow，感谢社区插件的开源分享。

---

目录

• 功能概览
• 支持的图片格式
• 安装
• 快速上手
• 功能详述
  • 图片管理器
  • 图片选择器与插入
  • 图片排版语法
  • 图片拖拽调整尺寸
  • 图片查看器
  • 右键上下文菜单
  • 自定义文件类型
• 设置项参考
• 兼容性与限制
• 致谢
• 许可证

---

功能概览

模块	说明
图片管理器	以网格视图浏览 Vault 中的全部图片资源；支持文件夹筛选、文件名搜索、多字段排序、引用状态检查及批量删除
图片选择器	通过命令面板唤起模态框，快速选择并插入图片到编辑器光标处，可同时配置对齐方式、深色反色与标题
图片排版	通过 Wiki 链接参数控制图片的居中、左浮动、右浮动、行内显示，以及深色模式反色和标题注释
拖拽调整尺寸	在编辑器实时预览模式下，通过拖拽图片右下角边缘即可调整宽度，自动回写 Markdown 链接中的尺寸参数
图片查看器	Ctrl + 单击任意图片即可打开全屏 Lightbox 查看器，支持滚轮缩放与拖拽平移
右键上下文菜单	对编辑器内的 Wiki 链接图片提供对齐调整、反色切换、标题编辑、源文件打开、链接删除等快捷操作
自定义文件类型	允许将非图片格式（如 PDF、PSD 等）纳入管理器，通过关联封面图片进行可视化展示

---

支持的图片格式

插件默认识别以下图片格式：

分类	扩展名
通用格式	PNG, JPG, JPEG, GIF, BMP, WebP, SVG
专业格式	TIFF, TIF, ICO
新一代格式	AVIF, HEIC, HEIF

如需管理上述格式之外的文件，请参阅 自定义文件类型 一节。

---

安装

从 Obsidian 社区插件市场安装（尚未上架）

1. 打开 Settings → Community plugins → Browse。
2. 搜索 "Imagine"。
3. 选择安装并启用。

通过 BRAT 安装

1. 安装 BRAT 插件。
2. 在 BRAT 设置中选择 Add a plugin repository。
3. 输入仓库地址：https://github.com/AlbusGuo/albus-imagine。
4. 等待安装完成后，在 Community plugins 列表中启用 "Imagine"。

手动安装

1. 从 Releases 页面下载最新版本的 main.js、manifest.json 和 styles.css。
2. 在 Vault 目录下创建文件夹 .obsidian/plugins/albus-imagine/，并将上述三个文件放入其中。
3. 重新启动 Obsidian，在 Settings → Community plugins 中启用 "Imagine"。

---

快速上手

完成安装并启用插件后，可通过以下方式快速体验核心功能：

1. 打开图片管理器 -- 点击左侧功能区（Ribbon）中的图片图标，或在命令面板中执行 Imagine: 打开图片管理器。
2. 插入图片到文档 -- 在命令面板中执行 Imagine: 插入图片，在弹出的选择器中选择目标图片后即可插入到当前光标位置。
3. 拖拽调整尺寸 -- 在编辑器实时预览模式下，将鼠标移动到图片右下角，当光标变为 nwse-resize 形态时按住左键拖拽即可调整宽度。
4. 全屏查看图片 -- 按住 Ctrl 键并单击编辑器或阅读模式中的任意图片，即可进入全屏 Lightbox 查看器。

---

功能详述

图片管理器

图片管理器以独立标签页的形式存在，提供对 Vault 内图片资源的集中浏览与管理。

布局结构

管理器界面自上而下分为三个区域：

1. 头部 -- 文件夹选择器（带路径自动补全）、图片统计信息、批量操作按钮。
2. 搜索与排序栏 -- 文件名搜索框、排序字段选择（修改时间 / 创建时间 / 文件大小 / 文件名 / 引用数量）、升降序切换、引用状态筛选（全部 / 仅未引用）。
3. 图片网格 -- 响应式缩略图网格，支持懒加载与增量渲染（每批 50 张），滚动至底部自动加载更多。

图片卡片

每张图片以卡片形式呈现，根据设置可在缩略图上叠加显示文件大小和修改时间。鼠标悬停时在卡片右上角显示操作按钮：

• 打开 -- 在 Obsidian 中使用默认方式打开文件。
• 重命名 -- 弹出对话框修改文件名（不含扩展名），自定义文件类型的封面文件会同步重命名。
• 删除 -- 将文件移至系统回收站（可在设置中关闭删除前确认对话框）。

单击缩略图可打开图片预览模态框，查看完整尺寸图片并浏览引用详情。

引用检查

点击筛选栏中的 "未引用" 按钮后，插件会调用 Obsidian 的元数据缓存 API 扫描所有笔记中的引用关系。扫描结果以引用计数标签的形式显示在每张卡片上，未被任何笔记引用的图片可被批量选中并一次性删除。

批量操作

• 选中删除 -- 进入多选模式，勾选目标图片后执行批量删除，删除过程中显示百分比进度。
• 删除全部未引用 -- 一键删除当前筛选结果中所有未被引用的图片。

图片预览模态框

在管理器中单击任意缩略图即可打开预览模态框，功能包括：

• 无限画布式图片查看（滚轮缩放、鼠标拖拽平移、双击重置）。
• 文件元数据展示（路径、文件大小、创建时间、修改时间）。
• 引用列表 -- 显示引用该图片的所有文档，单击任一条目即可跳转到对应文件并关闭弹窗。
• 对于自定义文件类型，预览模态框以分栏形式同时展示源文件与封面文件的元数据。

---

图片选择器与插入

通过命令面板执行 Imagine: 插入图片 即可打开图片选择器模态框。

选项面板

模态框顶部提供以下选项：

选项	说明
位置	居中（center）、左侧环绕（left）、右侧环绕（right）、行内（inline）
深色反色	开启后在深色主题下对图片应用反色处理
标题	在输入框中填写图片标题说明文字

插入模式

• 单选插入 -- 直接单击某张图片，插件立即将该图片链接插入到编辑器光标处并关闭模态框。
• 多选插入 -- 切换至多选模式后勾选多张图片，确认后插件以 [!grid] callout 格式批量插入，生成自适应网格排列。

生成的链接语法

根据选项面板的组合，插件生成两种不同的 Wiki 链接格式：

无标题时（参数置于 | 之后）：

![[image.png|center]]
![[image.png|dark|center]]

有标题时（位置与反色参数置于 # 之后，标题作为 | 后的别名文本）：

![[image.png#center|这是图片标题]]
![[image.png#center#dark|这是图片标题]]

---

图片排版语法

插件通过 CSS 规则解析 Wiki 链接中的参数，实现多种图片排版效果。以下为完整的参数说明。

位置控制

参数	效果	阅读模式行为	编辑模式行为
center	居中显示	块级居中	块级居中
left	左侧排列	左浮动，文字环绕	左对齐（不浮动）
right	右侧排列	右浮动，文字环绕	右对齐（不浮动）
inline	行内显示	行内排列	行内排列

使用示例：

![[diagram.svg|center]]
![[photo.jpg|left]]
![[icon.png|inline]]

深色模式反色

添加 dark 参数后，图片在 Obsidian 深色主题下自动应用 invert(1) hue-rotate(180deg) 滤镜，适用于在白色背景上绘制的 SVG、线稿或黑白图表：

![[flowchart.svg|dark|center]]

该反色行为仅在深色主题下生效，浅色主题下不受影响。

图片标题

当需要为图片添加标题注释时，使用 # 语法将位置和反色参数编码到链接路径中，将标题文本作为链接别名：

![[architecture.png#center|系统架构示意图]]
![[flowchart.svg#center#dark|数据处理流程]]

标题文本以小字号、弱化颜色显示在图片下方，布局方式为 table-caption，不会撑开图片容器宽度。

Grid Callout 布局

当通过图片选择器多选插入时，插件生成 [!grid] callout 代码块：

> [!grid]
> ![[photo1.jpg]]
> ![[photo2.jpg]]
> ![[photo3.jpg]]

该 callout 的标题栏和图标被隐藏，内部图片以 CSS Grid 自适应网格排列，适合并排展示多张图片。

---

图片拖拽调整尺寸

在编辑器的实时预览（Live Preview）模式下，插件为所有图片注入拖拽调整功能。

操作方式

1. 将鼠标移至图片的右下角区域（默认 20 像素范围内），光标将变为 nwse-resize 形态。
2. 按住鼠标左键向右下方或左上方拖拽，图片宽度将等比例改变。
3. 松开鼠标后，插件将新的宽度值回写到 Markdown 源代码中对应的图片链接。

技术特性

• 拖拽过程中保持原始宽高比，最小宽度限制为 50 像素。
• 视觉更新通过 requestAnimationFrame 驱动，确保流畅性。
• Markdown 链接的回写通过 CodeMirror 6 的事务机制（dispatch）实现，确保与编辑器撤销历史的一致性。
• 支持对 callout 内部和外部的图片分别启用或禁用拖拽。
• 支持对内部链接（Wiki link）和外部链接（Markdown 标准语法）两种格式的尺寸回写。
• 可选的调整步长设置，用于将最终宽度对齐到指定的像素间隔。

排除场景

以下场景中拖拽调整功能不会激活：

• 阅读模式（Reading View）和 Canvas 视图。
• 模态框或图片选择器内部的图片。

---

图片查看器

图片查看器提供全屏 Lightbox 式的图片浏览体验。

打开方式

按住 Ctrl 键（不按 Alt 或 Shift）并单击编辑器、阅读模式或社区插件详情页中的任意 <img> 元素。触发时插件会在事件捕获阶段拦截鼠标事件，阻止 Obsidian 默认的图片查看行为。

交互操作

操作	效果
鼠标滚轮	以鼠标位置为锚点缩放图片，最小宽度 50 像素
鼠标左键拖拽	平移图片位置
单击图片外背景区域	关闭查看器
按下 Esc 键	关闭查看器

透明背景的图片在查看器中自动添加棋盘格底色，便于辨识边界。

多窗口支持

插件会监听 Obsidian 的 window-open 事件，在新打开的弹出窗口中自动注册查看器的事件监听，确保多窗口环境下功能一致。

---

右键上下文菜单

在编辑器中对通过 Wiki 链接嵌入的图片（.internal-embed）右键单击时，插件会在 Obsidian 原生右键菜单的顶部注入以下操作项：

菜单项	说明
图片对齐	子菜单，包含居中、左侧环绕、右侧环绕三个选项；选择后自动修改 Markdown 源代码中的对齐参数
深色反色	切换图片链接中的 dark 参数
编辑标题	在图片下方弹出行内编辑框，按 Enter 保存，修改结果即时回写到 Markdown
打开源文件	使用 Obsidian 默认方式打开图片文件；对于自定义文件类型，打开的是原始工程文件
在文件管理器中显示	在 Obsidian 内置文件管理器中定位并高亮该文件
在系统资源管理器中显示	调用操作系统的文件管理器打开文件所在目录
删除链接	从 Markdown 源代码中移除该图片的嵌入链接

上下文菜单仅在编辑模式下的 Wiki 链接图片上生效，Canvas 视图中不可用。当同一图片在文档中出现多次时，插件通过 CodeMirror 6 的 posAtDOM API 精确定位到被右键点击的那一处实例。

---

自定义文件类型

对于 Vault 中存放的非图片格式文件（如 .pdf、.psd、.ai、.blend 等），插件支持通过关联封面图片将其纳入图片管理器进行可视化管理。

配置方式

在 Settings → Imagine → 图片管理器 → 自定义文件类型 中，点击 "添加文件类型" 按钮，填写以下三个字段：

字段	说明	示例
文件扩展名	需要管理的文件的扩展名（不含点号）	pdf
封面扩展名	对应封面图片的扩展名	png
封面文件夹	封面图片所在的文件夹路径（相对路径；留空表示与源文件同级目录）	covers

工作原理

• 插件在加载图片列表时，会同时扫描符合自定义扩展名的文件，并尝试在指定位置查找同名封面图片。
• 在管理器中，这些文件以封面图片作为缩略图展示，并带有特殊的格式标签以示区分。
• 重命名、删除操作会同时处理源文件和封面文件。
• 引用检查针对封面文件执行（因为 Markdown 中嵌入的是封面图片链接）。
• 如果封面文件缺失，卡片上会显示缺失提示。

---

设置项参考

插件的设置界面分为三个标签页，以下为全部可配置项。

图片管理器

设置项	说明	默认值
显示文件大小	在图片卡片上叠加显示文件大小	开启
显示修改时间	在图片卡片上叠加显示最后修改时间	开启
默认排序字段	打开管理器时的初始排序方式	修改时间
默认排序顺序	打开管理器时的初始排序方向	降序
排除文件夹	不在管理器中显示的文件夹列表（每行一个路径）	空
删除确认	删除文件前是否弹出确认对话框	开启
深色模式下 SVG 图片反色	在深色主题下对 SVG 图片全局应用反色处理	开启
自定义文件类型	配置非图片格式文件与封面图片的关联关系	空

图片拖拽

设置项	说明	默认值
启用 callout 外图片拖拽调整大小	是否允许对 callout 外部的图片进行拖拽调整	开启
启用 callout 内图片拖拽调整大小	是否允许对 callout 内部的图片进行拖拽调整	开启
调整大小的时间间隔	拖拽调整的最小刻度（0 表示不对齐刻度），单位为像素	0
边缘检测区域大小	鼠标在图片右下角多少像素范围内可触发调整，范围 5 - 150	20

图片查看器

设置项	说明	默认值
启用图片查看器	是否在所有位置启用 Ctrl + 点击图片查看功能	开启

---

兼容性与限制

• 平台支持：本插件标记为 isDesktopOnly: true，仅在桌面端（Windows / macOS / Linux）可用。
• 最低版本：要求 Obsidian 1.12.1 或更高版本。
• 编辑模式：拖拽调整尺寸和右键上下文菜单仅在编辑器的实时预览模式下可用。
• 链接格式：右键上下文菜单仅对 Wiki 链接格式（![[...]]）的图片嵌入生效，标准 Markdown 图片语法（![]()）不受支持。
• 多窗口：图片查看器和拖拽调整功能均支持 Obsidian 的多窗口弹出。

---

致谢

本项目的图片查看器功能参考了 Image Toolkit 插件的实现思路，图片拖拽调整尺寸功能借鉴了 AttachFlow 插件的设计。在此对上述开源项目的作者及 Obsidian 社区表示感谢。

许可证

本项目基于 AGPL-3.0 许可证发布。