kylinH5框架之项目脚手架

一时失言乱红尘 2021-08-29 18:05 564阅读 0赞

## 初始化结构 ##

项目初始化结构如下:

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` 将在下面单独展开。

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

pages

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

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

<table> 
 <thead> 
  <tr> 
   <th>字段名</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>备注</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>entry</td> 
   <td>string</td> 
   <td>-</td> 
   <td>相对路径，指向当前页面的 JS 打包入口。</td> 
  </tr> 
  <tr> 
   <td>template</td> 
   <td>string</td> 
   <td>-</td> 
   <td>相对路径，指向当前页面的 HTML 打包路径，如果为空，会寻找&nbsp;<code>kylinApp.pageTemplate</code>&nbsp;字段值。</td> 
  </tr> 
 </tbody> 
</table>

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` 文件中，有如下配置项：

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

### 示例 ###

在执行 `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` 的值。

[mock]: https://help.aliyun.com/document_detail/72531.html
[resource]: https://help.aliyun.com/document_detail/72532.html
[Link 1]: https://help.aliyun.com/document_detail/87472.html