新版本1.4.2发布了。第一次升级到 1.4.x 版本请注意在1.4.0版本的重大变动,具体请阅读更新日志

设计规范

开发者文档

对话框分为独占式和非独占式两种。
注意href属性可用来指向对话框主体元素,不再能引用远程内容url
文档写的渣,有任何疑惑可以联系@半边。

  • 更新 v1.1.3:增加了cancelHide/cancelHidden接口,增加了高度控制,增加了对绝对定位元素导致滚动条的说明。
  • 更新 v1.2.2:加载远程内容的时候不再加载 href属性指定的地址,只能通过 remote 参数或者 data-remote 属性来指定。
  • 更新 v1.4.3:增加了closeBtn, transition 2个布尔值配置项,决定是否显示右上角叉叉和是否动画显示、隐藏(html使用方式直接改html结构即可).

概览

原型方法 $ele需要事先写到html中
$ele.modal(options | 'toggle' | 'show' | 'hide') // $ele是对话框元素,不是触发元素
静态方法
$.alert('this is typical alert')
$.alert(options)
$.confirm('this is typical confirm')
$.confirm(options)

1. 不写js初始化对话框,原型方法控制。用于复杂结构对话框。


              
$ele.modal(opstions)  让指定的内容变成一个模态对话框。接受一个可选的参数
$ele.modal('show')  手动打开一个模态对话框。
$ele.modal('hide')  手动关闭一个模态对话框。
$ele.modal('okHide')  手动关闭一个模态对话框,此时不会再触发okHide事件回调,而是在对话框关闭后会触发okHidden事件。
$ele.modal('toggle')  手动打开或关闭一个模态对话框。
$ele.modal('shadeIn')  使该对话框自身被遮罩层遮住,方便层上层的调用操作。
$ele.modal('shadeOut')  顾名思义,上一条的逆操作。
$ele.modal('shadeToggle')  顾名思义,上两条的交替操作。
$ele.modal('resize') dialog展示后,如果高度动态发生变化,比如塞入异步数据后撑高容器,则调用该接口使dialog重新定位居中

简单使用方法

无需编写JavaScript代码即可生成一个对话框。在一个主控元素,例如按钮,上设置data-toggle="modal",然后再设置data-target="#foo"href="#foo" 用以指向某个将要被启动的对话框。

属性都是必须的。也可通过$ele.modal(opt)触发,注意这里的$ele是对话框元素,不是触发元素(如某个按钮)

对异步操作的增强支持

对确定按钮[data-ok="modal"]动态添加class="disabled" 可以阻止按钮被点击,同时阻止okHide事件的执行

此HTML模板方法对话框针对层上层的处理

层上层通常是对 对话框操作的确认提示以及反馈,不会再有复杂业务逻辑,所以合理搭配是:
下层为复杂业务的原型方法对话框,上层为简单静态方法对话框。其他组合可能会有问题。
调用$ele.modal('shade')可以使自身被遮罩(不是全屏遮罩),然后可安心处理上层对话框弹出并让用户操作。

2种对话框的取舍。

涉及弹层html结构/的参数(如hasfoot,okbtn,cancelbtn)不适用此类调用方法,因为弹层html结构已经被写在html中,比如不要脚部,则.modal-footer及其子元素不写到html里即可

属性参数不止下方这些。除了不能使用回调函数型的参数,其余均和js调用的对话框参数相同,注入data-**属性即可,部分data-属性参数举例:
名称 类型 默认值 描述
backdrop boolean true 决定是否为模态对话框添加一个背景遮罩层。另外,该属性指定static时,表示添加遮罩层,同时点击模态对话框的外部区域不会将其关闭。
keyboard boolean true 按下esc键时关闭模态对话框
show boolean true 初始化时即显示模态对话框
remote path false 如果提供了远程url地址,就会通过 jQuery的load方法加载内容并注入到.modal-body中。案例如下
<a data-toggle="modal" href="remote.html" data-target="#modal">click me</a>

原型方法的事件接口,与bootstrap提供的一致,与静态方法不互用

名称 类型
show show方法被调用时,此事件将被立即触发。
shown 当模态对话框呈现到用户面前时(会等待过渡效果执行结束)此事件被触发。
hide hide方法被调用时,此事件被立即触发。
hidden 当模态对话框被隐藏(而且过渡效果执行完毕)之后,此事件将被触发。
okHide 当模态对话框因为被点击了确认按钮而被隐藏之前,此事件被立即触发。回调函数可以通过返回true|false控制对话框是否会被继续关闭。如果多次绑定okHide事件,只取最后一次绑定的事件回调执行,并取返回值。
okHidden 当模态对话框因为确认逻辑而被隐藏(而且过渡效果执行完毕)之后,此事件将被触发。
cancelHide 当模态对话框因确认逻辑而被隐藏之前,此事件被立即触发。
cancelHidden 当模态对话框因确认逻辑而被隐藏(而且过渡效果执行完毕)之后,此事件将被触发。
$('#myModal').on('hidden', function () {
  // do something…
})


