MUI框架 — init()方法

在APP开发中，若要使用H5+ API，必须等 plusready 事件发生之后才能正常使用，MUI框架将其封装成 mui.plusReady() 方法。因此，涉及调用H5+ API，则建议都写在 mui.plusReady() 方法中。

mui.init() （MUI插件初始化）
MUI需要在页面加载时初始化很多基础控件，因此务必在每个页面中调用。

MUI框架提供了在使用 mui.init 方法初始化时配置其他功能，如创建子页面、关闭页面、手势事件配置、预加载、下拉刷新、上拉加载、设置系统状态栏背景颜色。

mui.init({
    //子页面
    subpages: [{}],
    //预加载
    preloadPages: [],
    //下拉刷新、上拉加载
    pullRefresh: {},
    //手势配置
    gestureConfig:{},
    //侧滑关闭
    swipeBack:true,//(默认false)启用右滑关闭功能
    //监听Android手机的back、menu按键
    keyEventBind: {
        backbutton: false,//(默认true)关闭back按键监听
        menubutton: false//(默认true)关闭menu按键监听
    },
    //处理窗口关闭前的业务
    beforeback: function() {},
    //设置状态栏颜色
    statusBarBackground: '#9defbcg',//设置状态栏颜色,仅IOS有效
    preloadLimit: 5//预加载窗口限制
});

创建子页面

对于APP开发中共用导航栏或选项卡，加载页面重新渲染出现卡顿的现象以及滚动不流畅的问题。MUI提供两种解决方案：

• 第一种（官方推荐）：使用原生 titleNView 以及原生 tabbar 来替换页面的导航栏或者选项卡。
• 第二种：通过双 webview 模式解决，此种情况多适用于需要上下刷新的列表页面。将需要滚动的区域通过单独的 webview 来实现，完全使用原生滚动。具体做法：将目标页面分解为主页面和内容页面，主页面显示头尾区域，如顶部导航栏、底部选项卡等；内容页面显示具体需要滚动的内容，然后在主页面中使用 mui.init() 方法初始化内容页面。

mui.init({
    //子页面
    subpages: [{
        url: 'content.html',//子页面HTML地址,支持本地和网络地址
        id: 'content',//子页面标识
        styles: {//窗口样式,可参考H5+ API 中的WebviewStyle中查看
            top: '45px',//子页面顶部位置,若存在导航栏,则去除导航栏高度
            bottom: '51px',//子页面底部位置,若存在底部选项卡,则去除底部选项卡高度
            width: '100%',//子页面宽度,默认为100%
            height: '100%',//子页面高度,默认为100%
        },
        extras: {}//额外扩展参数
    }],
})

官方 Hello mui 的首页就是典型的双 webview 模式的案例。

关闭页面

MUI框架将窗口关闭功能封装在 mui.back() 方法中。

• 若当前 webview 为预加载页面，则 hide 当前 webview;
• 否则，close 当前 webview。
  在MUI框架中，有三种操作可触发页面关闭：
• 点击包含 mui-action-back 样式的控件；
• 在屏幕内，向右快速滑动；
• Android手机按下 back 按键
  MUI框架封装的页面右滑关闭功能，默认未启用，若有需要，则需要在初始化时设置swipeBack参数：

mui.init({
    swipeBack:true //启用右滑关闭功能
});

MUI框架默认会监听Android手机的back按键，然后执行页面关闭逻辑。若不希望MUI自动处理，则关闭MUI的back按键监听。

mui.init({
    keyEventBind: {
        backbutton: false  //关闭back按键监听
    }
});

我们也可以调用 mui.back() 方法，执行窗口关闭逻辑。
mui.back() 方法仅处理窗口逻辑，若希望在窗口关闭之前处理一些其他业务逻辑，则需要在MUI初始化时设置beforeback 参数。

• 执行 beforeback 参数对应的函数若返回false，则不再执行 mui.back() 方法；
• 否则（返回true或无返回值），继续执行 mui.back() 方法。
  示例：从详情页返回列表页希望刷新列表界面。

mui.init({
    beforeback: function(){
        //获得列表界面的webview
        var list = plus.webview.getWebviewById('list');
        //触发列表界面的自定义事件（refresh）,从而进行数据刷新
        mui.fire(list,'refresh');
        //返回true，继续页面关闭逻辑
        return true;
    }
});

因为 beforeback 的执行返回必须是同步的，因此我们有时候需要重写 mui.back() 方法。

