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 |
如需管理上述格式之外的文件，请参阅 自定义文件类型 一节。
- 打开 Settings → Community plugins → Browse。
- 搜索 "Imagine"。
- 选择安装并启用。
- 安装 BRAT 插件。
- 在 BRAT 设置中选择 Add a plugin repository。
- 输入仓库地址：
https://github.com/AlbusGuo/albus-imagine。 - 等待安装完成后，在 Community plugins 列表中启用 "Imagine"。
- 从 Releases 页面下载最新版本的
main.js、manifest.json和styles.css。 - 在 Vault 目录下创建文件夹
.obsidian/plugins/albus-imagine/，并将上述三个文件放入其中。 - 重新启动 Obsidian，在 Settings → Community plugins 中启用 "Imagine"。
完成安装并启用插件后，可通过以下方式快速体验核心功能：
- 打开图片管理器 -- 点击左侧功能区（Ribbon）中的图片图标，或在命令面板中执行
Imagine: 打开图片管理器。 - 插入图片到文档 -- 在命令面板中执行
Imagine: 插入图片，在弹出的选择器中选择目标图片后即可插入到当前光标位置。 - 拖拽调整尺寸 -- 在编辑器实时预览模式下，将鼠标移动到图片右下角，当光标变为
nwse-resize形态时按住左键拖拽即可调整宽度。 - 全屏查看图片 -- 按住 Ctrl 键并单击编辑器或阅读模式中的任意图片，即可进入全屏 Lightbox 查看器。
图片管理器以独立标签页的形式存在，提供对 Vault 内图片资源的集中浏览与管理。
管理器界面自上而下分为三个区域：
- 头部 -- 文件夹选择器（带路径自动补全）、图片统计信息、批量操作按钮。
- 搜索与排序栏 -- 文件名搜索框、排序字段选择（修改时间 / 创建时间 / 文件大小 / 文件名 / 引用数量）、升降序切换、引用状态筛选（全部 / 仅未引用）。
- 图片网格 -- 响应式缩略图网格，支持懒加载与增量渲染（每批 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]
> ![[photo1.jpg]]
> ![[photo2.jpg]]
> ![[photo3.jpg]]该 callout 的标题栏和图标被隐藏，内部图片以 CSS Grid 自适应网格排列，适合并排展示多张图片。
在编辑器的实时预览（Live Preview）模式下，插件为所有图片注入拖拽调整功能。
- 将鼠标移至图片的右下角区域（默认 20 像素范围内），光标将变为
nwse-resize形态。 - 按住鼠标左键向右下方或左上方拖拽，图片宽度将等比例改变。
- 松开鼠标后，插件将新的宽度值回写到 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 许可证发布。