Bruce Chen's Blog

quick notes

0%

React 开发之Umi乌米框架使用

发表于 分类于

以往搭建 React 应用时往往使用官方推荐的 # create-react-app 不过使用官方的脚手架往往不能很好的适应我们现有的项目，比如我们要集合 webpack 打包？我们要引入 Redux 状态管理器？Umi （乌米）框架应运而生。

让我们来看看官方的自我介绍：

umi 以路由为基础的，支持类 next.js 的约定式路由，以及各种进阶的路由功能，并以此进行功能扩展，比如支持路由级的按需加载。然后配以完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求，目前内外部加起来已有 50+ 的插件。

再让我们看看 Umi 的特色：

  • 📦 开箱即用，内置 react、react-router 等
  • 🏈 类 next.js 且功能完备的路由约定，同时支持配置的路由方式
  • 🎉 完善的插件体系，覆盖从源码到构建产物的每个生命周期
  • 🚀 高性能，通过插件支持 PWA、以路由为单元的 code splitting 等
  • 💈 支持静态页面导出，适配各种环境，比如中台业务、无线业务、egg、支付宝钱包、云凤蝶等
  • 🚄 开发启动快，支持一键开启 dll 等
  • 🐠 一键兼容到 IE9，基于 umi-plugin-polyfills
  • 🍁 完善的 TypeScript 支持，包括 d.ts 定义和 umi test
  • 🌴 与 dva 数据流的深入融合，支持 duck directory、model 的自动加载、code splitting 等等

一、搭建流程

现在我们自己手动搭建一套完整可用的 Umi 框架吧

第一步：环境检测及安装

首先需要 node, 并确保 node 版本是 8.10 或以上。（mac 下推荐使用 nvm 来管理 node 版本）
而包管理器，这里推荐使用 yarn 管理 npm 依赖

1.安装 yarn
可根据官网介绍选择安装方式 https://yarnpkg.com/zh-Hans/docs/install#windows-stable

2.全局安装 umi，并确保版本是 2.0.0 或以上。

1
$ yarn global add umi

第二步：通过脚手架创建项目

umi 通过 create-umi 提供脚手架能力

  1. 在需要生成项目的文件夹下，打开 CMD or 终端 命令行输入 yarn create umi
1
$ yarn create umi
  1. 选择需要生成的项目类型
1
2
3
4
5
6
? Select the boilerplate type (Use arrow keys)
  ant-design-pro  - Create project with an layout-only ant-design-pro boilerplate, use together with umi block.
❯ app             - Create project with a simple boilerplate, support typescript.
  block           - Create a umi block.
  library         - Create a library with umi.
  plugin          - Create a umi plugin.
  • app，通用项目脚手架，支持选择是否启用 TypeScript，以及 umi-plugin-react 包含的功能
  • ant-design-pro，仅包含 ant-design-pro 布局的脚手架，具体页面可通过 umi block 添加
  • block，区块脚手架
  • plugin，插件脚手架
  • library，依赖（组件）库脚手架，基于 umi-plugin-library
    在此我们 上下箭头切换到 app 并回车确定选择。
  1. 其他选项

此时会出现提示是否需要支持 Typescript, 可根据实际项目开发情况选择是否使用。

1
? Do you want to use typescript? (y/N)

选择 Typescript 支持后再选择你需要的功能（多选），功能介绍详见 plugin/umi-plugin-react。

1
2
3
4
5
? What functionality do you want to enable? (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ antd
 ◯ dva
 ◯ code splitting
 ◯ dll

同样按上下箭头移动，并按 空格 键选中需要的功能。
antd: UI 框架，启用后实现 antd, antd-mobile 和 antd-pro 的按需编译，无需要手动配置。
dva: 基于 redux 和 redux-saga 的数据流方案，然后为了简化开发体验，dva 还额外内置了 react-router 和 fetch，所以也可以理解为一个轻量级的应用框架
code splitting: 是否代码分包
dll: 通过 webpack 的 dll 插件预打包一份 dll 文件来达到二次启动提速的目的
注意 此处多选项未选择，后期也可以在配置文件中配置。

确定后，会根据你的选择自动创建好目录和文件。

第三步：运行及编译

安装依赖

1
$ yarn

启动项目

1
$ yarn start

这样我们就可以愉快的开发和调试了。

当我们开发好要编译项目发布测试 or 生产时，执行：

1
$ yarn build

二、目录结构说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
.
├── dist/ // 默认的 build 输出目录
├── mock/ // mock 文件所在目录，基于 express
├── config/
├── config.js // umi 配置，同 .umirc.js，二选一， 建议配置.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

三、开发提示

.umirc.js 配置，
该文件中可以配置项目基本情况，如上面安装步骤中出现是否选用 antd, dva 等，在此文件中都可以更改为 true, 另外还可以配置 webpack 打包配置，具体的配置项详见.umirc.js 配置。

设置.umirc.local.js 文件
由于.umirc 里的配置众多而且为了优化项目必然会分包代码抽离等，而在本地运行时无需这些，便可配置.umirc.local.js 文件，注意此文件中的选项配置和.umirc.js 配置一样，不要提交到 git，所以通常需要配置到 .gitignore。本地运行时会和 .umirc.js 合并后再返回。

由于 umi 会根据 pages 目录自动生成路由配置，所以无需要手动配置路由，会根据 src / pages 下 文件名自动生成路由，但是你也可以配置.umirc.js 中的 routes 属性，此配置项存在时则不会对 src/pages 目录做约定式的解析。

常用路由操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import React, { PureComponent } from 'react';
import Link from 'umi/link';
import router from 'umi/router';

class Examples extends PureComponent {
    render () {
        return (
            <>
                {/* 普通使用 */}
                <Link to="/list">跳转</Link>

                {/* 带参数 */}
                <Link to="/list?a=b">跳转</Link>

                {/* 包含子组件 */}
                <Link to="/list?a=b"><button>跳转</button></Link>

                {/* 点击跳转 */}
                <button onClick={() => router.push('/list')}>跳转</button>
            </>
        )
    }
}
export default Examples;

更多查看路由配置

四、总结

umi 框架为我们开发项目提升了效率，而其本身也在不断的升级完善中，在 2.8.0+版本，umi 可配置 ssr 服务器端渲染，相信 umi 还将越来越完善。
更多查看官方文档 https://umijs.org/