docs(Toast): add component usage guide (#11019)

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
+<van-toast v-model:show="show" style="padding: 0">
+  <template #message>
+    <van-image :src="image" width="200" height="140" style="display: block" />
+  </template>
+</van-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const show = ref(false);
+    return { show };
+  },
+};
+```
+
 ## API
 
 ### Methods
 
-| Methods | Attribute | Return value | Description |
+Vant export following utility functions:
-| --- | --- | --- | --- |
-| 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 |
 
-### 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:

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
+<van-toast v-model:show="show" style="padding: 0">
+  <template #message>
+    <van-image :src="image" width="200" height="140" style="display: block" />
+  </template>
+</van-toast>
+```
+
+```js
+import { ref } from 'vue';
+
+export default {
+  setup() {
+    const show = ref(false);
+    return { show };
+  },
+};
+```
+
 ## API
 
 ### 方法
 
+Vant 中导出了以下 Toast 辅助函数：
+
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| showToast | 展示提示 | `options \| message` | toast 实例 |
+| showToast | 展示提示 | `ToastOptions \| string` | toast 实例 |
-| showLoadingToast | 展示加载提示 | `options \| message` | toast 实例 |
+| showLoadingToast | 展示加载提示 | `ToastOptions \| string` | toast 实例 |
-| showSuccessToast | 展示成功提示 | `options \| message` | toast 实例 |
+| showSuccessToast | 展示成功提示 | `ToastOptions \| string` | toast 实例 |
-| showFailToast | 展示失败提示 | `options \| message` | toast 实例 |
+| showFailToast | 展示失败提示 | `ToastOptions \| string` | toast 实例 |
 | closeToast | 关闭提示 | `closeAll: boolean` | `void` |
 | allowMultipleToast | 允许同时存在多个 Toast | - | `void` |
-| setToastDefaultOptions | 修改默认配置，影响所有的 `showToast` 调用。<br>传入 type 可以修改指定类型的默认配置 | `type \| options` | `void` |
+| setToastDefaultOptions | 修改默认配置，影响所有的 `showToast` 调用。<br>传入 type 可以修改指定类型的默认配置 | `type \| ToastOptions` | `void` |
 | resetToastDefaultOptions | 重置默认配置，影响所有的 `showToast` 调用。<br>传入 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 | 自定义文本内容 |
+
 ### 类型定义
 
 组件导出以下类型定义：

packages/vant/src/toast/demo/index.vue

@@ -1,7 +1,9 @@
 <script setup lang="ts">
+import { ref } from 'vue';
 import VanCell from '../../cell';
+import VanImage from '../../image';
 import { cdnURL, useTranslate } from '../../../docs/site';
-import {
+import VanToast, {
   showToast,
   closeToast,
   showFailToast,
@@ -25,6 +27,7 @@ const t = useTranslate({
     customImage: '自定义图片',
     loadingType: '自定义加载图标',
     positionTop: '顶部展示',
+    useComponent: '使用 Toast 组件',
     updateMessage: '动态更新提示',
     positionBottom: '底部展示',
     customPosition: '自定义位置',
@@ -43,6 +46,7 @@ const t = useTranslate({
     customImage: 'Custom Image',
     loadingType: 'Loading Type',
     positionTop: 'Top',
+    useComponent: 'Use Toast Component',
     updateMessage: 'Update Message',
     positionBottom: 'Bottom',
     customPosition: 'Custom Position',
@@ -103,6 +107,9 @@ const showCustomToast = () => {
     }
   }, 1000);
 };
+
+const show = ref(false);
+const image = cdnURL('cat.jpeg');
 </script>
 
 <template>
@@ -139,4 +146,18 @@ const showCustomToast = () => {
   <demo-block card :title="t('updateMessage')">
     <van-cell is-link :title="t('updateMessage')" @click="showCustomToast" />
   </demo-block>
+
+  <demo-block card :title="t('useComponent')">
+    <van-cell is-link :title="t('useComponent')" @click="show = true" />
+    <van-toast v-model:show="show" style="padding: 0">
+      <template #message>
+        <van-image
+          :src="image"
+          width="200"
+          height="140"
+          style="display: block"
+        />
+      </template>
+    </van-toast>
+  </demo-block>
 </template>

packages/vant/src/toast/test/__snapshots__/demo.spec.ts.snap

@@ -129,4 +129,20 @@ exports[`should render demo and match snapshot 1`] = `
     </i>
   </div>
 </div>
+<div>
+  <div class="van-cell van-cell--clickable"
+       role="button"
+       tabindex="0"
+  >
+    <div class="van-cell__title">
+      <span>
+        Use Toast Component
+      </span>
+    </div>
+    <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">
+    </i>
+  </div>
+  <transition-stub>
+  </transition-stub>
+</div>
 `;