官方文档链接:
UmiJS官方文档
React官方文档
Ant Design官方文档
一、项目搭建
对于react umi项目搭建,umi官方文档已经写的很清晰了,具体请查看上面的umi官方文档链接。这里我不再详细说明,着重说明一些需要注意的地方。
-
首先,确认是否已安装node和umi,本文umi版本使用3.0版本。
$ node -v
$ umi -v -
可通过以下两种命令创建项目,但创建出来的项目umi版本不同
$ yarn create umi
说明:
使用此命令创建的项目,umi版本为2.x版本,如需使用3.x版本还需要手动升级,关于手动升级的操作umi官网也有详细步骤
除此之外,此命令可选择创建哪种项目,如需使用ant-design-pro框架可使用此法创建(如下图)$ yarn create @umijs/umi-app
说明:
此命令为umi官网提供的项目创建工具,创建完成umi项目即为3.x版本推荐使用
注意:以上两种创建方式都需要手动安装 antd
依赖,项目工程默认自带的是 @ant-design/pro-layout
,但pro-layout相关文档阅读体验不够好,个人比较推荐直接使用 antd
(使用ant-design-pro框架除外)
二、ESLint相关配置
umi项目的lint相关配置使用 @umijs/fabric
就已经足够了,运行过程中如果有什么依赖找不到直接yarn安装就行。
- 新增
.eslintrc.js、.eslintignore、.stylelintrc.js、.stylelintignore
配置文件
eslintrc.js
module.exports = {
extends: [require.resolve('@umijs/fabric/dist/eslint')],
rules: {
'no-unused-vars': 'warn',
'@typescript-eslint/no-unused-vars': 'warn'
},
}
.stylelintrc.js
module.exports = {
extends: [require.resolve('@umijs/fabric/dist/stylint')]
};
prettierrc相关配置使用项目创建时默认的就行,不用修改。
-
配置lint相关命令(仅供参考,可根据需求灵活配置)
"lint": "umi g tmp && yarn lint:js && yarn lint:style && yarn lint:prettier",
"lint:prettier": "prettier --check "/*" --end-of-line auto",
"lint:fix": "eslint --fix --cache --ext .js,.jsx,.ts,.tsx --format=pretty ./src && npm run lint:style",
"lint:js": "eslint --cache --ext .js,.jsx,.ts,.tsx --format=pretty ./src",
"lint:style": "stylelint --fix "src//*.less""
三、Umi项目配置
1. 两种配置方式(推荐config方式)
详见:https://umijs.org/zh-CN/docs/config
注意,使用config配置方式需注意config文件夹所在目录为根目录,不要配错到src目录之下了!
2. 两种路由配置方式(约定式路由与配置式路由)
详见:https://umijs.org/zh-CN/docs/convention-routing
注意:如需配置不在 /
根路由下的独立路由页面(如登录页),避免访问此独立页面时,此页面嵌入到了 layout
中,可通过配置式路由将独立页面放到根路由配置到上方,路由时首先匹配到了独立页面就不会继续匹配根路由下的子页面,从而避免出现独立页面嵌套 layout
的情况。
3. 两种 layout
布局方式
1)config配置layout(不推荐)
config/config.ts
import { defineConfig } from 'umi';
export default defineConfig({
title: '管理系统',
layout: { name: '这是菜单', locale: false }
routes: [
{
path: '/dashboard',
name: 'dashboard',
icon: 'dashboard',
},
...
]
})
配置好 layout
和路由后,按照路由创建对应页面组件即可
2) 在src目录下新增 layouts
布局文件夹配置(推荐)
在项目src目录创建 layouts
文件夹,项目运行时会自动读取此文件路径下的布局组件。
布局时,使用 @ant-design/pro-layout
或 antd
两种UI组件其中某一种皆可,我使用的是antd
组件库的布局组件。
4. 全局配置
1)全局样式
在src
文件夹下创建global.less
样式文件,此样式文件中设置的样式会全局生效,可将公共样式放到此文件中
2)入口html文件
在 src/pages
目录下创建document.ejs
文件,文件内容为html,此文件默认是umi的入口html文件,类似于Vue项目中public/index.html
文件
5. Umi的其他常用配置说明
1)devServer
如果你想像Vue中,在vue.config.js配置服务器端口号之类的信息可以使用devServer配置。
import { defineConfig } from 'umi';
export default defineConfig({
devServer: {
port: 3000,
}
})
2)chainWebpack
如果你想要修改webpack配置,或使用各种webpack插件,可通过此配置来实现
import { defineConfig } from 'umi';
import XXPlugin from 'xx-plugin'
export default defineConfig({
chainWebpack(config, { webpack }) {
config.plugin('XXPlugin').use(XXPlugin);
}
})
3) dynamicImport
启用按需加载
4)hash
如果配置了hash: true
, 会让dist目录下生成的文件包含 hash 后缀,如下logo.[hash字符].png
+ dist
- logo.sw892d.png
- umi.df723s.js
- umi.8sd8fw.css
- index.html
5)alias
Vue:
chainWebpack: (config) => {
config.entry('app').clear()
config.entry('app').add('./src/main.js')
config.resolve.alias
.set('@', resolve('src'))
.set('@utils', resolve('src/utils'))
.set('@assets', resolve('src/assets'))
}
Umi:
import { defineConfig } from 'umi';
export default defineConfig({
// 配置别名,对引用路径进行映射。
alias: {
'@utils': '/src/utils',
'@assets': '/src/assets'
}
})
6)history
可通过history配置哈希路由,注意不要和hash
配置混淆。
import { defineConfig } from 'umi';
export default defineConfig({
// 配置路由模式为hash模式,type可选 browser、hash 和 memory,默认browser
history: { type: 'hash' }
})
7) theme
如果想要定制不同主题,可通过theme
配置主题样式变量,变量为less
变量
// config.ts
import { defineConfig } from 'umi';
import theme from './theme';
export default defineConfig({
theme: theme
})
// theme.ts
export default {
'@headerColor': '#0099FF',
'@menuFontColor': '#001949',
};
8)cssLoader
若希望将 ClassName 类名变成驼峰命名形式,可设置
import { defineConfig } from 'umi';
export default defineConfig({
cssLoader: {
localsConvention: 'camelCase',
}
})
设置之后,在具体页面中,className会被解析成驼峰形式
import React from 'react';
import styles from './index.less'; // .bar-foo { font-size: 16px; }
export default () => <div className={styles.barFoo}>Hello</div>;
// => <div class="bar-foo___{hash}">Hello</div>
9)外部js
和css
文件引入
如果想要引入其他的外部css文件或js文件,如iconfont
字体文件等,可通过scripts
和styles
配置进行设置
import { defineConfig } from 'umi';
export default defineConfig({
scripts: ['//at.alicdn.com/t/font_XXXX.js', 'XXX.js'],
styles: ['//at.alicdn.com/t/font_XXXX.css', 'XXX.css'],
})
更多配置请参考官方文档配置说明:https://umijs.org/zh-CN/config
注意 :若你在项目中进行了静态化配置,你会发现你在通过路由访问页面的时候无法访问到对应的页面,需要加一个.html
后缀才能正常访问。如http://127.0.0.1/login
路由页面需要访问http://127.0.0.1/login.html
才能正常访问页面(坑~,初次配置的时候不小心加了这个配置,结果找了好久路由无法访问页面的问题!)
// 如果htmlSuffix为true,umi生成的路由文件会自动加上.html后缀
exportStatic: {
htmlSuffix: true
},
还有一点需要注意,如果你发现你的项目采用的是 history
模式,且部署到服务器上之后,刷新页面时路由地址会自动追加一个一个 /
,导致页面访问空白或重定向,但本地调试不会有问题,这也有可能是配置里配置了 exportStatic
的问题,需要注意的是,即使没有配置htmlSuffix
仅仅是空的 exportStatic: {}
配置也不行!
具体问题参考umi的github issues: 项目部署后,浏览器刷新后,url pathname尾部会多出一个 / #9140
四、项目目录结构(参考)
├── config
├── config.ts
├── dist
├── mock
├── public
└── src
├── .umi
├── api
├── assets
├── components
├── utils
├── layouts
├── index.less
└── index.tsx
├── pages
└── login
├── index.less
└── index.tsx
├── app.ts
└── global.less
├── .env
├── .editorconfig
├── .eslintrc.js
├── .eslintignore
├── .stylelintrc.js
├── .stylelintignore
├── tsconfig.json
├── package.json
├── README.md