# modal (w-modal)

- **Import**: `WModal` from `win-design-next`
- **Tag**: `<w-modal>`
- **说明**: Modal 弹出框
- **分类**: feedback
- **Skill 版本**: V1.1.0
- **适配组件库**: win-design-next 1.2.2
- **API 来源**: `docs/zh-CN/component/modal.md`

## API

## Events

打开开发者控制台(ctrl + shift + J)，查看事件的顺序。

## API

### Attributes

| 属性名                          | 说明                                                                                           | 类型                                | 默认  |
| ------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------- | ----- |
| model-value / v-model           | 是否显示 Modal                                                                                 | ^[boolean]                          | —     |
| title                           | Modal 对话框 Modal 的标题， 也可通过具名 slot （见下表）传入                                   | ^[string]                           | ''    |
| width                           | 对话框的宽度，默认值为 50%                                                                     | ^[string] / ^[number]               | ''    |
| fullscreen                      | 是否为全屏 Modal                                                                               | ^[boolean]                          | false |
| top                             | modal CSS 中的 margin-top 值，默认为 15vh                                                      | ^[string]                           | ''    |
| modal                           | 是否需要遮罩层                                                                                 | ^[boolean]                          | true  |
| modal-class                     | 遮罩的自定义类名                                                                               | ^[string]                           | —     |
| header-class                    | header 部分的自定义 class 名                                                                   | ^[string]                           | —     |
| body-class                      | body 部分的自定义 class 名                                                                     | ^[string]                           | —     |
| footer-class                    | footer 部分的自定义 class 名                                                                   | ^[string]                           | —     |
| append-to-body                  | Modal 自身是否插入至 body 元素上。 嵌套的 Modal 必须指定该属性并赋值为 `true`                  | ^[boolean]                          | false |
| append-to                       | Modal 挂载到哪个 DOM 元素 将覆盖 `append-to-body`                                              | ^[string] / ^[HTMLElement]          | body  |
| lock-scroll                     | 是否在 Modal 出现时将 body 滚动锁定                                                            | ^[boolean]                          | true  |
| open-delay                      | modal 打开的延时时间，单位毫秒                                                                 | ^[number]                           | 0     |
| close-delay                     | modal 关闭的延时时间，单位毫秒                                                                 | ^[number]                           | 0     |
| close-on-click-modal            | 是否可以通过点击 modal 关闭 Modal                                                              | ^[boolean]                          | true  |
| close-on-press-escape           | 是否可以通过按下 ESC 关闭 Modal                                                                | ^[boolean]                          | true  |
| show-close                      | 是否显示关闭按钮                                                                               | ^[boolean]                          | true  |
| before-close                    | 关闭前的回调，会暂停 Modal 的关闭. 回调函数内执行 done 参数方法的时候才是真正关闭对话框的时候. | ^[Function]`(done: DoneFn) => void` | —     |
| draggable                       | 为 Modal 启用可拖拽功能                                                                        | ^[boolean]                          | false |
| overflow                        | 拖动范围可以超出可视区                                                                         | ^[boolean]                          | false |
| center                          | 是否让 Modal 的 header 和 footer 部分居中排列                                                  | ^[boolean]                          | false |
| align-center                    | 是否水平垂直对齐对话框                                                                         | ^[boolean]                          | false |
| destroy-on-close                | 当关闭 Modal 时，销毁其中的元素                                                                | ^[boolean]                          | false |
| close-icon                      | 自定义关闭图标，默认 Close                                                                     | ^[string] / ^[Component]            | —     |
| z-index                         | 和原生的 CSS 的 z-index 相同，改变 z 轴的顺序                                                  | ^[number]                           | —     |
| header-aria-level ^(a11y)       | header 的 `aria-level` 属性                                                                    | ^[string]                           | 2     |
| custom-class ^(deprecated)      | Modal 的自定义类名                                                                             | ^[string]                           | ''    |
| subtitle ^(1.0.0)               | 对话框的副标题                                                                                 | ^[string]                           | ''    |
| color ^(1.0.0)                  | 是否为彩色对话框                                                                               | ^[boolean]                          | false |
| transition ^(1.0.0)             | 自定义动画类名                                                                                 | ^[string]                           | —     |
| click-modal-other ^(1.0.0)      | 关闭遮罩时是否可以操作其它功能区域                                                             | ^[boolean]                          | false |
| click-to-front ^(1.0.0)         | 多个 Modal 并存时点击置顶显示                                                                  | ^[boolean]                          | false |
| resize ^(1.0.0)                 | 是否允许拖拽改变大小                                                                           | ^[boolean]                          | false |
| resize-min-width ^(1.0.0)       | 拖拽改变大小时的最小宽度                                                                       | ^[number]                           | 300   |
| resize-min-height ^(1.0.0)      | 拖拽改变大小时的最小高度                                                                       | ^[number]                           | 150   |
| height ^(1.0.0)                 | 对话框的高度                                                                                   | ^[number]                           |       |
| max-height ^(1.0.0)             | 对话框的最大高度                                                                               | ^[number]                           |       |
| horizontal-paddingless ^(1.0.4) | 是否移除对话框的左右边距                                                                       | ^[boolean]                          | false |
| vertical-paddingless ^(1.0.4)   | 是否移除对话框的上下边距                                                                       | ^[boolean]                          | false |

### Slots

| 插槽名              | 说明                                                   |
| ------------------- | ------------------------------------------------------ |
| default             | 对话框的默认内容                                       |
| header              | 对话框标题的内容；会替换标题部分，但不会移除关闭按钮。 |
| footer              | Modal 按钮操作区的内容                                 |
| title ^(deprecated) | 与 header 作用相同 请使用 header                       |

### 事件

| 名称                          | 详情                              | Type                    |
| ----------------------------- | --------------------------------- | ----------------------- |
| open                          | Modal 打开的回调                  | ^[Function]`() => void` |
| opened                        | Modal 打开动画结束时的回调        | ^[Function]`() => void` |
| close                         | Modal 关闭的回调                  | ^[Function]`() => void` |
| closed                        | Modal 关闭动画结束时的回调        | ^[Function]`() => void` |
| open-auto-focus               | 输入焦点聚焦在 Modal 内容时的回调 | ^[Function]`() => void` |
| close-auto-focus              | 输入焦点从 Modal 内容失焦时的回调 | ^[Function]`() => void` |
| before-resize-change ^(1.0.0) | 拖拽改变大小时的回调              | ^[Function]`() => void` |
| after-resize-change ^(1.0.0)  | 拖拽改变大小结束时的回调          | ^[Function]`() => void` |

### Exposes

| 名称          | 详情     | 类型                    |
| ------------- | -------- | ----------------------- |
| resetPosition | 重置位置 | ^[Function]`() => void` |
