sard-uniapp
Version:
sard-uniapp 是一套基于 Uniapp + Vue3 框架开发的兼容多端的 UI 组件库
213 lines (154 loc) • 10.7 kB
Markdown
---
title: Dialog
subtitle: 对话框
group: 反馈组件
---
## 介绍
提示或接收用户的确认。
## 引入
```js
import Dialog from 'sard-uniapp/components/dialog/dialog.vue'
import DialogAgent from 'sard-uniapp/components/dialog-agent/dialog-agent.vue'
import { dialog } from 'sard-uniapp'
```
## 代码演示
### 基础使用
先在页面放置代理组件。
```tsx
<sar-dialog-agent />
```
接着便可以使用 `dialog` 等方法显示对话框。
<<< @demo/dialog/demo/Basic.vue
### 异步关闭
如果 `beforeClose` 返回 `false` 或 `rejected` 状态的 `Promise` 可阻止关闭。
<<< @demo/dialog/demo/AsyncClose.vue
### 圆角按钮
`buttonType` 属性值为 `round` 可以将底部按钮显示为圆角的形式。
<<< @demo/dialog/demo/Round.vue
### 有头部的
配置 `headed` 属性让对话框显示头部，此时的对话框更像一个模态框。
<<< @demo/dialog/demo/Headed.vue
### 自定义内容
对话框里面可以放置任何内容，例如以模态的方式展示一个表单，通常要配合 `headed` 属性一起使用。
<<< @demo/dialog/demo/Content.vue
### 内容中包含弹出框
`v1.4.1` 起，对话框底层的 `Popup` 组件包裹在了 `root-portal` (小程序)和 `teleport` (H5)中，因此基于 `Popup` 的可弹出组件都可以相互嵌套使用，也可以放置在 `scroll-view` 里面。
<<< @demo/dialog/demo/PopupContent.vue
### 自定义按钮属性
使用 `cancelProps` 和 `confirmProps` 属性可以自定义取消和确定按钮组件的属性。
<<< @demo/dialog/demo/ButtonProps.vue
## API
### DialogProps
| 属性 | 描述 | 类型 | 默认值 |
| ------------------------------ | ----------------------------------------------------------------------------------------- | ----------------- | ------- |
| root-class | 对话框根元素类名 | string | - |
| root-style | 对话框根元素样式 | StyleValue | - |
| popup-class <sup>1.14.1+</sup> | 弹窗框根元素类名 | string | - |
| popup-style <sup>1.14.1+</sup> | 弹窗框根元素样式 | StyleValue | - |
| visible (v-model) | 是否可见 | boolean | false |
| title | 标题 | string | - |
| message | 文本内容 | string | - |
| headed | 是否显示带头部类型 | boolean | true |
| button-type | 按钮类型 | 'round' \| 'text' | 'round' |
| show-cancel | 是否显示取消按钮 | boolean | true |
| cancel-text | 取消按钮文案 | string | '取消' |
| show-confirm | 是否显示确定按钮 | boolean | true |
| confirm-text | 确定按钮文案 | string | '确定' |
| overlay-closable | 点击遮罩是否关闭 | boolean | false |
| before-close | 关闭前的回调，返回 `false` 或 `Promise{<rejected>}` 可阻止关闭 | DialogBeforeClose | - |
| duration | 显隐动画时长，单位 ms | number | 300 |
| confirm-props <sup>1.10+</sup> | 设置确定按钮 props | ButtonProps | - |
| cancel-props <sup>1.10+</sup> | 设置取消按钮 props | ButtonProps | - |
| back-press <sup>1.30.3+</sup> | 弹出框显示时，劫持用户的返回操作，`close`: 关闭弹出框、`back`: 返回上一页（仅小程序支持） | 'close' \| 'back' | 'close' |
#### DialogBeforeClose
- 当点击确定按钮时，`type` 为 `confirm`；
- 当点击取消按钮时，`type` 为 `cancel`；
- 当点击关闭按钮或遮罩时，`type` 为 `close`。
`loading` 表示当前哪个按钮处于异步关闭状态。
```ts
type DialogBeforeClose = (
type: 'close' | 'cancel' | 'confirm',
loading: {
readonly cancel: boolean
readonly confirm: boolean
readonly close: boolean
},
) => any | Promise<any>
```
### DialogSlots
| 插槽 | 描述 | 属性 |
| ------- | -------------- | ---- |
| default | 自定义默认内容 | - |
### DialogEmits
| 事件 | 描述 | 类型 |
| -------------------------------- | --------------------------- | ------------------------------------ |
| update:visible | 对话框显隐时触发 | `(visible: boolean) => void` |
| close | 点击关闭按钮或遮罩时触发 | `() => void` |
| cancel | 点击取消按钮时触发 | `() => void` |
| confirm | 点击确定按钮时触发 | `() => void` |
| visible-hook | 入场/退场动画状态改变时触发 | `(name: TransitionHookName) => void` |
| before-enter <sup>1.12+</sup> | 入场动画开始前触发 | `() => void` |
| enter <sup>1.12+</sup> | 入场动画开始时触发 | `() => void` |
| after-enter <sup>1.12+</sup> | 入场动画结束时触发 | `() => void` |
| enter-cancelled <sup>1.12+</sup> | 入场动画取消时触发 | `() => void` |
| before-leave <sup>1.12+</sup> | 退场动画开始前触发 | `() => void` |
| leave <sup>1.12+</sup> | 退场动画开始时触发 | `() => void` |
| after-leave <sup>1.12+</sup> | 退场动画结束时触发 | `() => void` |
| leave-cancelled <sup>1.12+</sup> | 退场动画取消时触发 | `() => void` |
### DialogAgentProps / DialogOptions
继承 [`DialogProps`](#DialogProps) 并有以下额外属性。
| 属性 | 描述 | 类型 | 默认值 |
| ----------------------------------- | --------------------------- | ------------------------------------ | -------- |
| id | 对话框组件的 id | string | 'dialog' |
| onClose <sup>1.20.2+</sup> | 点击关闭按钮或遮罩时调用 | `() => void` |
| onCancel <sup>1.20.2+</sup> | 点击取消按钮时调用 | `() => void` |
| onConfirm <sup>1.20.2+</sup> | 点击确定按钮时调用 | `() => void` |
| onVisibleHook <sup>1.20.2+</sup> | 入场/退场动画状态改变时调用 | `(name: TransitionHookName) => void` |
| onBeforeEnter <sup>1.20.2+</sup> | 入场动画开始前调用 | `() => void` |
| onEnter <sup>1.20.2+</sup> | 入场动画开始时调用 | `() => void` |
| onAfterEnter <sup>1.20.2+</sup> | 入场动画结束时调用 | `() => void` |
| onEnterCancelled <sup>1.20.2+</sup> | 入场动画取消时调用 | `() => void` |
| onBeforeLeave <sup>1.20.2+</sup> | 退场动画开始前调用 | `() => void` |
| onLeave <sup>1.20.2+</sup> | 退场动画开始时调用 | `() => void` |
| onAfterLeave <sup>1.20.2+</sup> | 退场动画结束时调用 | `() => void` |
| onLeaveCancelled <sup>1.20.2+</sup> | 退场动画取消时调用 | `() => void` |
### DialogAgentSlots <sup>1.30.3+</sup>
继承 [`DialogSlots`](#DialogSlots)。
### DialogAgentEmits <sup>1.20.2+</sup>
继承 [`DialogEmits`](#DialogEmits)。
### 命令式方法
| 名称 | 描述 | 类型 |
| -------------- | ---------------------------- | ------------------------- |
| dialog | 显示对话框 | DialogFunction |
| dialog.alert | 显示警告框 | DialogSimpleShowFunction |
| dialog.confirm | 显示确认框 | DialogSimpleShowFunction |
| dialog.hide | 隐藏指定 `id` 的命令式对话框 | `(id = 'dialog') => void` |
| dialog.hideAll | 隐藏所有命令式对话框 | `() => void` |
### DialogFunction
```ts
type DialogFunction = DialogSimpleShowFunction & {
alert: DialogSimpleShowFunction
confirm: DialogSimpleShowFunction
hide: (id?: string) => void
hideAll: () => void
}
```
### DialogSimpleShowFunction
```ts
interface DialogSimpleShowFunction {
(options: DialogOptions): void
(title: string, options?: DialogOptions): void
}
```
### defaultDialogOptions
命令式默认值和声明式有所区别。
```ts
const defaultDialogOptions = {
headed: false,
buttonType: 'text',
showCancel: false,
}
```
## 主题定制
### CSS 变量
<<< @comp/dialog/variables.scss#variables