Framework7插件API

优质

小牛编辑

121浏览

2023-12-01

Framework7拥有简单易用的插件API，允许你创造自己的Framework7插件。

插件文件结构

首先，我们来看一下基本插件的JS结构：

framework7.myplugin.js:

Framework7.prototype.plugins.myPlugin = function (app, params) {
    ... plugin code here ...
};

其中

myPlugin - 插件名称，需要唯一，当用户向你的插件传递参数的时候，需要用到这个名称
app - 插件函数的第一个参数，它是一个初始化的实例
params - 插件参数（非必需）

插件参数

我们的插件要怎样接收，作为params参数传递给插件原型函数的个人参数呢？它相当简单，只需要在App初始化的时候，指定插件的名字，然后提供参数：

var myApp = new Framework7({
    modalTitle: 'My App',
    pushState: true,
    /* 
    Here comes your plugin parameters that will be passed to your plugin in case of parameter name is the same as plugin name:
    */
    myPlugin: {
        foo: 'bar'
    }
});

现在，在插件中：

Framework7.prototype.plugins.myPlugin = function (app, params) {
    console.log(params.foo); // 'bar'
};

插件代码

怎样让我们的插件执行期望的功能呢？

Framework7的插件系统非常有趣而简单，它基于"hooks", "prevents" (暂时不在内核中) and "process" (暂时不在内核中)：

hooks - 与一般的回调函数一样，它们在应用的很多内核部件中被调用。它们允许你的插件在指定的时刻执行代码，或者在不同的阶段处理数据。每个hook接收不同的参数。
prevents - 允许禁用应用的默认行为，比如它们可以禁用默认的页面动画，而使用你自己的
processes - 它们像预处理器一样，每道处理步骤都会读取数据，然后修改它

所以，插件返回的对象，应该含有3个对象成员（hooks，prevents和processes）：

Framework7.prototype.plugins.myPlugin = function (app, params) {
 
    /* 
    Local plugin scope 
    */
 
    // Handle app init hook
    function handleAppInit() {
        console.log('app initialized');
    }
 
    // Return hooks
    return {
        hooks: {
  // App init hook
  appInit: handleAppInit
        }
    };    
};

注意，插件会在应用初始化的第一个阶段初始化，有些东西还无法获取（比如上面例子提到的“local plugin scope”）。如果你想要在应用完全初始化之后再执行代码，应该使用‘appInit’ hook

可用的Hooks

我们首先看一下现有可用的hooks（这个列表会扩展的）和它们的参数：

appInit	在App完全初始化时，会被触发
navbarInit (navbar, pageData)	和"navbarInit"事件一样
pageInit (pageData)	和"pageInit"事件（或者是同名的页面回调函数）一样。在Framework7初始化页面组件和导航栏之后，会被触发
pageBeforeInit (pageData)	和"pageBeforeInit"事件（或者是同名的页面回调函数）一样。在Framework7将要向DOM插入新页面之前，会被触发
pageBeforeAnimation (pageData)	和"pageBeforeAnimation"事件（或者是同名的页面回调函数）一样。在每样东西都已经初始化，并且页面（和导航栏）做好动画准备的时候，会被触发
pageAfterAnimation (pageData)	和"pageAfterAnimation"事件（或者是同名的页面回调函数）一样。在页面（和导航栏）动画结束后，会被触发
pageBeforeRemove (pageData)	和"pageBeforeRemove"事件（或者是同名的页面回调函数）一样。在Page要从DOM中被删除时，会被触发
addView (view)	在用户通过调用`myApp.addView`来添加页面时，会被触发。它接收初始化的页面实例作为参数
loadPage (view, url, content)	在页面加载进程的最开始，即它还没有被加入DOM的时候，会被触发
goBack (view, url, preloadOnly)	在返回操作的最开始，会被触发
swipePanelSetTransform (views, panel, percentage)	在滑动面板上滑动时，会被触发

安装插件

要想安装插件，你只需要把它放到Framework7 JavaScript库之后：

<body>
    ...
    <script src="path/to/framework7.js"></script>
    <script src="path/to/framework7.myplugin.js"></script>
</body>

示例插件

让我们来创建简单的调试示例插件。它只会记录所有的hooks和它们的参数，不做其他事情

framework7.debug.js:

Framework7.prototype.plugins.debug = function (app, params) {
    // exit if not enabled
    if (!params) return;
 
    return {
        hooks: {
  appInit: function () {
      console.log ('appInit');
  },
  navbarInit: function (navbar, pageData) {
      console.log('navbarInit', navbar, pageData);
  },
  pageInit: function (pageData) {
      console.log('pageInit', pageData);
  },
  pageBeforeInit: function (pageData) {
      console.log('pageBeforeInit', pageData);
  },
  pageBeforeAnimation: function (pageData) {
      console.log('pageBeforeAnimation', pageData);
  },
  pageAfterAnimation: function (pageData) {
      console.log('pageAfterAnimation', pageData);
  },
  pageBeforeRemove: function (pageData) {
      console.log('pageBeforeRemove', pageData);
  },
  addView: function (view) {
      console.log('addView', view);
  },
  loadPage: function (view, url, content) {
      console.log('loadPage', view, url, content);
  },
  goBack: function (view, url, preloadOnly) {
      console.log('goBack', view, url, preloadOnly);
  },
  swipePanelSetTransform: function (views, panel, percentage) {
      console.log('swipePanelSetTransform', views, panel, percentage);
  }
        }
    };
};

我们需要把它添加到应用中：

<body>
    ...
    <script src="path/to/framework7.js"></script>
    <script src="path/to/framework7.debug.js"></script>
    <script src="path/to/myapp.js"></script>
</body>

并且在myapp.js中启用它：

var myApp = new Framework7({
    debug: true
});