设计规范
开发者文档
对话框分为独占式和非独占式两种。
注意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) 调用。
静态方法不调用后不返回实例对象。
$.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修改。