From f1d5376c9cd23c3912690ed4db1d9c2840c26cda Mon Sep 17 00:00:00 2001 From: neverland Date: Fri, 6 Oct 2023 10:12:52 +0800 Subject: [PATCH] feat(Dialog): add JSDoc for utility functions (#12343) --- packages/vant/src/dialog/README.md | 20 +++++++++++--------- packages/vant/src/dialog/README.zh-CN.md | 12 ++++++------ packages/vant/src/dialog/function-call.tsx | 15 +++++++++++++++ 3 files changed, 32 insertions(+), 15 deletions(-) diff --git a/packages/vant/src/dialog/README.md b/packages/vant/src/dialog/README.md index 769e724418c..92dbc10aabf 100644 --- a/packages/vant/src/dialog/README.md +++ b/packages/vant/src/dialog/README.md @@ -32,7 +32,7 @@ showDialog({ message: 'Content' }); ### Alert dialog -Used to prompt for some messages, only including one confirm button. +Used to prompt for some messages, only including one confirm button by default. ```js showDialog({ @@ -51,7 +51,7 @@ showDialog({ ### Confirm dialog -Used to confirm some messages, including a confirm button and a cancel button. +Used to confirm some messages, including a confirm button and a cancel button by default. ```js showConfirmDialog({ @@ -68,7 +68,7 @@ showConfirmDialog({ ### Round Button Style -Use round button style. +Setting the `theme` option to `round-button` will display the Dialog with a rounded button style. ```js showDialog({ @@ -89,6 +89,8 @@ showDialog({ ### Async Close +You can pass a callback function through the `beforeClose` option to perform specific operations before closing the Dialog. + ```js const beforeClose = (action) => new Promise((resolve) => { @@ -106,7 +108,7 @@ showConfirmDialog({ ### Use Dialog Component -If you need to render Vue components within a Dialog, you can use the Dialog component. +If you need to embed components or other custom content within a Dialog, you can directly use the Dialog component and customize it using the default slot. Before using it, you need to register the component using `app.use` or other methods. ```html @@ -133,11 +135,11 @@ Vant exports following Dialog utility functions: | Name | Description | Attribute | Return value | | --- | --- | --- | --- | -| showDialog | Show dialog | _options: DialogOptions_ | `Promise` | -| showConfirmDialog | 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` | +| showDialog | Display a message prompt dialog with a default confirm button | _options: DialogOptions_ | `Promise` | +| showConfirmDialog | Display a message confirmation dialog with default confirm and cancel buttons | _options: DialogOptions_ | `Promise` | +| closeDialog | Close the currently displayed dialog | - | `void` | +| setDialogDefaultOptions | Modify the default configuration that affects all `showDialog` calls | _options: DialogOptions_ | `void` | +| resetDialogDefaultOptions | Reset the default configuration that affects all `showDialog` calls | - | `void` | ### DialogOptions diff --git a/packages/vant/src/dialog/README.zh-CN.md b/packages/vant/src/dialog/README.zh-CN.md index 28b68cad520..8acdfc4b5bb 100644 --- a/packages/vant/src/dialog/README.zh-CN.md +++ b/packages/vant/src/dialog/README.zh-CN.md @@ -32,7 +32,7 @@ showDialog({ message: '提示' }); ### 消息提示 -用于提示一些消息，只包含一个确认按钮。 +用于提示一些消息，默认只包含一个确认按钮。 ```js import { showDialog } from 'vant'; @@ -53,7 +53,7 @@ showDialog({ ### 消息确认 -用于确认消息，包含取消和确认按钮。 +用于确认消息，默认包含确认和取消按钮。 ```js import { showConfirmDialog } from 'vant'; @@ -123,7 +123,7 @@ showConfirmDialog({ ### 使用 Dialog 组件 -如果需要在 Dialog 内嵌入组件或其他自定义内容，可以直接使用 Dialog 组件，并使用默认插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。 +如果你需要在 Dialog 内嵌入组件或其他自定义内容，可以直接使用 Dialog 组件，并使用默认插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。 ```html @@ -150,9 +150,9 @@ Vant 中导出了以下 Dialog 相关的辅助函数： | 方法名 | 说明 | 参数 | 返回值 | | --- | --- | --- | --- | -| showDialog | 展示弹窗 | _options: DialogOptions_ | `Promise` | -| showConfirmDialog | 展示消息确认弹窗 | _options: DialogOptions_ | `Promise` | -| closeDialog | 关闭弹窗 | - | `void` | +| showDialog | 展示消息提示弹窗，默认包含确认按钮 | _options: DialogOptions_ | `Promise` | +| showConfirmDialog | 展示消息确认弹窗，默认包含确认和取消按钮 | _options: DialogOptions_ | `Promise` | +| closeDialog | 关闭当前展示的弹窗 | - | `void` | | setDialogDefaultOptions | 修改默认配置，影响所有的 `showDialog` 调用 | _options: DialogOptions_ | `void` | | resetDialogDefaultOptions | 重置默认配置，影响所有的 `showDialog` 调用 | - | `void` | diff --git a/packages/vant/src/dialog/function-call.tsx b/packages/vant/src/dialog/function-call.tsx index 79f794aeb61..e6e5a8949f4 100644 --- a/packages/vant/src/dialog/function-call.tsx +++ b/packages/vant/src/dialog/function-call.tsx @@ -46,6 +46,9 @@ function initInstance() { ({ instance } = mountComponent(Wrapper)); } +/** + * Display a message prompt dialog with a default confirm button + */ export function showDialog( options: DialogOptions, ): Promise { @@ -69,17 +72,29 @@ export function showDialog( }); } +/** + * Modify the default configuration that affects all `showDialog` calls + */ export const setDialogDefaultOptions = (options: DialogOptions) => { extend(currentOptions, options); }; +/** + * Reset the default configuration that affects all `showDialog` calls + */ export const resetDialogDefaultOptions = () => { currentOptions = extend({}, DEFAULT_OPTIONS); }; +/** + * Display a message confirmation dialog with default confirm and cancel buttons + */ export const showConfirmDialog = (options: DialogOptions) => showDialog(extend({ showCancelButton: true }, options)); +/** + * Close the currently displayed dialog + */ export const closeDialog = () => { if (instance) { instance.toggle(false);