feat: add @vant/compat package (#10806)

* feat: add @vant/compat package

* chore: remove prepare script

packages/vant-compat/LICENSE

@@ -0,0 +1,10 @@
+MIT License
+
+Copyright (c) Youzan
+Copyright (c) Chen Jiahan and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

packages/vant-compat/README.md

@@ -0,0 +1,32 @@
+# @vant/compat
+
+This package provides Vant 3 compatible behavior for Vant 4 users.
+
+## Install
+
+```shell
+# with npm
+npm i @vant/compat
+
+# with yarn
+yarn add @vant/compat
+
+# with pnpm
+pnpm add @vant/compat
+```
+
+## Usage
+
+```js
+// Same as Toast in Vant 3
+import { Toast } from '@vant/compat';
+
+// Same as Dialog in Vant 3
+import { Dialog } from '@vant/compat';
+
+// Same as Notify in Vant 3
+import { Notify } from '@vant/compat';
+
+// Same as ImagePreview in Vant 3
+import { ImagePreview } from '@vant/compat';
+```

packages/vant-compat/build.js

@@ -0,0 +1 @@
+require('../vant-use/build');

packages/vant-compat/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@vant/compat",
+  "version": "1.0.0",
+  "description": "Provide Vant 3 compatible behavior for Vant 4",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.mjs",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "rimraf ./dist",
+    "dev": "node ./build.js -w",
+    "build:types": "tsc -p ./tsconfig.json --emitDeclarationOnly",
+    "build:bundle": "node ./build.js",
+    "build": "pnpm clean && pnpm build:bundle && pnpm build:types",
+    "release": "pnpm build && release-it"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/youzan/vant.git",
+    "directory": "packages/vant-compat"
+  },
+  "bugs": "https://github.com/youzan/vant/issues",
+  "author": "chenjiahan",
+  "license": "MIT",
+  "devDependencies": {
+    "@vue/runtime-core": "^3.2.27",
+    "vant": "workspace:*",
+    "vue": "^3.2.27",
+    "esbuild": "^0.14.29",
+    "release-it": "^15.1.1",
+    "typescript": "^4.7.4"
+  },
+  "release-it": {
+    "git": {
+      "tag": false,
+      "commitMessage": "release: @vant/compat ${version}"
+    }
+  }
+}

packages/vant-compat/src/dialog.ts

@@ -0,0 +1,30 @@
+import {
+  Dialog as VanDialog,
+  showDialog,
+  closeDialog,
+  showConfirmDialog,
+  setDialogDefaultOptions,
+  resetDialogDefaultOptions,
+} from 'vant';
+import type { App } from 'vue';
+
+export const Dialog = (...args: Parameters<typeof showDialog>) =>
+  showDialog(...args);
+
+Dialog.Component = VanDialog;
+Dialog.alert = Dialog;
+Dialog.config = showConfirmDialog;
+Dialog.close = closeDialog;
+Dialog.setDefaultOptions = setDialogDefaultOptions;
+Dialog.resetDefaultOptions = resetDialogDefaultOptions;
+
+Dialog.install = (app: App) => {
+  app.use(Dialog.Component);
+  app.config.globalProperties.$dialog = Dialog;
+};
+
+declare module '@vue/runtime-core' {
+  interface ComponentCustomProperties {
+    $dialog: typeof Dialog;
+  }
+}

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

@@ -0,0 +1,11 @@
+import { ImagePreview as VanImagePreview, showImagePreview } from 'vant';
+import type { App } from 'vue';
+
+export const ImagePreview = (...args: Parameters<typeof showImagePreview>) =>
+  showImagePreview(...args);
+
+ImagePreview.Component = VanImagePreview;
+
+ImagePreview.install = (app: App) => {
+  app.use(ImagePreview.Component);
+};

packages/vant-compat/src/index.ts

@@ -0,0 +1,4 @@
+export * from './toast';
+export * from './notify';
+export * from './dialog';
+export * from './image-preview';

packages/vant-compat/src/notify.ts

