对话框触发器允许你不需要书写静态对话框HTML,直接使用触发按钮或者一行Javascript代码即可让一个全新的对话框展现。支持使用Ajax从远程获取内容,或者通过iframe加载任何页面内容,当然不使用远程内容,直接使用本地内容也是很方便。

加载远程内容

这里提供两种方法(Ajax和iframe)来加载远程内容,使用起来几乎似乎没有任何区别,你只需要确保远程地址所提供的内容是正确的类型。

在获取远程内容到显示的过程中,会显示正在加载的图标动画。

使用Ajax

使用data-remote="(ajax get url)"属性来指定ajax片段获取地址。或者同时指定data-type="ajax"data-url="(ajax get url)"属性。

<!-- 使用data-remote属性 -->
<button type="button" class="btn btn-primary" data-remote="partial/remote-modal.html" data-toggle="modal">Ajax对话框</button>

<!-- 使用data-type 和data-url属性 -->
<button type="button" class="btn btn-primary" data-type="ajax" data-url="partial/remote-modal.html" data-toggle="modal">Ajax对话框≶/button>

在返回的ajax片段中,你可以包含一个完整的.modal-dialog内容,或者仅包含.modal-content,甚至不是任何静态modal结构,触发器会根据所包含的内容自动补全对话框的缺失部分。

使用iframe(内嵌框架)

使用data-iframe="(iframe url)"属性来指定远程页面内容获取地址。或者同时指定data-type="iframe"data-url="(iframe url)"属性。

<!-- 使用data-iframe属性 -->
<button type="button" class="btn btn-primary" data-iframe="partial/iframe-modal.html" data-toggle="modal">iframe对话框</button>

<!-- 使用data-type 和data-url属性 -->
<button type="button" class="btn btn-primary" data-type="iframe" data-url="partial/iframe-modal.html" data-toggle="modal">iframe对话框≶/button>

加载自定义内容

通过定义custom属性可以更灵活的为对话框更新内容。

指定内容文本

最简单的方法是为custom指定内容文本即可。同样可以使用data-custom属性。

<!-- 使用data-custom 属性 -->
<button type="button" class="btn btn-primary" data-custom="此内容是自定义的:)" data-toggle="modal">指定内容文本</button>
/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({custom: '<h1>此内容是自定义的</h1><p>哈哈:)</p>'});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({custom: '自定义内容'})).show();

指定页面元素作为内容

通过指定一个jQuery选择器名称来获取其内容作为对话框的内容。

我希望能够在对话框看到此消息。
<!-- 使用data-custom 属性 -->
<button type="button" class="btn btn-primary" data-custom="#myModalAlert" data-toggle="modal">指定页面元素的内容</button>
/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({custom: '#myModalAlert'});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({custom: '#myModalAlert'})).show();

使用jQuery对象作为内容

直接为custom参数赋值为一个jQuery对象,此对象的内容将显示在对话框中。此方式无法使用data属性调用。

/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({custom: $('#myModalAlert')});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({custom: $('#myModalAlert')})).show();

使用回调函数动态生成内容

将一个回调函数赋值给custom参数,触发器对象会自动调用此函数来实时获得动态内容并显示在对话框中。

回调函数提供一个参数对象,可以在生成内容时灵活运用。如果生成的内容是异步的时候,需要在内容准备就绪时调用参数提供的.ready()方法来显示对话框。

/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({custom: function() {
    return "当对话框显示时,时间是:" + (new Date).toString();
}});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({custom: function() {
    return "当对话框显示时,时间是:" + (new Date).toString();
}})).show();

如果你的回调函数是全局的,则只需要将custom参数指定为该函数的名称的字符串。

自动调整位置

当对话框内的内容发生更改导致对话框尺寸发生改变时,对话框会根据设置自动调整位置。

自动调整位置适合任何形式的对话框。

全屏对话框

<button type="button" class="btn btn-primary" data-custom="..." data-toggle="modal" data-size="fullscreen">全屏对话框</button>

自定义头部

不显示头部

不显示头部需要指定参数showHeaderfalse

<!-- 使用data-showHeader 属性 -->
<button type="button" class="btn btn-primary" data-show-header="false" data-toggle="modal">不显示头部</button>
/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({showHeader: false});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({showHeader: false})).show();

自定义对话框标题

如果不指定对话框的标题,会自动使用触发按钮的title属性或文本作为对话框的标题。

<!-- 使用data-title 属性 -->
<button type="button" class="btn btn-primary" data-title="新的标题" data-toggle="modal">不显示头部</button>
/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({title: '新的标题'});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({title: '新的标题'})).show();

使用图标

通过指定icon属性来在标题前面增加一个图标。

图标的定义请参考“控件->图标”章节。

<!-- 使用data-title 属性 -->
<button type="button" class="btn btn-primary" data-icon="heart" data-toggle="modal">不显示头部</button>
/* 使用Javascript方法绑定在按钮上触发 */
$('#triggerButton').modalTrigger({icon: 'heart'});

/* 使用触发器对象直接显示 */
(new $.zui.ModalTrigger({icon: 'heart'})).show();

可拖动的对话框

开启此选项可以允许用户在对话框显示之后通过拖拽头部移动对话框。

<button type="button" class="btn btn-primary" data-moveable="true" data-toggle="modal" data-custom="..."><i class="icon icon-move"></i> 打开我 拖动我</button>

如何使用

使用data属性来调用

