Umi 小白纪实(一)—— 创建项目&常用配置

时间:2024-04-17 08:48:23

umi 是一个企业级 react 应用框架,也是蚂蚁金服的底层前端框架

《蚂蚁金服的前端框架和工程化实践》

 

一、安装脚手架

在创建项目之前,需要保证有 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

 

 

二、按需创建项目

选择 app 创建一个 umi 应用

选择是否使用 typeScript,默认不使用

然后使用空格键选择需要的功能,功能介绍详见 plugin/umi-plugin-react

这里的 antd 和 dva 可以不用选,只要创建项目后配置相应的插件,就能在项目中内置 antd、antd-mobile 和 dva

然后就会生成如下的项目

 现在可以使用 yarn start 命令启动项目了,在浏览器中访问 http://localhost:8000 可以查看预置页面

 

 

三、配置插件

根目录下的 .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 的生命周期里都可以被使用

 

 

四、约定目录

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> 

 

五、路由与页面跳转

如果采用约定式路由,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>
);