@@ -0,0 +1,27 @@
+import {
+  Notify as VanNotify,
+  showNotify,
+  closeNotify,
+  setNotifyDefaultOptions,
+  resetNotifyDefaultOptions,
+} from 'vant';
+import type { App } from 'vue';
+
+export const Notify = (...args: Parameters<typeof showNotify>) =>
+  showNotify(...args);
+
+Notify.clear = closeNotify;
+Notify.Component = VanNotify;
+Notify.setDefaultOptions = setNotifyDefaultOptions;
+Notify.resetDefaultOptions = resetNotifyDefaultOptions;
+
+Notify.install = (app: App) => {
+  app.use(Notify.Component);
+  app.config.globalProperties.$notify = Notify;
+};
+
+declare module '@vue/runtime-core' {
+  interface ComponentCustomProperties {
+    $notify: typeof Notify;
+  }
+}

packages/vant-compat/src/toast.ts

@@ -0,0 +1,49 @@
+import {
+  showToast,
+  closeToast,
+  showFailToast,
+  showSuccessToast,
+  allowMultipleToast,
+  setToastDefaultOptions,
+  resetToastDefaultOptions,
+} from 'vant';
+import type { App } from 'vue';
+
+export const Toast = (...args: Parameters<typeof showToast>) => {
+  const toast = showToast(...args);
+  return {
+    clear: toast.close,
+    ...toast,
+  };
+};
+
+Toast.fail = (...args: Parameters<typeof showFailToast>) => {
+  const toast = showFailToast(...args);
+  return {
+    clear: toast.close,
+    ...toast,
+  };
+};
+
+Toast.success = (...args: Parameters<typeof showSuccessToast>) => {
+  const toast = showSuccessToast(...args);
+  return {
+    clear: toast.close,
+    ...toast,
+  };
+};
+
+Toast.clear = closeToast;
+Toast.allowMultiple = allowMultipleToast;
+Toast.setDefaultOptions = setToastDefaultOptions;
+Toast.resetDefaultOptions = resetToastDefaultOptions;
+
+Toast.install = (app: App) => {
+  app.config.globalProperties.$toast = Toast;
+};
+
+declare module '@vue/runtime-core' {
+  interface ComponentCustomProperties {
+    $toast: typeof Toast;
+  }
+}

packages/vant-compat/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}

packages/vant-popperjs/package.json

@@ -31,7 +31,7 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/youzan/vant.git",
-    "directory": "packages/vant-markdown-loader"
+    "directory": "packages/vant-popperjs"
   },
   "bugs": "https://github.com/youzan/vant/issues",
   "author": "chenjiahan",

packages/vant-use/build.js

@@ -14,7 +14,7 @@ function bundleBundle(format) {
     outfile,
     // preserve Chinese character
     charset: 'utf8',
-    external: ['vue'],
+    external: ['vue', 'vant'],
     entryPoints: ['./src/index.ts'],
   }).then(finish);
 }

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

@@ -89,36 +89,16 @@ Dialog.setDefaultOptions(); // -> setDialogDefaultOptions()
 Dialog.resetDefaultOptions(); // -> resetDialogDefaultOptions()
 ```
 
-同时，Vant 4 将不再在 `this` 对象上全局注册 `$dialog` 方法，这意味着 `this` 对象上将无法访问到 `$dialog`。
+为了便于代码迁移，你可以使用 `@vant/compat` 中导出的 `Dialog` 对象：
 
 ```js
-export default {
-  mounted() {
-    // 无效代码
-    this.$dialog.alert({
-      message: '弹窗内容',
-    });
-  },
-};
+import { Dialog } from '@vant/compat';
+
+Dialog();
+Dialog.close();
 ```
 
-大多数场景下，推荐通过 `import` 引入对应的函数进行使用。
-
-如果需要全局方法，可以手动在 `app` 对象上注册：
-
-```js
-import { showDialog } from 'vant';
-
-// 注册 $dialog 方法
-app.config.globalProperties.$dialog = showDialog;
-
-// 添加 TS 类型定义
-declare module '@vue/runtime-core' {
-  interface ComponentCustomProperties {
-    $dialog: typeof showDialog;
-  }
-}
-```
+`@vant/compat` 中导出的 `Dialog` 与 Vant 3 中的 `Dialog` 拥有完全一致的 API 和行为。
 
 ### Toast 调用方式调整
 
@@ -147,31 +127,17 @@ Toast.resetDefaultOptions(); // -> resetToastDefaultOptions()
 
 同时，Vant 4 将不再在 `this` 对象上全局注册 `$toast` 方法，这意味着 `this` 对象上将无法访问到 `$toast`。
 
-```js
-export default {
-  mounted() {
-    // 无效代码
-    this.$toast('内容');
-  },
-};
-```
-
-如果需要全局方法，可以手动在 `app` 对象上注册：
+为了便于代码迁移，你可以使用 `@vant/compat` 中导出的 `Toast` 对象：
 
 ```js
