介绍

Display 的核心功能是在特定时机在显示或隐藏目标并目标上展示内容。允许指定触发元素并绑定事件来决定显示或隐藏的时机。每次显示可以更新目标内的内容,这些内容可以是本地的、复制已有元素内容或者来自远程服务器。

Display 拥有丰富的选项可供定制,使用不同的选项组合实现各种丰富的功能,例如打开对话框、显示悬浮消息、展示远程内容、实现标签页、打开下拉菜单等。

名称解释
目标 页面内要操作的 DOM 元素。在选项中使用 target 来指定。
触发元素 页面内绑定触发事件的元素。目标和触发元素可以相同。
内容 用来显示在目标上的内容。内容可以为 HTML 文本或者复制页面上已有的元素。
使用方式
[data-display]
<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');
$().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');
new $.Display()
// 创建 display 实例
var myDisplay = new $.Display({
  display: 'messager'
});

// 调用 show() 方法显示
myDisplay.show({
  content: 'Hello',
  type: 'success'
});
$.Display.all[name]

当已知一个 Display 实例的名称,可以根据实例名称直接从全局对象获取实例。

var myNamedDisplay = $.Display.all['myDisplayName'];
myNamedDisplay.show();

更多使用例子参见 JS > Display 玩法 章节。

选项

Display 选项可以使用 data-* 属性进行设定,如果使用 JavaScript 进行调用,$().display()$.Display()display.show() 方法均支持设定选项,新的选项会覆盖旧的选项。

全部选项如下:

name

用于指定当前 Display 实例所使用的名称,如果不设置此选项则会在创建每个 Display 实例时设置一个随机的名称。

当需要通过 $.Display.all[name] 来获取 Display 实例时应该设置一个便于记忆且全局唯一的名称。

element

触发器元素:有效的 CSS 选择器字符串,或者指定为回调函数来返回结果。

当使用 [data-display] 方式或者 $().display() 调用时,改参数会自动使用获取到的 Zepto 实例作为选项的值。当使用 $.Display() 方式调用时,可以忽略该选项,则不会绑定触发器事件。

当该值为回调函数时,该回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

selector

触发事件代理选择器,可省略,默认为 null

当该选项被使用时,触发器事件会使用代理的方式进行绑定。

preventDefault

是否在触发器上触发事件发生时调用 e.preventDefault() 来阻止浏览器默认行为。默认为 true

stopPropagation

是否在触发器上触发事件发生时调用 e.stopPropagation() 来阻止事件冒泡。默认为 false

target

要操作的目标:'!new', '!self' 或者有效的 CSS 选择器字符串,或者指定为回调函数来返回结果。

当改选项被指定为 '!new',会在页面中动态创建一个唯一的元素。

当该选项被指定为 '!self' 时,element 不可省略,目标会直接使用 element 选项值,这样就可以为某个元素自身更新内容。

当该值为回调函数时,该回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

targetClass

当目标准备显示时追加到目标上的 CSS class 名称,可忽略。

每次显示时都会追加,隐藏时会移除。

targetZIndex

是否重新设定目标样式中的 z-index 值,默认为空值,允许自动设定全局不断递增的用于层的值。设定此选项为一个整数来重置该值,如果指定为 'none' 则不进行设定。

container

目标父元素:有效的 CSS 选择器字符串,或者指定为回调函数来返回结果。

当目标为动态创建时,会将动态创建的元素追加到该值对应的父元素中。一些指示目标显示状态的辅助类也会在该值对应的父元素上进行操作。

当该值为回调函数时,该回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

trigger

触发事件名称(例如:'click', 'mouseenter', 'tap', 'swipeLeft' 等),在触摸设备上,默认值为 'tap',在非触摸设备上为 'click'

element 选项有效时,会自动绑定该事件来触发目标的显示或切换显示过程。

triggerMethod

触发事件调用的方法:'show'(默认), 'hide', 'toggle'

当指定的触发事件被响应时,会调用在 display 实例上的由此选项指定的方法。

arrow

是否显示箭头:true, false(默认)。

启用该选项绘制目标边缘的合适位置显示箭头形状,这可以方便的创建带方向指示弹出层。

scrollTop

是否滚动到目标顶部:true, false(默认)。

当目标可以滚动时,如果启用改选项,当目标内容显示之后会滚动到顶部。

plugSkin

是否在更新内容之后初始化 skin.js 快捷绑定:true(默认), false

参考 JS > Skin.js 章节。

plugDisplay

是否在更新内容之后初始化 Display 快捷绑定:true(默认), false

当目标内容更新之后会调用 $('[data-display]').display();

targetDismiss

是否点击目标自动隐藏:true(默认), false

当启用该选项后,目标显示后用户点击目标会隐藏目标。例如显示下拉菜单之后允许用户点击下拉菜单项目自动关闭下拉菜单。

