新版本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结构即可).

概览

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

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

  1. <button data-toggle="modal" data-target="#myModal" data-keyboard="false" class="sui-btn btn-primary btn-lg">对话框已写入html</button>
  2. <!-- Modal-->
  3. <div id="myModal" tabindex="-1" role="dialog" data-hasfoot="false" class="sui-modal hide fade">
  4. <div class="modal-dialog">
  5. <div class="modal-content">
  6. <div class="modal-header">
  7. <button type="button" data-dismiss="modal" aria-hidden="true" class="sui-close">×</button>
  8. <h4 id="myModalLabel" class="modal-title">Modal title</h4>
  9. </div>
  10. <div class="modal-body">我是内容body</div>
  11. <div class="modal-footer">
  12. <button type="button" data-ok="modal" class="sui-btn btn-primary btn-large">可自定ok</button>
  13. <button type="button" data-dismiss="modal" class="sui-btn btn-default btn-large">可自定dismiss</button>
  14. </div>
  15. </div>
  16. </div>
  17. </div>
  18. <script>
  19. $('#myModal').on('okHide', function(e){console.log('okHide')})
  20. $('#myModal').on('okHidden', function(e){console.log('okHidden')})
  21. $('#myModal').on('cancelHide', function(e){console.log('cancelHide')})
  22. $('#myModal').on('cancelHidden', function(e){console.log('cancelHidden')})
  23. </script>
$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 当模态对话框因确认逻辑而被隐藏(而且过渡效果执行完毕)之后,此事件将被触发。
  1. $('#myModal').on('hidden', function () {
  2. // do something…
  3. })


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

  1. <button id="J_alert1" class="sui-btn btn-primary btn-lg">$.alert('xxx')</button>
  2. <button id="J_confirm1" class="sui-btn btn-primary btn-lg">$.confirm('xxx')</button>
  3. <script>
  4. $('#J_alert1').on('click', function(e){
  5. $.alert('alert it is | alert it is | alert it is | alert it is | alert it is | alert it is | alert it is | alert it is | alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | <br>| alert it is | ')
  6. })
  7. $('#J_confirm1').on('click', function(e){
  8. $.confirm({
  9. body: 'cconfirmconfirmconfirmconfirmconfirmonfirm <br> 这里设置了height属性手动改变高度'
  10. ,height: 300
  11. })
  12. })
  13. </script>

静态方法有alert和confirm

静态方法的构造原则

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

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

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

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

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

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

  1. <button id="J_lizi1" class="sui-btn btn-primary btn-lg">各种状态检测(打开F12)</button>
  2. <script>
  3. $('#J_lizi1').on('click', function(e){
  4. $.confirm({
  5. body: 'confirm again'
  6. ,width: 'normal'
  7. ,backdrop: true
  8. ,bgcolor: 'none'
  9. ,show: function(){console.log('show')}
  10. ,shown: function(){console.log('shown')}
  11. ,hide: function(){console.log('hide')}
  12. ,hidden: function(){console.log('hiden')}
  13. ,okHide: function(){var a=confirm('true or false');if(!a) return false}
  14. ,okHidden: function(){console.log('okHidden')}
  15. ,cancelHide: function(){console.log('cancelHide')}
  16. ,cancelHidden: function(){console.log('cancelHidden')}
  17. })
  18. })
  19. </script>
  20. <button id="J_remote" data-toggle="modal" data-remote="../package.json" data-target="#J_remotemodal" class="sui-btn btn-primary">加载远端内容</button>
  21. <div id="J_remotemodal" tabindex="-1" role="dialog" data-hasfoot="false" class="sui-modal hide fade">
  22. <div class="modal-dialog">
  23. <div class="modal-content">
  24. <div class="modal-header">
  25. <button type="button" data-dismiss="modal" aria-hidden="true" class="sui-close">×</button>
  26. <h4 class="modal-title">remote Modal title</h4>
  27. </div>
  28. <div class="modal-body">我是内容body</div>
  29. </div>
  30. </div>
  31. </div>

对话框叠加,层上层

  1. <button id="J_addsuppliers" data-toggle="modal" data-target="#J_addsuppliersDialog" data-width="large" data-backdrop="static" class="sui-btn btn-primary">添加供应商</button><div id="J_addsuppliersDialog" tabindex="-1" role="dialog" class="sui-modal hide fade" data-addsupplierurl="http://" data-getsuppliersurl="http://xxx">
  2. <div class="modal-dialog">
  3. <div class="modal-content">
  4. <div class="modal-header">
  5. <button type="button" data-dismiss="modal" aria-hidden="true" class="sui-close">×</button>
  6. <h4 id="myModalLabel" class="modal-title">供应商收编</h4>
  7. </div>
  8. <div class="modal-body sui-form form-horizontal">
  9. <div class="sui-msg msg-block msg-default msg-tips">
  10. <div class="msg-con">以下为供销平台上已经获得小二授权经营您的品牌但还未被您进行收编的供应商</div>
  11. <s class="msg-icon"></s>
  12. </div>
  13. <table class="sui-table table-bordered-simple">
  14. <thead>
  15. <tr>
  16. <th>供应商昵称</th>
  17. <th>公司名称</th>
  18. <th>供应商类型</th>
  19. <th>分销商数量</th>
  20. <th>授权品牌</th>
  21. <th>操作</th>
  22. </tr>
  23. </thead>
  24. <tbody>
  25. <tr>
  26. <td><span>only淘宝商城官方旗舰店</span></td>
  27. <td><span>九牧官方旗舰店</span></td>
  28. <td><span>企业</span></td>
  29. <td><span class="distributor-num">432</span></td>
  30. <td>
  31. <ul class="authorize-brand">
  32. <li>海尔</li>
  33. <li>统帅</li>
  34. </ul>
  35. </td>
  36. <td data-supplierid="111">
  37. <button class="sui-btn btn-small J_addOneSupplier">添加</button>
  38. </td>
  39. </tr>
  40. </tbody>
  41. </table>
  42. </div>
  43. </div>
  44. </div>
  45. </div>
  46. <script>
  47. $supDialog = $('#J_addsuppliersDialog')
  48. $supDialog.on('click', '.J_addOneSupplier', function(e) {
  49. $supDialog.modal('shadeIn');
  50. return $.confirm({
  51. title: '确认',
  52. body: '您确认添加该供应商吗?',
  53. backdrop: false,
  54. okHide: function() {
  55. $.alert({
  56. hasfoot: false,
  57. backdrop: false,
  58. title: '不管发生了什么,总之成功了',
  59. body: 'msg-large msg-block msg-',
  60. timeout: 1000
  61. });
  62. },
  63. hide: function() {
  64. return $supDialog.modal('shadeOut');
  65. }
  66. });
  67. });
  68. </script>

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

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

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


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

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

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