mirror of
https://gitee.com/vant-contrib/vant.git
synced 2025-04-05 19:41:42 +08:00
feat(Toast): add JSDoc for utility functions (#12344)
This commit is contained in:
neverland
GitHub
parent
f1d5376c9c
commit
927206e25b
@ -32,6 +32,8 @@ showToast('Some messages');
|
||||
|
||||
### Text
|
||||
|
||||
Use the `showToast` method to display a text toast in the center of the screen.
|
||||
|
||||
```js
|
||||
import { showToast } from 'vant';
|
||||
|
||||
@ -40,6 +42,8 @@ showToast('Some messages');
|
||||
|
||||
### Loading
|
||||
|
||||
Use the `showLoadingToast` method to display a loading toast. The `forbidClick` option can be used to disable background clicks.
|
||||
|
||||
```js
|
||||
import { showLoadingToast } from 'vant';
|
||||
|
||||
@ -51,6 +55,8 @@ showLoadingToast({
|
||||
|
||||
### Success/Fail
|
||||
|
||||
Use the `showSuccessToast` method to display a success message, and use the `showFailToast` method to display a failure message.
|
||||
|
||||
```js
|
||||
import { showSuccessToast, showFailToast } from 'vant';
|
||||
|
||||
@ -60,6 +66,8 @@ showFailToast('Fail');
|
||||
|
||||
### Custom Icon
|
||||
|
||||
The `icon` option allows you to customize the icon by specifying either the icon name or an image URL, which is equivalent to the `name` attribute of the Icon component.
|
||||
|
||||
```js
|
||||
import { showToast, showLoadingToast } from 'vant';
|
||||
|
||||
@ -72,7 +80,11 @@ showToast({
|
||||
message: 'Custom Image',
|
||||
icon: 'https://fastly.jsdelivr.net/npm/@vant/assets/logo.png',
|
||||
});
|
||||
```
|
||||
|
||||
The `loadingType` option allows you to customize the type of loading icon.
|
||||
|
||||
```js
|
||||
showLoadingToast({
|
||||
message: 'Loading...',
|
||||
forbidClick: true,
|
||||
@ -82,6 +94,8 @@ showLoadingToast({
|
||||
|
||||
### Custom Position
|
||||
|
||||
By default, the Toast is rendered in the center of the screen. You can control the position of the Toast by using the `position` option.
|
||||
|
||||
```js
|
||||
import { showToast } from 'vant';
|
||||
|
||||
@ -98,7 +112,7 @@ showToast({
|
||||
|
||||
### Word Break
|
||||
|
||||
Using `wordBreak` option to set whether line breaks appear wherever the text would otherwise overflow its content box. The default value is `break-all`, and can be set to `break-word` or `normal`.
|
||||
The `wordBreak` option controls how the text in the Toast is truncated when it exceeds the available space. The default value is `break-all`, and the optional values are `break-word` and `normal`.
|
||||
|
||||
```js
|
||||
import { showToast } from 'vant';
|
||||
@ -116,6 +130,8 @@ showToast({
|
||||
|
||||
### Update Message
|
||||
|
||||
When executing the Toast method, it returns the corresponding Toast instance. You can dynamically update the message by modifying the `message` property on the instance.
|
||||
|
||||
```js
|
||||
import { showLoadingToast, closeToast } from 'vant';
|
||||
|
||||
@ -140,7 +156,7 @@ const timer = setInterval(() => {
|
||||
|
||||
### Singleton
|
||||
|
||||
Toast use singleton mode by default, if you need to pop multiple Toast at the same time, you can refer to the following example:
|
||||
The Toast is implemented as a singleton by default, which means that only one Toast can exist at a time. If you need to display multiple Toasts at the same time, you can refer to the following example:
|
||||
|
||||
```js
|
||||
import { showToast, showSuccessToast, allowMultipleToast } from 'vant';
|
||||
@ -156,7 +172,7 @@ toast2.close();
|
||||
|
||||
### Set Default Options
|
||||
|
||||
The Toast default configuration can be globally modified with the `setToastDefaultOptions` function.
|
||||
You can globally modify the default configuration of the `showToast` and other methods by using the `setToastDefaultOptions` function.
|
||||
|
||||
```js
|
||||
import { setToastDefaultOptions, resetToastDefaultOptions } from 'vant';
|
||||
@ -172,7 +188,7 @@ resetToastDefaultOptions('loading');
|
||||
|
||||
### Use Toast Component
|
||||
|
||||
If you want to render Vue components within a Toast, you can use the Toast component.
|
||||
If you need to embed components or other custom content within the Toast, you can directly use the Toast component and customize it using the message slot. Before using it, you need to register the component using `app.use` or other methods.
|
||||
|
||||
```html
|
||||
<van-toast v-model:show="show" style="padding: 0">
|
||||
@ -201,14 +217,14 @@ Vant exports following Toast utility functions:
|
||||
|
||||
| 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` |
|
||||
| showToast | Display a text toast | `ToastOptions \| string` | Toast instance |
|
||||
| showLoadingToast | Display a loading toast | `ToastOptions \| string` | Toast instance |
|
||||
| showSuccessToast | Display a success toast | `ToastOptions \| string` | Toast instance |
|
||||
| showFailToast | Display a fail toast | `ToastOptions \| string` | Toast instance |
|
||||
| closeToast | Close the currently displayed toast | `closeAll: boolean` | `void` |
|
||||
| allowMultipleToast | Allow multiple toasts to be displayed as the same time | - | `void` |
|
||||
| setToastDefaultOptions | Modify the default configuration that affects all `showToast` calls. Specify the `type` parameter to modify the default configuration of a specific type of toast | `type \| ToastOptions` | `void` |
|
||||
| resetToastDefaultOptions | Reset the default configuration that affects all `showToast` calls. Specify the `type` parameter to reset the default configuration of a specific type of toast | `type` | `void` |
|
||||
|
||||
### ToastOptions
|
||||
|
||||
|
||||
@ -32,6 +32,8 @@ showToast('提示内容');
|
||||
|
||||
### 文字提示
|
||||
|
||||
使用 `showToast` 方法在屏幕中间展示一条文字提示。
|
||||
|
||||
```js
|
||||
import { showToast } from 'vant';
|
||||
|
||||
@ -80,7 +82,7 @@ showToast({
|
||||
});
|
||||
```
|
||||
|
||||
通过`loadingType` 属性可以自定义加载图标类型。
|
||||
通过 `loadingType` 属性可以自定义加载图标类型。
|
||||
|
||||
```js
|
||||
import { showLoadingToast } from 'vant';
|
||||
@ -112,7 +114,7 @@ showToast({
|
||||
|
||||
### 文字换行方式
|
||||
|
||||
通过 `wordBreak` 选择可以控制 Toast 中的文字过长时的截断方式，默认值为 `break-all`，可选值为 `break-word` 和 `normal`。
|
||||
通过 `wordBreak` 选项可以控制 Toast 中的文字过长时的截断方式，默认值为 `break-all`，可选值为 `break-word` 和 `normal`。
|
||||
|
||||
```js
|
||||
import { showToast } from 'vant';
|
||||
@ -189,7 +191,7 @@ resetToastDefaultOptions('loading');
|
||||
|
||||
### 使用 Toast 组件
|
||||
|
||||
如果需要在 Toast 内嵌入组件或其他自定义内容，可以直接使用 Toast 组件，并使用 message 插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
|
||||
如果你需要在 Toast 内嵌入组件或其他自定义内容，可以直接使用 Toast 组件，并使用 message 插槽进行定制。使用前需要通过 `app.use` 等方式注册组件。
|
||||
|
||||
```html
|
||||
<van-toast v-model:show="show" style="padding: 0">
|
||||
@ -218,14 +220,14 @@ Vant 中导出了以下 Toast 相关的辅助函数：
|
||||
|
||||
| 方法名 | 说明 | 参数 | 返回值 |
|
||||
| --- | --- | --- | --- |
|
||||
| showToast | 展示提示 | `ToastOptions \| string` | toast 实例 |
|
||||
| showLoadingToast | 展示加载提示 | `ToastOptions \| string` | toast 实例 |
|
||||
| showSuccessToast | 展示成功提示 | `ToastOptions \| string` | toast 实例 |
|
||||
| showFailToast | 展示失败提示 | `ToastOptions \| string` | toast 实例 |
|
||||
| closeToast | 关闭提示 | `closeAll: boolean` | `void` |
|
||||
| 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 \| ToastOptions` | `void` |
|
||||
| resetToastDefaultOptions | 重置默认配置，影响所有的 `showToast` 调用。<br>传入 type 可以重置指定类型的默认配置 | `type` | `void` |
|
||||
| setToastDefaultOptions | 修改默认配置，影响所有的 `showToast` 调用。传入 type 可以修改指定类型 Toast 的默认配置 | `type \| ToastOptions` | `void` |
|
||||
| resetToastDefaultOptions | 重置默认配置，影响所有的 `showToast` 调用。传入 type 可以重置指定类型 Toast 的默认配置 | `type` | `void` |
|
||||
|
||||
### ToastOptions 数据结构
|
||||
|
||||
@ -233,7 +235,7 @@ Vant 中导出了以下 Toast 相关的辅助函数：
|
||||
|
||||
| 参数 | 说明 | 类型 | 默认值 |
|
||||
| --- | --- | --- | --- |
|
||||
| type | 提示类型，可选值为 `loading` `success`<br>`fail` `html` | _ToastType_ | `text` |
|
||||
| type | 提示类型，可选值为 `loading` `success` `fail` `html` | _ToastType_ | `text` |
|
||||
| position | 位置，可选值为 `top` `bottom` | _ToastPosition_ | `middle` |
|
||||
| message | 文本内容，支持通过`\n`换行 | _string_ | `''` |
|
||||
| wordBreak | 文本内容的换行方式，可选值为 `normal` `break-all` `break-word` | _ToastWordBreak_ | `'break-all'` |
|
||||
|
||||
@ -89,6 +89,9 @@ function getInstance() {
|
||||
return queue[queue.length - 1];
|
||||
}
|
||||
|
||||
/**
|
||||
* Display a text toast
|
||||
*/
|
||||
export function showToast(options: string | ToastOptions = {}) {
|
||||
if (!inBrowser) {
|
||||
return {} as ToastWrapperInstance;
|
||||
@ -112,10 +115,24 @@ export function showToast(options: string | ToastOptions = {}) {
|
||||
const createMethod = (type: ToastType) => (options: string | ToastOptions) =>
|
||||
showToast(extend({ type }, parseOptions(options)));
|
||||
|
||||
/**
|
||||
* Display a loading toast
|
||||
*/
|
||||
export const showLoadingToast = createMethod('loading');
|
||||
|
||||
/**
|
||||
* Display a success toast
|
||||
*/
|
||||
export const showSuccessToast = createMethod('success');
|
||||
|
||||
/**
|
||||
* Display a fail toast
|
||||
*/
|
||||
export const showFailToast = createMethod('fail');
|
||||
|
||||
/**
|
||||
* Close the currently displayed toast
|
||||
*/
|
||||
export const closeToast = (all?: boolean) => {
|
||||
if (queue.length) {
|
||||
if (all) {
|
||||
@ -131,6 +148,10 @@ export const closeToast = (all?: boolean) => {
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Modify the default configuration that affects all `showToast` calls.
|
||||
* Specify the `type` parameter to modify the default configuration of a specific type of toast
|
||||
*/
|
||||
export function setToastDefaultOptions(options: ToastOptions): void;
|
||||
export function setToastDefaultOptions(
|
||||
type: ToastType,
|
||||
@ -147,6 +168,10 @@ export function setToastDefaultOptions(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Reset the default configuration that affects all `showToast` calls.
|
||||
* Specify the `type` parameter to reset the default configuration of a specific type of toast
|
||||
*/
|
||||
export const resetToastDefaultOptions = (type?: ToastType) => {
|
||||
if (typeof type === 'string') {
|
||||
defaultOptionsMap.delete(type);
|
||||
@ -156,6 +181,9 @@ export const resetToastDefaultOptions = (type?: ToastType) => {
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Allow multiple toasts to be displayed as the same time
|
||||
*/
|
||||
export const allowMultipleToast = (value = true) => {
|
||||
allowMultiple = value;
|
||||
};
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user