content

用来更新目标的内容,允许使用下列值:

contentType

可选值:'text', 'html'(默认)。

决定填充目标时是否将内容解析为 HTML 源码。

template

用来预处理内容的模板字符串或者回调函数。

当该选项为字符串时,会调用 $.format(template, content) 来格式化内容,$.format 用法参考 JS > Utils

当该选项为回调函数时,回调函数 this 引用指向当前Display 实例,每次调用回调函数会依次传入以下两个参数:

remote

用来表示远程内容的地址或使用一个对象来提供 Ajax 请求所使用的参数(参考 Zepto.Ajax)。

设置此选项会通过 Ajax 方式从远程获取内容再更新到目标。

remoteType

远程内容类型,可选值: 'html'(默认),'json'

一般会将远程内容视为字符串,如果将该值指定为 'json' 则会尝试将字符串转换为 对象。

remoteError

当从远程加载内容时(remoteload 选项可用)发生错误时会使用该选项来取代 content 选项。

loadingClass

用来指定 CSS class 的字符串,默认为 'loading'

当开始从远程服务器获取内容时会在目标上添加该选项指定的 CSS class,当远程连接结束之后会从目标上移除该值。

source

指定用来拷贝的 DOM 元素,允许以下值:

showInClass

当目标显示后添加到目标上的 CSS class,默认为 'in'

该值会影响过渡动画及显示和隐藏效果,触发需要自定义过渡动画,否则不建议更改该值。

animate

显示和隐藏目标时是否启用过渡动画,允许使用以下值:

多个过渡动画类型可以用空格分隔,例如:'fade scale'

duration

数字,用来指定过渡动画执行的时间,单位为毫秒,默认为 300

backdrop

指定是否启用遮罩层及遮罩层的类型,允许使用以下值:

backdropDismiss

指定是否允许点击遮罩层来隐藏目标:true(默认) 或 false

autoHide

指定是否在显示目标之后自动隐藏,允许以下值:

activeClass

指定当通过触发元素触发事件显示目标之后添加到触发元素上的 CSS class,目标隐藏后会从触发元素上移除该 class,默认为''

activeSingle

设定触发器及其兄弟元素是否仅允许出现一个元素拥有 activeClasstrue(默认) 或 false

如果启用改选项,则会在显示目标之前,移除触发器兄弟元素上的所有 activeClass 指定的 CSS class。

displayAuto

指定是否在初始化之后立即显示目标:truefalse(默认)。

placement

用于决定目标显示的位置,允许以下值:

show

回调函数,用于在显示目标之前时(此时没有执行过渡动画和加载远程内容)调用。

在回调函数中返回 false 则会取消显示目标。

回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

shown

回调函数,用于在显示目标之后且过渡动画已执行完毕(此时远程内容可能还没加载完成)时调用。

回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

hide

回调函数,用于在隐藏目标之前时(此时没有执行过渡动画)调用。

回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

hidden

回调函数,用于在隐藏目标之后且过渡动画已执行完毕时调用。

回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

loaded

回调函数,用于在远程内容加载完毕之后调用。

回调函数拥有一个参数 options 表示当前 Display 实例的 options,回调函数 this 引用指向当前 Display 实例。

display

所使用的插件名称:''(默认), 'messager', 'dropdown', 'popover', 'modal', 'collapse'

指定 Display 所使用的插件,如果为空,则不使用插件。

Display 插件相关用法参考 JS > Display 插件 章节。

方法

当获取 Display 实例之后就可以调用实例上的方法。

显示目标

参数:

隐藏目标

参数:

如果目标是临时创建的,则会在隐藏之后从页面 DOM 中移除。

切换显示或隐藏目标

参数:

判断目标是否显示

参数:

解除目标

解除目标有三种方式:

调用实例方法 hide()
myDisplay.hide();
使用全局方法 $.Display.dismiss()

参数:

$.Display.dismiss(function() {
    // 上一个显示的 Display 目标已隐藏
});
使用触发器 [data-dismiss="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 则取消显示目标
    }
});
使用 $().on(eventName, function) 绑定事件

事件绑定回调函数拥有一个参数 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() 方法之前对选项进行预处理。

参数:

如果添加一个已有该名称的插件,新的插件会覆盖旧的插件。

插件名称可以添加 _ 前缀,这样其设置的选项预处理函数会在插件实例初始化之前对选项进行预处理,而不是在 show() 方法之前。

带前缀的预处理函数和不带前缀的预处理函数可以同时设定。调用的时候插件名称都不需要添加前缀。

获取插件预处理函数

参数:

在插件的预处理函数中,先获取已有插件的预处理函数对选项进行预处理,这样可以实现对已有插件的继承。

var messagerFlugFunc = $.Display.plugs('messager');