feat(Toast): add z-index prop (#12587)

youzan · Jan 20, 2024 · fdb01be · fdb01be
1 parent 08d11b4
commit fdb01be
Show file tree

Hide file tree

Showing 4 changed files with 82 additions and 4 deletions.
diff --git a/packages/vant/src/toast/README.md b/packages/vant/src/toast/README.md
@@ -228,6 +228,8 @@ Vant exports following Toast utility functions:
 
 ### ToastOptions
 
+When calling the `showToast` and other related methods, the following options are supported:
+
 | Attribute | Description | Type | Default |
 | --- | --- | --- | --- |
 | type | Can be set to `loading` `success` `fail` `html` | _ToastType_ | `text` |
@@ -246,10 +248,47 @@ Vant exports following Toast utility functions:
 | className | Custom className | _string \| Array \| object_ | - |
 | overlayClass | Custom overlay class | _string \| Array \| object_ | - |
 | overlayStyle | Custom overlay style | _object_ | - |
-| onOpened | Callback function after opened | _Function_ | - |
+| transition | Transition, equivalent to `name` prop of [transition](https://vuejs.org/api/built-in-components.html#transition) | _string_ | `van-fade` |
+| teleport | Specifies a target element where Toast will be mounted | _string \| Element_ | `body` |
+| zIndex | Set the z-index to a fixed value | _number \| string_ | `2000+` |
 | onClose | Callback function after close | _Function_ | - |
+| onOpened | Callback function after opened | _Function_ | - |
+
+### Props
+
+When using `Toast` as a component, the following props are supported:
+
+| Attribute | Description | Type | Default |
+| --- | --- | --- | --- |
+| v-model:show | Whether to show toast | _boolean_ | `false` |
+| type | Can be set to `loading` `success` `fail` `html` | _ToastType_ | `text` |
+| position | Can be set to `top` `middle` `bottom` | _ToastPosition_ | `middle` |
+| message | Message | _string_ | `''` |
+| word-break | Can be set to `normal` `break-all` `break-word` | _ToastWordBreak_ | `'break-all'` |
+| icon | Custom icon | _string_ | - |
+| icon-size | Custom icon size | _number \| string_ | `36px` |
+| icon-prefix | Icon className prefix | _string_ | `van-icon` |
+| overlay | Whether to show overlay | _boolean_ | `false` |
+| forbid-click | Whether to forbid click background | _boolean_ | `false` |
+| close-on-click | Whether to close after clicked | _boolean_ | `false` |
+| close-on-click-overlay | Whether to close when overlay is clicked | _boolean_ | `false` |
+| loading-type | Loading icon type, can be set to `spinner` | _string_ | `circular` |
+| duration | Toast duration(ms), won't disappear if value is 0 | _number_ | `2000` |
+| class-name | Custom className | _string \| Array \| object_ | - |
+| overlay-class | Custom overlay class | _string \| Array \| object_ | - |
+| overlay-style | Custom overlay style | _object_ | - |
 | transition | Transition, equivalent to `name` prop of [transition](https://vuejs.org/api/built-in-components.html#transition) | _string_ | `van-fade` |
 | teleport | Specifies a target element where Toast will be mounted | _string \| Element_ | `body` |
+| z-index | Set the z-index to a fixed value | _number \| string_ | `2000+` |
+
+### Events
+
+When using `Toast` as a component, the following events are supported:
+
+| Event  | Description                    | Parameters |
+| ------ | ------------------------------ | ---------- |
+| close  | Callback function after close  | -          |
+| opened | Callback function after opened | -          |
 
 ### Slots
 

diff --git a/packages/vant/src/toast/README.zh-CN.md b/packages/vant/src/toast/README.zh-CN.md
@@ -251,10 +251,46 @@ Vant 中导出了以下 Toast 相关的辅助函数：
 | className | 自定义类名 | _string \| Array \| object_ | - |
 | overlayClass | 自定义遮罩层类名 | _string \| Array \| object_ | - |
 | overlayStyle | 自定义遮罩层样式 | _object_ | - |
-| onOpened | 完全展示后的回调函数 | _Function_ | - |
+| transition | 动画类名，等价于 [transition](https://cn.vuejs.org/api/built-in-components.html#transition) 的`name`属性 | _string_ | `van-fade` |
+| teleport | 指定挂载的节点，等同于 Teleport 组件的 [to 属性](https://cn.vuejs.org/api/built-in-components.html#teleport) | _string \| Element_ | `body` |
+| z-index | 将组件的 z-index 层级设置为一个固定值 | _number \| string_ | `2000+` |
 | onClose | 关闭时的回调函数 | _Function_ | - |
+| onOpened | 完全展示后的回调函数 | _Function_ | - |
+
+### Props
+
+通过组件调用 `Toast` 时，支持以下 Props：
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| type | 提示类型，可选值为 `loading` `success` `fail` `html` | _ToastType_ | `text` |
+| position | 位置，可选值为 `top` `bottom` | _ToastPosition_ | `middle` |
+| message | 文本内容，支持通过`\n`换行 | _string_ | `''` |
+| word-break | 文本内容的换行方式，可选值为 `normal` `break-all` `break-word` | _ToastWordBreak_ | `'break-all'` |
+| icon | 自定义图标，支持传入图标名称或图片链接，等同于 Icon 组件的 [name 属性](#/zh-CN/icon#props) | _string_ | - |
+| icon-size | 图标大小，如 `20px` `2em`，默认单位为 `px` | _number \| string_ | `36px` |
+| icon-prefix | 图标类名前缀，等同于 Icon 组件的 [class-prefix 属性](#/zh-CN/icon#props) | _string_ | `van-icon` |
+| overlay | 是否显示背景遮罩层 | _boolean_ | `false` |
+| forbid-click | 是否禁止背景点击 | _boolean_ | `false` |
+| close-on-click | 是否在点击后关闭 | _boolean_ | `false` |
+| close-on-click-overlay | 是否在点击遮罩层后关闭 | _boolean_ | `false` |
+| loading-type | [加载图标类型](#/zh-CN/loading), 可选值为 `spinner` | _string_ | `circular` |
+| duration | 展示时长(ms)，值为 0 时，toast 不会消失 | _number_ | `2000` |
+| class-name | 自定义类名 | _string \| Array \| object_ | - |
+| overlay-class | 自定义遮罩层类名 | _string \| Array \| object_ | - |
+| overlay-style | 自定义遮罩层样式 | _object_ | - |
 | transition | 动画类名，等价于 [transition](https://cn.vuejs.org/api/built-in-components.html#transition) 的`name`属性 | _string_ | `van-fade` |
 | teleport | 指定挂载的节点，等同于 Teleport 组件的 [to 属性](https://cn.vuejs.org/api/built-in-components.html#teleport) | _string \| Element_ | `body` |
+| z-index | 将组件的 z-index 层级设置为一个固定值 | _number \| string_ | `2000+` |
+
+### Events
+
+通过组件调用 `Toast` 时，支持以下事件：
+
+| 事件名 | 说明                 | 回调参数 |
+| ------ | -------------------- | -------- |
+| close  | 关闭时的回调函数     | -        |
+| opened | 完全展示后的回调函数 | -        |
 
 ### Slots
 

diff --git a/packages/vant/src/toast/Toast.tsx b/packages/vant/src/toast/Toast.tsx
@@ -39,6 +39,7 @@ const popupInheritProps = [
   'overlayClass',
   'overlayStyle',
   'closeOnClickOverlay',
+  'zIndex',
 ] as const;
 
 export const toastProps = {
@@ -61,6 +62,7 @@ export const toastProps = {
   overlayStyle: Object as PropType<CSSProperties>,
   closeOnClick: Boolean,
   closeOnClickOverlay: Boolean,
+  zIndex: numericProp,
 };
 
 export type ToastProps = ExtractPropTypes<typeof toastProps>;

diff --git a/packages/vant/src/toast/types.ts b/packages/vant/src/toast/types.ts
@@ -11,8 +11,6 @@ export type ToastOptions = {
   type?: ToastType;
   mask?: boolean;
   message?: Numeric;
-  onClose?: () => void;
-  onOpened?: () => void;
   overlay?: boolean;
   duration?: number;
   teleport?: TeleportProps['to'];
@@ -28,6 +26,9 @@ export type ToastOptions = {
   overlayClass?: unknown;
   overlayStyle?: Record<string, any>;
   closeOnClickOverlay?: boolean;
+  zIndex?: Numeric;
+  onClose?: () => void;
+  onOpened?: () => void;
 };
 
 export type ToastWrapperInstance = ComponentPublicInstance<