From 4590703e637ccb5cb399681314966b07ac8ec8da Mon Sep 17 00:00:00 2001
From: pengzhanbo <volodymyr@foxmail.com>
Date: Sat, 5 Jul 2025 23:22:25 +0800
Subject: [PATCH] feat(theme): add `image-preview` configuration (#637)

---
 docs/.vuepress/notes/zh/theme-guide.ts        |  1 +
 .../theme/guide/features/image-preview.md     | 46 +++++++++++++++++++
 theme/src/node/plugins/setupPlugins.ts        |  3 +-
 theme/src/shared/plugins.ts                   |  3 +-
 4 files changed, 51 insertions(+), 2 deletions(-)
 create mode 100644 docs/notes/theme/guide/features/image-preview.md

diff --git a/docs/.vuepress/notes/zh/theme-guide.ts b/docs/.vuepress/notes/zh/theme-guide.ts
index eff3dc9b..55e9d0d8 100644
--- a/docs/.vuepress/notes/zh/theme-guide.ts
+++ b/docs/.vuepress/notes/zh/theme-guide.ts
@@ -125,6 +125,7 @@ export const themeGuide: ThemeNote = defineNoteConfig({
       items: [
         'icon',
         'search',
+        'image-preview',
         'comments',
         'bulletin',
         'encryption',
diff --git a/docs/notes/theme/guide/features/image-preview.md b/docs/notes/theme/guide/features/image-preview.md
new file mode 100644
index 00000000..e581c02d
--- /dev/null
+++ b/docs/notes/theme/guide/features/image-preview.md
@@ -0,0 +1,46 @@
+---
+title: 图片预览
+icon: ri:image-line
+createTime: 2025/07/03 20:46:17
+permalink: /guide/features/image-preview/
+---
+
+在主题中，图片默认支持点击后放大预览。通过查找 文档内容中的图片，形成图片预览列表。
+
+该功能由 [@vuepress/plugin-photo-swipe](https://ecosystem.vuejs.press/zh/plugins/features/photo-swipe.html) 插件提供支持。
+
+## 配置
+
+图片预览默认启用，也可以通过以下配置修改行为：
+
+```ts title=".vuepress/config.ts"
+export default defineUserConfig({
+  theme: plumeTheme({
+    plugins: {
+      photoSwipe: {
+        // 图片选择器
+        selector: '[vp-content] :not(a) > img:not([no-view],.no-view,.ignore)',
+        download: true, // 是否显示下载按钮
+        fullscreen: true, // 是否显示全屏按钮
+        scrollToClose: true, // 是否在滚动时关闭当前图片
+      }
+    }
+  })
+})
+```
+
+更多配置请参考 [@vuepress/plugin-photo-swipe](https://ecosystem.vuejs.press/zh/plugins/features/photo-swipe.html)
+
+## 忽略图片预览
+
+可以通过 `no-view` 或 `ignore` 类名，或者 `no-view` 属性来忽略图片预览。
+
+```md
+![](path/to/image){.no-view}
+![](path/to/image){.ignore}
+![](path/to/image){no-view}
+
+<img src="path/to/image" class="no-view">
+<img src="path/to/image" class="ignore">
+<img src="path/to/image" no-view>
+```
diff --git a/theme/src/node/plugins/setupPlugins.ts b/theme/src/node/plugins/setupPlugins.ts
index 82c27e1e..ab0cce8d 100644
--- a/theme/src/node/plugins/setupPlugins.ts
+++ b/theme/src/node/plugins/setupPlugins.ts
@@ -53,7 +53,8 @@ export function setupPlugins(
   // 图片浏览
   if (pluginOptions.photoSwipe !== false) {
     plugins.push(photoSwipePlugin({
-      selector: '.plume-content > img, .plume-content :not(a) > img',
+      selector: '[vp-content] :not(a) > img:not([no-view],.no-view,.ignore)',
+      ...pluginOptions.photoSwipe,
     }))
   }
 
diff --git a/theme/src/shared/plugins.ts b/theme/src/shared/plugins.ts
index 8be77ad0..d5acaf0c 100644
--- a/theme/src/shared/plugins.ts
+++ b/theme/src/shared/plugins.ts
@@ -7,6 +7,7 @@ import type { MarkdownChartPluginOptions } from '@vuepress/plugin-markdown-chart
 import type { MarkdownImagePluginOptions } from '@vuepress/plugin-markdown-image'
 import type { MarkdownIncludePluginOptions } from '@vuepress/plugin-markdown-include'
 import type { MarkdownMathPluginOptions } from '@vuepress/plugin-markdown-math'
+import type { PhotoSwipePluginOptions } from '@vuepress/plugin-photo-swipe'
 import type { ReadingTimePluginOptions } from '@vuepress/plugin-reading-time'
 import type { SeoPluginOptions } from '@vuepress/plugin-seo'
 import type { ShikiPluginOptions } from '@vuepress/plugin-shiki'
@@ -49,7 +50,7 @@ export interface ThemeBuiltinPlugins {
   /**
    * 图片预览 插件
    */
-  photoSwipe?: false
+  photoSwipe?: false | PhotoSwipePluginOptions
 
   /**
    * @deprecated 插件相关功能已迁移至其他官方插件，此插件已弃用