From 5d8282ddae16326a05338085a7787af82f47f881 Mon Sep 17 00:00:00 2001 From: neverland Date: Sat, 10 Sep 2022 11:40:11 +0800 Subject: [PATCH] docs(Toast): add component usage guide (#11019) --- packages/vant/src/toast/README.md | 55 +++++++++++++++---- packages/vant/src/toast/README.zh-CN.md | 45 ++++++++++++--- packages/vant/src/toast/demo/index.vue | 23 +++++++- .../test/__snapshots__/demo.spec.ts.snap | 16 ++++++ 4 files changed, 120 insertions(+), 19 deletions(-) diff --git a/packages/vant/src/toast/README.md b/packages/vant/src/toast/README.md index 0f489da62..dc7eba904 100644 --- a/packages/vant/src/toast/README.md +++ b/packages/vant/src/toast/README.md @@ -152,22 +152,47 @@ resetToastDefaultOptions(); resetToastDefaultOptions('loading'); ``` +### Use Toast Component + +If you want to render Vue components within a Toast, you can use the Toast component. + +```html + + + +``` + +```js +import { ref } from 'vue'; + +export default { + setup() { + const show = ref(false); + return { show }; + }, +}; +``` + ## API ### Methods -| Methods | Attribute | Return value | Description | -| --- | --- | --- | --- | -| showToast | `options \| message` | toast instance | Show toast | -| showLoadingToast | `options \| message` | toast instance | Show loading toast | -| showSuccessToast | `options \| message` | toast instance | Show success toast | -| showFailToast | `options \| message` | toast instance | Show fail toast | -| closeToast | `closeAll: boolean` | `void` | Close toast | -| allowMultipleToast | - | `void` | Allow multiple toast at the same time | -| setToastDefaultOptions | `type \| options` | `void` | Set default options of all toasts | -| resetToastDefaultOptions | `type` | `void` | Reset default options of all toasts | +Vant export following utility functions: -### Options +| Name | Description | Attribute | Return value | +| --- | --- | --- | --- | +| showToast | Show toast | `ToastOptions \| string` | toast instance | +| showLoadingToast | Show loading toast | `ToastOptions \| string` | toast instance | +| showSuccessToast | Show success toast | `ToastOptions \| string` | toast instance | +| showFailToast | Show fail toast | `ToastOptions \| string` | toast instance | +| closeToast | Close toast | `closeAll: boolean` | `void` | +| allowMultipleToast | Allow multiple toast at the same time | - | `void` | +| setToastDefaultOptions | Set default options of all toasts | `type \| ToastOptions` | `void` | +| resetToastDefaultOptions | Reset default options of all toasts | `type` | `void` | + +### ToastOptions | Attribute | Description | Type | Default | | --- | --- | --- | --- | @@ -191,6 +216,14 @@ resetToastDefaultOptions('loading'); | transition | Transition, equivalent to `name` prop of [transition](https://v3.vuejs.org/api/built-in-components.html#transition) | _string_ | `van-fade` | | teleport | Specifies a target element where Toast will be mounted | _string \| Element_ | `body` | +### Slots + +You can use following slots when using `Toast` component: + +| Name | Description | +| ------- | -------------- | +| message | Custom message | + ### Types The component exports the following type definitions: diff --git a/packages/vant/src/toast/README.zh-CN.md b/packages/vant/src/toast/README.zh-CN.md index 573af94ea..fc5e43a83 100644 --- a/packages/vant/src/toast/README.zh-CN.md +++ b/packages/vant/src/toast/README.zh-CN.md @@ -135,8 +135,6 @@ const timer = setInterval(() => { }, 1000); ``` -> Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。 - ### 单例模式 Toast 默认采用单例模式，即同一时间只会存在一个 Toast，如果需要在同一时间弹出多个 Toast，可以参考下面的示例： @@ -169,19 +167,44 @@ resetToastDefaultOptions(); resetToastDefaultOptions('loading'); ``` +### 使用 Toast 组件 + +如果需要在 Toast 内嵌入组件或其他自定义内容，可以直接使用 Toast 组件，并使用 message 插槽进行定制。 + +```html + + + +``` + +```js +import { ref } from 'vue'; + +export default { + setup() { + const show = ref(false); + return { show }; + }, +}; +``` + ## API ### 方法 +Vant 中导出了以下 Toast 辅助函数： + | 方法名 | 说明 | 参数 | 返回值 | | --- | --- | --- | --- | -| showToast | 展示提示 | `options \| message` | toast 实例 | -| showLoadingToast | 展示加载提示 | `options \| message` | toast 实例 | -| showSuccessToast | 展示成功提示 | `options \| message` | toast 实例 | -| showFailToast | 展示失败提示 | `options \| message` | toast 实例 | +| showToast | 展示提示 | `ToastOptions \| string` | toast 实例 | +| showLoadingToast | 展示加载提示 | `ToastOptions \| string` | toast 实例 | +| showSuccessToast | 展示成功提示 | `ToastOptions \| string` | toast 实例 | +| showFailToast | 展示失败提示 | `ToastOptions \| string` | toast 实例 | | closeToast | 关闭提示 | `closeAll: boolean` | `void` | | allowMultipleToast | 允许同时存在多个 Toast | - | `void` | -| setToastDefaultOptions | 修改默认配置，影响所有的 `showToast` 调用。
传入 type 可以修改指定类型的默认配置 | `type \| options` | `void` | +| setToastDefaultOptions | 修改默认配置，影响所有的 `showToast` 调用。
传入 type 可以修改指定类型的默认配置 | `type \| ToastOptions` | `void` | | resetToastDefaultOptions | 重置默认配置，影响所有的 `showToast` 调用。
传入 type 可以重置指定类型的默认配置 | `type` | `void` | ### ToastOptions 数据结构 @@ -208,6 +231,14 @@ resetToastDefaultOptions('loading'); | transition | 动画类名，等价于 [transition](https://v3.cn.vuejs.org/api/built-in-components.html#transition) 的`name`属性 | _string_ | `van-fade` | | teleport | 指定挂载的节点，等同于 Teleport 组件的 [to 属性](https://v3.cn.vuejs.org/api/built-in-components.html#teleport) | _string \| Element_ | `body` | +### Slots + +使用 `Toast` 组件时，支持以下插槽： + +| 名称 | 说明 | +| ------- | -------------- | +| message | 自定义文本内容 | + ### 类型定义 组件导出以下类型定义： diff --git a/packages/vant/src/toast/demo/index.vue b/packages/vant/src/toast/demo/index.vue index 6826814f7..6e7a48d7d 100644 --- a/packages/vant/src/toast/demo/index.vue +++ b/packages/vant/src/toast/demo/index.vue @@ -1,7 +1,9 @@ diff --git a/packages/vant/src/toast/test/__snapshots__/demo.spec.ts.snap b/packages/vant/src/toast/test/__snapshots__/demo.spec.ts.snap index b2bbb1a92..f11efc1e7 100644 --- a/packages/vant/src/toast/test/__snapshots__/demo.spec.ts.snap +++ b/packages/vant/src/toast/test/__snapshots__/demo.spec.ts.snap @@ -129,4 +129,20 @@ exports[`should render demo and match snapshot 1`] = ` +
+
+
+ + Use Toast Component + +
+ + +
+ + +
`;