2. $.alert/$.confirm静态方法快速生成,返回对话框元素的jQuery对象。用于简单对话框。


              

静态方法有alert和confirm

静态方法的构造原则

最大限度的还原系统自带alert,confirm的使用体验,快捷同时可通过扩展参数加强功能。

静态方法和原型方法使用的基本原则

静态方法适宜于较少重复/多处出现/勿需记忆状态的弹层,可方便的直接调用,最简单形式就是$.alert('亚哈了他了该')。

若弹层Dom结构复杂,本身可作为复杂业务组件,建议将弹层html结构写到html里,用$ele.modal(options) 调用。

静态方法不调用后不返回实例对象。

和confirm2个方法的参数一致,参见下面:
$.alert({
 backdrop: true   决定是否为模态对话框添加一个背景遮罩层。另外,该属性指定static时,表示添加遮罩层,同时点击模态对话框的外部区域不会将其关闭。
 bgcolor: '#123456'   背景遮罩层颜色,默认是黑色。可以用rgba设置透明度
 keyboard: true   是否可由esc按键关闭
 title: '自定义标题'
 body: 'html' //必填
 okBtn : '好的'
 cancelBtn : '雅达'
 closeBtn: true/false   是否显示右上角叉叉(html使用方式无需配置,直接改html结构即可)
 transition: true/false   是否以transition动画方式显示隐藏对话框(html使用方式调用对话框时,也可直接删除.sui-modal元素上的类名fade即可)
 hasfoot: {Boolean}  是否显示脚部  默认true
 width: {number|string(px)|'small'|'normal'|'large'}推荐优先使用后三个描述性字符串,统一样式
 height: {number|string(px)} 内容区(.modal-body)高度
 remote: {string} 如果提供了远程url地址,就会加载远端内容
 timeout: {number} 1000    单位毫秒ms ,对话框打开后多久自动关闭
 show:     fn --------------function(e){}
 shown:    fn
 hide:     fn
 hidden:   fn
 okHide:   function(e){alert('点击确认后、对话框消失前的逻辑,
           函数返回true(默认)则对话框关闭,反之不关闭;若不传入则默认是直接返回true的函数
           注意不要人肉返回undefined!!')}
 okHidden: function(e){alert('点击确认后、对话框消失后的逻辑')}
 cancelHide: fn  取消关闭前
 cancelHidden: fn  取消关闭后
 
})
静态方法事件不用人肉再去写绑定代码,直接将事件回调写进参数。
名称 类型
show 方法被调用时对话框尚未展现前,此事件将被立即触发。
shown 对话框展现后此事件被触发。
hide 当对话框因为任何原因(点击确定或取消,等等)要关闭,但尚未关闭前,此事件被立即触发。
hidden 当对话框因为任何原因(点击确定或取消,等等)要关闭,并确实关闭后,此事件被触发。
okHide 当对话框因为触发正向原因(点击确定、保存或之类的逻辑按钮)要关闭,但尚未关闭前,此事件被立即触发。
okHidden 当对话框因为触发正向原因(点击确定、保存或之类的逻辑按钮)要关闭,并确实关闭后,此事件被触发。


              

对话框叠加,层上层


              

有几点注意,使用层上层时

底层:一定是复杂对话框,一定是使用的原型方法,即HTML写在模板中的对话框。要设置backdrop:static,已防止上层显示时不小心点击背景使底层消失了。。。

上层:只要不是底层,都设置backdrop:false,避免多背景。同时上层show时可以调用底层方法 $supDialog.modal('shadeIn')使底层被遮罩,防止又对底层做了其他操作。上层关闭后调用$supDialog.modal('shadeOut')复原。


绝对定位元素导致对话框的滚动条问题

为了控制对话框的高度,并且在内容超过高度之后可以滚动,我们在 modal-body 上加了如下css代码:

由于设定了 overflow-y: auto;,如果在 modal-body 中有绝对定位元素并且超过了 modal-body 边界,那么依然会引起滚动。比如在对话框底部用了下拉菜单元素,下拉菜单是绝对定位的,会导致对话框的内容滚动,这种情况下需要给 modal-body 设置overflow: initial
如果想控制高度可以为对话框传入 height 参数。max-height目前可以通过css修改。