//备份mui.back，mui.back已将窗口关闭逻辑封装的比较完善（预加载及父子窗口），因此最好复用mui.back
var old_back = mui.back;
mui.back = function(){
  var btn = ["确定","取消"];
  mui.confirm('确认关闭当前窗口？','Hello MUI',btn,function(e){
    if(e.index==0){
        //执行mui封装好的窗口关闭逻辑；
        old_back();
    }
  });
}

手势事件配置

在开发APP时，会用到很多的手势操作，如滑动、长按、点击等。为了方便我们能够快速使用，MUI框架内置了常用的手势事件。

分类	参数	描述
点击	tap	单击屏幕
点击	doubletap	双击屏幕
长按	longtap	长按屏幕
长按	hold	按住屏幕
长按	release	离开屏幕
滑动	swipeleft	向左滑动
滑动	swiperight	向右滑动
滑动	swipeup	向上滑动
滑动	swipedown	向下滑动
拖动	dragstart	开始拖动
拖动	drag	拖动中
拖动	dragend	拖动结束

手势事件配置
可以通过 mui.init() 方法中的 gestrueConfig 参数进行配置。

mui.init({
  gestureConfig:{
   tap: true, //默认为true
   doubletap: true, //默认为false
   longtap: true, //默认为false
   swipe: true, //默认为true，滑动共用
   drag: true, //默认为true，拖动共用
   hold:false,//默认为false，不监听
   release:false//默认为false，不监听
  }
});

事件监听
单个元素的事件监听，直接使用 addEventListener()。

elem.addEventListener("swipeleft",function(){
     console.log("你正在向左滑动");
});

预加载

所谓的预加载就是用户尚未触发页面跳转时，提前创建目标页面。

• 方法一：通过 mui.init() 方法中的 preloadPages 参数配置。

mui.init({
  preloadPages:[
    {
      url:'content.html',
      id:'content',
      styles:{},//窗口参数
      extras:{},//自定义扩展参数
      subpages:[{},{}]//预加载页面的子页面
    }
  ],
  preloadLimit:5//预加载窗口数量限制(一旦超出,先进先出)默认不限制
});

注：使用简单、可预加载多个页面，但不会返回预加载每个页面的引用，若要获得对应 webview 引用，需要使用 plus.webview.getWebviewById 方式获得; 另外，因为mui.init() 方法是异步执行，所有在该方法执行完后立即获得对应webview引用，可能会失败。

• 方法二：通过 mui.preload 方法预加载。

var page = mui.preload({
    url:'content.html',
    id:'content',//默认使用当前页面的url作为id
    styles:{},//窗口参数
    extras:{}//自定义扩展参数
});

注：通过 mui.preload() 方法预加载，可立即返回对应webview的引用，但一次仅能预加载一个页面；若需要加载多个页面，则需要多次调用 mui.preload() 方法。

下拉刷新

单 webview 模式

• 动画原理：下拉刷新时，触发原生下拉刷新控件，而整个 webview 位置不会发生变化，因此不会再拖动过程中发生DOM重绘，当控件拖动到一定位置触发动态加载数据以及刷新操作。相比较双 webview 模式，不会创建额外的 webview，性能更优。
• 使用方法： MUI初始化时设置 pullRefresh 各项参数。

mui.init({
  pullRefresh : {
    container:"#refreshContainer",//下拉刷新容器标识，querySelector能定位的css选择器均可，比如：id、.class等
    down : {
      style:'circle',//必选，下拉刷新样式，目前支持原生5+ ‘circle’ 样式
      color:'#2BD009', //可选，默认“#2BD009” 下拉刷新控件颜色
      height:'50px',//可选,默认50px.下拉刷新控件的高度,
      range:'100px', //可选 默认100px,控件可下拉拖拽的范围
      offset:'0px', //可选 默认0px,下拉刷新控件的起始位置
      auto: true,//可选,默认false.首次加载自动上拉刷新一次
      callback :pullfresh-function //必选，刷新函数，根据具体业务来编写，比如通过ajax从服务器获取新数据；
    }
  }
});

• 模式优点：

1. 不创建额外的 webview ，性能消耗更少；
2. 下拉拖动过程中不发生重绘，减少了性能消耗。

双 webview 模式

• 动画原理：使用双 webview 模式的下拉刷新，创建一个子 webview 添加列表；拖动时，拖动的是一个完整的 webview，回弹动画使用原生动画。
• 使用方法：只需要创建子页面即可。

