Images Preview (Obsidian Plugin)

一个面向 Obsidian 的图片浮窗预览插件：点击笔记中的图片即可打开预览窗口，支持缩放、拖拽、切图与 Pin 多图并行查看。

功能总览

1. 两种预览模式

• 普通模式（Normal）：同一时间仅保留一个预览窗口，带遮罩，适合专注查看。
• Pin 模式（Pin）：可同时保留多个浮窗，适合对比多张图。
• Pin 模式支持上限控制：
  • Pin mode max images：最多保留 1~6 张。
  • Replace oldest image when full：达到上限后自动替换最早打开的预览。

2. 图片浏览与画廊

• 支持在同一上下文中收集图片并切换上一张/下一张。
• 可显示底部缩略图画廊（可在设置中关闭）。
• 当 DOM 收集不到图片时，自动回退到当前 Markdown 文本解析（支持 Markdown 图片、WikiLink 图片、HTML img）。

3. 交互能力（桌面 + 移动端）

• 鼠标左键拖拽移动图片。
• 滚轮缩放（已做触控板/滚轮归一化）。
• 双击在 fit 与 1:1 之间切换。
• 右键（或移动端长按）打开快捷菜单。
• 点击图片下方名称可复制图片名称。
• 点击遮罩可关闭当前普通模式预览。

4. 工具栏能力

工具栏内置以下动作：

• 缩小 -
• 放大 +
• 原始比例 1:1
• 自适应 Fit
• 复制图片 Copy
• 上一张 ◀
• 下一张 ▶
• 关闭 Close

5. 键盘能力

• Esc：关闭当前激活预览。
• 方向键 + 切换修饰键：上一张 / 下一张。
• 方向键 + 移动修饰键：按速度参数移动图片。

命令面板（Command Palette）

插件注册了以下命令：

命令 ID	默认名称（中文）	说明
open-preview-at-active-image	在当前图片打开预览	在当前活动视图中打开预览
toggle-preview-mode	切换预览模式	普通模式 / Pin 模式切换
close-active-preview	关闭当前预览	关闭当前激活预览
next-image	下一张图片	切换到下一张
prev-image	上一张图片	切换到上一张

设置项说明

分类	设置项	说明
基础	Interface language	界面语言：跟随系统 / 中文 / 英文
基础	Preview mode	默认预览模式：Normal / Pin
触发	Trigger scope	触发范围：仅 Markdown / Markdown+常见面板 / 全局图片
触发	Enable linked images	是否支持点击链接包裹的图片触发
Pin	Pin mode max images	Pin 模式最多保留图片数（1~6）
Pin	Replace oldest image when full	达到上限后是否替换最旧预览
视觉	Enable gallery navbar	是否显示底部缩略图画廊
键盘	Keyboard move speed	方向键移动速度
键盘	Move image modifier	移动图片时所需修饰键
键盘	Switch image modifier	切图时所需修饰键
移动端	Enable mobile gestures	是否启用移动端手势交互

安装

方式 A：手动安装（本地仓库/未上架场景）

1. 在你的 Vault 下创建插件目录：

mkdir -p <your-vault>/.obsidian/plugins/images-preview

2. 将以下文件放入该目录：

• manifest.json
• main.js
• styles.css

3. 打开 Obsidian：

• 设置 -> 第三方插件 -> 已安装插件
• 启用 Images Preview

快速上手

1. 打开任意包含图片的笔记。
2. 单击图片打开预览。
3. 用滚轮缩放、拖拽移动、双击切换 fit/1:1。
4. 用工具栏或键盘切换上一张/下一张。
5. 需要多图对比时，切换到 Pin 模式。

开发与验证

# 开发监听构建
npm run dev

# 生产构建
npm run build

# 类型检查
npm run typecheck

# 单元测试（一次性）
npm run test:run

# 单元测试（交互模式）
npm run test

内部开发与多设备无软链接部署流程请见：docs/DEVELOPMENT.md。

项目结构

src/
  main.ts                          # 插件入口
  controllers/preview-controller.ts # 预览编排层
  core/                            # 纯逻辑（变换引擎、状态机）
  input/input-adapter.ts           # 鼠标/触摸输入适配
  services/                        # 画廊收集、设置存储、剪贴板
  ui/overlay-host.ts               # 预览 DOM 渲染/销毁
  settings.ts                      # 设置页
  i18n.ts                          # 中英文本地化
styles.css                         # UI 样式
tests/                             # Vitest 单元测试

兼容性

• Obsidian >= 1.8.7
• 桌面端与移动端均可用（manifest.json 中 isDesktopOnly: false）

常见问题（FAQ）

Q1：为什么某些图片点了没反应？

优先检查：

• 当前视图是否在你设置的 Trigger scope 范围内。
• 图片是否被链接包裹且 Enable linked images 已关闭。

Q2：方向键为什么不能切图或移动？

切图/移动依赖你设置的修饰键组合。请在设置中确认：

• Switch image modifier
• Move image modifier

License

MIT