bookHidden: true title: 应用前端开发指引

weight: 1

应用前端开发指引

0. 开始之前

应用的前端可以独立开发，但是在开发过程中一般需要调用后台接口获取数据。在项目开始的早期，可以通过自行模拟后台返回结果的方式来开发页面逻辑。当后台服务部署完成后，在本地可以通过代理的方式来调用服务器上的接口进行调试，这时就需要登录系统。

plugin-starter-shell项目内置了系统的登录页面，以及访问服务器接口的代理服务。可以通过下面的方式获取到plugin-starter-shell项目：

git clone https://github.com/xsio/plugin-starter-shell.git

或者点击 plugin-starter-shell-v1.0.zip 下载。

在获取plugin-starter-shell项目代码之后，执行下面的命令来启动项目：

cd plugin-starter-shell
npm install
npm start

中运行npm start命令时默认连接的是产品研发的test环境，后面可以指定要连接的目标系统，如：npm start prod ，会连接生产环境。各环境的连接配置在文件scripts/start.js中：

const targets = {
    test: 'https://app.dmhub.cn',
    validation: 'https://app.convertwork.cn',
    prod: 'https://app.convertlab.com',
    appz: 'https://appaz.convertlab.com',
    foton: 'https://app-dmhub.foton.com.cn',
    v1:'https://appv1.convertwork.cn',
};
 
const target = process.argv[2] || 'test';

在此可以配置要对接的私有云环境。

启动成功后，将自动打开浏览器，可以用下面的链接来访问登录页：

http://localhost:3003/login.html

如果可以正常看到登录页面，则说明项目启动成功。

接下来挂载plugin-quick-starter模板项目的前端代码。可以按照下面步骤进行：

cd plugin-quick-starter/src/main/webapp
npm install
npm run mount

正常情况下，terminal上应该输出如下log：

dev server running at http://localhost:58189
successfully mounted.
[BABEL] Note: The code generator has deoptimised the styling of /Users/eric/gitlab/plugin-quick-starter/src/main/webapp/node_modules/lodash/lodash.js as it exceeds the max of 500KB.
Hash: f7b392d8bd6b74fe9021
Version: webpack 3.12.0
 
......//此处省略若干行
 
Child html-webpack-plugin for "index.html":
         Asset     Size  Chunks  Chunk Names
    index.html  1.29 MB       0 
    [./node_modules/html-webpack-plugin/lib/loader.js!./template.html] ./node_modules/html-webpack-plugin/lib/loader.js!./template.html 3.13 kB {0} [built]
    [./node_modules/lodash/lodash.js] ./node_modules/lodash/lodash.js 478 kB {0} [built]
    [./node_modules/webpack/buildin/global.js] (webpack)/buildin/global.js 492 bytes {0} [built]
    [./node_modules/webpack/buildin/module.js] (webpack)/buildin/module.js 546 bytes {0} [built]
webpack: Compiled successfully.

看到上面的日志则说明模板项目挂载成功，登录之后访问如下链接：

http://localhost:3003/application/sample/index.html#/templates

如果能看到项目模板页面，则说明项目编译成功。

至此，整个前端开发环境搭建完毕，可以参考下一节开始开发。

1.项目结构

前端项目源代码的目录结构如下：

plugin-quick-starter
|-src
    |-main
        |-webapp
            |-src
            |   |-components
            |   |-constants
            |   |-services
            |   |-index.js
            |   |-index.less
            |   |-TemplateList.js
            |-dependencies.js
            |-mount.js
            |-package.json
            |-template.html
            |-webpack.config.common.js
            |-webpack.config.js
            |

前端的代码都位于项目的src/main/webapp目录下面，webapp即为前端项目的根目录。开发时请按照该目录结构规范进行开发。

各目录和文件说明如下：

components目录下存放各个UI模块的组件，例如模板项目中的GroupMenu和LeftMenu等。

constants目录下存放项目中用到的常量文件。

services目录下存放调用后台接口的请求封装。

TemplateList.js文件是模板项目中首页的源码文件，包括了左侧的导航栏，右侧的表格，上面的工具栏等。

index.js中定义了页面的路由信息，基于react-router来实现。

template.html文件为html文件的模板页面，在用webpack来执行build操作时，会以该文件为模板来生成目标html文件。

其他的目录包括：

webapp下的node_modules为执行npm install命令后安装的npm依赖。

