refactor(ImagePreview): redesign function-call API (#10802)

packages/vant/docs/markdown/migrate-from-v3.zh-CN.md

@@ -172,6 +172,20 @@ declare module '@vue/runtime-core' {
 }
 ```
 
+### ImagePreview 调用方式调整
+
+Vant 4 中，`ImagePreview` 组件的调用方式也进行了调整，与 `ImagePreview` 组件的改动一致：
+
+```js
+// Vant 3
+ImagePreview(); // 函数调用
+ImagePreview.Component; // 组件对象
+
+// Vant 4
+showImagePreview(); // 函数调用
+ImagePreview; // 组件对象
+```
+
 ### 事件命名调整
 
 从 Vant 4 开始，所有的事件均采用 Vue 官方推荐的**驼峰格式**进行命名。

packages/vant/src/dialog/README.zh-CN.md

@@ -297,16 +297,3 @@ Dialog.alert({
   // on close
 });
 ```
-
-### 在 JSX 中渲染 Dialog 组件无法展示？
-
-请注意 `Dialog` 是一个函数，`Dialog.Component` 才是 Dialog 对应的组件。JSX 调用弹窗的正确姿势如下：
-
-```jsx
-export default {
-  setup() {
-    const show = ref(false);
-    return () => <Dialog.Component v-model={[show, 'show']} />;
-  },
-};
-```

packages/vant/src/image-preview/README.md

@@ -16,12 +16,26 @@ const app = createApp();
 app.use(ImagePreview);
 ```
 
+### Function Call
+
+Vant provides some utility functions that can quickly evoke global `ImagePreview` components.
+
+For example, calling the `showImagePreview` function will render a Dialog directly in the page.
+
+```js
+import { showImagePreview } from 'vant';
+
+showImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);
+```
+
 ## Usage
 
 ### Basic Usage
 
 ```js
