语言: 英文中文

Framework7插件API

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
});