Modal对话框

模态对话框。

何时使用#

需要用户处理事务,又不希望跳转页面以致打断工作流程时,可以使用 Modal 在当前页面正中打开一个浮层,承载相应的操作。

另外当需要一个简洁的确认框询问用户时,可以使用精心封装好的 NzModalService.confirm() 等方法。

推荐使用加载Component的方式弹出Modal,这样弹出层的Component逻辑可以与外层Component完全隔离,并且做到可以随时复用,

在弹出层Component中可以通过依赖注入NzModalRef方式直接获取模态框的组件实例,用于控制在弹出层组件中控制模态框行为。

import { NzModalModule } from 'ng-zorro-antd/modal';

代码演示

第一个对话框。

expand codeexpand code
加载中

使用 NzModalService.confirm() 可以快捷地弹出确认框。

expand codeexpand code
加载中

各种类型的信息提示,只提供一个按钮用于关闭。

expand codeexpand code
加载中

手动关闭modal。

expand codeexpand code
加载中




Modal的service用法,示例中演示了用户自定义模板、自定义component、以及注入模态框实例的方法。

使用模版作为内容或页脚时的上下文为 { $implicit: nzComponentParams, modalRef: NzModalRef }

expand codeexpand code
加载中

点击确定后异步关闭对话框,例如提交表单。

expand codeexpand code
加载中


使用 nzModalFooter 指令自定义了页脚的按钮。

expand codeexpand code
加载中

使用 NzModalService.confirm() 可以快捷地弹出确认框。NzOnCancel/NzOnOk 返回 promise 可以延迟关闭

expand codeexpand code
加载中

设置 nzOkTextnzCancelText 以自定义按钮文字。

expand codeexpand code
加载中


使用 nzCentered 或类似 style.top 的样式来设置对话框位置。

注意 由于Angular的样式隔离,若在Component中没有加入encapsulation: ViewEncapsulation.None,则您可能需要在自定义样式内采用::ng-deep来覆盖NgZorro的样式

expand codeexpand code
加载中

API#

NzModalService#

对话框当前分为2种模式,普通模式确认框模式(即Confirm对话框,通过调用confirm/info/success/error/warning弹出),两种模式对API的支持程度稍有不同。

参数说明类型默认值全局配置
nzAfterOpenModal 打开后的回调EventEmitter-
nzAfterCloseModal 完全关闭后的回调,可监听close/destroy方法传入的参数EventEmitter-
nzBodyStyleModal body 样式object-
nzCancelText取消按钮文字。设为 null 表示不显示取消按钮(若在普通模式下使用了 nzFooter 参数,则该值无效)string取消
nzCentered垂直居中展示 Modalbooleanfalse
nzClosable是否显示右上角的关闭按钮。确认框模式下该值无效(默认会被隐藏)booleantrue
nzOkLoading确定按钮 loadingbooleanfalse
nzCancelLoading取消按钮 loadingbooleanfalse
nzOkDisabled是否禁用确定按钮booleanfalse
nzCancelDisabled是否禁用取消按钮booleanfalse
nzFooter底部内容。1. 仅在普通模式下有效。
2. 可通过传入 ModalButtonOptions 来最大程度自定义按钮(详见案例或下方说明)。
3. 当不需要底部时,可以设为 null
string
TemplateRef
ModalButtonOptions
默认的确定取消按钮
nzKeyboard是否支持键盘esc关闭booleantrue
nzMask是否展示遮罩booleantrue
nzMaskClosable点击蒙层是否允许关闭booleantrue
nzCloseOnNavigation当用户在历史中前进/后退时是否关闭模态框。注意,这通常不包括点击链接(除非用户使用HashLocationStrategy)。booleantrue
nzDirection文字方向'ltr' | 'rtl'-
nzMaskStyle遮罩样式object-
nzOkText确认按钮文字。设为 null 表示不显示确认按钮(若在普通模式下使用了 nzFooter 参数,则该值无效)string确定
nzOkType确认按钮类型。nz-buttonnzType 类型值一致stringprimary
nzOkDanger确认按钮是否为危险按钮。nz-buttonnzDanger 值保持一致booleanfalse
nzStyle可用于设置浮层的样式,调整浮层位置等object-
nzTitle标题。留空表示不展示标题。TemplateRef的使用方法可参考案例string
TemplateRef
-
nzCloseIcon自定义关闭图标string|TemplateRef<void>-
nzVisible对话框是否可见。当以 <nz-modal> 标签使用时,请务必使用双向绑定,例如:[(nzVisible)]="visible"booleanfalse
nzWidth宽度。使用数字时,默认单位为pxstring
number
520
nzClassName对话框的类名string-
nzWrapClassName对话框外层容器的类名string-
nzZIndex设置 Modal 的 z-indexnumber1000
nzOnCancel点击遮罩层或右上角叉或取消按钮的回调(若nzContent为Component,则将会以该Component实例作为参数)。注:当以NzModalService.create创建时,此参数应传入function(回调函数)。该函数可返回promise,待执行完毕或promise结束时,将自动关闭对话框(返回false可阻止关闭)EventEmitter-
nzOnOk点击确定回调(若nzContent为Component,则将会以该Component实例作为参数)。注:当以NzModalService.create创建时,此参数应传入function(回调函数)。该函数可返回promise,待执行完毕或promise结束时,将自动关闭对话框(返回false可阻止关闭)EventEmitter-
nzContent内容string
TemplateRef
Component
ng-content
-
nzComponentParamsnzContent 为组件时将作为实例属性,为 TemplateRef 时将作为模版变量object-
nzIconType图标 Icon 类型。仅 确认框模式 下有效string'question-circle'
nzAutofocus自动聚焦及聚焦位置,为 null 时禁用'ok' | 'cancel' | 'auto' | null'auto'

