# Dialog 对话框

[toc]

`Dialog` 组件提供一个模态对话框，在浮层中显示，用于消息提示、消息确认等使用场景，引导用户进行相关操作。此组件支持函数调用和组件调用两种方式。

## 组件引入

在`app.json`或在`index.json`中引入：

```json

{
  "usingComponents": {
    "tea-dialog": "../dist/dialog/index"
  }
}

```

## 用法

### 基础用法

```html
<tea-button bind:click="handleClick">显示对话框</tea-button>

<tea-dialog 
  show="{{ show }}" 
  title="标题" 
  content="告知当前状态，信息和解决方法，描述文字盡量控制在三行内" 
  showConfirm="{{ true }}" 
  showCancel="{{ true }}" 
  confirmButtonText="确认" 
  cancelButtonText="取消"
>
</tea-dialog>
```

```javascript
Page({
  data: {
    show: false
  }, 
  
  handleClick() {
    this.setData({ 
      show: true 
    });
  }
})
```

### 点击遮罩层关闭弹出层

通过 `backdropClosable` 属性来设置点击遮罩层关闭对话框。

```html
<tea-dialog 
  show="{{ show }}" 
  title="标题" 
  content="告知当前状态，信息和解决方法，描述文字盡量控制在三行内" 
  showConfirm="{{ true }}" 
  showCancel="{{ true }}" 
  confirmButtonText="确认" 
  cancelButtonText="取消" 
  backdropClosable="{{ true }}"
>
</tea-dialog>
```

### 异步关闭

通过 `asyncClose` 属性来开启异步关闭对话框，此属性只在 `confirmButton` 生效。<br>
开启异步关闭后，需要手动调用 `Dialog.close` 方法来关闭对话框。

```html
<tea-button bind:click="handleClick">显示对话框</tea-button>

<tea-dialog 
  show="{{ show }}" 
  title="标题" 
  content="告知当前状态，信息和解决方法，描述文字盡量控制在三行内" 
  showConfirm="{{ true }}" 
  showCancel="{{ true }}" 
  confirmButtonText="确认" 
  cancelButtonText="取消" 
  asyncClose="{{ true }}" 
  bind:confirm="handleConfirm"
>
</tea-dialog>
```

```javascript
Page({
  data: {
    show: false
  }, 

  handleClick() {
    this.setData({ 
      show: true 
    });
  }, 
  
  handleConfirm(e) {
    const { Dialog } = e.detail;
    
    setTimeout(() => {
      Dialog.close();
    }, 3000);
  }
})
```

### 函数调用

```html
<tea-dialog id="tea-dialog" />
```

```javascript
import Dialog from 'path/to/@tencent/tea-mp/dist/dialog/dialog.js';

Dialog.confirm({
  title: '标题',
  content: '告知当前状态，信息和解决方法，描述文字盡量控制在三行内',
})
  .then(() => {
    console.log('confirm');
  })
  .catch(() => {
    console.log('cancel');
  });
```

## Props

| 参数                | 描述                                               | 类型        | 默认值     |
| ----------------- | ------------------------------------------------ | --------- | ------- |
| show              | 是否显示对话框                                          | `Boolean` | `false` |
| title             | 标题                                               | `String`  | -       |
| useTitleSlot      | 是否使用自定义标题的插槽                                     | `Boolean` | `false` |
| content           | 文本内容                                             | `String`  | -       |
| showConfirm       | 是否展示确认按钮                                         | `Boolean` | `true`  |
| showCancel        | 是否展示取消按钮                                         | `Boolean` | `false` |
| confirmButtonText | 确认按钮的文案                                          | `String`  | `确认`    |
| cancelButtonText  | 取消按钮的文案                                          | `String`  | `取消`    |
| backdropClosable  | 点击遮罩层是否关闭对话框                                     | `Boolean` | `false` |
| asyncClose        | 是否开启异步关闭，开启后需要手动控制对话框的关闭。此属性只在 confirmButton 生效。 | `Boolean` | `false` |

## API

| 方法名            | 参数        | 描述        |
| -------------- | --------- | --------- |
| Dialog.alert   | `options` | 展示消息提示对话框 |
| Dialog.confirm | `options` | 展示确认对话框   |
| Dialog.close   | `options` | 关闭对话框     |

## options

通过函数调用 Dialog 组件时，支持传入以下参数：

| 参数                | 描述                        | 类型        | 默认值           |
| ----------------- | ------------------------- | --------- | ------------- |
| title             | 标题                        | `String`  | -             |
| content           | 文本内容                      | `String`  | -             |
| selector          | 自定义选择器                    | `String`  | `#tea-dialog` |
| showConfirm       | 是否展示确认按钮                  | `Boolean` | `true`        |
| showCancel        | 是否展示取消按钮                  | `Boolean` | `false`       |
| confirmButtonText | 确认按钮的文案                   | `String`  | `确认`          |
| cancelButtonText  | 取消按钮的文案                   | `String`  | `取消`          |
| backdropClosable  | 点击遮罩层是否关闭对话框              | `Boolean` | `false`       |
| asyncClose        | 是否开启异步关闭，开启后需要手动控制对话框的关闭。 | `Boolean` | `false`       |

## 事件

| 事件名          | 描述        | 回调参数                                               |
| ------------ | --------- | -------------------------------------------------- |
| bind:confirm | 点击确认按钮时触发 | -                                                  |
| bind:cancel  | 点击取消按钮时触发 | -                                                  |
| bind:closed  | 关闭对话框时触发  | e.detail: 触发关闭事件来源，如：`confirm`、`cancel`、`backdrop` |

## Slots

| 名称      | 描述                                    |
| ------- | ------------------------------------- |
| title   | 自定义`title`显示内容，需要设置useTitleSlot为true，且设置了`title`属性不生效     |
| content | 自定义`content`显示内容，如果设置了`content`属性则不生效 |

## 外部样式类

| 类名                        | 描述          |
| -------------------------- | ------------- |
| `ext-class`                | 组件根节点样式类 |
| `ext-class-body`           | 内容区域样式类   |
| `ext-class-confirm-button` | 确认按钮样式类   |
| `ext-class-cancel-button`  | 取消按钮样式类   |

## CSS变量属性表

| 变量名                                 | 默认值                                 | 描述  |
| ----------------------------------- | ----------------------------------- | --- |
| dialog-width                        | 300px                               | -   |
| dialog-line-height                  | @line-height-zh                     | -   |
| dialog-background-color             | @background-base-color              | -   |
| dialog-border-radius                | 4px                                 | -   |
| dialog-header-text-size             | @font-size-h3                       | -   |
| dialog-header-font-weight           | @font-weight-bold                   | -   |
| dialog-header-text-color            | @text-base-color                    | -   |
| dialog-header-padding-top           | @padding-xl                         | -   |
| dialog-content-text-size            | @font-size-sm                       | -   |
| dialog-content-font-weight          | @font-weight-normal                 | -   |
| dialog-content-text-color           | @text-light-color                   | -   |
| dialog-content-padding              | @padding-md @padding-xl @padding-xl | -   |
| dialog-no-title-content-text-size   | @font-size-xl                       | -   |
| dialog-no-title-content-text-color  | @text-base-color                    | -   |
| dialog-no-title-content-padding-top | @padding-xl                         | -   |
| dialog-confirm-button-text-color    | @text-primary-color                 | -   |
| dialog-cancel-button-text-color     | @text-base-color                    | -   |