Umi 小白紀實（一）—— 建立項目&經常使用配置

umi 是一個企業級 react 應用框架，也是螞蟻金服的底層前端框架

《螞蟻金服的前端框架和工程化實踐》

 

1、安裝腳手架

在建立項目以前，須要保證有 node 8.10 以上的環境

可使用官方腳手架 create-umi 快速建立項目

首先建立一個新目錄

mkdir myapp && cd myapp

而後直接建立項目

yarn create umi 
// 或
npm create umi

若是提示 create-umi 命令不存在，能夠先執行  yarn global bin ，而後把 global bin 的路徑添加到 PATH 環境變量裏

 

另外也能夠選擇手動安裝 create-umi 並執行

$ npm install create-umi -g $ create-umi

 

 

2、按需建立項目

選擇 app 建立一個 umi 應用

選擇是否使用 typeScript，默認不使用

而後使用空格鍵選擇須要的功能，功能介紹詳見 plugin/umi-plugin-react

這裏的 antd 和 dva 能夠不用選，只要建立項目後配置相應的插件，就能在項目中內置 antd、antd-mobile 和 dva

而後就會生成以下的項目

 如今可使用 yarn start 命令啓動項目了，在瀏覽器中訪問 http://localhost:8000 能夠查看預置頁面

 

 

3、配置插件

根目錄下的 .umirc.js 是整個應用的配置文件，上面提到的插件也能夠在這裏配置

配置項能夠寫在 .umirc.js 文件中，也能夠寫在 config/config.js 文件中，兩者只有一個生效 

完整的配置項能夠參考文檔，這裏介紹幾個比較實用的配置項：

1. proxy

const HOST_URL = '';
export default { proxy: { '/api': { target: HOST_URL, changeOrigin: true, pathRewrite: { '/api': '' }, }, }, }

 

2. theme

全局配置 less 變量（umi 項目默認使用 less）

export default { theme: { 'primary-color': '#3385ff', 'font-size-base': '14px', }, }

而後在 less 文件頂部引入

@import '~antd/lib/style/themes/default.less';

就能直接使用配置的 theme 變量了

 

3. routes

umi 會基於約定的 pages 目錄自動生成路由

若是更傾向於使用配置路由，能夠在配置文件中單獨配置 routes

export default { routes: [ { path: '/', component: './a' }, { path: '/list', component: './b', Routes: ['./routes/PrivateRoute.js'] }, { path: '/users', component: './users/_layout', routes: [ { path: '/users/detail', component: './users/detail' }, { path: '/users/:id', component: './users/id' } ] }, ], };

配置項中的 component 路徑是從 src/pages 目錄開始解析的

⚠️注意：routes 配置項存在時則不會對 src/pages 目錄作約定式的解析，即約定式路由沒法生效

 

4.alias

能夠配置 webpack 的 resolve.alias 屬性

alias: { '@': require('path').resolve(__dirname, './src'), '@components': require('path').resolve(__dirname, './src/components'), },

配置以後在 import 的時候可使用快捷路徑

另外根目錄下有一個 webpack.config.js，這裏也有配置 alias，但這裏的 alias 不會在項目中生效

 

 5.devServer

官方文檔上說能夠配置 devServer

但實際上直接配置 devServer 是無效的

 而圖上提到的 https、port 等須要使用 .env 文件來配置環境變量

BROWSER=none ESLINT=1 PORT=9000 // 自定義本地服務端口

這裏定義的系統環境變量在整個 umi-build-dev 的生命週期裏均可以被使用

 

 

4、約定目錄

umi 對於項目中的目錄有嚴格的約定，路由、model 都是基於目錄結構實現

. ├── dist/                          // 默認的 build 輸出目錄
├── mock/                          // mock 文件所在目錄，基於 express
├── config/ ├── config.js // umi 配置，同 .umirc.js，二選一
└── src/                           // 源碼目錄，可選
    ├── layouts/index.js           // 全局佈局 ├── pages/                     // 頁面目錄，裏面的文件即路由
        ├── .umi/                  // dev 臨時目錄，需添加到 .gitignore
        ├── .umi-production/       // build 臨時目錄，會自動刪除
        ├── document.ejs           // HTML 模板
        ├── 404.js                 // 404 頁面
        ├── page1.js               // 頁面 1，任意命名，導出 react 組件
        ├── page1.test.js          // 用例文件，umi test 會匹配全部 .test.js 和 .e2e.js 結尾的文件
        └── page2.js               // 頁面 2，任意命名
    ├── global.css                 // 約定的全局樣式文件，自動引入，也能夠用 global.less
    ├── global.js                  // 能夠在這裏加入 polyfill
    ├── app.js                     // 運行時配置文件
├── .umirc.js                      // umi 配置，同 config/config.js，二選一
├── .env                           // 環境變量
└── package.json

以上的目錄除了 pages 下面的自定義頁面文件之外，都不能夠重命名

若是須要給整個項目添加一個靜態 HTML 模版，能夠新建一個 src/pages/document.ejs 文件

但這個 document.ejs 文件必須包含  <div id="root"></div> 

 

5、路由與頁面跳轉

若是採用約定式路由，pages 目錄下的頁面須要嚴格遵照相關規範

具備 $ 前綴的頁面會被識別爲動態路由

pages/users/$id.js -> path: '/users/:id'

同時具有 $ 前綴和後綴的頁面會被識別爲可選的動態路由

pages/users/$id$.js -> path: '/users/:id?'

 

當目錄下存在 _layout.js 文件時，會以 _layout.js 做爲基礎頁面生成嵌套路由

+ pages/
  + users/
    - _layout.js - $id.js - index.js

以上的目錄結構會生成：

[ { path: '/users', component: './pages/users/_layout.js', routes: [ { path: '/users/', component: './pages/users/index.js' }, { path: '/users/:id', component: './pages/users/$id.js' }, ], }, ]

 

在頁面中能夠經過 umi/router 提供的 API 跳轉頁面

import router from 'umi/router'; function goToList() { router.push('/list'); }

或者使用 umi/link 做爲組件跳轉

import Link from 'umi/link'; export default () => ( <Link to="/list">Go to list page</Link>
);