可以在折叠面板中放置任何内容;折叠面板默认收缩,若希望某个面板默认展开,只需要在包含.mui-collapse
类的li
节点上,增加.mui-active
类即可;mui官网中的方法说明,使用的就是折叠面板控件。
扩展阅读
代码块激活字符: maccordion
actionsheet一般从底部弹出,显示一系列可供用户选择的操作按钮; actionsheet是从popover控件基础上演变而来,实际上就是一个固定从底部弹出的popover,故DOM结构和popove类似,只是需要在含.mui-popover
类的节点上增加.mui-popover-bottom
、.mui-popover-action
类;
和popover一样,推荐使用锚点方式显示、隐藏actionsheet;若要使用js代码动态显示、隐藏actionsheet,同样在popover插件的构造方法中传入'toggle'参数即可,如下:
卡片视图常用于展现一段完整独立的信息,比如一篇文章的预览图、作者信息、点赞数量等,如下是一个卡片demo示例;
使用mui-card
类即可生成一个卡片容器,卡片视图主要有页眉、内容区、页脚三部分组成,结构如下:
卡片页眉及内容区,均支持放置图片; 页眉放置图片的话,需要在.mui-card-header
节点上增加.mui-card-media
类,然后设置一张图片做背景图即可,代码如下:
若希望在页眉放置更丰富的信息,比如头像、主标题、副标题,则需使用.mui-media-body
类,示例代码如下:
checkbox常用于多选的情况,比如批量删除、添加群聊等;
DOM结构
默认checkbox在右侧显示,若希望在左侧显示,只需增加.mui-left
类即可,如下:
若要禁用checkbox,只需在checkbox上增加disabled属性即可;
扩展阅读
代码块激活字符: mckeckbox
创建并显示对话框,弹出的对话框为非阻塞模式
,用户点击对话框上的按钮后关闭( h5模式的对话框也可通过 closepopup关闭 ),并通过callback函数返回用户点击按钮的索引值或输入框中的值。
mui会根据ua
判断,弹出原生对话框还是h5绘制的对话框,在基座中默认会弹出原生对话框,可以配置type属性,使得弹出h5模式对话框
两者区别:1.原生对话框可以跨webview,2.h5对话框样式统一而且可以修改对话框属性或样式
mui v3.0 版本(含)以上的dialog控件支持换行(\n)显示
如果有定制对话框样式的需求( 只能修改h5模式对话框)可以在mui.css中修改.mui-popup
类下的样式
如果需要修改DOM
结构可以按照以下方式处理.
扩展阅读
问答社区话题讨论:利用mui toast制作下拉刷新获取新内容的提示
代码块激活字符: mdalert
mdconfirm
mdprompt
mdtoast
mdclosepopup
mdclosepopups
图片轮播继承自slide插件,因此其DOM结构、事件均和slide插件相同;
DOM结构
默认不支持循环播放,DOM结构如下:假设当前图片轮播中有1、2、3、4四张图片,从第1张图片起,依次向左滑动切换图片,当切换到第4张图片时,继续向左滑动,接下来会有两种效果:
- 支持循环:左滑,直接切换到第1张图片;
- 不支持循环:左滑,无反应,继续显示第4张图片,用户若要显示第1张图片,必须连续向右滑动切换到第1张图片;
当显示第1张图片时,继续右滑是否显示第4张图片,是同样问题;这个问题的实现需要通过.mui-slider-loop
类及DOM节点来控制;若要支持循环,则需要在.mui-slider-group
节点上增加.mui-slider-loop
类,同时需要重复增加2张图片,图片顺序变为:4、1、2、3、4、1,代码示例如下:
JS Method
mui框架内置了图片轮播插件,通过该插件封装的JS API,用户可以设定是否自动轮播及轮播周期,如下为代码示例:
因此若希望图片轮播不要自动播放,而是用户手动滑动才切换,只需要通过如上方法,将interval参数设为0即可。
若要跳转到第x张图片,则可以使用图片轮播插件的gotoItem方法,例如:
注意:mui框架会默认初始化当前页面的图片轮播组件;若轮播组件内容为js动态生成时(比如通过ajax动态获取的营销信息),则需要在动态生成完整DOM (包含mui-slider
下所有DOM结构) 后,手动调用图片轮播的初始化方法;代码如下:
扩展阅读
问答社区话题讨论: 图片轮播
代码块激活字符: mslider
栅格系统简介:
MUI 提供了非常简单实用的12
列响应式栅格系统。使用时只需在外围容器上添加.mui-row
,在列上添加 .mui-col-[sm|xs]-[1-12]
,即可
栅格参数:
尺寸 | 超小屏幕(<400px)(extrasmall)> | 小屏幕(≥400px) Small |
类前缀 | .mui-col-xs-[1-12] | .mui-col-sm-[1-12] |
列(column)数 | 12 |
可嵌套 | 是 |
实例:
左侧:通过定义.mui-col-sm-6
类在大屏(≥400px)设备上会展现为并排的两列,而.mui-col-xs-12
在小屏(<400px)设备上会覆盖之前定义的类展现为水平排列
实例:多余的列将会另起一行排列
左侧:如果在一个.mui-row
内包含的列(column)大于12个,包含多余列(column)的元素将作为一个整体单元被另起一行排列。
右侧:如果不足12个列将不会撑满整个.mui-row
容器
实例:通过为列
设置padding
属性,从而创建列与列之间的间隔
两列之间白色区域为左侧列的padding
扩展阅读
代码块激活字符: mrow
mcolsm
mcolxs
mui默认提供了手机App开发常用的字体图标,如下:(点击icon即可复制样式)
使用时,只需要在span
节点上分别增加.mui-icon
、.mui-icon-name
两个类即可(name为图标名称,例如:weixin、weibo等),如下代码即可显示一个微信图标:
关联阅读
扩展阅读
代码块激活字符: micon
基本说明: 所有包裹在.mui-input-row
类中的 input、textarea等元素都将被默认设置宽度属性为width: 100%;
。 将 label 元素和上述控件控件包裹在.mui-input-group
中可以获得最好的排列。
输入增强: mui目前提供的输入增强包括:快速删除、语音输入*5+ only和密码框显示隐藏密码。
- 快速删除:只需要在input控件上添加
.mui-input-clear
类,当input 控件中有内容时,右侧会有一个删除图标,点击会清空当前input的内容;
- 搜索框:在
.mui-input-row
同级添加.mui-input-search
类,就可以使用search控件
- 语音输入*5+ only:为了方便快速输入,mui集成了 HTML5+的语音输入,只需要在对应input控件上添加
.mui-input-speech
类,就可以在5+环境下使用语音输入
- 密码框:给input元素添加
.mui-input-password
类即可使用
初始化: mui在mui.init()中会自动初始化基本控件,但是 动态添加的Input组件需要重新进行初始化
打开chrome控制台运行下面这段代码,赋予☝️此密码框生命力😀
示例:
验证表单是否为空
提交时校验三个字段均不能为空,若为空则提醒并终止业务逻辑运行,使用each()
方法循环校验,如下:
扩展阅读
- 注:始终为button按钮添加
type
属性,若button按钮没有type属性,浏览器默认按照type='submit'
逻辑处理, 这样若将没有type的button放在form表单中,点击按钮就会执行form表单提交,页面就会刷新,用户体验极差。
- 使用Native.js实现打开页面默认弹出软键盘
代码块激活字符: minput
普通列表 列表是常用的UI控件,mui封装的列表组件比较简单,只需要在ul
节点上添加.mui-table-view
类、在li
节点上添加.mui-table-view-cell
类即可,如下为示例代码
自定义列表高亮颜色点击列表,对应列表项显示灰色高亮,若想自定义高亮颜色,只需要重写.mui-table-view-cell.mui-active
即可,如下:
右侧添加导航箭头若右侧需要增加导航箭头,变成导航链接,则只需在li
节点下增加a
子节点,并为该a
节点增加.mui-navigate-right
类即可,如下:
右侧添加数字角标等控件 mui支持将数字角标、按钮、开关等控件放在列表中;mui默认将数字角标放在列表右侧显示,代码如下:
- Item 1 11
- Item 2 22
- Item 3 33
media list(图文列表) 图文列表继承自列表组件,主要添加了.mui-media
、.mui-media-object
、.mui-media-body
、.mui-pull-left/right
几个类,如下为示例代码
PopPicker
创建实例并填充数据后,可以设定每个层级的选中项,因为 PopPicker 是支持多层级联的,所以,可通过 instance.pickers[index]
拿到指定层级的实例,然后通过setSelectedIndex()
和setSelectedValue()
两个方法,设定指定层级的选中项,如下代码供参考:
*如果设置多级默认值可依次获取每一层级Picker对象并设置默认值,如下:
-
setSelectedIndex(index[, duration, callback])
-
参数:index
指定列表选中项
如:picker.pickers[0].setSelectedIndex(4)
-
参数:duration
过渡效果持续时间( ms
)
如:picker.pickers[0].setSelectedIndex(4,200)
-
参数:callback
设置成功回调
如:picker.pickers[0].setSelectedIndex(4,200,function(){})
-
-
setSelectedValue(value[, duration, callback])
-
参数:value
指定列表选中项
如:picker.pickers[0].setSelectedValue('fourth')
-
参数:duration
渡效果持续时间( ms
)
如:picker.pickers[0].setSelectedValue('fourth',200)
-
参数:callback
设置成功回调
如:picker.pickers[0].setSelectedValue('fourth', 200, function(){})
-
-
show( getSelectedItems )
-
返回值:[data]
获取选中的项(数组)
如:
*return false;
可以阻止选择框的关闭
-
dispose()
-
释放组件资源(释放后将将不能再操作组件)
如:picker.dispose()
* 通常情况下,不需要释放组件资源,初始化之后,可以一直使用。
* 当内容较多,如不释放组件资源,在某些设备上可能会卡顿。
* 所以每次用完便立即调用 dispose() 进行释放,下次用时再创建新实例。
dtpicker组件适用于弹出日期选择器
快速体验
通过new mui.DtPicker()
初始化DtPicker组件
显示picker
实例
API详解
-
new DtPicker({options}})
-
1.参数:type
设置日历初始视图模式
支持的值:
可选值 | 视图模式 |
'datetime' | 完整日期视图(年月日时分) |
'date' | 年视图(年月日) |
'time' | 时间视图(时分) |
'month' | 月视图(年月) |
'hour' | 时视图(年月日时) |
*若需要指定其他显示视图,
则需要通过css来控制显示项,通过js获取对应选择项.如
设置月日时,需要在
mui.dtpicker.css
中设置显示视图宽度,隐藏不需要的视图
在
mui.dtpicker.js
中
getSelected()
方法下添加
selected
对象值
-
2.参数:customData
设置时间/日期别名
设置格式:
示例:
支持的值:
可选值 | 视图模式 |
'y' | 可设置 年别名 |
'm' | 可设置 月 别名 |
'd' | 可设置 日别名 |
'h' | 可设置 时别名 |
'i' | 可设置 分别名 |
*customData
值生效的前提需要有指定的日期视图,如设置'y',需要在视图使用'年'视图
-
3.参数:labels
设置默认标签区域提示语
可设置
['年', '月', '日', '时', '分']
这五个字段,
可以根据视图模式选择设置个别标签,也可以设置所有标签,
dtpicker
显示的时候只会根据当前视图显示设置项,
*建议不要设置空字符串,会影响美观哦
-
4.参数:beginDate
设置可选择日期最小范围
可单独设置最小年范围, 如: beginYear:2015
,
其他日期支持Date格式,如:new Date(2016,5)
可指定最小月份6月
-
5.参数:endDate
设置可选择日期最大范围
可单独设置最大年范围, 如: endYear:2017
,
其他日期支持Date格式,如:new Date(2016,10)
可指定最大月份11月
- 完整示例:
-
show( getSelectedItems )
-
返回值:[data]
获取选中的项(数组)
如:
*return false;
可以阻止选择框的关闭
-
hide()
-
隐藏dtPicker
如:dtPicker.hide()
-
dispose()
-
释放组件资源(释放后将将不能再操作组件)
如:dtPicker.dispose()
* 通常情况下,不需要释放组件资源,初始化之后,可以一直使用。
* 当内容较多,如不释放组件资源,在某些设备上可能会卡顿。
* 所以每次用完便立即调用 dispose() 进行释放,下次用时再创建新实例。
扩展阅读
*picker
组件会触发webview硬件加速,在部分手机上可以能出现卡顿或变形的情况此时需要开启硬件加速,硬件加速请参考 硬件加速章节
代码块激活字符: mpoppicker
mdtpicker
有准确值的进度条
- 有准确值的进度条会显示当前进度正处于整体进度的占比位置,用户可以更直观的预期完成时间;
- 使用进度条控件,需要一个进度条控件容器,mui会自动识别该容器下是否有进度条控件,若没有,则自动创建。
进度条控件DOM结构:
初始化:
例如:
progressbar初始化逻辑:
检查当前容器(container控件)自身是否包含.mui-progressbar
类:
- 当前容器包含
.mui-progressbar
类,则以当前容器为目标控件,直接显示进度; - 否则,检查当前容器的直接孩子节点是否包含
.mui-progressbar
类,若存在,则以遍历到的第一个含有.mui-progressbar
类的孩子节点为目标控件,显示进度; - 若当前容器的直接孩子节点,均不含.mui-progressbar类,则自动创建进度条控件;
更改显示进度条:
关闭进度条:
备注:关闭进度条一般用于动态创建(DOM中预先未定义)的进度条,调用hide方法后,会直接删掉对应的DOM节点;若已提前创建好DOM节点的进度条,调用hide方法无效;
无限循环进度条:
若无法准确提供当前进度,可以提供无限循环进度条(无限循环进度条类似于waiting等待框,参考[HTML5+规范]
无限循环进度条和准确值的进度条的用法基本相同,有如下差异:
进度条控件DOM结构(多了.mui-progressbar-infinite
):
初始化
注意:无限循环进度条不显示具体进度,因此初始化时,不能传入progress参数;mui框架也是根据progressbar构造方法中是否包含progress参数来区分当前进度条为有准确值的进度条还是无限循环进度条;
同样因为不显示具体进度的原因,无限循环进度条调用setProgress()方法无效。
关闭进度条
页面顶部进度条
页面顶部进度条类似浏览器进度条,固定显示在页面顶部(标题导航控件下方); 因此,若当前页面使用父子双webview模式,子页面没有标题导航组件,则需通过自定义css的方式,重定义顶部进度条的位置,示例代码如下:
使用页面顶部进度条时,无需编写DOM结构,使用如下代码即可自动创建(顶部无限循环进度条同理):
扩展阅读
代码块激活字符: mprogressbar
当用户向下滚动时,标题栏逐渐由透明转变为不透明;当用户再次向上滚动时,标题栏又从不透明变为透明状态。
透明标题栏组件比较简单,只需要在header
组件上添加.mui-bar-transparent
类即可,如下为示例代码
如果需要个性化定制可通过data-*
属性或者jsAPI
DIY
DOM API | 作用 | JS API |
data-top | 距离顶部高度(滚动到该位置即触发 ) | {top:0} |
data-offset | 滚动透明距离 | {offset:150} |
data-duration | 过渡时间 ms | {duration:16} |
data-scrollby | 监听区域滚动容器 (*mui 3.5版本+支持) 默认window 默认监听原生滚动, 如监听mui scroll控件滚动,则: document.querySelector('.mui-scroll-wrapper') | {scrollby:DOM} |
扩展阅读
问答社区参考示例:原生版本透明渐变导航条使用教程
代码块激活字符: mtransparent
radio用于单选的情况
DOM结构
默认radio在右侧显示,若希望在左侧显示,只需增加.mui-left
类即可,如下:
若要禁用radio,只需在radio上增加disabled属性即可;
mui基于列表控件,提供了列表式单选实现;在列表根节点上增加.mui-table-view-radio
类即可,若要默认选中某项,只需要在对应li
节点上增加.mui-selected
类即可,dom结构如下:
列表式单选在切换选中项时会触发selected事件,在事件参数(e.detail.el
)中可以获得当前选中的dom节点,如下代码打印当前选中项的innerHTML:
扩展阅读
代码块激活字符: mradio
滑块常用于区间数字选择
DOM结构
扩展阅读
代码块激活字符: mrange
在App开发中,div区域滚动的需求是普遍存在的,但系统默认实现又有如下问题:
- Android平台4.0以下不支持div滚动
- Android平台4.0以上支持div滚动,但不显示滚动条
- 弹出层的div滚动在iOS平台存在事件透传的问题
因此,mui额外提供了区域滚动组件,使用时需要遵循如下DOM结构
区域滚动组件默认为absolute定位,全屏显示;在实际使用过程中,需要手动设置滚动区域的位置(top和height)
若使用区域滚动组件,需手动初始化scroll控件
*常用配置项:
scroll.options
示例:初始化scroll控件:
mui中iOS平台的下拉刷新(Android平台的下拉刷新使用的是双webview+原生滚动方案)、popover、可拖动式选项卡均使用了scroll组件。 为方便大家使用,mui还额外为scroll插件封装了部分方法。
示例:快速回滚到该区域顶部,代码如下:
滚动到顶部的代码比较容易实现,坐标值设为0、0即可;但滚动到底部,需要计算该区域的实际高度,因此mui封装了scrollToBottom方法。
横向滚动只需在scroll组件基础上添加mui-slider-indicatorcode
mui-segmented-control
mui-segmented-control-inverted
这三个class即可.(给子元素添加mui-control-item
可加大文字间距增强体验
如:)
扩展阅读
代码块激活字符: mscroll
mscrollsegmented
轮播组件是mui提供的一个核心组件,在该核心组件基础上,衍生出了图片轮播、可拖动式图文表格、可拖动式选项卡、左右滑动9宫格等组件,这些组件有较多共同点。首先,Dom构造基本相同,如下:
当拖动切换显示内容时,会触发slide事件,通过该事件的detail.slideNumber参数可以获得当前显示项的索引(第一项索引为0,第二项为1,以此类推),利用该事件,可在显示内容切换时,动态处理一些业务逻辑。
如下为一个可拖动式选项卡示例,为提高页面加载速度,页面加载时,仅显示第一个选项卡的内容,第二、第三选项卡内容为空。
当切换到第二、第三个选项卡时,再动态获取相应内容进行显示:
图片轮播、可拖动式图文表格等均可按照同样方式监听内容变化,比如我们可以在图片轮播界面显示当前正在看的是第几张图片:
扩展阅读
问答社区话题讨论: 轮播
代码块激活字符: mslider
mui提供了开关控件,点击滑动两种手势都可以对开关控件进行操作,UI如下:
默认开关控件,带on/off文字提示,打开时为绿色背景,基本class类为.mui-switch
、.mui-switch-handle
,DOM结构如下:
若希望开关默认为打开状态,只需要在.mui-switch
节点上增加.mui-active
类即可,如下:
若希望隐藏on/off文字提示,变成简洁模式,需要在.mui-switch
节点上增加.mui-switch-mini
类,如下:
mui默认还提供了蓝色开关控件,只需在.mui-switch
节点上增加.mui-switch-blue
类即可,如下:
蓝色开关上增加.mui-switch-mini
即可变成无文字的简洁模式
方法
若要获得当前开关状态,可通过判断当前开关控件是否包含.mui-active
类来实现,若包含,则为打开状态,否则即为关闭状态;如下为代码示例:
若使用js打开、关闭开关控件,可使用switch插件的toggle()
方法,如下为示例代码:
事件
开关控件在打开/关闭两种状态之间进行切换时,会触发toggle事件,通过事件的detail.isActive属性可以判断当前开关状态。可通过监听toggle事件,可以在开关切换时执行特定业务逻辑。如下为使用示例:
初始化: mui在mui.init()中会自动初始化基本控件,但是 动态添加的 Switch 组件需要手动初始化