Mioyui's Blog

Appearance

VitePress 图片查看组件 ​

组件简介 ​

这个图片查看组件用于给文章中的配图提供更完整的浏览体验。正文里默认展示的是轻度压缩后的预览图，保证首屏加载更轻；读者点击后会打开全屏查看器，并继续加载真正的高质量原图，兼顾浏览体验和图片清晰度。

当前项目里，这套能力分成两部分：

  • BlogImage：写在 Markdown 里的图片触发组件
  • 全局图片查看器：负责弹层、缩放、翻页、工具栏和图片信息展示

这也是推荐的使用方式。以后文章里只要按约定写 <BlogImage />，就能复用同一套查看体验。

核心功能 ​

  • 正文默认加载预览图，点击后再加载原图
  • 查看器右上角提供下载、图片信息、缩小、放大、关闭功能
  • 支持同组图片上一张/下一张切换
  • 桌面端支持鼠标滚轮缩放与拖拽平移
  • 移动端支持双指缩放和单指拖拽
  • 底部可展示原图尺寸和文件大小信息

使用方式 ​

在 Markdown 中显式使用 BlogImage 组件：

md
<BlogImage
  src="./statics/example.png"
  alt="示意图"
  width="800"
/>

目前支持的属性如下：

  • src：原图路径，必填，支持相对当前文章路径书写
  • alt：图片替代文本，必填
  • group：图片分组名，可选；同组图片可在查看器中上一张/下一张切换
  • width：正文中的预览显示宽度，可选
  • download-name：下载原图时使用的文件名，可选

如果不传 group，组件会默认使用当前文章路径作为分组名，这样同一篇文章里的多张图片就能自然组成一个查看序列。

预览图与原图机制 ​

这个组件不是单纯在前端把原图缩小显示，而是通过构建期脚本提前生成预览资源。

当前机制如下：

  1. 脚本扫描文章里的 <BlogImage />
  2. 将需要用到的原图复制到 public/blog-images/ 下
  3. 为每张本地图片生成一个 .preview.webp 预览图，并同样输出到 public/blog-images/
  4. 同时生成一份图片元数据清单
  5. 正文渲染时先用预览图
  6. 打开查看器后再请求 public 中的高质量原图

这样做的好处是正文初始加载的网络开销会更低，而不是一开始就把大图完整下载下来。

工具栏与查看器行为 ​

查看器打开后，右上角工具栏包含这些能力：

  • 下载：下载原图文件
  • 图片信息：在底部展开原图尺寸和文件大小
  • 缩小：按步进缩小当前图片
  • 放大：按步进放大当前图片
  • 关闭：关闭查看器并重置状态

查看器中的其他交互包括：

  • Esc 关闭查看器
  • ← / → 切换上一张和下一张
  • 双击或双点可在 1x 和 2x 之间快速切换
  • 点击遮罩空白区域可关闭查看器

图片信息来源 ​

底部展示的图片信息来自构建期生成的元数据，而不是运行时临时计算。

当前默认展示的是原图信息，包括：

  • 原图宽度
  • 原图高度
  • 原图文件大小

展示格式类似：

text
1193 x 972 37.1 KB

样式与接入位置 ​

这套能力的接入点位于 VitePress 自定义主题中：

  • BlogImage 在主题入口注册为全局组件
  • 全局图片查看器挂载在主题布局底部
  • 原图和预览图都会在构建前输出到 public/blog-images/
  • 预览图元数据由构建脚本生成后供运行时读取

这样文章本身只需要关心怎么写 <BlogImage />，不需要手动管理弹层逻辑。

支持范围与当前限制 ​

当前版本的支持范围如下：

  • 支持本地静态栅格图：png、jpg、jpeg、webp
  • 仅处理显式写成 <BlogImage /> 的图片
  • 当前已在 cloudflare-deploy.md 这篇文章中接入

当前限制如下：

  • 暂不处理外链图片
  • 暂不处理 gif 和 svg
  • 暂不自动增强普通 Markdown 图片语法 ![]() 和原生 <img>

后续优化方向 ​

如果后面继续完善，可以考虑这些方向：

  • 让普通 Markdown 图片也能自动接入查看器
  • 为不同栏目提供不同的图片展示风格
  • 在文档中补充效果截图或动图
  • 增加对外链图片和更多格式的兼容支持