注意#

nzComponentParams 属性的创建或修改不会触发 nzContent 组件的 ngOnChanges 生命周期钩子。

采用服务方式创建普通模式对话框#

您可调用 NzModalService.create(options) 来动态创建普通模式对话框,这里的 options 是一个对象,支持上方API中给出的支持 普通模式 的参数

确认框模式 - NzModalService.method()#

包括:

  • NzModalService.info
  • NzModalService.success
  • NzModalService.error
  • NzModalService.warning
  • NzModalService.confirm

以上均为一个函数,参数为 object,与上方API一致。部分属性类型或初始值有所不同,已列在下方:

参数说明类型默认值
nzOnOk点击确定按钮时将执行的回调函数(若nzContent为Component,则将会以该Component实例作为参数)。该函数可返回promise,待执行完毕或promise结束时,将自动关闭对话框(返回false可阻止关闭)function-
nzOnCancel点击遮罩层或右上角叉或取消按钮的回调(若nzContent为Component,则将会以该Component实例作为参数)。该函数可返回promise,待执行完毕或promise结束时,将自动关闭对话框(返回false可阻止关闭)function-
nzWidth宽度string
number
416
nzMaskClosable点击蒙层是否允许关闭booleanfalse

以上函数调用后,会返回一个引用,可以通过该引用关闭弹窗。

constructor(modal: NzModalService) {
  const ref: NzModalRef = modal.info();
  ref.close(); // 或 ref.destroy(); 将直接销毁对话框
}

相关类型定义#

NzModalService的其他方法/属性#

方法/属性说明类型
openModals当前打开的所有Modal引用列表NzModalRef[]
afterAllClose所有Modal完全关闭后的回调Observable<void>
closeAll()关闭所有模态框function

NzModalRef#

NzModalRef 对象用于控制对话框以及进行内容间的通信

通过服务方式 NzModalService.xxx() 创建的对话框,都会返回一个 NzModalRef 对象,用于操控该对话框(若使用nzContent为Component时,也可通过依赖注入 NzModalRef 方式获得此对象),该对象具有以下方法:

方法/属性说明
afterOpen同nzAfterOpen,但类型为Observable<void>
afterClose同nzAfterClose,但类型为Observable<result:any>
close(result: any)关闭(隐藏)对话框。注:当用于以服务方式创建的对话框,此方法将直接 销毁 对话框(同destroy方法)
destroy(result: any)销毁对话框。注:仅用于服务方式创建的对话框(非服务方式创建的对话框,此方法只会隐藏对话框)
getContentComponent()获取对话框内容中nzContent的Component实例instance。注:当对话框还未初始化完毕(ngOnInit未执行)时,此函数将返回undefined
triggerOk()手动触发nzOnOk
triggerCancel()手动触发nzOnCancel
updateConfig(config: ModalOptions): void更新配置

ModalButtonOptions(用于自定义底部按钮)#

可将此类型数组传入 nzFooter,用于自定义底部按钮。

按钮配置项如下(与button组件保持一致):

nzFooter: [{
  label: string; // 按钮文本
  type?: string; // 类型
  danger?: boolean; // 是否danger
  shape?: string; // 形状
  ghost?: boolean; // 是否ghost
  size?: string; // 大小
  autoLoading?: boolean; // 默认为true,若为true时,当onClick返回promise时此按钮将自动置为loading状态

  // 提示:下方方法的this指向该配置对象自身。当nzContent为组件类时,下方方法传入的contentComponentInstance参数为该组件类的实例
  // 是否显示该按钮
  show?: boolean | ((this: ModalButtonOptions, contentComponentInstance?: object) => boolean);
  // 是否显示为loading
  loading?: boolean | ((this: ModalButtonOptions, contentComponentInstance?: object) => boolean);
  // 是否禁用
  disabled?: boolean | ((this: ModalButtonOptions, contentComponentInstance?: object) => boolean);
  // 按钮点击回调
  onClick?(this: ModalButtonOptions, contentComponentInstance?: object): void | Promise&lt;void&gt; | any;
}]

以上配置项也可在运行态实时改变,来触发按钮行为改变。

[nzModalTitle]#

自定义标题。

<div *nzModalTitle>
  Custom Modal Title
</div>

<!-- or -->

<ng-template [nzModalTitle]>
  Custom Modal Title
</ng-template>

[nzModalFooter]#

自定义页脚。

<div *nzModalFooter>
  <button nz-button nzType="default" (click)="handleCancel()">Custom Callback</button>
  <button nz-button nzType="primary" (click)="handleOk()" [nzLoading]="isConfirmLoading">Custom Submit</button>
</div>

<!-- or -->

<ng-template [nzModalFooter]>
  <button nz-button nzType="default" (click)="handleCancel()">Custom Callback</button>
  <button nz-button nzType="primary" (click)="handleOk()" [nzLoading]="isConfirmLoading">Custom Submit</button>
</ng-template>