使用在触发按钮上设置data属性即可使用。此方法与常规对话框触发按钮属性书写方式完全一致,只不过需要增加几个特殊属性,包括data-remotedata-iframedata-custom

使用dta属性来调用请参考上面的实例章节。

使用Javascript手动调用

Javascript方法也十分灵活。

jQuery对象方法

使得一个jquery对象能够监听事件(一般为点击)并启动对话框。

$('#triggerButton').modalTrigger(options);

也可以使用modalTrigger的别名方法modal,这样与传统对话框的初始化方法完全一致。

使用预设的modalTrigger实例

$.zui对象上已默认绑定了一个对话框触发器对象,可以直接使用方法并传递不同的参数来随时启动对话框。

$.zui.modalTrigger.show(options);

创建新的触发器对象

创建一个新的对话框触发器来保存配置并启动对话框。

var myModalTrigger = new $.zui.ModalTrigger(options);
myModalTrigger.show();

参数

在初始化对话框或者显示时都能够使用参数来个性化你的对话框。

参数 名称 可选值 说明
type 对话框类型
  • 'custom'(默认),自定义类型
  • 'iframe'
  • 'ajax'
通常该参数和参数url一起使用,当指定了customremoteiframe参数时该参数可以忽略
url 远程内容地址 远程地址字符串 通常该参数和type一起似乎用,当指定了customremoteiframe参数时该参数可以忽略
remote Ajax内容地址 远程地址字符串 如果使用该参数,则参数typeurl可以忽略
iframe iframe页面地址 远程地址字符串 如果使用该参数,则参数typeurl可以忽略
size 对话框大小
  • ''(默认),默认大小
  • 'lg',大对话框
  • 'sm',小对话框
  • 'fullscreen',全屏显示
width 对话框宽度
  • null(默认),默认宽度
  • 其他表示宽度的CSS值字符串
如果使用size参数,则可以忽略该参数
height 对话框宽度
  • 'auto'(默认),自动根据内容调整
  • 其他表示高度的CSS值字符串
如果指定了高度不是'auto'则可能出现内容与高度不匹配的情况。
showHeader 是否显示标题
  • true(默认)
  • false
title 对话框标题文本 字符串 当参数showHeaderfalse则此参数无效。
icon 对话框标题图标 图标名称字符串 当参数showHeaderfalse则此参数无效。
fade 是否使用淡入淡出动画
  • true(默认)
  • false
position 对话框位置
  • 'fit'(默认),最佳位置
  • 'center',显示在窗口中间
  • 数字,按像素计算与顶部的距离
  • '',显示在顶部
  • 标识距离的CSS字符串,具体顶部的偏移
最佳位置在窗口中间稍偏上的位置。
backdrop 背景遮罩
  • true(默认)
  • false
  • 'static'
使用布尔值来启用或禁用背景遮罩,如果指定为'static'则会启动背景遮罩,但点击背景遮罩时不会触发关闭对话框的过程。
keyboard 按键
  • true(默认)
  • false
当为ture时,按下esc键会关闭对话框。
moveable 可移动的
  • false(默认),不启用;
  • true,启用;
是否启用对话框拖拽移动功能
waittime 加载远程内容时的最大等待时间 整数,代表等待的毫秒数,默认为0 在指定的时间之后会直接显示对话框,不管远程内容是否加载完毕;默认值为0,表示一直等待直到远程内容加载完毕才显示对话框。在等待时会显示正在加载的动画。
loadingIcon 加载时显示的动画所使用的图标
  • icon-*形式定义的图标名称
  • 自定义加载动画所使用的html
icon-*定义的图标名称请参考图标

方法

获取触发器对象实例

要使用触发器方法,需要首先获取触发器对象的实例。

通过触发按钮的data属性
var modalTrigger = $('#triggerButton').data('zui.modaltrigger');
使用预设的$.zui对象绑定的触发器
var myTrigger = $.zui.modalTrigger;
创建新的触发器实例
var newTrigger = new $.zui.ModalTrigger(options);

显示对话框

在显示对话框时,可以重新传入新的参数,而不影响触发器对象原来的参数。

myModalTrigger.show(options);

关闭对话框

myModalTrigger.close();

切换显示和关闭状态

如果对话框没有显示,则立即显示,如果已经显示则关闭。

在切换显示和关闭状态时,可以重新传入新的参数,而不影响触发器对象原来的参数。

myModalTrigger.toggle(options);

重新调整位置

使用新的位置参数来重新设置对话框的显示位置。

myModalTrigger.ajustPosition(options);

事件

因为对话框的DOM内容是动态生成的,不方便使用jQuery方法来绑定事件,不过可以将监听事件的回调函数传入参数中。

事件 jquery事件名称 说明
onShow show.zui.modal 当对话框的show方法被调用时立即发生
shown shown.zui.modal 当对话框完全显示后发生(执行完显示动画之后)
onHide hide.zui.modal 当对话框hide方法被调用是立即发生
hidden hidden.zui.modal 当对话框完全隐藏后发生(执行完隐藏动画之后)
loaded loaded.zui.modal 当远程内容加载完成后发生
broken broken.zui.modal 当加载远程内容失败之后调用,在次回调方法中返回字符串会更新对话框现实的内容(例如在对话框中显示一个加载失败之后的帮助信息)。
myModalTrigger.show({shown: function() {
    alert('对话框已显示。');
}});

如果对话框的name参数是已知的,则可以获取对话框的jquery对象实例通过jQuery对象的on方法来绑定事件。

$('#triggerModal').on('shown.zui.modal', function() {...});