webapp下的dist目录为执行npm run build之后生成的目标文件，即将来线上系统中要使用的文件。由于webapp为前端页面的根目录，因此在访问页面时需要考虑到dist目录，例如访问首页的路径为：/dist/index.html

2.项目开发

在开始正式开始开发时，需要对模板项目里的一些设置做些调整，主要调整点如下：

package.json文件中第2行：
```
"name": "sample-ui",
```
此处的默认属性"sample-ui"，需要改成自己项目的名称。

package.json文件中的第6行：
```
"mount": "node mount.js sample"
```
此处的"sample"需要改成项目的名称，可以与第一步中的不一样，尽量不要包含特殊字符。该处的改动会影响到本地开发时页面的访问路径：
```
http://localhost:3003/application/sample/index.html#/templates
```
路径中的sample即为该处设置的值。

webpack.config.js：

module.exports = require('./webpack.config.common.js')({
    title: 'sample',
    css: []
});
module.exports.entry.index = "./src/index.js";
//module.exports.externals.echarts = 'echarts';
var HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports.plugins.find(p => p instanceof HtmlWebpackPlugin).options.filename = "index.html";

第2行中的title为浏览器tab上默认显示的标题，但是该标题可能被TitleBar组件中设置的标题覆盖。

第3行中的css为需要在页面中引入的css文件路径。

第5行中的"./src/index.js"为默认的module入口页面，可按需调整。

第8行中的"index.html"为执行npm run build命令后在webapp/dist目录下生成的html页面的名称，可按需调整。

webpack.config.common.js中定义了webpack中的plugin，loader，输出路径等设置，请仔细阅读，按需修改。

3. 前端国际化

如果应用项目的界面需要支持英文版本，需要对页面上的文字进行翻译。模板项目内置了对国际化的支持，默认的页面可以进行中英文的切换。应用项目国际化的支持可以按照以下步骤进行配置和开发：

在package.json中增加如下devDependencies:
```
"babel-plugin-i18n": "0.4.*"
```

确保.babelrc文件中增加了对plugins的设置。完整的文件内容如下：

{
    "presets": [
        "@babel/preset-react",
        "@convertlab/es"
    ],
    "plugins": [
        "i18n"
    ]
}

在项目根目录放置i18n.config.js。目前只有一个参数languageConditionExpression，是一个函数，设置区分语言的条件。

module.exports = {
    languageConditionExpression(t) {
        return t.memberExpression(
            t.identifier('localStorage'),
            t.identifier('locale')
        );
    }
};

开始翻译。

应用使用的是localStorage.locale作为语言条件，也就是，当localStorage.locale的值是"en-US"时是英文环境，否则就是中文环境。

对文字进行翻译有两种方式。一是在需要翻译对文件的同目录下创建同名（包括扩展名）切后缀为.i18n.json的文件，例如为webapp下面的src/TemplateList.js文件增加对应的TemplateList.js.i18n.json文件，内容如下：

{
    "项目模板": "Project Template",
    "搜索内容": "Search this page",
    "应用项目快速开始模板": "Quick starter for plugin",
    "帮助": "Help",
    "新建": "New",
    "名称": "Name",
    "类型": "Type",
    "状态": "Status",
    "预览": "Preview",
    "创建时间": "Created At",
    "创建人": "Created By",
    "操作": "Actions"
}

在代码中出现的中文在这里指定对应的翻译后，即可实现两种语言的切换。

如果文字中包含变量，可按如下方式处理：

{
    "你好，{}": "Hello, {}",
    "第{}-{}条记录，共{}条": "Record {0}-{1} of all {2} record(s)"
}

另一种方法是在指定的文件夹中创建名为i18n.json的文件，其中的翻译对该文件夹下的所有文件(包括子文件夹)起作用。如果有多层文件夹，内部的设置会覆盖外部的设置。对于应用项目，如果页面不是很多，建议在最外层，例如webapp/src目录下，创建一个名为i18n.json的文件，将所有的翻译都在这里集中管理。

4. 其他注意事项

请按照前端开发规范进行开发，开发规范请参考前端代码开发规范。对于私有云应用和内部应用，由于共享了产品的app域名和session，可以直接在前端代码中调用app服务的接口。调用应用后台接口的格式请参考应用后端开发文档，或咨询对应的后端开发人员。