基于 layui 的下拉菜单控件 dropdown文档

分享 未结 置顶 精帖 110 15241
Microanswer
Microanswer 2020-3-20
悬赏:20飞吻
一、简介预览

dropdown 是一款基于layui框架的下拉框控件,填补了layui原生没有下拉框这个空隙。借助下拉框的操作方式和UI交互,可以带来更加直观、便于操作、模块划分清晰等优势。带来了这些优势的同时又加入了许多意想不到的细节:

1. 如果下拉框出现的位置会超出浏览器边缘,那么会自动找一个‘凉快’的地方呆着。
2. 在你打开下拉框后又进行了界面滚动,她也不依不舍的跟着你走。

新版v2.0.0已经发布,这一版性能和稳定性有提升,建议使用了老版本的用户升级到新版。

那么先不妨先看看本控件的预览效果:


可以让小箭头动态变化的[v1.0.3]:


要立刻体验?可以 点击此处 立即在线体验。去 Github 查看源码。

二、安装

只需要 点击下载(v2.2.0) 将JavaScript文件解压到你的layui扩展目录,然后将css文件找一个自己喜欢的目录,最后将其引入html文件里即可开始使用。

从v2.1.0开始,你可以忽略css文件,只引入js就可以了。

下面示例页面中如何使用:

<html>
<head>
<title>dropdown</title>
<link type="text/css" rel="stylesheet" href="假设这是你原本layui的css目录/layui.css">
<link type="text/css" rel="stylesheet" href="你放css的目录/dropdown.css"><!-- 从v2.1.0开始,css可以不用写了,将会自动加载。 -->
</head>
<body>
<button class="layui-btn layui-btn-sm"
lay-filter="test1"
lay-dropdown="{menus: [{layIcon:'layui-icon-username',txt: '个人中心', event:'usercenter'}, {layIcon: 'layui-icon-set',txt: '设置', event:'set'}, {layIcon: 'layui-icon-logout', txt: '退出登录', event:'loginout'}]}">
<span>下拉菜单</span>
<i class="layui-icon layui-icon-triangle-d"></i>
</button>
<script>
// 把 dropdown.js 放在了你的扩展控件目录,你可以:
layui.config({
base: '你的扩展目录'
}).use(['dropdown'], function () {
var dropdown = layui.dropdown;
// 监听菜单点击
dropdown.onFilter('test1', function (event) {
// ...业务代码
})
});
</script>
</body>
</html>

三、详细使用

3-1、开启下拉

你需要某个按钮(或dom)点击它时它可以下拉展开一个菜单时,你只需要为这个按钮添加lay-dropdown属性,在后面填写相应的配置。刷新页面,你就可以点击这个按钮实现下拉框了。是不是很简单。就像这样:

<button class="layui-btn layui-btn-sm" 
lay-filter="test1"
lay-dropdown="{menus: [{layIcon:'layui-icon-username',txt: '个人中心', event:'usercenter'}, {layIcon: 'layui-icon-set',txt: '设置', event:'set'}, {layIcon: 'layui-icon-logout', txt: '退出登录', event:'loginout'}]}">
<span>下拉菜单</span>
<i class="layui-icon layui-icon-triangle-d"></i>
</button>
<script>
layui.config({
base: '你的扩展目录'
}).use(['dropdown'], function () {
});
</script>
你或许注意到了,通过给lay-dropdown传入一个包含菜单条目menus的对象,就可以立即实现下拉菜单的功能了。有关这个对象的具体内容,请往下看。

3-2、监听点击事件

要监听下拉菜单的点击事件,使用dropdown.onFilter方法即可监听,示例代码如下:

<script>
layui.config({
base: '你的扩展目录'
}).use(['dropdown'], function () {
var dropdown = layui.dropdown;
// test1 就是触发下拉的按钮的lay-filter属性的内容
dropdown.onFilter("test1", function (event) {
// 根据上一节的配置来说,这里的event可能为:
// usercenter、set、loginout
// 这就取决于你点击的是哪一个菜单项了。
console.log(event);
});
});
</script>
值得注意: 当我们在数据表格里使用下拉控件时,则可以不需要使用 onFilter 来监听了,一旦你为menu条目设置了event后,你就可以按照 Layui 官方文档里:监听行工具事件的方式来进行监听,一样会监听到,同时不会因为使用了下拉框而丢失了这些对表格操作的功能。这得益于与dropdown在设计时使用了$.after的方式插入下拉dom,每一个下拉框的dom都在每一条数据行dom中,使事件监听直接通过表格的方法也能得以实现,这在不知不觉中达到了不谋而合。

dropdown.onFilter方法提供了两个参数,第一个是确定多个下拉框唯一性的lay-filter值,第二个就是回调函数,这个回调函数会传入一个event,通过它你就可以知道点击的具体是哪一个菜单条目了。

