Display 的核心功能是在特定时机在显示或隐藏目标并目标上展示内容。允许指定触发元素并绑定事件来决定显示或隐藏的时机。每次显示可以更新目标内的内容,这些内容可以是本地的、复制已有元素内容或者来自远程服务器。
Display 拥有丰富的选项可供定制,使用不同的选项组合实现各种丰富的功能,例如打开对话框、显示悬浮消息、展示远程内容、实现标签页、打开下拉菜单等。
目标 | 页面内要操作的 DOM 元素。在选项中使用 target 来指定。 |
---|---|
触发元素 | 页面内绑定触发事件的元素。目标和触发元素可以相同。 |
内容 | 用来显示在目标上的内容。内容可以为 HTML 文本或者复制页面上已有的元素。 |
<a id="test" class="btn primary outline" data-display="messager" data-content="Hello" data-type="success">使用 Display 显示消息</a>
// 使用 $().data('mzui.display') 获取 Display 实例
var myDisplay = $('#test').data('mzui.display');
// HTML
<a id="showDisplayMessage" class="btn primary outline" >使用 Display 显示消息</a>
// Javascript
$('#showDisplayMessage').display({
display: 'messager'
content: 'Hello',
type: 'success'
});
// 使用 $().data('mzui.display') 获取 Display 实例
var myDisplay = $('#showDisplayMessage').data('mzui.display');
// 创建 display 实例
var myDisplay = new $.Display({
display: 'messager'
});
// 调用 show() 方法显示
myDisplay.show({
content: 'Hello',
type: 'success'
});
当已知一个 Display 实例的名称,可以根据实例名称直接从全局对象获取实例。
var myNamedDisplay = $.Display.all['myDisplayName'];
myNamedDisplay.show();
更多使用例子参见 JS > Display 玩法 章节。
Display 选项可以使用 data-*
属性进行设定,如果使用 JavaScript 进行调用,$().display()
、$.Display()
和 display.show()
方法均支持设定选项,新的选项会覆盖旧的选项。
全部选项如下:
用于指定当前 Display 实例所使用的名称,如果不设置此选项则会在创建每个 Display 实例时设置一个随机的名称。
当需要通过 $.Display.all[name]
来获取 Display 实例时应该设置一个便于记忆且全局唯一的名称。
触发器元素:有效的 CSS 选择器字符串,或者指定为回调函数来返回结果。
当使用 [data-display]
方式或者 $().display()
调用时,改参数会自动使用获取到的 Zepto 实例作为选项的值。当使用 $.Display()
方式调用时,可以忽略该选项,则不会绑定触发器事件。
当该值为回调函数时,该回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
触发事件代理选择器,可省略,默认为 null
。
当该选项被使用时,触发器事件会使用代理的方式进行绑定。
是否在触发器上触发事件发生时调用 e.preventDefault()
来阻止浏览器默认行为。默认为 true
。
是否在触发器上触发事件发生时调用 e.stopPropagation()
来阻止事件冒泡。默认为 false
。
要操作的目标:'!new'
, '!self'
或者有效的 CSS 选择器字符串,或者指定为回调函数来返回结果。
当改选项被指定为 '!new'
,会在页面中动态创建一个唯一的元素。
当该选项被指定为 '!self'
时,element
不可省略,目标会直接使用 element
选项值,这样就可以为某个元素自身更新内容。
当该值为回调函数时,该回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
当目标准备显示时追加到目标上的 CSS class 名称,可忽略。
每次显示时都会追加,隐藏时会移除。
是否重新设定目标样式中的 z-index
值,默认为空值,允许自动设定全局不断递增的用于层的值。设定此选项为一个整数来重置该值,如果指定为 'none'
则不进行设定。
目标父元素:有效的 CSS 选择器字符串,或者指定为回调函数来返回结果。
当目标为动态创建时,会将动态创建的元素追加到该值对应的父元素中。一些指示目标显示状态的辅助类也会在该值对应的父元素上进行操作。
当该值为回调函数时,该回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
触发事件名称(例如:'click'
, 'mouseenter'
, 'tap'
, 'swipeLeft'
等),在触摸设备上,默认值为 'tap'
,在非触摸设备上为 'click'
。
当 element
选项有效时,会自动绑定该事件来触发目标的显示或切换显示过程。
触发事件调用的方法:'show'
(默认), 'hide'
, 'toggle'
。
当指定的触发事件被响应时,会调用在 display 实例上的由此选项指定的方法。
是否显示箭头:true
, false
(默认)。
启用该选项绘制目标边缘的合适位置显示箭头形状,这可以方便的创建带方向指示弹出层。
是否滚动到目标顶部:true
, false
(默认)。
当目标可以滚动时,如果启用改选项,当目标内容显示之后会滚动到顶部。
是否在更新内容之后初始化 skin.js 快捷绑定:true
(默认), false
。
参考 JS > Skin.js 章节。
是否在更新内容之后初始化 Display 快捷绑定:true
(默认), false
。
当目标内容更新之后会调用 $('[data-display]').display();
。
是否点击目标自动隐藏:true
(默认), false
。
当启用该选项后,目标显示后用户点击目标会隐藏目标。例如显示下拉菜单之后允许用户点击下拉菜单项目自动关闭下拉菜单。
用来更新目标的内容,允许使用下列值:
false
,不对目标进行更新;contentType
选项为 'html'
时才会以 HTML 源码更新目标;false
,则不会对目标进行更新;回调函数拥有一个参数为 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前Display 实例;{...}
来更新目标,一般会配合 template
选项一起使用。可选值:'text'
, 'html'
(默认)。
决定填充目标时是否将内容解析为 HTML 源码。
用来预处理内容的模板字符串或者回调函数。
当该选项为字符串时,会调用 $.format(template, content)
来格式化内容,$.format
用法参考 JS > Utils。
当该选项为回调函数时,回调函数 this 引用指向当前Display 实例,每次调用回调函数会依次传入以下两个参数:
content
,准备用来更新目标对象的内容;options
,当前 Display 实例的 options。用来表示远程内容的地址或使用一个对象来提供 Ajax 请求所使用的参数(参考 Zepto.Ajax)。
设置此选项会通过 Ajax 方式从远程获取内容再更新到目标。
远程内容类型,可选值: 'html'
(默认),'json'
。
一般会将远程内容视为字符串,如果将该值指定为 'json'
则会尝试将字符串转换为 对象。
当从远程加载内容时(remote
或 load
选项可用)发生错误时会使用该选项来取代 content
选项。
用来指定 CSS class 的字符串,默认为 'loading'
。
当开始从远程服务器获取内容时会在目标上添加该选项指定的 CSS class,当远程连接结束之后会从目标上移除该值。
指定用来拷贝的 DOM 元素,允许以下值:
'<div>I am content in source.</div>'
;options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。当目标显示后添加到目标上的 CSS class,默认为 'in'
。
该值会影响过渡动画及显示和隐藏效果,触发需要自定义过渡动画,否则不建议更改该值。
显示和隐藏目标时是否启用过渡动画,允许使用以下值:
true
(默认) 或 false
;'fade'
、'scale'
、'enter-from-bottom'
、'scale-from-top'
等;'scale-suggest'
或 'enter-suggest'
,其中 'suggest'
会被替换,指定为最合适的过渡方式。300
,指定用来表示过渡动画的执行时间,单位为毫秒,此时相当于设定了 duration
选项。多个过渡动画类型可以用空格分隔,例如:'fade scale'
。
数字,用来指定过渡动画执行的时间,单位为毫秒,默认为 300
。
指定是否启用遮罩层及遮罩层的类型,允许使用以下值:
true
(默认) 或 false
;'fade'
,启用渐变效果的遮罩层;'clean'
,启用完全透明的遮罩层;指定是否允许点击遮罩层来隐藏目标:true
(默认) 或 false
;
指定是否在显示目标之后自动隐藏,允许以下值:
false
(默认),不自动隐藏;3000
,则会在目标显示 3 秒之后隐藏。指定当通过触发元素触发事件显示目标之后添加到触发元素上的 CSS class,目标隐藏后会从触发元素上移除该 class,默认为''
。
设定触发器及其兄弟元素是否仅允许出现一个元素拥有 activeClass
:true
(默认) 或 false
。
如果启用改选项,则会在显示目标之前,移除触发器兄弟元素上的所有 activeClass
指定的 CSS class。
指定是否在初始化之后立即显示目标:true
或 false
(默认)。
用于决定目标显示的位置,允许以下值:
'top'
,在页面上方显示;'bottom'
,在页面上方显示;'left'
,在页面左侧显示;'right'
,在页面右侧显示;'top-center'
,在页面上方显示,并且在水平方向上居中;'bottom-center'
,在页面下方显示,并且在水平方向上居中;'left-center'
,在页面左侧显示,并且在垂直方向居中;'right-center'
,在页面右侧显示,并且在垂直方向上居中;'top-left'
,在页面左上方显示;'top-right'
,在页面右上方显示;'bottom-left'
,在页面左下方显示;'bottom-right'
,在页面右下方显示;'beside'
,相对于触发元素,在其四周寻找空间最多的位置显示;'beside-left'
,在触发元素左侧显示;'beside-left-start'
,在触发元素左侧靠上方显示;'beside-left-end'
,在触发元素左侧靠下方显示;'beside-right'
,在触发元素右侧显示;'beside-right-start'
,在触发元素右侧靠上方显示;'beside-right-end'
,在触发元素右侧靠下方显示;'beside-top'
,在触发元素上方显示;'beside-top-start'
,在触发元素上方靠左侧显示;'beside-top-end'
,在触发元素上方靠右侧显示;'beside-bottom'
,在触发元素下方显示;'beside-bottom-start'
,在触发元素下方靠左侧显示;'beside-bottom-end'
,在触发元素下方靠右侧显示;'overlay'
,覆盖在触发元素所在位置,并将目标尺寸设置与触发元素一致;{left, top, ...}
,JavaScript 对象,用于应用于目标上的 CSS 样式对象,相当于调用 $().css(placement);'{"left": ...}'
,JSON 对象字符串,用于转换为 CSS 样式对象;回调函数,用于在显示目标之前时(此时没有执行过渡动画和加载远程内容)调用。
在回调函数中返回 false
则会取消显示目标。
回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
回调函数,用于在显示目标之后且过渡动画已执行完毕(此时远程内容可能还没加载完成)时调用。
回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
回调函数,用于在隐藏目标之前时(此时没有执行过渡动画)调用。
回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
回调函数,用于在隐藏目标之后且过渡动画已执行完毕时调用。
回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
回调函数,用于在远程内容加载完毕之后调用。
回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
所使用的插件名称:''
(默认), 'messager'
, 'dropdown'
, 'popover'
, 'modal'
, 'collapse'
。
指定 Display 所使用的插件,如果为空,则不使用插件。
Display 插件相关用法参考 JS > Display 插件 章节。
当获取 Display 实例之后就可以调用实例上的方法。
参数:
options
,当前使用的选项,此选项会与初始化时的选项进行合并,但不会覆盖初始化时的选项,同一个 Display 实例在每次调用 show()
方法时传入不同的选项来实现不同的功能;callback
,显示完成之后的回调函数。参数:
callback
,显示完成之后的回调函数。如果目标是临时创建的,则会在隐藏之后从页面 DOM 中移除。
参数:
toggle
,当前使用的选项;options
,切换显示时使用的选项;callback
,切换显示或隐藏之后的回调函数。参数:
options
,显示时使用的选项。解除目标有三种方式:
myDisplay.hide();
参数:
name
,实例名称,当次参数缺省时会自动使用上次已显示过目标实例;callback
,在解除目标之后的回调函数。$.Display.dismiss(function() {
// 上一个显示的 Display 目标已隐藏
});
点击触发器元素,会自动解除触发器元素在父级容器上对应的 Display 实例。
如果需要在任意位置解除,需要为触发器 [data-display-name]
属性设定为需要解除的 Display 实例名称。
<a data-dismiss="display">点我关闭</a>
// 指定需要解除的实例名称
<a data-dismiss="display" data-display-name="myDisplayName">点我关闭</a>
回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
// 在选项中指定回调函数来监听 show 事件
$('#test').display({
show: function(options) {
// 即将显示目标
// return false; // 在此处返回 false 则取消显示目标
}
});
事件绑定回调函数拥有一个参数 options
表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。
// 使用 Zepto 的 $().on() 方法来绑定事件
$('#test').on('show', function(options) {
// 即将显示目标
// return false; // 在此处返回 false 则取消显示目标
});
全局事件对所有 Display 实例生效。全局事件在 document
对象上触发,只需要在 document
上绑定事件即可。
$(document).on('display.shown', function(e, display, element, options) {
// 此时有 Display 在页面显示
});
支持以下全局事件:
Display 丰富的功能需要搭配不同的选项进行使用,但每次设置过多的选项会带来不便。插件机制允许重置默认选项并在获取用户设定选项之前进行一次预处理,这样就可以使用最少的选项来实现特定功能。
设置 display
选项为要使用的插件名称即可。
当使用 [data-display]
形式调用时,直接将该属性值设置为要使用的插件名称即可。
插件会以其名称注册为 $.fn
上的方法,这样就可以使用 $().plugName()
的形式来调用插件。
更多插件例子参见 JS > Display 玩法 章节。
// [data-display="plugName"] 形式调用
<a data-display="messager" data-content="Hello" data-type="success">使用名称为 messager 的插件</a>
// 以 $().plugName() 形式调用
$('#testMessager').messager();
// $().display({display: 'plugName'}) 形式调用
$('#testMessager').display({display: 'messager'});
// new $.Display({display: 'plugName'}) 形式调用
new $.Display({display: 'messager'}).show();
通过指定插件名称和选项预处理函数来添加插件。
插件预处理函数会在每次调用 show()
方法之前对选项进行预处理。
参数:
name
,设置插件名称;function
,该插件使用选项预处理函数,改函数包括一个参数 options
,this
引用指向当前 Display 实例,该函数需要重新返回处理过的 options
;fnName
,设定要绑定到 $.fn
上的方法名称,如果不设定此参数,则直接使用 name
作为方法名称,如果将此参数设定为 false
,则不在 $.fn
绑定快捷方法;plugs
,一个对象,每一个键名指定一个插件名称,其值对应为选项预处理函数,这样就可以一次性添加多个插件。如果添加一个已有该名称的插件,新的插件会覆盖旧的插件。
插件名称可以添加 _
前缀,这样其设置的选项预处理函数会在插件实例初始化之前对选项进行预处理,而不是在 show()
方法之前。
带前缀的预处理函数和不带前缀的预处理函数可以同时设定。调用的时候插件名称都不需要添加前缀。
参数:
name
,插件名称在插件的预处理函数中,先获取已有插件的预处理函数对选项进行预处理,这样可以实现对已有插件的继承。
var messagerFlugFunc = $.Display.plugs('messager');