npm package: @kdcloudjs/create-kd-app
Description: 一个前端提供的快速开发页面的脚手架。   苍穹平台现支持前后端分离，支持依据开放平台提供的API独立开发应用。前端开发人员可以基于提供的API，独立完成开发任务，与后台解耦，开发效率更快。
Latest version: 1.0.8

# 前端脚手架使用说明
## 一、简介
一个前端提供的快速开发页面的脚手架。  
苍穹平台现支持前后端分离，支持依据开放平台提供的API独立开发应用。前端开发人员可以基于提供的API，独立完成开发任务，与后台解耦，开发效率更快。

## 二、需求配置
`node ^12.21.0 及以上`


## 三、简单指引
### npm
1.	创建项目 `npx @kdcloudjs/create-kd-app myapp`
2.	选择shop-demo（商城案例）、react-app（基础模版）
3.	安装依赖 `cd myapp && npm install` 
4.	启动服务 `npm start` 
5.	打包项目用于部署 `npm run build`

### yarn
1.	创建项目 `yarn create @kdcloudjs/kd-app myapp`
2.	选择shop-demo（商城案例）、react-app（基础模版）
3.	安装依赖 `cd myapp && yarn` 
4.	启动服务 `yarn start` 
5.	打包项目用于部署 `yarn run build`  

## 四、详细介绍
### 1.脚手架安装
1） 根据脚手架，创建项目  
`npx @kdcloudjs/create-kd-app myapp(项目名称)` 

2） 选择模板，进行快速开发  
提供**shop-demo**（商城案例）或**react-app**（基础模板），可通过更改部分代码，达到快速开发目的。当选择商城案例时，支持用户配置服务器地址。  
![](img/1.png) 

![](img/2.png)  
*注：在git bash中，可通过输入数字1或2选择模板；在cmd命令中，可通过上下箭头选择模板。如若忘记配置地址，默认内置服务器地址，也可在host.js文件中其进行更改。*
### 2.demo运行
1） 安装依赖  
`cd myapp && npm install`  
*进入myapp文件夹中，运行npm install命令，项目的package.json文件中所有依赖均被安装。* 

2） 启动服务，用于本地调试  
`npm start`
![](img/3.png)

   如果选择商城案例，且一切顺利，启动服务后，会看到如下页面：
![](img/4.png)   
   *左侧为项目目录，右侧为运行后的商城首页。*

3） 打包项目，用于部署  
`npm run build`
![](img/5.png)
   *本地运行该命令后，会打包生成dist文件夹，用于线上应用发布*  
![](img/6.png)
 
### 3.开发指引
#### 1) 项目结构
├── build                    # 所有打包配置项  
│   └── webpack.base.js         # webpack的一些基础配置  
│   └── webpack.dev.js          # 开发环境的webpack配置  
│   └── webpack.prod.js         # 生产环境的webpack配置  
├── node_modules             # 放置项目依赖的第三方包  
├── public                   # 公共文件（公用模板与图标等）  
├── src                      # 程序源文件  
│   ├── index.html              # 项目入口文件  
│   ├── assets                  # 项目所需的图片资源  
│   ├── components           	# 全局可复用的公共组件  
│   ├── constant             	# 全局变量  
│   ├── layouts              	# 主页结构  
│   ├── page                 	# 页面级组件，与路由对应  
│   └── routes               	# 路由文件  
│   │   ├── AppRouter.js       	# 路由与组件对应关系  
│   └── services.js             # API文件  
│   ├── stores               	# mbox指定块  
│   ├── styles               	# 程序样式  
├── .babelrc                 # babel转换的配置文件  
├── .gitignore               # git操作需要忽略的文件  
├── .postcssrc.js            # postcss的配置文件  
├── package-lock.json        # 锁定安装时的包的版本号  
└── package.json             # npm的包文件、项目的信息等  
#### 2) API使用
&emsp;&emsp;选择案例，启动服务，且demo运行成功后，可在server.js中使用api接口，与后端进行交互。例如，商城案例中，获取商品分类数据  
&emsp;&emsp;第一步：在server.js文件中，定义获取商品分类数据的api(getCommodityType)，如下:
```javascript
export const getCommodityType = async (accToken) => {
  const url = `http://${HOST}/kapi/v2/kdec/kdec_open/kdec_commodity_type/getCommodityType`
  const header = { access_token: accToken }
  const data = {
    pageSize: 10,
    pageNo: 1
  }
  try {
    const res = await getTypeApi(url, header, data)
    if (res.status) {
      const data = res.data || {}
      return data
    }
  } catch (error) {
    console.log('error', error)
  }
}
```
*其中，HOST为配置的服务器地址（可在host.js文件中对其修改），getTypeApi为项目预置的GET请求。*  

&emsp;&emsp;第二步：在HomeStore.js中对状态进行管理，将取回的商品分类数据，存放在可观察的类属性typeData中，如下：  
```javascript
async getCommodityTypeData () {
  const data = await getCommodityType(this.accToken)
  runInAction(() => {
    this.typeData = data.rows
  })
}
```
&emsp;&emsp;第三步：可在页面组件中使用typeData ，如下：
```javascript
{typeData && typeData.map((item, index) => {
  return (
    <li
      className={index === currentIndex ? styles.active : ''}
      key={item.number}
      onClick={() => handleTypeItem(item, index)}
    >
      {item.name}
    </li>
  )
})}
```
*您可以在商城案例中按需要更改代码，当然，您也可以使用基础模板，从头构建您的项目。*
#### 3) 数据存储
&emsp;&emsp;脚手架使用MobX对状态进行管理，项目中数据存储在stores文件夹。在商城案例，stores的HomeStore.js文件中，存放了首页相关的数据。如下：
```javascript
makeObservable(this, {
  accToken: observable, // accessToken值 string 可放入全局
  typeData: observable, // 商品类型数据 list 
  tabData: observable, // 同类商品的数据 list
  totalCount: observable, // 购物车中商品类型数量 number
  getAccToken: action.bound,
  getCommodityTypeData: action.bound,
  getQueryTabData: action.bound,
})
```
#### 4) 路由管理
&emsp;&emsp;脚手架使用React Router V6路由库，管理URL，实现组件的切换和状态的变化。
在AppRouter.js文件中，定义了URL路径与组件的对应关系，如下：
```javascript
const renderRoutes = () => {
  return (
    <Routes>
      <Route path='/' element={<BasicLayout />}>
        <Route index element={<Home />} />
        <Route path='details' element={<Details />} />
        <Route path='shopCart' element={<ShopCart />} />
        <Route path='*' element={<Exception404 />} />
      </Route>
    </Routes>
  )
}
```
*您可在此文件中管理您的路由.*  

&emsp;&emsp;同时，您可使用Link进行路由跳转，如在商城案例首页中，点击商品图片，可跳转到商品详情页，代码如下：
```javascript
<Link to='details' state={stateParams}>
  <img src={item.kdec_mainimage_fullurl} alt='Image' />
</Link>
```
*当然，也可使用其他方式实现路由跳转，脚手架并不会对其做任何限制。*