3-3、自定义下拉内容

这无疑是此下拉控件最具光荣的功能,通过它你可以实现任何你希望的下拉内容,这一刻就是你颅内高潮的moment。

通过配置一个参数template,传入你的布局模板,就可以实现下拉框显示自定义内容了:

<button
class="layui-btn layui-btn-sm"
lay-dropdown="{template: '#custMenu'}"
>
<span>自定义下拉内容</span>
<i class="layui-icon layui-icon-triangle-d"></i>
</button>
<!-- 下拉内容自定义模板 -->
<script id="custMenu" type="text/html">
<div>
<p>我是自定义下拉内容</p>
</div>
</script>
<script>
layui.config({
base: '你的扩展目录'
}).use(['dropdown'], function () {
var dropdown = layui.dropdown;
});
</script>
3-4、使用代码初始化

当然了,不可能每个下拉框都是在页面出现就跟随立即出现,有很多时候我们需要把下拉框通过后期进行初始化。常见的场景就是在表格里,我们则需要在表格的done函数里进行初始化。
这就不得不通过代码来初始化了,通过代码初始化,不仅可以带来html布局上的精简,还可以拥有更强大的功能和自定义效果。

下面示例了如何进行异步初始化:

<!-- 使用代码 -->
<button class="layui-btn layui-btn-sm" id="mybtn">异步初始化下拉</buton>
<script>
layui.config({
base: '你的扩展目录'
}).use(['dropdown'], function () {
var dropdown = layui.dropdown;
// 通过代码(也就是后期异步初始化)进行初始化下拉
// 这样可以把 mybtn 实现下拉菜单
dropdown.suite("#mybtn", {
menus: [{txt: "按钮1"}, {txt: "按钮2"}]
});
// 这样可以把 mybtn 实现下拉自定义内容
dropdown.suite("#mybtn", {
template: "xxxx自定义模板id",
success: function ($dom) {
// 当自定义内容模板初始化完成
// 此方法会调用. 传入的$dom就
// 包含了你的模板的内容,通过它
// 你可以在这里进行模板内其他组
// 件的初始化。
}
});
});
</script>
可以看到`suite`方法帮我们完成了下拉初始化,它有两个参数,第一个参数是一个dom选择器,第二个参数是一个`option`配置,关于`option`详细内容,请看最后一节。

注意: 使用代码初始化是比较推荐的使用方式,尤其是在表格里使用时,如果你的表格里某些字段允许排序,那么你除了在done回调方法中初始化一遍,你还需要在table的排序事件(这需要你自己去监听排序事件了)里进行初始化,毕竟排序了之后,表格内容会被重新绘制,之前的初始化就会丢失,所以你有必要再次进行初始化。


四、api列表

4-1、dropdown.suite(selector, option)
代码初始化下拉框,通过参数selector确定哪一个按钮触发下拉框。option为下拉框配置,配置见下一节。

4-2、dropdown.onFilter(filter, cb)
监听菜单点击事件,通过它可以监听使用menus配置的菜单条目点击事件。对于自定义下拉模板内的dom点击事件,可通过option提供的success回调函数进行监听,详见下一节option配置说明。

4-3、dropdown.hide(selector) v2.1.0新增
隐藏指定选择器的下拉框。

4-4、dropdown.show(selector) v2.1.0新增
显示指定选择器的下拉框。注意:如果选择器对应的dom没有进行下拉初始化,则此方法会进行初始化。此时会用到参数option,你可以通过第二个参数传入。但是通常建议传入的选择器对应的dom是经过了下拉框初始化的。


五、lay-dropdown配置详解

无论是通过在html上直接通过属性lay-dropdown来进行配置,还是通过代码suite方法进行初始化配置,它们传递的配置参数都适用于本节内容:

