From c0023297d7c70009350ca4293f936df222230383 Mon Sep 17 00:00:00 2001 From: Mister-Hope Date: Wed, 4 Jun 2025 14:11:34 +0800 Subject: [PATCH] refactor(plugin-medium-zoom): add jsdoc and update docs --- docs/plugins/features/medium-zoom.md | 9 +++------ docs/zh/plugins/features/medium-zoom.md | 17 +++++++---------- .../src/client/composables/useMediumZoom.ts | 15 +++++++++++++++ .../src/node/mediumZoomPlugin.ts | 7 +++++++ .../plugin-medium-zoom/src/node/options.ts | 6 ++++++ 5 files changed, 38 insertions(+), 16 deletions(-) diff --git a/docs/plugins/features/medium-zoom.md b/docs/plugins/features/medium-zoom.md index 56f209bb8e..193327980c 100644 --- a/docs/plugins/features/medium-zoom.md +++ b/docs/plugins/features/medium-zoom.md @@ -33,9 +33,7 @@ export default { ### selector - Type: `string` - - Default: `'[vp-content] > img, [vp-content] :not(a) > img'` - - Details: Selector of zoomable images. @@ -45,12 +43,11 @@ export default { ### zoomOptions - Type: `Object` - - Details: Options for medium-zoom. -- Also see: +- Reference: - [medium-zoom > Options](https://github.com/francoischalifour/medium-zoom#options) ## Styles @@ -65,11 +62,11 @@ You can customize most of the zoom styles via [zoomOptions](#zoomoptions), while - Details: - Returns the `Zoom` instance that used by this plugin, so that you can use the instance [methods](https://github.com/francoischalifour/medium-zoom#methods) directly. + Returns the `Zoom` instance that is used by this plugin, so that you can use the instance [methods](https://github.com/francoischalifour/medium-zoom#methods) directly. This plugin will make images zoomable after navigating to current page. But if you are going to add new images dynamically, you may need this method to make those new images zoomable, too. - This plugin adds an extra `refresh` method on the `Zoom` instance, which will call `zoom.detach()` then `zoom.attach()` with the [selector](#selector) as the default parameter. It will help you to refresh the zoomable images for current page. + This plugin adds an extra `refresh` method on the `Zoom` instance, which will call `zoom.detach()` then `zoom.attach()` with the [selector](#selector) as the default parameter. It will help you refresh the zoomable images for current page. - Example: diff --git a/docs/zh/plugins/features/medium-zoom.md b/docs/zh/plugins/features/medium-zoom.md index e28b6b74f5..9e96ef17c1 100644 --- a/docs/zh/plugins/features/medium-zoom.md +++ b/docs/zh/plugins/features/medium-zoom.md @@ -32,20 +32,17 @@ export default { ### selector -- 类型： `string` - -- 默认值： `'[vp-content] > img, [vp-content] :not(a) > img'` - +- 类型：`string` +- 默认值：`'[vp-content] > img, [vp-content] :not(a) > img'` - 详情： - 可缩放的图片的选择器。 + 可缩放图片的选择器。 默认情况下，该插件会使 `` 标签以外的所有图片都支持缩放。 ### zoomOptions -- 类型： `Object` - +- 类型：`Object` - 详情： medium-zoom 的配置项。 @@ -55,7 +52,7 @@ export default { ## 样式 -你可以通过 [zoomOptions](#zoomoptions) 对大部分的缩放样式进行自定义，不过作为补充，该插件同样提供了一些 CSS 变量： +你可以通过 [zoomOptions](#zoomoptions) 对大部分缩放样式进行自定义，该插件还提供了一些 CSS 变量用于补充自定义： @[code css](@vuepress/plugin-medium-zoom/src/client/styles/vars.css) @@ -65,11 +62,11 @@ export default { - 详情： - 返回该插件使用的 `Zoom` 实例，便于你直接使用实例上的 [methods](https://github.com/francoischalifour/medium-zoom#methods) 。 + 返回该插件使用的 `Zoom` 实例，便于你直接使用实例上的 [methods](https://github.com/francoischalifour/medium-zoom#methods)。 该插件会在切换路由进入当前页面时使图片支持缩放。但如果你要动态添加新图片，那么你可能就需要这个方法来让这些新图片也支持缩放。 - 该插件在 `Zoom` 实例上额外添加了一个 `refresh` 方法，它将使用 [selector](#selector) 作为默认参数，先调用 `zoom.detach()` 再调用 `zoom.attach()` ，便于你快速刷新当前页面图片的缩放状态。 + 该插件在 `Zoom` 实例上额外添加了一个 `refresh` 方法，它将使用 [selector](#selector) 作为默认参数，先调用 `zoom.detach()` 再调用 `zoom.attach()`，便于你快速刷新当前页面图片的缩放状态。 - 示例： diff --git a/plugins/features/plugin-medium-zoom/src/client/composables/useMediumZoom.ts b/plugins/features/plugin-medium-zoom/src/client/composables/useMediumZoom.ts index 131bb4e705..3c4502f276 100644 --- a/plugins/features/plugin-medium-zoom/src/client/composables/useMediumZoom.ts +++ b/plugins/features/plugin-medium-zoom/src/client/composables/useMediumZoom.ts @@ -8,10 +8,25 @@ declare module 'medium-zoom' { } } +/** + * Injection key for medium zoom instance + * + * medium zoom 实例的注入键 + */ export const mediumZoomSymbol: InjectionKey = Symbol('mediumZoom') /** * Inject medium zoom instance + * + * 注入 medium zoom 实例 + * + * @example + * ```ts + * import { useMediumZoom } from '@vuepress/plugin-medium-zoom/client' + * + * const zoom = useMediumZoom() + * zoom?.refresh() + * ``` */ export const useMediumZoom = (): Zoom | null => { if (__VUEPRESS_SSR__) return null diff --git a/plugins/features/plugin-medium-zoom/src/node/mediumZoomPlugin.ts b/plugins/features/plugin-medium-zoom/src/node/mediumZoomPlugin.ts index 55aa149bb2..2034f98d57 100644 --- a/plugins/features/plugin-medium-zoom/src/node/mediumZoomPlugin.ts +++ b/plugins/features/plugin-medium-zoom/src/node/mediumZoomPlugin.ts @@ -4,6 +4,13 @@ import type { MediumZoomPluginOptions } from './options' const __dirname = import.meta.dirname || getDirname(import.meta.url) +/** + * VuePress plugin - medium-zoom + * + * VuePress 插件 - medium-zoom + * + * @param options - Plugin options / 插件配置项 + */ export const mediumZoomPlugin = ({ selector = '[vp-content] > img, [vp-content] :not(a) > img', zoomOptions = {}, diff --git a/plugins/features/plugin-medium-zoom/src/node/options.ts b/plugins/features/plugin-medium-zoom/src/node/options.ts index cabb3dbfed..721ca612a5 100644 --- a/plugins/features/plugin-medium-zoom/src/node/options.ts +++ b/plugins/features/plugin-medium-zoom/src/node/options.ts @@ -2,11 +2,15 @@ import type { ZoomOptions } from 'medium-zoom' /** * Options for @vuepress/plugin-medium-zoom + * + * @vuepress/plugin-medium-zoom 的配置项 */ export interface MediumZoomPluginOptions { /** * Selector of zoomable images * + * 可缩放图片的选择器 + * * @default '[vp-content] > img, [vp-content] :not(a) > img' */ selector?: string @@ -14,6 +18,8 @@ export interface MediumZoomPluginOptions { /** * Options for medium-zoom * + * medium-zoom 的配置项 + * * @see https://github.com/francoischalifour/medium-zoom#options */ zoomOptions?: ZoomOptions