From e5e6e8aaa492961e3b065fe760a7448caa3cd9ce Mon Sep 17 00:00:00 2001 From: neverland Date: Sun, 3 Jul 2022 12:28:25 +0800 Subject: [PATCH] refactor(Dialog): redesign function-call API (#10781) * refactor(Dialog): re-design function-call API * chore: remove invalid char * docs: order * chore: remove var --- .../docs/markdown/migrate-from-v3.zh-CN.md | 58 ++++++++++ packages/vant/src/dialog/README.md | 51 ++++----- packages/vant/src/dialog/README.zh-CN.md | 90 +++++---------- packages/vant/src/dialog/demo/index.vue | 16 ++- packages/vant/src/dialog/function-call.tsx | 106 ++++++++---------- packages/vant/src/dialog/index.ts | 15 ++- .../__snapshots__/funciton-call.spec.jsx.snap | 9 -- ...nciton-call.spec.jsx => function-call.jsx} | 52 ++++----- packages/vant/src/dialog/types.ts | 7 -- packages/vant/src/swipe-cell/README.md | 4 +- packages/vant/src/swipe-cell/README.zh-CN.md | 4 +- packages/vant/src/swipe-cell/demo/index.vue | 4 +- packages/vant/src/switch/README.md | 4 +- packages/vant/src/switch/README.zh-CN.md | 4 +- packages/vant/src/switch/demo/index.vue | 4 +- 15 files changed, 217 insertions(+), 211 deletions(-) delete mode 100644 packages/vant/src/dialog/test/__snapshots__/funciton-call.spec.jsx.snap rename packages/vant/src/dialog/test/{funciton-call.spec.jsx => function-call.jsx} (56%) diff --git a/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md b/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md index 24e92260d..22a0df264 100644 --- a/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md +++ b/packages/vant/docs/markdown/migrate-from-v3.zh-CN.md @@ -62,6 +62,64 @@ Area 组件是基于 Picker 组件进行封装的，因此本次升级也对 Are ## API 调整 +### Dialog 调用方式调整 + +在 Vant 3 中，`Dialog` 是一个函数，调用函数可以快速唤起全局的弹窗组件，而 `Dialog.Component` 才是 `Dialog` 组件对象，这与大部分组件的用法存在差异，容易导致使用错误。 + +为了更符合直觉，我们在 Vant 4 中调整了 `Dialog` 的调用方式，将 `Dialog()` 函数重命名为 `openDialog()`。 + +```js +// Vant 3 +Dialog(); // 函数调用 +Dialog.Component; // 组件对象 + +// Vant 4 +openDialog(); // 函数调用 +Dialog; // 组件对象 +``` + +`Dialog` 上挂载的其他方法也进行了重命名，新旧 API 的映射关系如下： + +```js +Dialog(); // -> openDialog() +Dialog.alert(); // -> openDialog() +Dialog.confirm(); // -> openConfirmDialog() +Dialog.close(); // -> closeDialog(); +Dialog.setDefaultOptions(); // -> setDialogDefaultOptions() +Dialog.resetDefaultOptions(); // -> resetDialogDefaultOptions() +``` + +同时，Vant 4 将不再在 `this` 对象上全局注册 `$dialog` 方法，这意味着 `this` 对象上将无法访问到 `$dialog`。 + +```js +export default { + mounted() { + // 无效代码 + this.$dialog.alert({ + message: '弹窗内容', + }); + }, +}; +``` + +大多数场景下，推荐通过 `import` 引入对应的函数进行使用。 + +如果需要全局方法，可以手动在 `app` 对象上注册： + +```js +import { openDialog } from 'vant'; + +// 注册 $dialog 方法 +app.config.globalProperties.$dialog = openDialog; + +// 添加 TS 类型定义 +declare module '@vue/runtime-core' { + interface ComponentCustomProperties { + $dialog: typeof openDialog; + } +} +``` + ### 事件命名调整 从 Vant 4 开始，所有的事件均采用 Vue 官方推荐的**驼峰格式**进行命名。 diff --git a/packages/vant/src/dialog/README.md b/packages/vant/src/dialog/README.md index 5bf6a5ecb..ef00fb3dc 100644 --- a/packages/vant/src/dialog/README.md +++ b/packages/vant/src/dialog/README.md @@ -2,7 +2,7 @@ ### Intro -A modal box pops up on the page, which is often used for message prompts, message confirmation, or to complete specific interactive operations in the current page. It supports two methods: function call and component call. +A modal box pops up on the page, which is often used for message prompts, message confirmation, or to complete specific interactive operations in the current page. It supports two methods: component call and function call. ### Install @@ -16,6 +16,18 @@ const app = createApp(); app.use(Dialog); ``` +### Function Call + +Vant provides some utility functions that can quickly evoke global `Dialog` components. + +For example, calling the `openDialog` function will render a Dialog directly in the page. + +```js +import { openDialog } from 'vant'; + +openDialog({ message: 'Content' }); +``` + ## Usage ### Alert dialog @@ -23,14 +35,14 @@ app.use(Dialog); Used to prompt for some messages, only including one confirm button. ```js -Dialog.alert({ +openDialog({ title: 'Title', message: 'Content', }).then(() => { // on close }); -Dialog.alert({ +openDialog({ message: 'Content', }).then(() => { // on close @@ -42,7 +54,7 @@ Dialog.alert({ Used to confirm some messages, including a confirm button and a cancel button. ```js -Dialog.confirm({ +openConfirmDialog({ title: 'Title', message: 'Content', }) @@ -59,7 +71,7 @@ Dialog.confirm({ Use round button style. ```js -Dialog.alert({ +openDialog({ title: 'Title', message: 'Content', theme: 'round-button', @@ -67,7 +79,7 @@ Dialog.alert({ // on close }); -Dialog.alert({ +openDialog({ message: 'Content', theme: 'round-button', }).then(() => { @@ -85,27 +97,13 @@ const beforeClose = (action) => }, 1000); }); -Dialog.confirm({ +openConfirmDialog({ title: 'Title', message: 'Content', beforeClose, }); ``` -### Global Method - -After registering the Dialog component through `app.use`, the `$dialog` method will be automatically mounted on all subComponents of the app. - -```js -export default { - mounted() { - this.$dialog.alert({ - message: 'Content', - }); - }, -}; -``` - ### Advanced Usage If you need to render vue components within a dialog, you can use dialog component. @@ -133,12 +131,11 @@ export default { | Name | Description | Attribute | Return value | | --- | --- | --- | --- | -| Dialog | Show dialog | _options: DialogOptions_ | `Promise` | -| Dialog.alert | Show alert dialog | _options: DialogOptions_ | `Promise` | -| Dialog.confirm | Show confirm dialog | _options: DialogOptions_ | `Promise` | -| Dialog.setDefaultOptions | Set default options of all dialogs | _options: DialogOptions_ | `void` | -| Dialog.resetDefaultOptions | Reset default options of all dialogs | - | `void` | -| Dialog.close | Close dialog | - | `void` | +| openDialog | Show dialog | _options: DialogOptions_ | `Promise` | +| openConfirmDialog | Show confirm dialog | _options: DialogOptions_ | `Promise` | +| closeDialog | Close dialog | - | `void` | +| setDialogDefaultOptions | Set default options of all dialogs | _options: DialogOptions_ | `void` | +| resetDialogDefaultOptions | Reset default options of all dialogs | - | `void` | ### DialogOptions diff --git a/packages/vant/src/dialog/README.zh-CN.md b/packages/vant/src/dialog/README.zh-CN.md index a3abe3de5..fa686abdf 100644 --- a/packages/vant/src/dialog/README.zh-CN.md +++ b/packages/vant/src/dialog/README.zh-CN.md @@ -2,51 +2,30 @@ ### 介绍 -弹出模态框，常用于消息提示、消息确认，或在当前页面内完成特定的交互操作，支持函数调用和组件调用两种方式。 +弹出模态框，常用于消息提示、消息确认，或在当前页面内完成特定的交互操作。支持组件调用和函数调用两种方式。 -### 函数调用 +### 引入 -`Dialog` 是一个函数，调用后会直接在页面中弹出相应的模态框。 - -```js -import { Dialog } from 'vant'; - -Dialog({ message: '提示' }); -``` - -### 组件调用 - -通过组件调用 Dialog 时，可以通过下面的方式进行注册： +通过以下方式来全局注册组件，更多注册方式请参考[组件注册](#/zh-CN/advanced-usage#zu-jian-zhu-ce)。 ```js import { createApp } from 'vue'; import { Dialog } from 'vant'; -// 全局注册 const app = createApp(); app.use(Dialog); - -// 局部注册 -export default { - components: { - [Dialog.Component.name]: Dialog.Component, - }, -}; ``` -在 `script setup` 中，可以通过以下方式使用： +### 函数调用 -```html - +为了便于使用 `Dialog`，Vant 提供了一系列辅助函数，通过辅助函数可以快速唤起全局的弹窗组件。 - +比如使用 `openDialog` 函数，调用后会直接在页面中渲染对应的弹出框。 + +```js +import { openDialog } from 'vant'; + +openDialog({ message: '提示' }); ``` ## 代码演示 @@ -56,14 +35,16 @@ export default { 用于提示一些消息，只包含一个确认按钮。 ```js -Dialog.alert({ +import { openDialog } from 'vant'; + +openDialog({ title: '标题', message: '代码是写出来给人看的，附带能在机器上运行。', }).then(() => { // on close }); -Dialog.alert({ +openDialog({ message: '生命远不止连轴转和忙到极限，人类的体验远比这辽阔、丰富得多。', }).then(() => { // on close @@ -75,7 +56,9 @@ Dialog.alert({ 用于确认消息，包含取消和确认按钮。 ```js -Dialog.confirm({ +import { openConfirmDialog } from 'vant'; + +openConfirmDialog({ title: '标题', message: '如果解决方法是丑陋的，那就肯定还有更好的解决方法，只是还没有发现而已。', @@ -93,7 +76,9 @@ Dialog.confirm({ 将 theme 选项设置为 `round-button` 可以展示圆角按钮风格的弹窗。 ```js -Dialog.alert({ +import { openDialog } from 'vant'; + +openDialog({ title: '标题', message: '代码是写出来给人看的，附带能在机器上运行。', theme: 'round-button', @@ -101,7 +86,7 @@ Dialog.alert({ // on close }); -Dialog.alert({ +openDialog({ message: '生命远不止连轴转和忙到极限，人类的体验远比这辽阔、丰富得多。', theme: 'round-button', }).then(() => { @@ -114,6 +99,8 @@ Dialog.alert({ 通过 `beforeClose` 属性可以传入一个回调函数，在弹窗关闭前进行特定操作。 ```js +import { openConfirmDialog } from 'vant'; + const beforeClose = (action) => new Promise((resolve) => { setTimeout(() => { @@ -126,7 +113,7 @@ const beforeClose = (action) => }, 1000); }); -Dialog.confirm({ +openConfirmDialog({ title: '标题', message: '如果解决方法是丑陋的，那就肯定还有更好的解决方法，只是还没有发现而已。', @@ -134,22 +121,6 @@ Dialog.confirm({ }); ``` -### 全局方法 - -通过 `app.use` 全局注册 Dialog 组件后，会自动在 app 的所有子组件上挂载 `$dialog` 方法，在所有组件内部都可以直接调用此方法。 - -```js -export default { - mounted() { - this.$dialog.alert({ - message: '弹窗内容', - }); - }, -}; -``` - -> Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。 - ### 组件调用 如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式。 @@ -177,12 +148,11 @@ export default { | 方法名 | 说明 | 参数 | 返回值 | | --- | --- | --- | --- | -| Dialog | 展示弹窗 | _options: DialogOptions_ | `Promise` | -| Dialog.alert | 展示消息提示弹窗 | _options: DialogOptions_ | `Promise` | -| Dialog.confirm | 展示消息确认弹窗 | _options: DialogOptions_ | `Promise` | -| Dialog.setDefaultOptions | 修改默认配置，对所有 Dialog 生效 | _options: DialogOptions_ | `void` | -| Dialog.resetDefaultOptions | 重置默认配置，对所有 Dialog 生效 | - | `void` | -| Dialog.close | 关闭弹窗 | - | `void` | +| openDialog | 展示弹窗 | _options: DialogOptions_ | `Promise` | +| openConfirmDialog | 展示消息确认弹窗 | _options: DialogOptions_ | `Promise` | +| closeDialog | 关闭弹窗 | - | `void` | +| setDialogDefaultOptions | 修改默认配置，影响所有的 `openDialog` 调用 | _options: DialogOptions_ | `void` | +| resetDialogDefaultOptions | 重置默认配置，影响所有的 `openDialog` 调用 | - | `void` | ### DialogOptions diff --git a/packages/vant/src/dialog/demo/index.vue b/packages/vant/src/dialog/demo/index.vue index a4ab23883..341d8b152 100644 --- a/packages/vant/src/dialog/demo/index.vue +++ b/packages/vant/src/dialog/demo/index.vue @@ -1,12 +1,10 @@