-ImagePreview([
+import { showImagePreview } from 'vant';
+
+showImagePreview([
   'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
   'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
 ]);
@@ -30,7 +44,9 @@ ImagePreview([
 ### Set Start Position
 
 ```js
-ImagePreview({
+import { showImagePreview } from 'vant';
+
+showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -44,7 +60,9 @@ ImagePreview({
 After setting the `closeable` attribute, the close icon will be displayed in the upper right corner of the pop-up layer, and the icon can be customized through the `close-icon` attribute, and the icon location can be customized by using the `close-icon-position` attribute.
 
 ```js
-ImagePreview({
+import { showImagePreview } from 'vant';
+
+showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -56,9 +74,9 @@ ImagePreview({
 ### Close Event
 
 ```js
-import { Toast } from 'vant';
+import { Toast, showImagePreview } from 'vant';
 
-ImagePreview({
+showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -72,7 +90,9 @@ ImagePreview({
 ### Before Close
 
 ```js
-const instance = ImagePreview({
+import { showImagePreview } from 'vant';
+
+const instance = showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',

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

@@ -2,61 +2,42 @@
 
 ### 介绍
 
-图片放大预览，支持函数调用和组件调用两种方式。
+图片放大预览，支持组件调用和函数调用两种方式。
 
-### 函数调用
+### 引入
 
-`ImagePreview` 是一个函数，调用函数后会直接在页面中展示图片预览界面。
+通过以下方式来全局注册组件，更多注册方式请参考[组件注册](#/zh-CN/advanced-usage#zu-jian-zhu-ce)。
-
-```js
-import { ImagePreview } from 'vant';
-
-ImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);
-```
-
-### 组件调用
-
-通过组件调用 `ImagePreview` 时，可以通过下面的方式进行注册。
 
 ```js
 import { createApp } from 'vue';
 import { ImagePreview } from 'vant';
 
-// 全局注册
 const app = createApp();
 app.use(ImagePreview);
-
-// 局部注册
-export default {
-  components: {
-    [ImagePreview.Component.name]: ImagePreview.Component,
-  },
-};
 ```
 
-在 `script setup` 中，可以通过以下方式使用：
+### 函数调用
 
-```html
+为了便于使用 `ImagePreview`，Vant 提供了一系列辅助函数，通过辅助函数可以快速唤起全局的弹窗组件。
-<script setup>
-  const VanImagePreview = ImagePreview.Component;
-</script>
 
-<template>
+比如使用 `showImagePreview` 函数，调用后会直接在页面中渲染对应的图片预览组件。
-  <!-- 中划线命名 -->
+
-  <van-image-preview />
+```js
-  <!-- 也支持大驼峰命名 -->
+import { showImagePreview } from 'vant';
-  <VanImagePreview>
+
-</template>
+showImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);
 ```
 
 ## 代码演示
 
 ### 基础用法
 
-直接传入图片数组，即可展示图片预览。
+在调用 `showImagePreview` 时，直接传入图片数组，即可展示图片预览。
 
 ```js
-ImagePreview([
+import { showImagePreview } from 'vant';
+
+showImagePreview([
   'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
   'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
 ]);
@@ -64,10 +45,12 @@ ImagePreview([
 
 ### 指定初始位置
 
-`ImagePreview` 支持传入配置对象，并通过 `startPosition` 选项指定图片的初始位置（索引值）。
+`showImagePreview` 支持传入配置对象，并通过 `startPosition` 选项指定图片的初始位置（索引值）。
 
 ```js
-ImagePreview({
+import { showImagePreview } from 'vant';
+
+showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -81,7 +64,9 @@ ImagePreview({
 设置 `closeable` 属性后，会在弹出层的右上角显示关闭图标，并且可以通过 `close-icon` 属性自定义图标，使用`close-icon-position` 属性可以自定义图标位置。
 
 ```js
-ImagePreview({
+import { showImagePreview } from 'vant';
+
+showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -95,9 +80,9 @@ ImagePreview({
 通过 `onClose` 选项监听图片预览的关闭事件。
 
 ```js
-import { Toast } from 'vant';
+import { Toast, showImagePreview } from 'vant';
 
-ImagePreview({
+showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -113,7 +98,9 @@ ImagePreview({
 通过 `beforeClose` 属性可以拦截关闭行为。
 
 ```js
-const instance = ImagePreview({
+import { showImagePreview } from 'vant';
+
+const instance = showImagePreview({
   images: [
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
     'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
@@ -166,7 +153,7 @@ export default {
 
 ### Options
 
-通过函数调用 `ImagePreview` 时，支持传入以下选项：
+通过函数调用 `showImagePreview` 时，支持传入以下选项：
 
 | 参数名 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
@@ -307,16 +294,3 @@ imagePreviewRef.value?.swipeTo(1);
 ### 在桌面端无法操作组件？
 
 参见[桌面端适配](#/zh-CN/advanced-usage#zhuo-mian-duan-gua-pei)。
-
-### 在 JSX 中渲染 ImagePreview 组件无法展示？
-
-请注意 `ImagePreview` 是一个函数，`ImagePreview.Component` 才是 ImagePreview 对应的组件。JSX 调用图片预览的正确姿势如下：
-
-```jsx
-export default {
-  setup() {
-    const show = ref(false);
-    return () => <ImagePreview.Component v-model={[show, 'show']} />;
-  },
-};
-```

packages/vant/src/image-preview/demo/index.vue

@@ -1,12 +1,14 @@
 <script setup lang="ts">
 import VanCell from '../../cell';
-import { ImagePreview, ImagePreviewOptions } from '..';
+import {
+  showImagePreview,
+  ImagePreviewOptions,
+  ImagePreview as VanImagePreview,
+} from '..';
 import { ref } from 'vue';
 import { cdnURL, useTranslate } from '../../../docs/site';
 import { Toast } from '../../toast';
 
-const VanImagePreview = ImagePreview.Component;
-
 const t = useTranslate({
   'zh-CN': {
     closed: '关闭',
@@ -51,16 +53,16 @@ const beforeClose = () =>
     }, 1000);
   });
 
-const showComponentCall = () => {
-  show.value = true;
-};
-
 const onChange = (newIndex: number) => {
   index.value = newIndex;
 };
 
-const showImagePreview = (options: Partial<ImagePreviewOptions> = {}) => {
+const showComponentCall = () => {
-  const instance = ImagePreview({
+  show.value = true;
+};
+
+const showFunctionCall = (options: Partial<ImagePreviewOptions> = {}) => {
+  const instance = showImagePreview({
     images,
     ...options,
   });
@@ -75,24 +77,24 @@ const showImagePreview = (options: Partial<ImagePreviewOptions> = {}) => {
 
 <template>
   <demo-block card :title="t('basicUsage')">
-    <van-cell is-link :value="t('showImages')" @click="showImagePreview()" />
+    <van-cell is-link :value="t('showImages')" @click="showFunctionCall()" />
   </demo-block>
 
   <demo-block card :title="t('customConfig')">
     <van-cell
       is-link
       :value="t('startPosition')"
-      @click="showImagePreview({ startPosition: 1 })"
+      @click="showFunctionCall({ startPosition: 1 })"
     />
     <van-cell
       is-link
       :value="t('showClose')"
-      @click="showImagePreview({ closeable: true })"
+      @click="showFunctionCall({ closeable: true })"
     />
     <van-cell
       is-link
       :value="t('closeEvent')"
-      @click="showImagePreview({ onClose })"
+      @click="showFunctionCall({ onClose })"
     />
   </demo-block>
 
@@ -100,7 +102,7 @@ const showImagePreview = (options: Partial<ImagePreviewOptions> = {}) => {
     <van-cell
       is-link
       :value="t('beforeClose')"
-      @click="showImagePreview({ beforeClose })"
+      @click="showFunctionCall({ beforeClose })"
     />
   </demo-block>
 

packages/vant/src/image-preview/function-call.tsx

@@ -1,7 +1,6 @@
-import { extend, inBrowser, withInstall, ComponentInstance } from '../utils';
+import { extend, inBrowser, ComponentInstance } from '../utils';
 import { mountComponent, usePopupState } from '../utils/mount-component';
 import VanImagePreview from './ImagePreview';
-import type { App } from 'vue';
 import type { ImagePreviewOptions } from './types';
 
 let instance: ComponentInstance;
@@ -49,7 +48,7 @@ function initInstance() {
   }));
 }
 
-const ImagePreview = (
+export const showImagePreview = (
   options: string[] | ImagePreviewOptions,
   startPosition = 0
 ) => {
@@ -70,11 +69,3 @@ const ImagePreview = (
 
   return instance;
 };
-
-ImagePreview.Component = withInstall(VanImagePreview);
-
-ImagePreview.install = (app: App) => {
-  app.use(ImagePreview.Component);
-};
-
-export { ImagePreview };

packages/vant/src/image-preview/index.ts

@@ -1,8 +1,11 @@
-import { ImagePreview } from './function-call';
+import { withInstall } from '../utils';
+import _ImagePreview from './ImagePreview';
 import type { ImagePreviewProps } from './ImagePreview';
 
+export const ImagePreview = withInstall(_ImagePreview);
 export default ImagePreview;
-export { ImagePreview };
+export { showImagePreview } from './function-call';
+
 export type { ImagePreviewProps };
 export type {
   ImagePreviewOptions,

packages/vant/src/image-preview/test/function-call.spec.ts

@@ -1,22 +1,11 @@
 import { later, triggerDrag, mockGetBoundingClientRect } from '../../../test';
-import { createApp, nextTick } from 'vue';
+import { nextTick } from 'vue';
-import { ImagePreview } from '../function-call';
+import { showImagePreview } from '../function-call';
-import ImagePreviewComponent from '../ImagePreview';
 import { images, triggerZoom } from './shared';
 
-test('should expose ImagePreviewComponent in ImagePreview.Component', () => {
-  expect(ImagePreview.Component.name).toEqual('van-image-preview');
-});
-
-test('should register component to app', () => {
-  const app = createApp(document.body);
-  app.use(ImagePreview);
-  expect(app.component(ImagePreviewComponent.name)).toBeTruthy();
-});
-
 test('should allow to use the teleport option', async () => {
   const root = document.createElement('div');
-  ImagePreview({ images: [], teleport: root });
+  showImagePreview({ images: [], teleport: root });
 
   await later();
   expect(root.querySelector('.van-image-preview')).toBeTruthy();
@@ -24,7 +13,7 @@ test('should allow to use the teleport option', async () => {
 
 test('should trigger onClose option correctly', async () => {
   const onClose = jest.fn();
-  const instance = ImagePreview({
+  const instance = showImagePreview({
     images,
     startPosition: 1,
     onClose,
@@ -41,7 +30,7 @@ test('should trigger onClose option correctly', async () => {
 
 test('should trigger onChange option correctly', async () => {
   const onChange = jest.fn();
-  ImagePreview({
+  showImagePreview({
     images,
     startPosition: 0,
     onChange,
@@ -55,7 +44,7 @@ test('should trigger onChange option correctly', async () => {
 
 test('should trigger onScale option correctly', async () => {
   const restore = mockGetBoundingClientRect({ width: 100 });
-  ImagePreview({
+  showImagePreview({
     images,
     startPosition: 0,
     onScale({ index, scale }) {

packages/vant/src/uploader/Uploader.tsx

@@ -37,7 +37,7 @@ import { useExpose } from '../composables/use-expose';
 
 // Components
 import { Icon } from '../icon';
-import { ImagePreview, type ImagePreviewOptions } from '../image-preview';
+import { showImagePreview, type ImagePreviewOptions } from '../image-preview';
 import UploaderPreviewItem from './UploaderPreviewItem';
 
 // Types
@@ -238,7 +238,7 @@ export default defineComponent({
           })
           .filter(Boolean) as string[];
 
-        imagePreview = ImagePreview(
+        imagePreview = showImagePreview(
           extend(
             {
               images,