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

2025-04-05 19:41:42 +08:00 · 2022-07-09 15:32:02 +08:00 · 2022-07-09 15:32:02 +08:00 · 1bc6cbdb69
commit 1bc6cbdb69
parent 5f526c9f0e
9 changed files with 99 additions and 119 deletions
--- a/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md
+++ b/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 官方推荐的**驼峰格式**进行命名。
--- a/packages/vant/src/dialog/README.zh-CN.md
+++ b/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']} />;
-  },
-};
-```
--- a/packages/vant/src/image-preview/README.md
+++ b/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',
--- a/packages/vant/src/image-preview/README.zh-CN.md
+++ b/packages/vant/src/image-preview/README.zh-CN.md
@ -2,61 +2,42 @@

 ### 介绍

-图片放大预览，支持函数调用和组件调用两种方式。
+图片放大预览，支持组件调用和函数调用两种方式。

-### 函数调用
+### 引入

-`ImagePreview` 是一个函数，调用函数后会直接在页面中展示图片预览界面。
-
-```js
-import { ImagePreview } from 'vant';
-
-ImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);
-```
-
-### 组件调用
-
-通过组件调用 `ImagePreview` 时，可以通过下面的方式进行注册。
+通过以下方式来全局注册组件，更多注册方式请参考[组件注册](#/zh-CN/advanced-usage#zu-jian-zhu-ce)。

 ```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
-<script setup>
-  const VanImagePreview = ImagePreview.Component;
-</script>
+为了便于使用 `ImagePreview`，Vant 提供了一系列辅助函数，通过辅助函数可以快速唤起全局的弹窗组件。

-<template>
-  <!-- 中划线命名 -->
-  <van-image-preview />
-  <!-- 也支持大驼峰命名 -->
-  <VanImagePreview>
-</template>
+比如使用 `showImagePreview` 函数，调用后会直接在页面中渲染对应的图片预览组件。
+
+```js
+import { showImagePreview } from 'vant';
+
+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']} />;
-  },
-};
-```
--- a/packages/vant/src/image-preview/demo/index.vue
+++ b/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 instance = ImagePreview({
+const showComponentCall = () => {
+  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>

--- a/packages/vant/src/image-preview/function-call.tsx
+++ b/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 };
--- a/packages/vant/src/image-preview/index.ts
+++ b/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,
--- a/packages/vant/src/image-preview/test/function-call.spec.ts
+++ b/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 { ImagePreview } from '../function-call';
-import ImagePreviewComponent from '../ImagePreview';
+import { nextTick } from 'vue';
+import { showImagePreview } from '../function-call';
 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 }) {
--- a/packages/vant/src/uploader/Uploader.tsx
+++ b/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,