kylinH5框架之项目脚手架

初始化结构

项目初始化结构如下:

project
├── mock
│   ├── mock.config.js
│   └── rpc
│       └── test.js
├── package.json
├── www
└── src
    ├── common
    │   ├── components
    │   ├── css
    │   │   └── base.less
    │   ├── img
    │   └── js
    ├── layout
    │   ├── index.html
    │   └── layout.html
    └── pages
        └── index
            ├── components
            ├── index.js
            └── store

mock

该目录提供了一种数据 mock 方式，即使用 cnpm run dev:mock 启动时，会自动加载其中的 rpc 目录和 jsapi 目录的对应数据接口。

package.json

在 package.json 文件中的 kylinApp 字段包含了项目配置的元信息，主要有 pages、output、devPort、plugins、dirAlias。

简单举例如下:

{
  "kylinApp": {
    "output": "www",
    "pages": {
      "index": {...}
    },
    "devPort": 8090,
    "dirAlias": {
      "common": "./src/common/",
      "pages": "./src/pages/"
    },
    "plugins": [
    ]
  }
}

www

执行 cnpm run build 后，会自动将构建产物输出到 www 目录中。

src/common

用以放置项目中使用的 css,js,img 文件。

src/layout

对应着 ./src/pages/${pageName} 的各个页面，可以在 package.json 中配置对应页面使用的 html 模板路径。支持 nujuncks 语法。

src/pages

这个目录是用来放各个页面的，各个页面分别放在 ./src/pages/${pageName}/ 目录下。分别包含了 components , store 和 index.js 。

• components 目录中，每个组件都是 Vue 组件。
• store 目录中，有一个 Vuex.Store 实例。
• index.js 为当前 page 的主入口，这里的 page 页面最后会生成一个特定的 ${pageName}.html 页面。

常用参数

这里说到的常用参数是指 kylinApp 下一级中，除了 pages、options、plugins 之外的所有键值。pages、options、plugins 将在下面单独展开。

参数名	类型	默认值	备注
output	string	dist	输出相对目录。
devPort	number	8090	dev 模式监听的 IPv4 端口号(0.0.0.0:devPort)。
dirAlias	Record	{}	等同于 webpack.resolve.alias 中使用相对路径。
pageTemplate	string	-	公共 nunjucks 模板。

pages

此处列举 pages 键值对下的配置项，示例中的 home 表示以下配置均为对 pageName 为 home 的页面生效。

{
  "kylinApp": {
    "pages": {
      "home": {
        ... // 这里的字段
      }
    }
  }
}

字段名	类型	默认值	备注
entry	string	-	相对路径，指向当前页面的 JS 打包入口。
template	string	-	相对路径，指向当前页面的 HTML 打包路径，如果为空，会寻找 kylinApp.pageTemplate 字段值。

plugins

kylinApp.plugins 字段，是一个数组，支持按需加载各个插件。

{
  kylinApp: {
    plugins: [
      "xxxx",
      ["yyyy",{ a: 1 }],
      "zzzz",
      ["6666",{ b: 1 }]
    ]
  }
}

支持传入的形式有 2 种，分别是 默认配置 和 扩展配置 方式，在上述的示例中，引入了4个插件。

• @ali/kylin-plugin-xxxx, 以默认配置加载。
• @ali/kylin-plugin-yyyy, 以 {a:1} 选项加载。
• @ali/kylin-plugin-zzzz, 以默认配置加载。
• @ali/kylin-plugin-6666, 以 {b:1} 选项加载。

已有插件

目前，支持配置的插件有 mock、resource，分别见如下文档：

• mock
• resource

Kylin-plugin-mock 插件是针对在桌面浏览器（Chrome）中调试 JSAPI 的需要而开发的数据 mock 插件。

开启插件

在脚手架工程中，执行如下语句即可，其等价于运行命令时添加 --mock：

cnpm run dev:mock

使用插件

在项目的 ./mock/mock.config.js 文件中，有如下配置项：

const config = {};
// 用户自定义mock
config.call = {
    // mock rpc 接口
    rpc: function (opts, callback) {
        var type = opts.operationType;
        var rpc = require('./rpc/' + type);
        var data = typeof rpc === 'function' ? rpc(opts) : rpc;
        // 防止在业务逻辑中对传入的对象进行了修改
        data = Object.assign({}, data);
        // 模拟服务端/网络接口延迟，此时会发现打了 2 次 log，一次是请求，一次包含返回结果
        setTimeout(() => {
            callback && callback(data);
        }, 2000);
    },
}
window.lunaMockConfig = config;

上述配置将 ./mock/rpc/*.js 中的接口进行数据映射。更多详细配置，可 获取代码示例 后查看。

示例

在执行 cnpm run dev:mock 后，会进入 mock 模式。该模式下在浏览器内执行 AlipayJSBridge.call('abc') ，会去 ./mock/jsapi/abc.js 寻找模拟接口数据。

Kylin-plugin-resource 插件是针对 mPaaS 平台下的全局离线资源包设计的一种资源拦截机制。

使用插件

在脚手架的 package.json 中，可以看到如下配置：

["resource", 
   {
    "map": {
      "vue": {
        "external": "Vue",
        "js": "https://gw.alipayobjects.com/as/g/h5-lib/vue/2.5.13/vue.min.js"
      },
      "fastclick": {
        "external": "FastClick",
        "js": "https://as.alipayobjects.com/g/luna-component/luna-fastclick/0.1.0/index.js"
      }
    }
  }
]

上述配置项表示当代码中出现如下的依赖语句，会进行一定处理：

import xxx from 'vue';
var xxx = require('vue');

上述对 vue 的依赖使用，会做如下处理:

1. 在生成的 HTML 模板中注入 <script src="https://gw.alipayobjects.com/as/g/h5-lib/vue/2.5.13/vue.min.js" ></script> 脚本资源。
2. 把上述 vue 依赖重定向为 window.Vue 的值。