types(ImagePreview): add ImagePreviewInstance type (#9216)

src/image-preview/ImagePreview.tsx

@@ -7,6 +7,7 @@ import {
   onMounted,
   CSSProperties,
   defineComponent,
+  ExtractPropTypes,
 } from 'vue';
 
 // Utils
@@ -30,57 +31,59 @@ import { Swipe, SwipeToOptions } from '../swipe';
 import { Popup, PopupCloseIconPosition } from '../popup';
 import ImagePreviewItem from './ImagePreviewItem';
 
+// Types
+import { ImagePreviewScaleEventParams } from './types';
+
 const [name, bem] = createNamespace('image-preview');
 
-export type ScaleEventParams = {
-  scale: number;
-  index: number;
+const props = {
+  show: Boolean,
+  loop: truthProp,
+  overlay: truthProp,
+  closeable: Boolean,
+  showIndex: truthProp,
+  className: unknownProp,
+  transition: String,
+  beforeClose: Function as PropType<Interceptor>,
+  overlayStyle: Object as PropType<CSSProperties>,
+  showIndicators: Boolean,
+  closeOnPopstate: truthProp,
+  images: {
+    type: Array as PropType<string[]>,
+    default: () => [],
+  },
+  minZoom: {
+    type: [Number, String],
+    default: 1 / 3,
+  },
+  maxZoom: {
+    type: [Number, String],
+    default: 3,
+  },
+  swipeDuration: {
+    type: [Number, String],
+    default: 300,
+  },
+  startPosition: {
+    type: [Number, String],
+    default: 0,
+  },
+  closeIcon: {
+    type: String,
+    default: 'clear',
+  },
+  closeIconPosition: {
+    type: String as PropType<PopupCloseIconPosition>,
+    default: 'top-right',
+  },
 };
 
+export type ImagePreviewProps = ExtractPropTypes<typeof props>;
+
 export default defineComponent({
   name,
 
-  props: {
-    show: Boolean,
-    loop: truthProp,
-    overlay: truthProp,
-    closeable: Boolean,
-    showIndex: truthProp,
-    className: unknownProp,
-    transition: String,
-    beforeClose: Function as PropType<Interceptor>,
-    overlayStyle: Object as PropType<CSSProperties>,
-    showIndicators: Boolean,
-    closeOnPopstate: truthProp,
-    images: {
-      type: Array as PropType<string[]>,
-      default: () => [],
-    },
-    minZoom: {
-      type: [Number, String],
-      default: 1 / 3,
-    },
-    maxZoom: {
-      type: [Number, String],
-      default: 3,
-    },
-    swipeDuration: {
-      type: [Number, String],
-      default: 300,
-    },
-    startPosition: {
-      type: [Number, String],
-      default: 0,
-    },
-    closeIcon: {
-      type: String,
-      default: 'clear',
-    },
-    closeIconPosition: {
-      type: String as PropType<PopupCloseIconPosition>,
-      default: 'top-right',
-    },
-  },
+  props,
 
   emits: ['scale', 'close', 'closed', 'change', 'update:show'],
 
@@ -103,7 +106,8 @@ export default defineComponent({
       }
     };
 
-    const emitScale = (args: ScaleEventParams) => emit('scale', args);
+    const emitScale = (args: ImagePreviewScaleEventParams) =>
+      emit('scale', args);
 
     const updateShow = (show: boolean) => emit('update:show', show);
 

src/image-preview/README.md

@@ -187,7 +187,20 @@ Use [ref](https://vuejs.org/v2/api/#ref) to get ImagePreview instance and call i
 
 | Name | Description | Attribute | Return value |
 | --- | --- | --- | --- |
-| swipeTo `2.9.0` | Swipe to target index | index: target index, options: Options | - |
+| swipeTo `2.9.0` | Swipe to target index | _index: number, options?: SwipeToOptions_ | - |
+
+### Types
+
+Get the type definition of the ImagePreview instance through `ImagePreviewInstance`.
+
+```ts
+import { ref } from 'vue';
+import type { ImagePreviewInstance } from 'vant';
+
+const imagePreviewRef = ref<ImagePreviewInstance>();
+
+imagePreviewRef.value?.swipeTo(1);
+```
 
 ### Slots
 

src/image-preview/README.zh-CN.md

@@ -220,9 +220,22 @@ export default {
 
 通过组件调用 `ImagePreview` 时，通过 ref 可以获取到 ImagePreview 实例并调用实例方法，详见[组件实例方法](#/zh-CN/advanced-usage#zu-jian-shi-li-fang-fa)。
 
-| 方法名          | 说明           | 参数                            | 返回值 |
-| --------------- | -------------- | ------------------------------- | ------ |
-| swipeTo `2.9.0` | 切换到指定位置 | index: number, options: Options | -      |
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| swipeTo `2.9.0` | 切换到指定位置 | _index: number, options?: SwipeToOptions_ | - |
+
+### 类型定义
+
+通过 `ImagePreviewInstance` 获取 ImagePreview 实例的类型定义。
+
+```ts
+import { ref } from 'vue';
+import type { ImagePreviewInstance } from 'vant';
+
+const imagePreviewRef = ref<ImagePreviewInstance>();
+
+imagePreviewRef.value?.swipeTo(1);
+```
 
 ### Slots
 

src/image-preview/function-call.tsx

@@ -1,40 +1,11 @@
-import { App, CSSProperties, TeleportProps } from 'vue';
-import {
-  extend,
-  inBrowser,
-  withInstall,
-  Interceptor,
-  ComponentInstance,
-} from '../utils';
+import { extend, inBrowser, withInstall, ComponentInstance } from '../utils';
 import { mountComponent, usePopupState } from '../utils/mount-component';
-import { PopupCloseIconPosition } from '../popup';
 import VanImagePreview from './ImagePreview';
+import type { App } from 'vue';
+import type { ImagePreviewOptions } from './types';
 
 let instance: ComponentInstance;
 
-export type ImagePreviewOptions = {
-  loop?: boolean;
-  images: string[];
-  maxZoom?: number;
-  minZoom?: number;
-  teleport?: TeleportProps['to'];
-  className?: unknown;
-  showIndex?: boolean;
-  closeable?: boolean;
-  closeIcon?: string;
-  transition?: string;
-  beforeClose?: Interceptor;
-  overlayStyle?: CSSProperties;
-  swipeDuration?: number;
-  startPosition?: number;
-  showIndicators?: boolean;
-  closeOnPopstate?: boolean;
-  closeIconPosition?: PopupCloseIconPosition;
-  onClose?(): void;
-  onScale?(args: { scale: number; index: number }): void;
-  onChange?(index: number): void;
-};
-
 const defaultConfig: ImagePreviewOptions = {
   loop: true,
   images: [],

src/image-preview/index.ts

@@ -1,5 +1,9 @@
-import { ImagePreview, ImagePreviewOptions } from './function-call';
+import { ImagePreview } from './function-call';
 
 export default ImagePreview;
 export { ImagePreview };
-export type { ImagePreviewOptions };
+export type {
+  ImagePreviewOptions,
+  ImagePreviewInstance,
+  ImagePreviewScaleEventParams,
+} from './types';

src/image-preview/types.ts

@@ -0,0 +1,46 @@
+import type {
+  CSSProperties,
+  TeleportProps,
+  ComponentPublicInstance,
+} from 'vue';
+import type { Interceptor } from '../utils';
+import type { SwipeToOptions } from '../swipe';
+import type { PopupCloseIconPosition } from '../popup';
+import type { ImagePreviewProps } from './ImagePreview';
+
+export type ImagePreviewOptions = {
+  loop?: boolean;
+  images: string[];
+  maxZoom?: number;
+  minZoom?: number;
+  teleport?: TeleportProps['to'];
+  className?: unknown;
+  showIndex?: boolean;
+  closeable?: boolean;
+  closeIcon?: string;
+  transition?: string;
+  beforeClose?: Interceptor;
+  overlayStyle?: CSSProperties;
+  swipeDuration?: number;
+  startPosition?: number;
+  showIndicators?: boolean;
+  closeOnPopstate?: boolean;
+  closeIconPosition?: PopupCloseIconPosition;
+  onClose?(): void;
+  onScale?(args: { scale: number; index: number }): void;
+  onChange?(index: number): void;
+};
+
+export type ImagePreviewScaleEventParams = {
+  scale: number;
+  index: number;
+};
+
+export type ImagePreviewExpose = {
+  swipeTo: (index: number, options?: SwipeToOptions) => void;
+};
+
+export type ImagePreviewInstance = ComponentPublicInstance<
+  ImagePreviewProps,
+  ImagePreviewExpose
+>;