mui.init({
    subpages:[{
      url:pullrefresh-subpage-url,//下拉刷新内容页面地址
      id:pullrefresh-subpage-id,//内容页面标志
      styles:{
        top:subpage-top-position,//内容页面顶部位置,需根据实际页面布局计算，若使用标准mui导航，顶部默认为48px；
        .....//其它参数定义
      }
    }]
});

• 模式缺点：性能消耗更大。
• 滚动到特定位置
  下拉刷新组件滚动到特定位置的方法类似区域滚动组件。
  Hello mui 下拉刷新示例中，实现双击标题栏，返回顶部

var contentWebview = null;
//监听标题栏的双击事件
document.querySelector('header').addEventListener('doubletap',function () {
  if(contentWebview==null){
    contentWebview = plus.webview.currentWebview().children()[0];
  }
  //内容区滚动到顶部
  contentWebview.evalJS("mui('#pullrefresh').pullRefresh().scrollTo(0,0,100)");
});

• 更改下拉刷新文字位置

.mui-bar-nav ~ .mui-content .mui-pull-top-pocket{
  top: 180px !important;
}

• 自动触发下拉刷新

mui.init({
  pullRefresh : {
    container:"#refreshContainer",//下拉刷新容器标识，querySelector能定位的css选择器均可，比如：id、.class等
    down : {
      auto: true,//可选,默认false.首次加载自动下拉刷新一次
    },
    up : {
      auto: true //可选,默认false.首次加载自动上拉加载一次
    }
  }
});

• 下拉刷新结束
  两种模式在下拉刷新过程中，当获取数据后，都需要执行 endPulldown 方法，该方法的作用是关闭“正在刷新”的样式提示。

function pullfresh-function() {
     //业务逻辑代码，比如通过ajax从服务器获取新数据；
     ......
     //注意，加载完新数据后，必须执行如下代码，注意：若为ajax请求，则需将如下代码放置在处理完ajax响应数据之后
     //没有更多内容了，endPulldown 传入true， 不再执行下拉刷新
     mui('#refreshContainer').pullRefresh().endPulldown();
}

上拉加载

概述
MUI框架的上拉加载和下拉刷新类似，都属于 pullRefresh 插件。

• 页面滚动到底部，显示“正在加载...”提示
• 执行加载业务数据逻辑
• 加载完毕，隐藏“正在加载...”提示

初始化

mui.init({
  pullRefresh : {
    container:refreshContainer,//待刷新区域标识，querySelector能定位的css选择器均可，比如：id、.class等
    up : {
      height:50,//可选.默认50.触发上拉加载拖动距离
      auto:true,//可选,默认false.自动上拉加载一次
      contentrefresh : "正在加载...",//可选，正在加载状态时，上拉加载控件上显示的标题内容
      contentnomore:'没有更多数据了',//可选，请求完毕若没有更多数据时显示的提醒内容；
      callback :pullfresh-function //必选，刷新函数，根据具体业务来编写，比如通过ajax从服务器获取新数据；
    }
  }
});

结束上拉加载
加载完新数据后，需要执行 endPullupToRefresh() 方法，结束刷新进度条。

function pullfresh-function() {
     //业务逻辑代码，比如通过ajax从服务器获取新数据；
     ......
     //注意：
     //1、加载完新数据后，必须执行如下代码，true表示没有更多数据了：
     //2、若为ajax请求，则需将如下代码放置在处理完ajax响应数据之后
    //是否还有更多数据；若还有更多数据，则传入false；否则传入true，之后滚动条滚动到底部时，将不再显示“上拉显示更多”的提示语，而显示“没有更多数据了”的提示语。
     this.endPullupToRefresh(true|false);
}

重置上拉加载

//可以使用 refresh(true);方法重置上拉加载控件
mui('#pullup-container').pullRefresh().refresh(true);

禁止上拉刷新

//在固定的列表数据显示时，可以禁用上拉刷新
mui('#pullup-container').pullRefresh().disablePullupToRefresh();

启用上拉刷新

mui('#pullup-container').pullRefresh().enablePullupToRefresh();

设置系统状态背景颜色

//可以通过statusBarBackground:rgb 属性何止状态栏颜色。
mui.init({
    statusBarBackground: '#9defbcg',
})

参考文档

• MUI官方文档

上一章	下一章