From 4a721215993e2b3f7e39fce72f3d6be075358562 Mon Sep 17 00:00:00 2001
From: Robert Zeng <163709439+upthen@users.noreply.github.com>
Date: Fri, 27 Sep 2024 21:15:08 +0800
Subject: [PATCH] docs(components):  add FAQ for showToast on-demand loading
 (#13136)

Co-authored-by: yongbo.zeng_U+ <yongbo.zeng@united-imaging.com>
Co-authored-by: neverland <jait.chen@foxmail.com>
---
 packages/vant/src/toast/README.md       | 36 +++++++++++++++++++++++++
 packages/vant/src/toast/README.zh-CN.md | 36 +++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/packages/vant/src/toast/README.md b/packages/vant/src/toast/README.md
index 7a074481c..94e0f9275 100644
--- a/packages/vant/src/toast/README.md
+++ b/packages/vant/src/toast/README.md
@@ -336,3 +336,39 @@ The component provides the following CSS variables, which can be used to customi
 | --van-toast-default-min-height | _88px_ | - |
 | --van-toast-position-top-distance | _20%_ | - |
 | --van-toast-position-bottom-distance | _20%_ | - |
+
+## FAQ
+
+### Compilation error when referencing showToast?
+
+If you encounter the following error when referencing the `showToast` method, it indicates that the project is using the `babel-plugin-import` plugin, which causes incorrect compilation.
+
+```bash
+These dependencies were not found:
+
+* vant/es/show-toast in ./src/xxx.js
+* vant/es/show-toast/style in ./src/xxx.js
+```
+
+Starting from version 4.0, Vant no longer supports the `babel-plugin-import` plugin. Please refer to the [migration guide](#/en-US/migrate-from-v3#remove-babel-plugin-import) to remove this plugin.
+
+### Style Issues When Using showToast with On-Demand Component Import?
+
+When integrating Vant using the [on-demand component import](#/en-US/quickstart#import-on-demand) method, using functions like `showToast` does not require explicit import. Doing so can cause style issues.
+
+```js
+// The following import is not needed
+import { showToast } from 'vant'
+```
+
+This is because when you explicitly import functions like `showToast`, `@vant/auto-import-resolver` will not automatically import the style resources for Toast, leading to missing styles and resulting in style issues.
+
+There are two solutions:
+
+- Do not explicitly import `showToast` when using it.
+- If you must explicitly import `showToast`, you also need to manually import the related styles for the `Toast` component.
+
+```js
+import { showToast } from 'vant'
+import 'vant/lib/toast/style'
+```
diff --git a/packages/vant/src/toast/README.zh-CN.md b/packages/vant/src/toast/README.zh-CN.md
index 7c93e3f6e..503051380 100644
--- a/packages/vant/src/toast/README.zh-CN.md
+++ b/packages/vant/src/toast/README.zh-CN.md
@@ -353,3 +353,39 @@ These dependencies were not found:
 ```
 
 Vant 从 4.0 版本开始不再支持 `babel-plugin-import` 插件，请参考 [迁移指南](#/zh-CN/migrate-from-v3#yi-chu-babel-plugin-import) 移除该插件。
+
+## 常见问题
+
+### 引用 showToast 时出现编译报错？
+
+如果引用 `showToast` 方法时出现以下报错，说明项目中使用了 `babel-plugin-import` 插件，导致代码被错误编译。
+
+```bash
+These dependencies were not found:
+
+* vant/es/show-toast in ./src/xxx.js
+* vant/es/show-toast/style in ./src/xxx.js
+```
+
+Vant 从 4.0 版本开始不再支持 `babel-plugin-import` 插件，请参考 [迁移指南](#/zh-CN/migrate-from-v3#yi-chu-babel-plugin-import) 移除该插件。
+
+### 按需引入组件时，使用 showToast 时出现样式异常问题？
+
+在使用[按需引入组件](#/zh-CN/quickstart#fang-fa-er.-an-xu-yin-ru-zu-jian-yang-shi)方案集成 Vant 时，使用 showToast 等函数无需进行显式导入，否则会造成样式异常。
+
+```js
+// 以下方式是不需要的
+import { showToast } from 'vant'
+```
+
+这是因为在显式导入 showToast 等函数时，` @vant/auto-import-resolver` 将不会自动导入 Toast 的样式资源，这将导致 Toast 组件的样式缺失，从而导致样式异常问题。
+
+解决方案有 2 种：
+
+- 使用 `showToast` 时不进行显式导入；
+- 如果必须显示导入 `showToast` ，则同时需要手动导入 `Toast` 组件的相关样式。
+
+```js
+import { showToast } from 'vant'
+import 'vant/lib/toast/style'
+```