var option = {

// 【可选】对齐方式,默认left,可填:left,center,right
align: "left",

// 【与menus两者必填一个】自定义下拉模板id
// 如果同时配置了 menus,则优先 menus 作为下拉内容。
template: "",

// 【可选】当你使用template自定义模板时,支持通过此
// data 向模板里提供数据,从而实现动态渲染。
data: {},

// 【与template两者必填一个】下拉菜单项,数组,里面放多个对象。
menus: [
...
// 分割线 (v1.0.1)
"hr",

// 菜单头 (v1.0.1)
{
// 菜单头文案内容
header: "通用",

// 菜单头文案对齐方式, 可填:left(默认),center,right
align: "left",

// 是否启用带横线的菜单头。当设置为true时,align字段属性不会生效。
withLine: false
},

// 普通按钮项
{
// 菜单图标,示例: layui-icon-heart-fill
// layui图标大全:https://www.layui.com/doc/element/icon.html
layIcon: "",
// 菜单显示文字
txt: "",
// 点击此菜单的事件
event: ""
},
...
],

// 【可选】如果发现下拉框显示出来后被遮挡了
// 通过把此配置值修改大于遮挡层的zindex就好了
zIndex: 102,

// 【可选】触发下拉框的方式,可填: click, hover
showBy: "click",

// 【可选】下拉框最小宽度
minWidth: 10,

// 【可选】下拉框最小高度
minHeight: 10,

// 【可选】下拉框最大高度
maxHeight: 300,

// 【可选】下拉框与触发按钮的间隙大小
gap: 4,

// 【可选】多个下拉框确定唯一性的,和属性 lay-filter 一个作用
filter: "",

// 【可选】通过template参数自定义下拉内容时
// 模板渲染成功此方法调用,$down: 包含你的自定义模板的jquery对象。
success: function ($down) {},

// 【可选】当此下拉框被打开时,此方法会被调用。[v1.0.3]
// $maker 是触发下拉框的jquery对象(就是你按的那个按钮的jquery对象), $down 是包含下拉框的jquery对象。
// 不过要注意,layui-icon(即layui图标)若要成功执行transform动画,你需要为它添加css: display:inlibe-block
onShow: function ($maker, $down) {},

// 【可选】当此下拉框被关闭时,此方法会被调用。[v1.0.3]
// $maker 和 $down 和 onShow 方法的参数是一样的。
// 通过 onShow 和 onHide 你就可以完成对界面交互更加协调的视觉体验。
// 比如:按钮右侧小箭头根据相应状态变化指向。
onHide: function($maker, $down) {},

// 在界面滚动时,下拉框的行为, 默认为:follow 跟随按钮,可选值:hidden 表示隐藏[v2.0.0]
scrollBehavior: "follow",

// 下拉框背景颜色
backgroundColor: "#FFF",[v2.0.0]

// 初始化完成后是否立即显示下拉框。 [v2.2.0]新增
immed: false,

// 是否显示下拉框上的箭头。[v2.2.0]新增
arrow: true
}
六、更新历史

v2.2.0 优化滚动性能,修复隐藏下拉框方案。新增更多配置参数,详见文档。
v2.1.0 自动加载css,加入hide、show方法,让你可以通过代码控制下拉框的显示与否了。
v2.0.0 修复在ie浏览器下的滚动问题,修复局部滚动时不跟随的问题,加入配置支持定义滚动行为。
v1.0.3 加入 onShow 和 onHide 配置,使能实现更多交互上的体验。
v1.0.2 优化触发下拉体验,全局同时只允许下拉一个菜单。
v1.0.1 新增菜单分割线、菜单头功能。

七、关于

本文博文: 点击前往。觉得不错,不妨点个赞:作者网站
回帖
  • 前排围观点赞
    6 回复
  • 这个不错[good]
    3 回复
  • @kenvelo 用自定义下拉内容。
    那个menus配置还不支持中横线。
    不过看来这个需求有必要实现。
    3 回复
  • @kenvelo 现在发布了新版本,以支持了菜单分割线功能。立即下载(v1.0.1)

    现在只需要这样,即可开启菜单分割线:
    layui.config({
    base: '你的扩展目录'
    }).use(['dropdown'], function () {
    var dropdown = layui.dropdown;
    dropdown.suite("#mybtn", {
    menus: [
    {txt: "菜单一", event: "menu1"},
    {txt: "菜单二", event: "menu2"},
    "hr", // 此次加入一个分割线
    {txt: "菜单三", event: "menu3"},
    ]
    });
    })
    3 回复
  • @Microanswer 更新速度相当快,为你打call 点赞
    3 回复
  • 喜欢[good]
    2 回复
  • 李青石
    2020-3-21
    1 回复
  • 菜单中间加个横线如何处理?
    1 回复
  • [赞]
    1 回复
  • @sven7
    dropdown自身并不能把你在toolbar模板里面动态生成的按钮转移到下拉框的内容里面来。

    但我相信你动态生成按钮是因为每条数据具备了不同的操作功能按钮,所以才动态生成对应的操作按钮。

    dropdown不能把这些按钮转移到下拉框里,但这并不意味着它不能实现对应的功能,通过适当的代码结构,可以避免动态去生成不同的dom,取而代之的是动态的配置下拉按钮的菜单。这是一份案列效果图:

    右侧的下拉菜单总是会根据用户不同的状态提供不同的下拉功能


    这里 点击下载 是这张效果图的实现源码,希望能够对你有所帮助。

    最后,虽然dropdown自身并不能把你动态生成的dom转移到下拉框内,但你可以通过手动实现:
    1、使用自定义下拉内容。
    2、为option传入success回调方法,在此方法中通过代码将你生成的dom转移到下拉框里。
    这个方法在难度上和可维护性上都不存在优势,所以并不推荐。
    1 回复