docs: improve use component guide (#11020)

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

@@ -83,20 +83,23 @@ import 'vant/lib/index.css';
 
 DatetimePicker 组件被拆分为：
 
-- TimePicker: 用于时间选择。
-- DatePicker: 用于日期选择。
+- [TimePicker](#/zh-CN/time-picker): 用于时间选择。
+- [DatePicker](#/zh-CN/date-picker): 用于日期选择。
+- [PickerGroup](#/zh-CN/picker-group): 用于用于结合多个 Picker 选择器组件。
 
-同时，这两个组件也基于新版 Picker 组件进行重构，并优化了部分 API 设计。
+同时，TimePicker 和 DatePicker 组件也基于新版 Picker 组件进行重构，并优化了部分 API 设计。
 
 #### 主要变更
 
+以下是 TimePicker 和 DatePicker 的主要 API 变化，更多细节请参考 [TimePicker](#/zh-CN/time-picker) 和 [DatePicker](#/zh-CN/date-picker) 文档。
+
 - `v-model` 绑定的值调整为数组格式
 - 新增 `columns-type` 属性，用于控制选项类型和顺序
 - 移除 `type` 属性和 `columns-order` 属性
 - 移除 `getPicker` 方法
 - 调整 `confirm`、`cancel`、`change` 事件的参数，与 Picker 组件保持一致
 
-> 详细用法请参见 [TimePicker 组件](#/zh-CN/time-picker) 和 [DatePicker 组件](#/zh-CN/date-picker) 文档。
+> Vant 4 不再提供旧版的 DatetimePicker 组件，使用 PickerGroup 组件可以实现更灵活、更丰富的交互效果，具体用法请参考 [PickerGroup](#/zh-CN/picker-group) 组件文档。
 
 ### Area 组件重构
 

packages/vant/src/dialog/README.md

@@ -104,9 +104,9 @@ showConfirmDialog({
 });
 ```
 
-### Advanced Usage
+### Use Dialog Component
 
-If you need to render vue components within a dialog, you can use dialog component.
+If you need to render Vue components within a Dialog, you can use the Dialog component.
 
 ```html
 <van-dialog v-model:show="show" title="Title" show-cancel-button>
@@ -129,6 +129,8 @@ export default {
 
 ### Methods
 
+Vant exports following Dialog utility functions:
+
 | Name | Description | Attribute | Return value |
 | --- | --- | --- | --- |
 | showDialog | Show dialog | _options: DialogOptions_ | `Promise<void>` |

packages/vant/src/dialog/README.zh-CN.md

@@ -121,9 +121,9 @@ showConfirmDialog({
 });
 ```
 
-### 组件调用
+### 使用 Dialog 组件
 
-如果需要在弹窗内嵌入组件或其他自定义内容，可以使用组件调用的方式。
+如果需要在 Dialog 内嵌入组件或其他自定义内容，可以直接使用 Dialog 组件，并使用默认插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
 
 ```html
 <van-dialog v-model:show="show" title="标题" show-cancel-button>
@@ -146,6 +146,8 @@ export default {
 
 ### 方法
 
+Vant 中导出了以下 Dialog 相关的辅助函数：
+
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
 | showDialog | 展示弹窗 | _options: DialogOptions_ | `Promise<void>` |
@@ -156,7 +158,7 @@ export default {
 
 ### DialogOptions
 
-通过函数调用 `Dialog` 时，支持传入以下选项：
+调用 `showDialog` 等方法时，支持传入以下选项：
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |

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

@@ -17,7 +17,7 @@ const t = useTranslate({
       '如果解决方法是丑陋的，那就肯定还有更好的解决方法，只是还没有发现而已。',
     beforeClose: '异步关闭',
     roundButton: '圆角按钮样式',
-    componentCall: '组件调用',
+    useComponent: '使用 Dialog 组件',
   },
   'en-US': {
     title: 'Title',
@@ -29,7 +29,7 @@ const t = useTranslate({
     content3: 'Content',
     beforeClose: 'Before Close',
     roundButton: 'Round Button Style',
-    componentCall: 'Component Call',
+    useComponent: 'Use Dialog Component',
   },
 });
 
@@ -101,8 +101,8 @@ const onClickBeforeClose = () => {
     <van-cell is-link :title="t('beforeClose')" @click="onClickBeforeClose" />
   </demo-block>
 
-  <demo-block card :title="t('componentCall')">
-    <van-cell is-link :title="t('componentCall')" @click="show = true" />
+  <demo-block card :title="t('useComponent')">
+    <van-cell is-link :title="t('useComponent')" @click="show = true" />
     <van-dialog
       v-model:show="show"
       :title="t('title')"

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

@@ -86,7 +86,7 @@ exports[`should render demo and match snapshot 1`] = `
   >
     <div class="van-cell__title">
       <span>
-        Component Call
+        Use Dialog Component
       </span>
     </div>
     <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">

packages/vant/src/image-preview/README.md

@@ -105,7 +105,7 @@ setTimeout(() => {
 }, 2000);
 ```
 
-### Component Call
+### Use ImagePreview Component
 
 ```html
 <van-image-preview v-model:show="show" :images="images" @change="onChange">
@@ -140,7 +140,15 @@ export default {
 
 ## API
 
-### Options
+### Methods
+
+Vant exports following ImagePreview utility functions:
+
+| Methods          | Description        | Attribute | Return value         |
+| ---------------- | ------------------ | --------- | -------------------- | --------------------- |
+| showImagePreview | Show image preview | `string[] | ImagePreviewOptions` | imagePreview Instance |
+
+### ImagePreviewOptions
 
 | Attribute | Description | Type | Default |
 | --- | --- | --- | --- |

packages/vant/src/image-preview/README.zh-CN.md

@@ -114,9 +114,9 @@ setTimeout(() => {
 }, 2000);
 ```
 
-### 组件调用
+### 使用 ImagePreview 组件
 
-如果需要在图片预览内嵌入组件或其他自定义内容，可以使用组件调用的方式，调用前需要通过 `app.use` 注册组件。
+如果需要在 ImagePreview 内嵌入组件或其他自定义内容，可以直接使用 ImagePreview 组件，并使用 `index` 插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
 
 ```html
 <van-image-preview v-model:show="show" :images="images" @change="onChange">
@@ -151,9 +151,17 @@ export default {
 
 ## API
 
-### Options
+### 方法
 
-通过函数调用 `showImagePreview` 时，支持传入以下选项：
+Vant 中导出了以下 ImagePreview 相关的辅助函数：
+
+| 方法名           | 说明         | 参数      | 返回值               |
+| ---------------- | ------------ | --------- | -------------------- | ----------------- |
+| showImagePreview | 展示图片预览 | `string[] | ImagePreviewOptions` | imagePreview 实例 |
+
+### ImagePreviewOptions
+
+调用 `showImagePreview` 方法时，支持传入以下选项：
 
 | 参数名 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |

packages/vant/src/image-preview/demo/index.vue

@@ -18,7 +18,7 @@ const t = useTranslate({
     closeEvent: '监听关闭事件',
     customConfig: '传入配置项',
     startPosition: '指定初始位置',
-    componentCall: '组件调用',
+    useComponent: '使用 ImagePreview 组件',
     index: (index: number) => `第${index + 1}页`,
   },
   'en-US': {
@@ -29,7 +29,7 @@ const t = useTranslate({
     closeEvent: 'Close Event',
     customConfig: 'Custom Config',
     startPosition: 'Set Start Position',
-    componentCall: 'Component Call',
+    useComponent: 'Use ImagePreview Component',
     index: (index: number) => `Page: ${index}`,
   },
 });
@@ -106,8 +106,8 @@ const showFunctionCall = (options: Partial<ImagePreviewOptions> = {}) => {
     />
   </demo-block>
 
-  <demo-block card :title="t('componentCall')">
-    <van-cell is-link :title="t('componentCall')" @click="showComponentCall" />
+  <demo-block card :title="t('useComponent')">
+    <van-cell is-link :title="t('useComponent')" @click="showComponentCall" />
     <van-image-preview v-model:show="show" :images="images" @change="onChange">
       <template #index>{{ t('index', index) }}</template>
     </van-image-preview>

packages/vant/src/notify/README.md

@@ -75,10 +75,10 @@ showNotify({
 });
 ```
 
-### Component Call
+### Use Notify Component
 
 ```html
-<van-button type="primary" text="Component Call" @click="showNotify" />
+<van-button type="primary" text="Use Notify Component" @click="showNotify" />
 <van-notify v-model:show="show" type="success">
   <van-icon name="bell" style="margin-right: 4px;" />
   <span>Content</span>
@@ -111,14 +111,16 @@ export default {
 
 ### Methods
 
-| Methods | Attribute | Return value | Description |
-| --- | --- | --- | --- |
-| showNotify | `options \| message` | notify instance | Show notify |
-| closeNotify | - | `void` | Close notify |
-| setNotifyDefaultOptions | `options` | `void` | Set default options of all notifies |
-| resetNotifyDefaultOptions | - | `void` | Reset default options of all notifies |
+Vant exports following Notify utility functions:
 
-### Options
+| Methods | Description | Attribute | Return value |
+| --- | --- | --- | --- |
+| showNotify | Show notify | `NotifyOptions \| string` | notify instance |
+| closeNotify | Close notify | - | `void` |
+| setNotifyDefaultOptions | Set default options of all notifies | `NotifyOptions` | `void` |
+| resetNotifyDefaultOptions | Reset default options of all notifies | - | `void` |
+
+### NotifyOptions
 
 | Attribute | Description | Type | Default |
 | --- | --- | --- | --- |

packages/vant/src/notify/README.zh-CN.md

@@ -86,9 +86,9 @@ showNotify({
 });
 ```
 
-### 组件调用
+### 使用 Notify 组件
 
-如果需要在 Notify 内嵌入组件或其他自定义内容，可以使用组件调用的方式。
+如果需要在 Notify 内嵌入组件或其他自定义内容，可以直接使用 Notify 组件，并使用默认插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
 
 ```html
 <van-button type="primary" text="组件调用" @click="showNotify" />
@@ -124,14 +124,18 @@ export default {
 
 ### 方法
 
+Vant 中导出了以下 Notify 相关的辅助函数：
+
 | 方法名 | 说明 | 参数 | 返回值 |
 | --- | --- | --- | --- |
-| showNotify | 展示提示 | `options \| message` | notify 实例 |
+| showNotify | 展示提示 | `NotifyOptions \| string` | notify 实例 |
 | closeNotify | 关闭提示 | - | `void` |
-| setNotifyDefaultOptions | 修改默认配置，影响所有的 `showNotify` 调用 | `options` | `void` |
+| setNotifyDefaultOptions | 修改默认配置，影响所有的 `showNotify` 调用 | `NotifyOptions` | `void` |
 | resetNotifyDefaultOptions | 重置默认配置，影响所有的 `showNotify` 调用 | - | `void` |
 
-### Options
+### NotifyOptions
+
+调用 `showNotify` 等方法时，支持传入以下选项：
 
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |

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

@@ -15,7 +15,7 @@ const t = useTranslate({
     notifyType: '通知类型',
     customColor: '自定义颜色',
     customNotify: '自定义配置',
-    componentCall: '组件调用',
+    useComponent: '使用 Notify 组件',
     customDuration: '自定义时长',
     customPosition: '自定义位置',
   },
@@ -28,7 +28,7 @@ const t = useTranslate({
     notifyType: 'Notify Type',
     customColor: 'Custom Color',
     customNotify: 'Custom Notify',
-    componentCall: 'Component Call',
+    useComponent: 'Use Notify Component',
     customDuration: 'Custom Duration',
     customPosition: 'Custom Position',
   },
@@ -103,8 +103,8 @@ const showComponentCall = () => {
     />
   </demo-block>
 
-  <demo-block card :title="t('componentCall')">
-    <van-cell is-link :title="t('componentCall')" @click="showComponentCall" />
+  <demo-block card :title="t('useComponent')">
+    <van-cell is-link :title="t('useComponent')" @click="showComponentCall" />
 
     <van-notify v-model:show="show" type="success">
       <van-icon name="bell" style="margin-right: 4px" />

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

@@ -110,7 +110,7 @@ exports[`should render demo and match snapshot 1`] = `
   >
     <div class="van-cell__title">
       <span>
-        Component Call
+        Use Notify Component
       </span>
     </div>
     <i class="van-badge__wrapper van-icon van-icon-arrow van-cell__right-icon">

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 |
-| --- | --- | --- | --- |
-| 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 exports following Toast 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:

packages/vant/src/toast/README.zh-CN.md

@@ -135,8 +135,6 @@ const timer = setInterval(() => {
 }, 1000);
 ```
 
-> Tips: 由于 setup 选项中无法访问 this，因此不能使用上述方式，请通过 import 引入。
-
 ### 单例模式
 
 Toast 默认采用单例模式，即同一时间只会存在一个 Toast，如果需要在同一时间弹出多个 Toast，可以参考下面的示例：
@@ -169,23 +167,50 @@ resetToastDefaultOptions();
 resetToastDefaultOptions('loading');
 ```
 
+### 使用 Toast 组件
+
+如果需要在 Toast 内嵌入组件或其他自定义内容，可以直接使用 Toast 组件，并使用 message 插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
+
+```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 实例 |
-| 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` 调用。<br>传入 type 可以修改指定类型的默认配置 | `type \| options` | `void` |
+| setToastDefaultOptions | 修改默认配置，影响所有的 `showToast` 调用。<br>传入 type 可以修改指定类型的默认配置 | `type \| ToastOptions` | `void` |
 | resetToastDefaultOptions | 重置默认配置，影响所有的 `showToast` 调用。<br>传入 type 可以重置指定类型的默认配置 | `type` | `void` |
 
 ### ToastOptions 数据结构
 
+调用 `showToast` 等方法时，支持传入以下选项：
+
 | 参数 | 说明 | 类型 | 默认值 |
 | --- | --- | --- | --- |
 | type | 提示类型，可选值为 `loading` `success`<br>`fail` `html` | _ToastType_ | `text` |
@@ -208,6 +233,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/Toast.tsx

@@ -71,7 +71,7 @@ export default defineComponent({
 
   emits: ['update:show'],
 
-  setup(props, { emit }) {
+  setup(props, { emit, slots }) {
     let timer: NodeJS.Timeout;
     let clickable = false;
 
@@ -118,6 +118,10 @@ export default defineComponent({
     const renderMessage = () => {
       const { type, message } = props;
 
+      if (slots.message) {
+        return <div class={bem('text')}>{slots.message()}</div>;
+      }
+
       if (isDef(message) && message !== '') {
         return type === 'html' ? (
           <div key={0} class={bem('text')} innerHTML={String(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>
 `;

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

@@ -12,3 +12,17 @@ exports[`create a forbidClick toast 1`] = `
   </div>
 </transition-stub>
 `;
+
+exports[`should render message slot correctly 1`] = `
+<transition-stub>
+  <div role="dialog"
+       tabindex="0"
+       class="van-popup van-popup--center van-toast van-toast--middle van-toast--text"
+       style="z-index: 2007;"
+  >
+    <div class="van-toast__text">
+      Custom Message
+    </div>
+  </div>
+</transition-stub>
+`;

packages/vant/src/toast/test/index.spec.ts

@@ -88,3 +88,17 @@ test('should change loading icon size when using icon-size prop', async () => {
   expect(wrapper.find('.van-loading__spinner').style.width).toEqual('10px');
   expect(wrapper.find('.van-loading__spinner').style.height).toEqual('10px');
 });
+
+test('should render message slot correctly', async () => {
+  const wrapper = mount(Toast, {
+    props: {
+      show: true,
+    },
+    slots: {
+      message: () => 'Custom Message',
+    },
+  });
+
+  await later();
+  expect(wrapper.html()).toMatchSnapshot();
+});