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 的值。