MineImages — Obsidian 统一预览插件开发纪实

敏E好学

504人浏览 · 2026-05-26 00:48:33

敏E好学 · 2026-05-26 00:48:33 发布

MineImages — Obsidian 统一预览插件开发纪实

一、开发背景

1.1 痛点

Obsidian 作为一款优秀的本地知识库工具，在图片和 Mermaid 图表预览方面存在明显的交互短板：

图片预览：原生仅支持点击后在新标签页打开，无法在上下文中缩放、旋转或对比查看多张图片
Mermaid 图表：渲染后尺寸不可控，大图溢出容器，小图留白过多；编辑模式下无法直接预览
功能碎片化：社区中虽有一些独立插件，但各自解决单一问题，交互风格不统一且存在功能重叠

1.2 设计目标

开发一款统一、流畅、功能完整的预览插件，满足以下设计原则：

1.3 技术选型

秉持 “最大化利用 Obsidian 官方 API，避免重复造轮子” 的原则：

模块	选用方案	原因
预览容器	`Modal` 类	Obsidian 官方推荐，自带遮罩和关闭逻辑
图表捕获（阅读模式）	`MarkdownPostProcessor`	原生渲染管道，无需额外渲染
图表捕获（实时预览）	DOM 事件委托	兼容 `.cm-embed-block` 中的动态渲染
图片捕获	`registerDomEvent`	轻量级，无侵入
变换（缩放/旋转/平移）	CSS `transform`	GPU 加速，60fps
右键菜单	`Menu` 类	原生 Obsidian 风格
设置界面	`PluginSettingTab`	标准配置模式
主题适配	CSS 变量	自动跟随深浅主题
国际化	`i18n.ts` + `as const` 推导	中英双语 55 个 key，设置页实时切换

二、功能介绍

2.1 核心预览能力

点击笔记中的任意图片或 Mermaid 图表，立即在统一的模态浮层中打开：

在这里插入图片描述

2.2 交互功能矩阵

功能	触发方式	说明
缩放	Ctrl + 滚轮 / 工具栏 ± 按钮	步进可配置，范围 10%–1000%
拖动平移	鼠标拖拽	缩放后平移查看细节
旋转	工具栏按钮 / R 键	90° 步进
重置	双击内容 / 工具栏按钮 / 0 键	恢复初始缩放和旋转
复制	工具栏按钮 / 右键菜单	图片/Mermaid 均复制为 PNG
切换	← → 箭头键 / 工具栏 / 右键菜单	遍历当前文件所有预览项
关闭	ESC / 点击遮罩 / 工具栏关闭按钮
全屏	工具栏按钮	浏览器 Fullscreen API
标注	工具栏笔/箭头/矩形/清除	Canvas 叠加层，不修改原图
缩略图导航	左侧面板	固定大小的缩略图列表，点击跳转

2.3 页面内交互

对于 Mermaid 图表，在笔记页面中提供额外的交互能力：

三、技术实现

3.1 整体架构

3.2 模态框生命周期

3.3 关键实现细节

3.3.1 变换管理（TransformManager）

// 核心状态
class TransformManager {
  scale: number;      // 当前缩放 (0.1 ~ 10.0)
  translateX: number; // 水平偏移
  translateY: number; // 垂直偏移
  rotation: number;   // 旋转角度 (0 / 90 / 180 / 270)
  
  // 应用到 DOM 元素
  applyTo(el: HTMLElement) {
    el.style.transform = `
      translate(${this.translateX}px, ${this.translateY}px)
      scale(${this.scale})
      rotate(${this.rotation}deg)
    `;
  }
}

3.3.2 Mermaid 自适应与拖拽缩放

在页面中通过 MutationObserver 捕获所有 .mermaid 元素，自动添加 width: 100% 适配容器宽度。由于 Mermaid 是异步渲染，bindMermaidElement 内置了 5 次 × 500ms 的重试等待 SVG 元素就绪。右下角的拖拽手柄允许用户手动调整大小：

3.3.3 缩略图导航

左侧缩略图栏为固定 100×80px 的导航面板，自动收集当前文件所有图片和 Mermaid 图表，点击即可跳转：

// 缩略图构建流程
private buildThumbnailBar(): void {
  this.navigation.items.forEach((item, index) => {
    const thumb = createDiv("mine-images-thumbnail");
    if (item.type === "image") {
      this.loadThumbnailImage(item.source, thumb);
    } else {
      this.renderMermaidThumbnail(item, thumb);
    }
    thumb.addEventListener("click", () => this.navigateTo(index));
  });
}