-import { showNotify } from 'vant';
+import { Toast } from '@vant/compat';
 
-// 注册 $notify 方法
-app.config.globalProperties.$toast = showNotify;
-
-// 添加 TS 类型定义
-declare module '@vue/runtime-core' {
-  interface ComponentCustomProperties {
-    $toast: typeof showToast;
-  }
-}
+Toast();
+Toast.clear();
 ```
 
+`@vant/compat` 中导出的 `Toast` 与 Vant 3 中的 `Toast` 拥有完全一致的 API 和行为。
+
 ### Notify 调用方式调整
 
 Vant 4 中，`Notify` 组件的调用方式也进行了调整，与 `Dialog` 组件的改动一致：
@@ -197,33 +163,17 @@ Notify.resetDefaultOptions(); // -> resetNotifyDefaultOptions()
 
 同时，Vant 4 将不再在 `this` 对象上全局注册 `$notify` 方法，这意味着 `this` 对象上将无法访问到 `$notify`。
 
-```js
-export default {
-  mounted() {
-    // 无效代码
-    this.$notify({
-      message: '内容',
-    });
-  },
-};
-```
-
-如果需要全局方法，可以手动在 `app` 对象上注册：
+为了便于代码迁移，你可以使用 `@vant/compat` 中导出的 `Notify` 对象：
 
 ```js
-import { showNotify } from 'vant';
+import { Notify } from '@vant/compat';
 
-// 注册 $notify 方法
-app.config.globalProperties.$notify = showNotify;
-
-// 添加 TS 类型定义
-declare module '@vue/runtime-core' {
-  interface ComponentCustomProperties {
-    $notify: typeof showNotify;
-  }
-}
+Notify();
+Notify.clear();
 ```
 
+`@vant/compat` 中导出的 `Notify` 与 Vant 3 中的 `Notify` 拥有完全一致的 API 和行为。
+
 ### ImagePreview 调用方式调整
 
 Vant 4 中，`ImagePreview` 组件的调用方式也进行了调整，与 `ImagePreview` 组件的改动一致：
@@ -238,6 +188,16 @@ showImagePreview(); // 函数调用
 ImagePreview; // 组件对象
 ```
 
+为了便于代码迁移，你可以使用 `@vant/compat` 中导出的 `ImagePreview` 对象：
+
+```js
+import { ImagePreview } from '@vant/compat';
+
+ImagePreview();
+```
+
+`@vant/compat` 中导出的 `ImagePreview` 与 Vant 3 中的 `ImagePreview` 拥有完全一致的 API 和行为。
+
 ### 事件命名调整
 
 从 Vant 4 开始，所有的事件均采用 Vue 官方推荐的**驼峰格式**进行命名。

pnpm-lock.yaml

@@ -195,6 +195,22 @@ importers:
       react-dom: 18.2.0_react@18.2.0
       vue: 3.2.37
 
+  packages/vant-compat:
+    specifiers:
+      '@vue/runtime-core': ^3.2.27
+      esbuild: ^0.14.29
+      release-it: ^15.1.1
+      typescript: ^4.7.4
+      vant: workspace:*
+      vue: ^3.2.27
+    devDependencies:
+      '@vue/runtime-core': 3.2.37
+      esbuild: 0.14.48
+      release-it: 15.1.1
+      typescript: 4.7.4
+      vant: link:../vant
+      vue: 3.2.37
+
   packages/vant-eslint-config:
     specifiers:
       '@typescript-eslint/eslint-plugin': ^5.30.3