Images Preview

一个面向 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）

插件注册了以下命令：

设置项说明

安装

方式 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