编者按：Change the code, don't Workaround! Webpack
慢就去改他，优化到位后，Bundle 也可以很快。此方案会在 Umi 4
中默认开启，适用于既要 Webpack 功能与生态，又想要 Vite 速度的同学们。
Umi 4 中同时支持 webpack 和 vite 两种构建方式，跑通了后，迫不及待对比了 Vite 和 Webpack + MFSU 的效果，结果有点意外。关于什么是 MFSU，我在[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)中有一段详细介绍。
两个示例、四种模式、四个维度的对比。
两个示例分别是大型的全量 ant-design-pro 和小型的 libs example；四种模式分别是 webpack、webpack + MFSU、webpack + MFSU with esbuild mode、Vite in umi；四个维度分别是无缓存的冷启动、有缓存的热启动、修改代码后的热更新、页面打开速度。
多说几点和统计相关的。上述 webpack 相关模式全部开启物理缓存；Vite 是 Umi 中集成后的 Vite，也有担心是不是 Umi 对于 Vite 的误用，经开发者确认，基本排除误用的可能性，大段时间消耗在预编译依赖上；Ant Design Pro 中包含 less 的使用，这是使用 esbuild 无法加速的部分，这有影响，但对于不同模式应该是公平的；下图数据是本地用 13-inch M1 2022 重启电脑后跑 5 次后平均取值的结果；Vite 的热更速度没统计是因为由于 esm 的特性，改完后要等请求过来后处理完才算结束，无法统计，但肯定是很快的。
直接上结果。有兴趣手动验证的同学可到 umijs/umi 仓库的不同 example 目录下执行 npm run dev 验证。
图：全量 ant-design-pro 速度对比图
图：libs example 速度对比图
可以看到，**在这几个场景下，MFSU with esbuild 数据领先。** 四个模式的页面打开速度差不多，所以对比数据没在图中列出，这也是让我意外的点，原以为 Vite 请求多会让页面打开速度变慢，也有可能项目还不够复杂？
---
### Docs Blog Mfsu Faster Than Vite (`docs/docs/blog/mfsu-faster-than-vite.md`)
---
order: 3
toc: content
group:
title: Blog
---
# 比 Vite 还快的 MFSU
编者按：Change the code, don't Workaround! Webpack
慢就去改他，优化到位后，Bundle 也可以很快。此方案会在 Umi 4
中默认开启，适用于既要 Webpack 功能与生态，又想要 Vite 速度的同学们。
Umi 4 中同时支持 webpack 和 vite 两种构建方式，跑通了后，迫不及待对比了 Vite 和 Webpack + MFSU 的效果，结果有点意外。关于什么是 MFSU，我在[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)中有一段详细介绍。
两个示例、四种模式、四个维度的对比。
两个示例分别是大型的全量 ant-design-pro 和小型的 libs example；四种模式分别是 webpack、webpack + MFSU、webpack + MFSU with esbuild mode、Vite in umi；四个维度分别是无缓存的冷启动、有缓存的热启动、修改代码后的热更新、页面打开速度。
多说几点和统计相关的。上述 webpack 相关模式全部开启物理缓存；Vite 是 Umi 中集成后的 Vite，也有担心是不是 Umi 对于 Vite 的误用，经开发者确认，基本排除误用的可能性，大段时间消耗在预编译依赖上；Ant Design Pro 中包含 less 的使用，这是使用 esbuild 无法加速的部分，这有影响，但对于不同模式应该是公平的；下图数据是本地用 13-inch M1 2022 重启电脑后跑 5 次后平均取值的结果；Vite 的热更速度没统计是因为由于 esm 的特性，改完后要等请求过来后处理完才算结束，无法统计，但肯定是很快的。
直接上结果。有兴趣手动验证的同学可到 umijs/umi 仓库的不同 example 目录下执行 npm run dev 验证。
以上是 Umi 4 目前的新功能。
除此之外，还有一些计划在正式版发布之前做的事情。包括 api route、umi server and adapter、route loader、稳定的 lint、更多命令、组件研发 father 4、文档工具 dumi 2 等，会在之后的 RC 版本中与大家见面。
欢迎大家尝鲜 Umi 4，官方文档有准备 ant-design-pro 从 Umi 3 到 4 的升级文档。同时 RC 阶段，还准备了一个手把手升级的微信交流群，欢迎 Umi 4 的先行者们加入，祝大家升级顺利，也提前祝大家新年快乐 🧨，🐯 年吉祥。
---
### Docs Blog Webpack 5 Prod Cache.En US (`docs/docs/blog/webpack-5-prod-cache.en-US.md`)
---
toc: content
order: 7
group:
title: Blog
---
# 物理构建缓存
在 `umi build` 构建生产环境产物时，Umi 4 默认没有配置 webpack 5 的物理缓存，这是因为 webpack 的物理缓存失效时机问题，需要依赖用户项目的实际情况，所以没有很好的通用解决方案。
所以，当你不明确哪些依赖会让项目物理缓存失效时，很容易产生构建缓存不失效，导致产物是旧的问题，极大影响研发效率。
## 缓存场景
当你的项目需要构建缓存时，是有原因的，我们粗略把场景分成两类：普通项目、Monorepo 中的项目。
### 普通项目
构建比较慢，如何复用上次的物理缓存，做到多次构建提速？
#### 首选解决思路
此时首选的优化思路应该是：考虑使用其他更快的现代转译器，比如调整 [`srcTranspiler`](../docs/api/config#srctranspiler) 、[`cssMinifier`](../docs/api/config#cssminifier) 。
#### CI 中的问题
物理缓存一般存在于 `node_modules/.cache` ，这就意味着如果你在 CI 中构建，构建的基建必须要支持恢复上次的缓存文件，如果构建容器不支持恢复缓存，同样也无法享受好处。
#### 选择依据
所以，当你：
1. **多次构建**：确实有多次反复构建的需求。
2. **能恢复缓存**：在本地构建，或在 CI 有手段能恢复上次的物理缓存文件。
3. **时间长**：项目构建时间比较长、开启其他转译器仍无法提速（或有强诉求无法切换转译器）。
满足这些条件后，你才应该考虑开启物理缓存。
#### 配置方法
```ts
// .umirc.ts
import { join } from 'path';
import { defineConfig } from 'umi';
import { createHash } from 'crypto';
export default defineConfig({
chainWebpack(config, { env }) {
if (env === 'production') {
config.cache({
type: 'filesystem',
store: 'pack',
// 🟡 假如你的项目在 CI 中构建每次环境变量都不一样，请挑选或者排除
version: createEnvironmentHash(process.env),
buildDependencies: {
config: [__filename],
tsconfig: [join(__dirname, 'tsconfig.json')],
packagejson: [join(__dirname, 'package.json')],
umirc: [join(__dirname, '.umirc.ts')],
// 🟡 其他可能会影响项目的配置文件路径，其内容变更会使缓存失效
},
});
}
},
});
function createEnvironmentHash(env: Record) {
const hash = createHash('md5');
hash.update(JSON.stringify(env));
const result = hash.digest('hex');
return result;
}
```
请格外注意：
1. 你的项目有哪些文件、依赖会影响项目，配置他们作为依赖，变更时可以使得缓存失效。
2. 因为 `process.env` 包括了所有的 nodejs 环境变量，这非常多，如果环境变量在 CI 中每次构建都存在差异，请挑选所需的环境变量，或者排除掉会变化的。
```ts
// 如挑选可能会影响项目内容的环境变量
createEnvironmentHash({
NODE_ENV: process.env.NODE_ENV,
// ...
});
```
### Monorepo 中的项目
在 monorepo 中，如何缓存需要前置构建的其他子包，比如构建 `apps/project-umi` 需要先构建好他依赖的子包 `libs/component` ，但是下次 `libs/component` 没有代码改动，如何跳过这部分前置依赖的构建？
此时推荐你使用 [Turborepo](https://turbo.build/repo) 来做 monorepo 构建方案，具体使用方法请参见 [官方文档](https://turbo.build/repo/docs) 和 [examples](https://github.com/vercel/turbo/tree/main/examples) 。
注：如果在 CI 中构建，同样需要容器支持恢复上次的 turbo 缓存，可以通过 [`--cache-dir`](https://turbo.build/repo/docs/reference/command-line-reference#--cache-dir) 选项更改缓存位置。
---
### Docs Blog Webpack 5 Prod Cache (`docs/docs/blog/webpack-5-prod-cache.md`)
---
toc: content
order: 7
group:
title: Blog
---
# 物理构建缓存
在 `umi build` 构建生产环境产物时，Umi 4 默认没有配置 webpack 5 的物理缓存，这是因为 webpack 的物理缓存失效时机问题，需要依赖用户项目的实际情况，所以没有很好的通用解决方案。
所以，当你不明确哪些依赖会让项目物理缓存失效时，很容易产生构建缓存不失效，导致产物是旧的问题，极大影响研发效率。
## 缓存场景
当你的项目需要构建缓存时，是有原因的，我们粗略把场景分成两类：普通项目、Monorepo 中的项目。
### 普通项目
构建比较慢，如何复用上次的物理缓存，做到多次构建提速？
#### 首选解决思路
此时首选的优化思路应该是：考虑使用其他更快的现代转译器，比如调整 [`srcTranspiler`](../docs/api/config#srctranspiler) 、[`cssMinifier`](../docs/api/config#cssminifier) 。
#### CI 中的问题
物理缓存一般存在于 `node_modules/.cache` ，这就意味着如果你在 CI 中构建，构建的基建必须要支持恢复上次的缓存文件，如果构建容器不支持恢复缓存，同样也无法享受好处。
#### 选择依据
所以，当你：
1. **多次构建**：确实有多次反复构建的需求。
2. **能恢复缓存**：在本地构建，或在 CI 有手段能恢复上次的物理缓存文件。
3. **时间长**：项目构建时间比较长、开启其他转译器仍无法提速（或有强诉求无法切换转译器）。
满足这些条件后，你才应该考虑开启物理缓存。
#### 配置方法
```ts
// .umirc.ts
import { join } from 'path';
import { defineConfig } from 'umi';
import { createHash } from 'crypto';
export default defineConfig({
chainWebpack(config, { env }) {
if (env === 'production') {
config.cache({
type: 'filesystem',
store: 'pack',
// 🟡 假如你的项目在 CI 中构建每次环境变量都不一样，请挑选或者排除
version: createEnvironmentHash(process.env),
buildDependencies: {
config: [__filename],
tsconfig: [join(__dirname, 'tsconfig.json')],
packagejson: [join(__dirname, 'package.json')],
umirc: [join(__dirname, '.umirc.ts')],
// 🟡 其他可能会影响项目的配置文件路径，其内容变更会使缓存失效
},
});
}
},
});
function createEnvironmentHash(env: Record) {
const hash = createHash('md5');
hash.update(JSON.stringify(env));
const result = hash.digest('hex');
return result;
}
```
请格外注意：
1. 你的项目有哪些文件、依赖会影响项目，配置他们作为依赖，变更时可以使得缓存失效。
2. 因为 `process.env` 包括了所有的 nodejs 环境变量，这非常多，如果环境变量在 CI 中每次构建都存在差异，请挑选所需的环境变量，或者排除掉会变化的。
```ts
// 如挑选可能会影响项目内容的环境变量
createEnvironmentHash({
NODE_ENV: process.env.NODE_ENV,
// ...
});
```
### Monorepo 中的项目
在 monorepo 中，如何缓存需要前置构建的其他子包，比如构建 `apps/project-umi` 需要先构建好他依赖的子包 `libs/component` ，但是下次 `libs/component` 没有代码改动，如何跳过这部分前置依赖的构建？
此时推荐你使用 [Turborepo](https://turbo.build/repo) 来做 monorepo 构建方案，具体使用方法请参见 [官方文档](https://turbo.build/repo/docs) 和 [examples](https://github.com/vercel/turbo/tree/main/examples) 。
注：如果在 CI 中构建，同样需要容器支持恢复上次的 turbo 缓存，可以通过 [`--cache-dir`](https://turbo.build/repo/docs/reference/command-line-reference#--cache-dir) 选项更改缓存位置。
---
### Docs Docs Api Api.En US (`docs/docs/docs/api/api.en-US.md`)
---
order: 1
toc: content
translated_at: '2024-03-17T10:47:17.550Z'
---
# API
For ease of search, the following content is sorted alphabetically.
## umi
### createBrowserHistory
Creates a `BrowserHistory` that uses the browser's built-in `history` to track application navigation. It is recommended for use in modern web browsers that support the HTML5 `history` API.
Type definition is as follows:
```ts
function createBrowserHistory(options?: { window?: Window }) => BrowserHistory;
```
Usage example:
```ts
// create a BrowserHistory
import { createBrowserHistory } from 'umi';
const history = createBrowserHistory();
// or a iframe BrowserHistory
import { createBrowserHistory } from 'umi';
const history = createBrowserHistory({
window: iframe.contentWindow,
});
```
### createHashHistory
`createHashHistory` returns a `HashHistory` instance. The default `window` is the current document's `defaultView`.
The main difference between `HashHistory` and `BrowserHistory` is that `HashHistory` stores the current location in the hash part of the URL, which means it does not send a request to the server when switching routes. If you are hosting your site on a server that you cannot fully control, or in a single-page Electron application, `HashHistory` is recommended.
Usage example:
```ts
// create a HashHistory
import { createHashHistory } from 'umi';
const history = createHashHistory();
```
### createMemoryHistory
`MemoryHistory` is not operated or read from the address bar. It is also very suitable for testing and other rendering environments.
```ts
const history = createMemoryHistory(location)
```
### createSearchParams
A utility function that wraps `new URLSearchParams(init)`, supports creating with arrays and objects
```ts
import { createSearchParams } from 'umi';
// Assuming the path http://a.com?foo=1&bar=2
createSearchParams(location.search);
createSearchParams("foo=1&bar=2");
createSearchParams("?foo=1&bar=2");
// Key-value pair object
createSearchParams({ foo: 'bar', qux: 'qoo'}).toString()
// foo=bar&qux=qoo
// Key-value tuple array
createSearchParams([["foo", "1"], ["bar", "2"]]).toString()
// foo=1&bar=2
```
[URLSearchParams documentation](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams)
### generatePath
Generates the actual route to be accessed using the given path with parameters and the corresponding params.
```ts
import { generatePath } from 'umi';
generatePath("/users/:id", { id: "42" }); // "/users/42"
generatePath("/files/:type/*", {
type: "img",
"*": "cat.jpg",
}); // "/files/img/cat.jpg"
```
### Helmet
The Helmet component provided by [react-helmet-async](https://github.com/staylor/react-helmet-async), used to dynamically configure tags in the `head` of the page, such as the `title`.
> Note: To ensure Helmet still works during SSR, be sure to use the Helmet provided by Umi instead of installing react-helmet separately
```tsx
import { Helmet } from 'umi';
export default function Page() {
return (
Hello World
);
}
```
### history
Operations related to history, used to obtain current route information, execute route jumps, and listen for route changes.
```ts
// Recommended to use useLocation in components or hooks
import { useLocation } from 'umi';
export default function Page() {
let location = useLocation();
return (
;
}
```
Umi 也同时提供了对 `.styl` 和 `.stylus` 文件的内置支持。使用前必须安装 `stylus` 相应的预处理器依赖，其他用法用上面的例子
```bash
# .styl and .stylus
npm add -D stylus
```
## 进阶设置
如果你需要使用除了常见的 LESS, SASS 或 SCSS 以外的其他样式预处理器，你可以透过 Umi
插件提供的 [chainWebpack 接口](../api/config#chainwebpack)来加入自己需要的 Loader。
## 使用 Tailwindcss
Umi 提供了内置的 [Tailwindcss](https://tailwindcss.com/)
插件，并且可以直接方便地使用 [微生成器](./generator#tailwind-css-配置生成器) 来启用。
## 使用 UnoCSS
与 Tailwindcss 相同，Umi 也提供了内置的 [UnoCSS](https://github.com/unocss/unocss) 插件，可以按照相同方式开启。
1. 安装 `plugin-unocss`
2. 安装 `unocss` 及 `@unocss/cli`
```bash
pnpm i unocss @unocss/cli
```
3. 在 Umi 设置中启用插件，并声明会用到 `unocss` 的文件目录
```js
// .umirc.ts
export default {
plugins: [
require.resolve('@umijs/plugins/dist/unocss')
],
unocss: {
// 检测 className 的文件范围，若项目不包含 src 目录，可使用 `pages/**/*.tsx`
watch: ['src/**/*.tsx']
},
};
```
4. 在项目目录下加入 `unocss.config.ts`
配置文件，并加入项目需要的 [UnoCSS Presets](https://github.com/unocss/unocss#presets)
```js
// unocss.config.ts
import {defineConfig, presetAttributify, presetUno} from 'unocss';
export function createConfig({strict = true, dev = true} = {}) {
return defineConfig({
envMode: dev ? 'dev' : 'build', presets: [presetAttributify({strict}), presetUno()],
});
}
export default createConfig();
```
5. 启动项目进行开发，插件会监听设置文件中的 `unocss.watch` 字段，动态生成样式文件并自动套用
---
### Docs Docs Guides Test.En US (`docs/docs/docs/guides/test.en-US.md`)
---
order: 15
toc: content
translated_at: '2024-03-17T10:00:43.176Z'
---
# Testing
Automated testing is an effective means to ensure quality, and Umi 4 provides scaffolding for unit testing. Umi 4 recommends using [Jest](https://jestjs.io/) and [@testing-library/react](https://github.com/testing-library/react-testing-library) to complete the unit tests in your project.
## Configuration
Quickly configure Jest using Umi 4's micro-generator [reference](./generator#jest-configurator), and if you need to modify the Jest related configuration, you can do so in `jest.config.ts`.
Umi project
```ts
import { Config, configUmiAlias, createConfig } from 'umi/test';
export default async () => {
return (await configUmiAlias({
...createConfig({
target: 'browser',
jsTransformer: 'esbuild',
jsTransformerOpts: { jsx: 'automatic' },
}),
// Override the default Jest configuration of Umi, such as
// displayName: "Umi jest",
})) as Config.InitialOptions;
};
```
@umijs/max project
```ts
import { Config, configUmiAlias, createConfig } from '@umijs/max/test';
export default async () => {
return (await configUmiAlias({
...createConfig({
target: 'browser',
jsTransformer: 'esbuild',
jsTransformerOpts: { jsx: 'automatic' },
}),
// Override the default Jest configuration of Umi, such as
// displayName: "Umi jest",
})) as Config.InitialOptions;
};
```
After configuration, you can start writing unit tests.
## Non-UI Related Tests
Suppose we need to test a utils function `reverseApiData` that swaps the keys and values of the `data` object from an API request's result.
It's recommended to place the test file in the same directory as the module being tested for easy review and understanding of the module's functionality.
```txt
.
└── utils
├── reverseApiData.test.ts
└── reverseApiData.ts
```
```ts
// utils/reverseApiData.ts
export async function reverseApiData(url: string, fetcher = fetch) {
const res = await fetcher(url);
const json = await res.json();
const { data = {} } = json;
const reversed: Record = {};
for (const key of Object.keys(data)) {
const val = data[key];
reversed[val] = key;
}
return reversed;
}
```
First, let's write our first test case to ensure `fetcher` uses the passed `url` to request API data
```ts
import { reverseApiData } from './reverseApiData';
// The test case name indicates the purpose of the test
test('reverseApiData use fetcher to request url', async () => {
// Test cases are written in the structure of 3A
// Arrange stage, prepare mock functions or data
const fetcher = jest.fn().mockResolvedValue({
json: () => Promise.resolve(),
});
// Act on the object under test
await reverseApiData('https://api.end/point', fetcher);
// Assert the test result
expect(fetcher).toBeCalledWith('https://api.end/point');
});
```
Run the tests
```bash
$npx jest
info - generate files
PASS src/utils/reverseApiData.test.ts
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 0.894 s, estimated 1 s
Ran all test suites.
```
:::info{title=💡}
You can use `npx jest --watch` to keep the Jest process alive, saving you the wait time to start Jest again.
:::
Let's write another case to test the utility function's ability to reverse key-value pairs.
```ts
test('reverseApiData reverse simple object', async () => {
const fetcher = jest.fn().mockResolvedValue({
json: () => Promise.resolve({ data: { a: 'b' } }),
});
const reversed = await reverseApiData('url', fetcher);
expect(reversed).toEqual({ b: 'a' });
});
```
Having each test case focus on one aspect of functionality can give us more accurate feedback during refactoring, such as what functionality a change has broken. Please refer to more cases [code](https://github.com/umijs/umi/tree/master/examples/test-test/utils/reverseApiData.test.ts).
## UI Testing
For component and UI-related testing, the use of `@testing-library/react` is recommended.
### Judging the Rendering Result
- Using Jest's snapshot
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
import { render } from '@testing-library/react';
import React from 'react';
import Greet from './Greet';
test('renders Greet without name by snapshot', () => {
const { container } = render();
expect(container).toMatchSnapshot();
});
```
After running `npx jest`, a `__snapshots__` folder and the snapshot of the test case will be generated in the directory alongside the test cases. Please add them to version control.
- Using Jest's inline snapshot
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
test('renders Greet without name by inline snapshot', () => {
const { container } = render();
expect(container).toMatchInlineSnapshot();
});
```
After running `npx jest`, the snapshot string will be filled in the parameters of the `toMatchInlineSnapshot` function. This method is suitable for short rendering results.
- Using @testing-library/jest-dom assertions
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
import '@testing-library/jest-dom';
test('renders Greet without name assert by testing-library', () => {
const { container } = render();
const greetDom = screen.getByText('Anonymous');
expect(greetDom).toBeInTheDocument();
});
```
For more [assertion APIs](https://github.com/testing-library/jest-dom)
### Judging Component Behavior
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
test('Greet click', async () => {
const onClick = jest.fn();
const { container } = render();
const greetDom = screen.getByText('Anonymous');
await fireEvent.click(screen.getByText(/hello/i));
expect(onClick).toBeCalledTimes(1);
});
```
---
### Docs Docs Guides Test (`docs/docs/docs/guides/test.md`)
---
order: 15
toc: content
---
# 测试
自动化测试是保障质量的有效手段，Umi 4 提供单元测试的脚手架。Umi 4 推荐使用 [Jest](https://jestjs.io/) 和 [@testing-library/react](https://github.com/testing-library/react-testing-library) 来完成项目中的单元测试。
## 配置
使用 Umi 4 的微生成器快速地配置好 Jest [参考](./generator#jest-配置生成器)，如果你需要修改 jest 相关的配置，可以在 `jest.config.ts` 修改。
umi 项目
```ts
import { Config, configUmiAlias, createConfig } from 'umi/test';
export default async () => {
return (await configUmiAlias({
...createConfig({
target: 'browser',
jsTransformer: 'esbuild',
jsTransformerOpts: { jsx: 'automatic' },
}),
// 覆盖 umi 的默认 jest 配置, 如
// displayName: "Umi jest",
})) as Config.InitialOptions;
};
```
@umijs/max 项目
```ts
import { Config, configUmiAlias, createConfig } from '@umijs/max/test';
export default async () => {
return (await configUmiAlias({
...createConfig({
target: 'browser',
jsTransformer: 'esbuild',
jsTransformerOpts: { jsx: 'automatic' },
}),
// 覆盖 umi 的默认 jest 配置, 如
// displayName: "Umi jest",
})) as Config.InitialOptions;
};
```
配置完后，就可以开始编写单元测试了。
## 与 UI 无关的测试
假设我们需要测试一个 utils 函数 `reverseApiData`, 它将 api 请求的结果 `data` 对象的 key 和 value 互换。
我们推荐将测试文件和被测模块放在同一级目录，这样可以方便查看测试文件以便理解模块的功能。
```txt
.
└── utils
├── reverseApiData.test.ts
└── reverseApiData.ts
```
```ts
// utils/reverseApiData.ts
export async function reverseApiData(url: string, fetcher = fetch) {
const res = await fetcher(url);
const json = await res.json();
const { data = {} } = json;
const reversed: Record = {};
for (const key of Object.keys(data)) {
const val = data[key];
reversed[val] = key;
}
return reversed;
}
```
先来写我们第一个测试用例, 确保 `fetcher` 使用传入的 `url` 请求 api 的数据
```ts
import { reverseApiData } from './reverseApiData';
// 测试用例名字表明测试的目的
test('reverseApiData use fetcher to request url', async () => {
// 测试用例以 3A 的结构来写
// Arrange 准备阶段，准备 mock 函数或者数据
const fetcher = jest.fn().mockResolvedValue({
json: () => Promise.resolve(),
});
// Act 执行被测对象
await reverseApiData('https://api.end/point', fetcher);
// Assert 断言测试结果
expect(fetcher).toBeCalledWith('https://api.end/point');
});
```
执行测试
```bash
$npx jest
info - generate files
PASS src/utils/reverseApiData.test.ts
Test Suites: 1 passed, 1 total
Tests: 1 passed, 1 total
Snapshots: 0 total
Time: 0.894 s, estimated 1 s
Ran all test suites.
```
:::info{title=💡}
可以使用`npx jest --watch` 让 jest 进程不退出，这样能省去启动重新 jest 的等待时间。
:::
我们再写一个用例来测试这个工具函数完成了键值的对换功能。
```ts
test('reverseApiData reverse simple object', async () => {
const fetcher = jest.fn().mockResolvedValue({
json: () => Promise.resolve({ data: { a: 'b' } }),
});
const reversed = await reverseApiData('url', fetcher);
expect(reversed).toEqual({ b: 'a' });
});
```
让每个测试用例只关注一个功能点，可以让用例在重构的时候给我们更准确的反馈，例如改动破坏了什么功能。更多的用例请参考 [代码](https://github.com/umijs/umi/tree/master/examples/test-test/utils/reverseApiData.test.ts)。
## UI 测试
组件和 UI 相关的测试推荐使用 `@testing-library/react`。
### 渲染结果判断
- 使用 jest 的 snapshot
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
import { render } from '@testing-library/react';
import React from 'react';
import Greet from './Greet';
test('renders Greet without name by snapshot', () => {
const { container } = render();
expect(container).toMatchSnapshot();
});
```
执行 `npx jest` 后会在测试用例同级目录会生成 `__snapshots__` 文件夹和用例的 snapshot，请加入到版本管理中。
- 使用 jest 的 inline snapshot
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
test('renders Greet without name by inline snapshot', () => {
const { container } = render();
expect(container).toMatchInlineSnapshot();
});
```
执行 `npx jest` 后会在 `toMatchInlineSnapshot` 函数的参数中填入 snapshot 字符串；这种方式适合渲染结果比较短的内容。
- 使用 @testing-library/jest-dom 断言
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
import '@testing-library/jest-dom';
test('renders Greet without name assert by testing-library', () => {
const { container } = render();
const greetDom = screen.getByText('Anonymous');
expect(greetDom).toBeInTheDocument();
});
```
更多[断言 API](https://github.com/testing-library/jest-dom)
### 组件行为判断
```tsx
// examples/test-test/components/Greet/Greet.test.tsx
test('Greet click', async () => {
const onClick = jest.fn();
const { container } = render();
const greetDom = screen.getByText('Anonymous');
await fireEvent.click(screen.getByText(/hello/i));
expect(onClick).toBeCalledTimes(1);
});
```
---
### Docs Docs Guides Typescript.En US (`docs/docs/docs/guides/typescript.en-US.md`)
---
order: 9
toc: content
translated_at: '2024-03-17T09:59:29.526Z'
---
# TypeScript
Umi enables TypeScript by default. If the project is created using the official scaffolding, the built-in files are mainly in the format of `xx.(ts|tsx)`.
## TypeScript Hints in Configuration
If you want to have TypeScript syntax hints during configuration, you can wrap the configuration with `defineConfig()`:
```ts
// .umirc.ts
import { defineConfig } from 'umi';
export default defineConfig({
routes: [
{ path: '/', component: '@/pages/index' },
],
});
```
---
### Docs Docs Guides Typescript (`docs/docs/docs/guides/typescript.md`)
---
order: 9
toc: content
---
# TypeScript
Umi 默认开启 TypeScript，如果是使用官方脚手架创建项目，内置的文件是以 `xx.(ts|tsx)` 为主的。
## 配置中的 TypeScript 提示
如果想要在配置时拥有 TypeScript 语法提示，可以在配置的地方包一层 `defineConfig()`：
```ts
// .umirc.ts
import { defineConfig } from 'umi';
export default defineConfig({
routes: [
{ path: '/', component: '@/pages/index' },
],
});
```
---
### Docs Docs Guides Use Plugins.En US (`docs/docs/docs/guides/use-plugins.en-US.md`)
---
order: 4
toc: content
translated_at: '2024-03-17T09:58:19.770Z'
---
# Plugins
## Using Plugins
In a standard Umi application, by default, **no plugins are included**. If you want to use Max's features (such as data flow, antd, etc.), you will need to manually install the plugins and enable them:
```bash
pnpm add -D @umijs/plugins
```
To enable the antd plugin:
```ts
// .umirc.ts
export default {
plugins: ['@umijs/plugins/dist/antd'],
antd: {}
}
```
The difference between Umi and Max is that Max already has most plugins built-in, such as data flow (`initial-state`, `model`), `antd`, etc. These plugins can be loaded and enabled from `@umijs/plugins/dist/*`.
For further information about the features and configuration instructions offered by Max, please refer to the [Umi Max](../max/introduce) section.
:::info{title=💡}
**Should I choose Max?**
Using Max does not mean you have to use all of its features; you can disable plugins according to your needs. So, when you need Max's features, you can always choose to create a Max project.
:::
## Project-level Plugins
If you want to quickly use the functionality of plugins in your project (such as [modifying the output html](../introduce/faq#documentejs-where-did-it-got-how-to-customize-the-html-template)), you can create a `plugin.ts` in the project's root directory to write a project-level plugin, which will be automatically loaded as a plugin.
For a more detailed explanation of the directory structure, please refer to the [Directory Structure](./directory-structure) section.
## Developing Plugins
Please refer to the [Developing Plugins](./plugins) section.
---
### Docs Docs Guides Use Plugins (`docs/docs/docs/guides/use-plugins.md`)
---
order: 4
toc: content
---
# 插件
## 使用插件
在普通的 Umi 应用中，默认 **不附带任何插件** ，如需使用 Max 的功能（如 数据流、antd 等），需要手动安装插件并开启他们：
```bash
pnpm add -D @umijs/plugins
```
如开启 antd 插件：
```ts
// .umirc.ts
export default {
plugins: ['@umijs/plugins/dist/antd'],
antd: {}
}
```
Umi 与 Max 的区别是 Max 已经内置了大部分插件，如 数据流（ `initial-state` 、 `model` ）、`antd` 等，这些插件都可以在 `@umijs/plugins/dist/*` 加载并且开启。
如需进一步了解 Max 具备的功能和配置说明，请参阅 [Umi Max](../max/introduce) 章节。
:::info{title=💡}
**我是否应该选择 Max ？**
使用 Max 并不代表需要使用全部 Max 的功能，可以根据需求关闭插件，所以当你需要使用 Max 的功能时，可以总是选择创建 Max 项目。
:::
## 项目级插件
若你想在项目中快速使用插件的功能（如 [修改产物的 html](../introduce/faq#documentejs-去哪了如何自定义-html-模板) ），可以在项目的根目录创建 `plugin.ts` 编写一个项目级插件，该文件将被自动作为插件加载。
有关更详细的目录结构说明请参阅 [目录结构](./directory-structure) 章节。
## 开发插件
请参阅 [开发插件](./plugins) 章节。
---
### Docs Docs Guides Use Vue.En US (`docs/docs/docs/guides/use-vue.en-US.md`)
---
order: 17
toc: content
translated_at: '2024-03-17T09:57:48.935Z'
---
# Using Vue
This article introduces how to use Vue in Umi, where most of the configuration for Umi Vue is the same as React. Here we only list some configurations unique to Vue.
## How to Start
### Installation
```bash
pnpm add @umijs/preset-vue -D
```
### Configure Preset
```ts
// In .umirc.ts or config/config.ts
export default {
presets: [require.resolve('@umijs/preset-vue')],
};
```
## Routing
### Config-based Routing
:::info
Here, we only list the parts that are different from React router configuration.
:::
#### name
Named routes
In addition to `path`, you can provide a `name` for any route:
```ts
export default {
routes: [
{
path: '/user/:username',
name: 'user',
component: 'index'
}
]
}
```
To link to a named route, you can pass an object to the `to` property of the `router-link` component:
```html
User
```
The effect is the same as imperatively calling `router.push`:
```ts
router.push({ name: 'user', params: { username: 'erina' } })
```
Both methods navigate to the path `/user/erina`.
#### redirect
You also use the `routes` configuration for redirections; for example, redirecting from `/home` to `/`:
```ts
export default {
routes: [
{
path: '/home',
redirect: '/'
}
]
}
```
The target of the redirect can also be a named route:
```ts
export default {
routes: [
{
path: '/home',
redirect: {
name: 'homepage'
}
}
]
}
```
#### alias
Redirect means that when a user accesses `/home`, the URL will be replaced with `/` and then matched to `/`. But what is an alias?
Aliasing `/` to `/home` means that when the user visits `/home`, the URL still is `/home`, but it will be matched as if the user is visiting `/`.
The corresponding route configuration is:
```ts
export default {
routes: [
{
path: '/',
component: 'index',
alias: '/home'
}
]
}
```
With aliases, you are free to map your UI structure to any URL without being constrained by the nesting structure of the configuration. Make aliases start with `/` to turn nested paths into absolute paths. You can even combine the two by providing multiple aliases with an array:
```ts
export default {
routes: [
{
path: '/users',
component: 'users',
routes: [
// Render UserList for these 3 URLs
// - /users
// - /users/list
// - /people
{ path: '', component: '/users/UserList', alias: ['/people', 'list'] },
]
}
]
}
```
### Page Navigation
```html
```
For more details, [see here](https://router.vuejs.org/guide/advanced/composition-api.html#accessing-the-router-and-current-route-inside-setup)
### router-link
For more details, [see here](https://router.vuejs.org/guide/#router-link)
### router-view
For more details, [see here](https://router.vuejs.org/guide/#router-view)
## Runtime Configuration
You can control Vue and Vue-router related configuration through exporting settings in the conventional `src/app.tsx`.
### router
Configure router settings
```ts
// src/app.tsx
export const router: RouterConfig = {
// @ts-ignore
scrollBehavior(to, from) {
console.log('scrollBehavior', to, from);
},
};
```
### onMounted({app, router})
Callback for successful Vue app mount, where you can get instances of app and router for global component registration, route interceptors, etc.
```ts
export function onMounted({ app, router }: any) {
console.log('onMounted', app, router);
app.provide('umi-hello', {
h: 'hello',
w: 'word',
});
}
```
### rootContainer(container)
Modify the root component rendered by vue-router.
For example, to wrap a parent component around the outside
```ts
import { h } from 'vue'
export function rootContainer(container) {
return h(ThemeProvider, null, container);
}
```
## Examples
For more examples, see demos:
* [boilerplate-vue](https://github.com/umijs/umi/tree/master/examples/boilerplate-vue)
* [with-vue-pinia](https://github.com/umijs/umi/tree/master/examples/with-vue-pinia)
* [with-vue-element-plus](https://github.com/umijs/umi/tree/master/examples/with-vue-element-plus)
---
### Docs Docs Guides Use Vue (`docs/docs/docs/guides/use-vue.md`)
---
order: 17
toc: content
---
# 使用 Vue
本文介绍如何在 Umi 中使用 Vue , Umi Vue 大部分配置和 React 相同，这里只列出一些 Vue 独有的配置。
## 启动方式
### 安装
```bash
pnpm add @umijs/preset-vue -D
```
### 配置预设
```ts
// .umirc.ts or config/config.ts 中
export default {
presets: [require.resolve('@umijs/preset-vue')],
};
```
## 路由
### 配置式路由
:::info
这里仅列出和 React 路由配置差异部分。
:::
#### name
命名路由
除了 `path` 之外，你还可以为任何路由提供 `name` ：
```ts
export default {
routes: [
{
path: '/user/:username',
name: 'user',
component: 'index'
}
]
}
```
要链接到一个命名的路由，可以向 `router-link` 组件的 `to` 属性传递一个对象：
```html
User
```
效果和命令式地调用 `router.push` 一致：
```ts
router.push({ name: 'user', params: { username: 'erina' } })
```
在这方法都能导航到路径 `/user/erina`。
#### redirect
重定向也是通过 `routes` 配置来完成，下面例子是从 `/home` 重定向到 `/`：
```ts
export default {
routes: [
{
path: '/home',
redirect: '/'
}
]
}
```
重定向的目标也可以是一个命名的路由：
```ts
export default {
routes: [
{
path: '/home',
redirect: {
name: 'homepage'
}
}
]
}
```
#### alias
重定向是指当用户访问 `/home` 时，URL 会被 `/` 替换，然后匹配成 `/`。那么什么是别名呢？
将 `/` 别名为 `/home`，意味着当用户访问 `/home` 时，URL 仍然是 `/home`，但会被匹配为用户正在访问 `/`。
上面对应的路由配置为：
```ts
export default {
routes: [
{
path: '/',
component: 'index',
alias: '/home'
}
]
}
```
通过别名，你可以自由地将 UI 结构映射到一个任意的 URL，而不受配置的嵌套结构的限制。使别名以 `/` 开头，以使嵌套路径中的路径成为绝对路径。你甚至可以将两者结合起来，用一个数组提供多个别名：
```ts
export default {
routes: [
{
path: '/users',
component: 'users',
routes: [
// 为这 3 个 URL 呈现 UserList
// - /users
// - /users/list
// - /people
{ path: '', component: '/users/UserList', alias: ['/people', 'list'] },
]
}
]
}
```
### 页面跳转
```html
```
更多[详见](https://router.vuejs.org/guide/advanced/composition-api.html#accessing-the-router-and-current-route-inside-setup)
### router-link
[详见](https://router.vuejs.org/guide/#router-link)
### router-view
[详见](https://router.vuejs.org/guide/#router-view)
## 运行时配置
可以通过在约定的 `src/app.tsx` 通过 export 配置来控制 vue vue-router 相关的配置。
### router
配置路由配置
```ts
// src/app.tsx
export const router: RouterConfig = {
// @ts-ignore
scrollBehavior(to, from) {
console.log('scrollBehavior', to, from);
},
};
```
### onMounted(\{app, router\})
Vue app mount 成功回调，这里可以拿到 app 的实例及 router 的实例，可以进行全局组件注册，路由拦截器等。
```ts
export function onMounted({ app, router }: any) {
console.log('onMounted', app, router);
app.provide('umi-hello', {
h: 'hello',
w: 'word',
});
}
```
### rootContainer(container)
修改交给 vue-router 渲染时的根组件。
比如用于在外面包一个父组件
```ts
import { h } from 'vue'
export function rootContainer(container) {
return h(ThemeProvider, null, container);
}
```
## Examples
更多详见 demo ：
* [boilerplate-vue](https://github.com/umijs/umi/tree/master/examples/boilerplate-vue)
* [with-vue-pinia](https://github.com/umijs/umi/tree/master/examples/with-vue-pinia)
* [with-vue-element-plus](https://github.com/umijs/umi/tree/master/examples/with-vue-element-plus)
---
### Docs Docs Introduce Contributing.En US (`docs/docs/docs/introduce/contributing.en-US.md`)
---
order: 3
toc: content
translated_at: '2024-03-17T09:56:34.842Z'
---
# Contributing
❤️ Loving Umi and want to get involved? Thanks!
## Environment Setup
### Node.js and pnpm
Developing Umi requires Node.js 18+ and `pnpm` v8.
It's recommended to use [Volta](https://volta.sh/) to manage the node and pnpm version. And you need to set the `VOLTA_FEATURE_PNPM` environment variable to enable pnpm support.
```bash
export VOLTA_FEATURE_PNPM=1
```
### Clone the Project
```bash
$ git clone git@github.com:umijs/umi.git
$ cd umi
```
### Install Dependencies and Build
```bash
$ pnpm i && pnpm build
```
## Developing Umi
### Start the dev Command
A must-run command for local development of Umi, for compiling TypeScript files in the `src` directory to the `dist` directory, and incrementally compiles on file changes.
```bash
$ pnpm dev
```
If you find it rather slow, you can also run the `pnpm dev` command for a specific package, for example.
```bash
$ cd packages/umi
$ pnpm dev
```
### Run Example
The `examples` directory contains various examples used for testing. Running an example is a common way to ensure functions work correctly during Umi development. Each example is equipped with a dev script, so just enter the example and run `pnpm dev`.
```bash
$ cd examples/boilerplate
$ pnpm dev
```
To run in vite mode, add the `--vite` argument,
```bash
$ pnpm dev --vite
```
### Testing
Currently running tests is fast, completing in just over 10s+. It’s recommended to run tests locally before submitting a PR to reduce Round Trips.
```bash
$ pnpm test
...
Test Suites: 1 skipped, 43 passed, 43 of 44 total
Tests: 6 skipped, 167 passed, 173 total
Snapshots: 0 total
Time: 13.658 s
Ran all test suites.
```
To run tests for specific files, use `pnpm jest` because `pnpm test` runs with turborepo enabled.
For example,
```bash
$ pnpm jest packages/plugin-docs/src/compiler.test.ts
```
## Contributing to Umi Documentation
Umi's documentation is implemented by Umi@4 and the `@umijs/plugin-docs` plugin, essentially an Umi project. Execute the following commands in the root directory to start development:
```bash
# Start Umi document development
# Compilation takes longer on first launch, please be patient
$ pnpm docs:dev
```
Open the specified port number to see real-time updates of documentation and results of the `@umijs/plugin-docs` plugin development.
### Writing Umi Documentation
Umi documentation is written in MDX format. MDX is an extension of the Markdown format allowing you to insert JSX components while writing Umi documentation.
:::success{title=🏆︎}
When writing **Documentation**, you can find usable components in `packages/plugin-docs/client/theme-doc/components`. When writing **Blog posts**, usable components can be found in `packages/plugin-docs/client/theme-blog/components`.
:::
Umi documentation code highlighting is based on [`Rehype Pretty Code`](https://github.com/atomiks/rehype-pretty-code), for full capabilities and instructions, please visit its [official documentation](https://rehype-pretty-code.netlify.app).
Execute the following command in the root directory to format existing Umi documentation:
```bash
$ pnpm format:docs
```
After formatting the documentation, it is recommended to **only submit the Umi documents you have written or modified**. Different document contributors have varying writing styles and formatting may not always retain the original intended style.
### Participating in Umi Documentation Plugin Development
Open a new terminal and execute the following commands:
```bash
$ cd packages/plugin-docs
$ pnpm dev:css
```
Now, when you modify the `tailwind.css` file or TailwindCSS style classes during development, a `tailwind.out.css` stylesheet file will be automatically compiled and generated.
Umi listens for changes in the `docs` and `packages/plugin-docs/client` directories, but does not listen to changes in `packages/plugin-docs/src`.
:::info{title=💡}
If you need to compile files in `packages/plugin-docs/src`, please move to the `packages/plugin-docs` directory and execute the `pnpm build` command, then restart development.
:::
Executing the following command in the root directory to format the code of Umi documentation plugin:
```bash
$ pnpm format:plugin-docs
```
Execute the following command in the root directory to build Umi documentation:
```bash
$ pnpm docs:build
```
## Adding a New Package
Adding a new package has a script encapsulated, no need to manually copy `package.json`, etc.:
```bash
# Create package directory
$ mkdir packages/foo
# Initialize package development
$ pnpm bootstrap
```
## Updating Dependencies
> It is not recommended for non-Core Maintainers to update a large number of dependencies because it involves pre-packaging of dependencies and there are many points to note.
Run `pnpm dep:update` to update dependencies.
```bash
$ pnpm dep:update
```
Since Umi pre-packages some dependencies, after updating dependencies, it's necessary to check if the updated dependency is in devDependencies and whether it has been pre-packaged. If so, execute `pnpm build:deps` in the corresponding package and specify the dependency to update pre-packaged dependency files.
```bash
$ pnpm build:deps --dep webpack-manifest-plugin
```
## Release
Only Core Maintainers can carry out releases. Umi now uses npm Trusted Publishing/OIDC, so the local release command only bumps versions, creates and pushes the release commit/tag, and no longer runs `npm publish` locally.
```bash
$ pnpm release
```
After the push, the GitHub Actions Release workflow obtains npm publishing permission through OIDC, runs `pnpm release:publish`, and publishes packages to npm with `--provenance`.
## Rolling Back through dist-tag
For example, to roll back to 4.0.81.
```bash
$ pnpm -rc --filter "./packages/**" exec pnpm dist-tag add \$PNPM_PACKAGE_NAME@4.0.81 latest
```
## Joining the Contributor Group
For those who have submitted Bugfix or Feature type PRs and are interested in participating in maintaining Umi, you can first scan the QR code below with DingTalk (mention your github id), and then I will add you to the group.
If you don't know what you can contribute, you can search TODO or FIXME in the source code.
---
### Docs Docs Introduce Contributing (`docs/docs/docs/introduce/contributing.md`)
---
order: 3
toc: content
---
# 参与贡献
❤️ Loving Umi and want to get involved? Thanks!
## 环境准备
### Node.js 和 pnpm
开发 Umi 需要 Node.js 18+ 和 `pnpm` v8。
推荐使用 [Volta](https://volta.sh/) 来管理 Node.js 和 pnpm 版本。并且需要设置 `VOLTA_FEATURE_PNPM` 环境变量来启用 pnpm 支持。
```bash
export VOLTA_FEATURE_PNPM=1
```
### Clone 项目
```bash
$ git clone git@github.com:umijs/umi.git
$ cd umi
```
### 安装依赖并构建
```bash
$ pnpm i && pnpm build
```
## 开发 Umi
### 启动 dev 命令
本地开发 Umi 必开命令，用于编译 `src` 下的 TypeScript 文件到 `dist` 目录，同时监听文件变更，有变更时增量编译。
```bash
$ pnpm dev
```
如果觉得比较慢，也可以只跑特定 package 的 `pnpm dev` 命令，比如。
```bash
$ cd packages/umi
$ pnpm dev
```
### 跑 Example
`examples` 目录下保存了各种用于测试的例子，跑 example 是开发 Umi 时确认功能正常的常用方式。每个 example 都配了 dev 脚本，所以进入 example 然后执行 `pnpm dev` 即可。
```bash
$ cd examples/boilerplate
$ pnpm dev
```
如果要用 vite 模式跑，加 `--vite` 参数，
```bash
$ pnpm dev --vite
```
### 测试
目前跑测试很快，10s+ 就完成了。推荐本地跑一遍再提 PR，减少 Round Trip。
```bash
$ pnpm test
...
Test Suites: 1 skipped, 43 passed, 43 of 44 total
Tests: 6 skipped, 167 passed, 173 total
Snapshots: 0 total
Time: 13.658 s
Ran all test suites.
```
如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 是开了 turborepo 功能的。
比如，
```bash
$ pnpm jest packages/plugin-docs/src/compiler.test.ts
```
## 贡献 Umi 文档
Umi 的文档由 Umi@4 和 `@umijs/plugin-docs` 插件实现，本质上就是一个 Umi 项目。在根目录执行如下命令即可开始 Umi 文档的开发：
```bash
# 启用 Umi 文档开发
# 首次启动时编译耗时较长，请耐心等待
$ pnpm docs:dev
```
打开指定的端口号，即可实时查看文档更新的内容，以及 `@umijs/plugin-docs` 插件开发的成果。
### 撰写 Umi 文档
Umi 文档的编写基于 MDX 格式。MDX 是 Markdown 格式的拓展，允许您在撰写 Umi 文档时插入 JSX 组件。
:::success{title=🏆︎}
撰写 **文档（Document）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-doc/components` 目录下找到。撰写 **博客（Blog）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-blog/components` 目录下找到。
:::
Umi 文档的代码高亮基于 [`Rehype Pretty Code`](https://github.com/atomiks/rehype-pretty-code)，完整的能力和使用说明请移步它的[官方文档](https://rehype-pretty-code.netlify.app)。
在根目录执行如下命令可以格式化仓库中已有的 Umi 文档：
```bash
$ pnpm format:docs
```
格式化文档后，建议**仅提交您撰写或修改的 Umi 文档**。不同文档贡献者的写作风格有一定的差异，格式化以后不一定能保留原来期望的样式。
### 参与 Umi 文档插件开发
新建一个终端，执行如下命令：
```bash
$ cd packages/plugin-docs
$ pnpm dev:css
```
现在，当您修改了 `tailwind.css` 文件或在开发时修改了 TailwindCSS 样式类时，会自动编译并生成 `tailwind.out.css` 样式表文件。
Umi 会监听 `docs` 和 `packages/plugin-docs/client` 目录下文件的变化，而不会监听 `packages/plugin-docs/src` 目录。
:::info{title=💡}
如果您需要编译 `packages/plugin-docs/src` 中的文件，请移动到 `packages/plugin-docs` 目录下执行 `pnpm build` 命令，然后重启开发。
:::
在根目录执行如下命令可以格式化 Umi 文档插件的代码：
```bash
$ pnpm format:plugin-docs
```
在根目录执行如下命令可以构建 Umi 文档：
```bash
$ pnpm s
```
## 新增 package
新增 package 有封装脚本，无需手动复制 `package.json` 等文件：
```bash
# 创建 package 目录
$ mkdir packages/foo
# 初始化 package 开发
$ pnpm bootstrap
```
## 更新依赖
> 不推荐非 Core Maintainer 做大量依赖更新。因为涉及依赖预打包，有较多需注意的点。
执行 `pnpm dep:update` 可更新依赖。
```bash
$ pnpm dep:update
```
由于 Umi 有针对依赖做预打包处理，更新依赖后还需检查更新的依赖是否为 devDependencies 并且有对此做依赖预打包。如果有，需要在对应 package 下执行 `pnpm build:deps` 并指定依赖，用于更新预打包的依赖文件。
```bash
$ pnpm build:deps --dep webpack-manifest-plugin
```
## 发布
只有 Core Maintainer 才能执行发布。Umi 已切换到 npm Trusted Publishing/OIDC，本地发布命令只负责 bump version、生成 release commit/tag 并推送，不再直接执行 `npm publish`。
```bash
$ pnpm release
```
推送后，GitHub Actions 的 Release workflow 会通过 OIDC 获取 npm 发布权限，执行 `pnpm release:publish`，并带上 `--provenance` 将 package 发布到 npm。
## 通过 dist-tag 回滚
比如要回滚到 4.0.81 。
```bash
$ pnpm -rc --filter "./packages/**" exec pnpm dist-tag add \$PNPM_PACKAGE_NAME@4.0.81 latest
```
## 加入 Contributor 群
提交过 Bugfix 或 Feature 类 PR 的同学，如果有兴趣一起参与维护 Umi，可先用钉钉扫下方二维码（注明 github id）加我钉钉，然后我会拉到群里。
如果你不知道可以贡献什么，可以到源码里搜 TODO 或 FIXME 找找。
---
### Docs Docs Introduce Faq.En US (`docs/docs/docs/introduce/faq.en-US.md`)
---
order: 5
toc: content
translated_at: '2024-03-17T09:54:04.320Z'
---
# FAQ
## Can I disable dynamicImport?
Yes, but it is not recommended to do so.
1. Install dependencies
```bash
pnpm i babel-plugin-dynamic-import-node -D
```
2. Add `extraBabelPlugins` to the configuration, but only enable it for production
```ts
// .umirc.ts
export default {
extraBabelPlugins: process.env.NODE_ENV === 'production'
? ['babel-plugin-dynamic-import-node']
: []
}
```
## How to configure loading for dynamicImport when it's not present?
Define `src/loading.tsx`:
See [Directory Structure > loading.tsx](../guides/directory-structure#loadingtsxjsx)
## Can I use React 17?
Since Umi v4 has upgraded the default version of React to v18, be aware of compatibility between dependency libraries and React 18 when using Umi4. If you still need to use React 17, run the following commands and restart.
```bash
pnpm add react@^17 react-dom@^17
```
## Constantly restarting and refreshing the page after proxying static resources locally
Solution: Configure `SOCKET_SERVER=127.0.0.1:${port}` to start the project
```bash
SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
```
## Error evaluating function `round`: argument must be a number
Solution: In the new version of less, `/` is recognized as property shorthand by default. To restore the old behavior (where `/` was used as a calculation symbol by default), configure `lessLoader: { math: 'always' }`.
## The layout configuration option in routes does not take effect
The layout configuration has been moved to `app.ts`, see [Runtime Config > layout](https://umijs.org/docs/api/runtime-config#layout)
## Where did document.ejs go and how do I customize the HTML template
In addition to the injection through the configuration of external [script](https://umijs.org/docs/api/config#scripts), [css](https://umijs.org/docs/api/config#styles), you can also use the project-level plugin to more flexibly modify HTML products, see: [issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
## Why are external js files configured in scripts by default inserted after umi.js
React only starts running after the page has fully loaded, so inserting after `umi.js` will not affect the project.
If you need to insert it before `umi.js`, see [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
## How do I code split with Umi4?
Umi 4 splits code by page by default. If you feel the need for further optimization, you can use sub-package strategies or manual splitting, see: [Code Splitting Guide](../../blog/code-splitting)
If you have the requirement to pack all js products into a single `umi.js` file, please disable [dynamicImport](#can-i-disable-dynamicimport).
## Where did _layout.tsx go and how do I nest routes?
Umi 4 uses react-router v6, and nested route content is displayed through ``. See: [issuecomment-1206194329](https://github.com/umijs/umi/issues/8850#issuecomment-1206194329)
## How to use GraphQL
For configuring `graph-ql` loader, see: [discussions/8218](https://github.com/umijs/umi/discussions/8218)
## How to use WebAssembly
Configure as follows:
```ts
// .umirc.ts
export default {
chainWebpack(config) {
config.set('experiments', {
...config.get('experiments'),
asyncWebAssembly: true
})
const REG = /\.wasm$/
config.module.rule('asset').exclude.add(REG).end();
config.module
.rule('wasm')
.test(REG)
.exclude.add(/node_modules/)
.end()
.type('webassembly/async')
.end()
},
}
```
See an actual example: [discussions/8541](https://github.com/umijs/umi/discussions/8541)
## How to customize loaders
Depending on the scenario, you may need to exclude the file type you need to load from the static asset rules first and then add your own loader or modify it. Refer to the following examples:
- [discussions/8218](https://github.com/umijs/umi/discussions/8218)
- [discussions/8452](https://github.com/umijs/umi/discussions/8452)
## How to use css modules in third-party packages
1. Directly publish the source code of third-party packages' `jsx` / `ts` / `tsx` to npm, no need to translate to `js`. Umi 4 supports direct use.
2. If the third-party package output is `js`, you need to include it for additional processing by babel to support css modules:
```ts
// .umirc.ts
export default {
extraBabelIncludes: ['your-pkg-name']
}
```
## How to solve the lack of hot updates in npm linked packages
Umi 4 has `mfsu` enabled by default and ignores changes in `node_modules` by default. Exclude the package from `mfsu` as follows:
```ts
// .umirc.ts
export default {
mfsu: {
exclude: ['package-name']
},
}
```
## What is the priority order of config files for different environments?
For the detailed loading priority, see [UMI_ENV](../../docs/guides/env-variables#umi_env), and the same applies to `config/config.ts` or `.umirc.ts`.
## Problems with IE compatibility
Umi 4 is not IE compatible by default in the context of modern browsers.
If you need to adjust the build for compatibility targets, for older browsers, or for IE, please refer to [Legacy Browser Compatibility](../../blog/legacy-browser).
## SSR Issues
SSR is still an experimental feature and not recommended for production environments. If any issues are encountered, they should be reported on [issues](https://github.com/umijs/umi/issues).
## Vue / Vite Issues
Umi 4 now supports Vite mode and Vue. There may be edge cases, so report any issues on [issue](https://github.com/umijs/umi/issues).
## Why does the pathname obtained from `history` differ from the one obtained from `useLocation`?
This situation occurs when the project is configured with `base`. `history.location.pathname` reflects the browser's pathname, which includes the `base`. Route-related hooks, however, return the **frontend route** definition's pathname, which does not include the `base`. [Reference](../guides/routes#location-information).
## How to change the compression encoding format of the output
By default, the js/css compressor `esbuild` uses `ascii` encoding for compression, which may lead to the encoding of Chinese characters and increase the size of the output.
Adjust the encoding to `utf8` to prevent character conversion:
```ts
// .umirc.ts
export default {
jsMinifierOptions: { charset: 'utf8' },
cssMinifierOptions: { charset: 'utf8' }
}
```
Or switch the compressor to resolve this:
```ts
// .umirc.ts
export default {
jsMinifier: 'terser',
cssMinifier: 'cssnano'
}
```
## How to configure devServer options
Umi 4 no longer supports configuring `devServer`, but you can find alternatives as follows:
1. Use the [`proxy`](../api/config#proxy) option to set up a proxy, and modify request header information through `onProxyReq`, see [#10760](https://github.com/umijs/umi/issues/10760#issuecomment-1471158059).
2. Write a [project-level plugin](../guides/use-plugins#project-level-plugins) to insert an express middleware to modify requests, see [#10060](https://github.com/umijs/umi/issues/10060#issuecomment-1471519707).
---
### Docs Docs Introduce Faq (`docs/docs/docs/introduce/faq.md`)
---
order: 5
toc: content
---
# FAQ
## 可以关闭 dynamicImport 吗？
可以，但不建议关闭。
1、安装依赖
```bash
pnpm i babel-plugin-dynamic-import-node -D
```
2、配置里加上 `extraBabelPlugins` ，但只针对 production 开启
```ts
// .umirc.ts
export default {
extraBabelPlugins: process.env.NODE_ENV === 'production'
? ['babel-plugin-dynamic-import-node']
: []
}
```
## 没有 dynamicImport 怎么配置它的 loading ？
定义 `src/loading.tsx` :
参考 [目录结构 > loading.tsx](../guides/directory-structure#loadingtsxjsx)
## 可以用 react 17 吗？
由于 umi v4 升级了默认的 react 版本到 v18，使用 umi4 时注意下依赖库和 react 18 的兼容情况，如果还需要使用 react 17，请执行以下命令并重启。
```bash
pnpm add react@^17 react-dom@^17
```
## 代理静态资源到本地后，一直 restart 刷新页面
解法：配置 `SOCKET_SERVER=127.0.0.1:${port}` 启动项目
```bash
SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
```
## Error evaluating function `round`: argument must be a number
解法：新版 less 中 `/` 默认被识别为属性简写，通过配置 `lessLoader: { math: 'always' }` 恢复旧版行为（默认将 `/` 用作计算符号）。
## routes 里的 layout 配置选项不生效
layout 配置被移动到了 `app.ts` ，详见 [runtime-config > layout](https://umijs.org/docs/api/runtime-config#layout)
## document.ejs 去哪了，如何自定义 HTML 模板
除了可以通过 配置项 注入外部 [script](https://umijs.org/docs/api/config#scripts) 、[css](https://umijs.org/docs/api/config#styles) 外，还可以使用项目级插件更灵活的修改 HTML 产物，参见：[issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
## scripts 里配置的外部 js 文件为什么默认插入到 umi.js 的后面
react 只有在页面加载完毕后才会开始运行，所以插到 `umi.js` 后面不会影响项目。
若需要插到 `umi.js` 前面，可参见 [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
## umi4 我怎么分包
Umi 4 默认按页拆包，如果你觉得还需要优化，可以使用分包策略或手动拆包，详见：[代码拆分指南](../../blog/code-splitting)
如果你有将所有 js 产物打包成单 `umi.js` 文件的需求，请关闭 [dynamicImport](#可以关闭-dynamicimport-吗) 。
## _layout.tsx 去哪了，我怎么嵌套路由
Umi 4 使用 react-router v6 ，通过 `` 展示嵌套路由内容，可参见：[issuecomment-1206194329](https://github.com/umijs/umi/issues/8850#issuecomment-1206194329)
## 怎么用 GraphQL
配置 `graph-ql` loader 的方式可参见： [discussions/8218](https://github.com/umijs/umi/discussions/8218)
## 怎么用 WebAssembly
配置如下：
```ts
// .umirc.ts
export default {
chainWebpack(config) {
config.set('experiments', {
...config.get('experiments'),
asyncWebAssembly: true
})
const REG = /\.wasm$/
config.module.rule('asset').exclude.add(REG).end();
config.module
.rule('wasm')
.test(REG)
.exclude.add(/node_modules/)
.end()
.type('webassembly/async')
.end()
},
}
```
一个实际例子可参见：[discussions/8541](https://github.com/umijs/umi/discussions/8541)
## 怎么自定义 loader
根据场景不同，你可能要先从 静态资源规则 中排除你需要加载的文件类型，再添加你自己的 loader / 或修改，可参考如下实例：
- [discussions/8218](https://github.com/umijs/umi/discussions/8218)
- [discussions/8452](https://github.com/umijs/umi/discussions/8452)
## 第三方包里如何使用 css modules
1. 直接将第三方包的 `jsx` / `ts` / `tsx` 源码发布到 npm ，无需转译为 `js` Umi 4 支持直接使用。
2. 若第三方包产物是 `js` 的情况，需要将其纳入 babel 额外处理，才可以支持 css modules：
```ts
// .umirc.ts
export default {
extraBabelIncludes: ['your-pkg-name']
}
```
## npm link 的包不热更新怎么解决
Umi 4 默认开启 `mfsu` ，默认忽略 `node_modules` 的变化，配置从 `mfsu` 排除该包即可：
```ts
// .umirc.ts
export default {
mfsu: {
exclude: ['package-name']
},
}
```
## 我的环境很多，多环境 config 文件的优先级是怎样的
加载优先级详见 [UMI_ENV](../../docs/guides/env-variables#umi_env) ，无论是 `config/config.ts` 还是 `.umirc.ts` 同理。
## IE 兼容性问题
现代浏览器主流背景下，Umi 4 默认不兼容 IE 。
若你有调整构建兼容目标、兼容非现代浏览器、兼容 IE 浏览器的需求，请参考 [非现代浏览器兼容](../../blog/legacy-browser) 。
## SSR 问题
SSR 目前还处于实验性特性，不建议在生产环境使用，若发现问题可即时在 [issue](https://github.com/umijs/umi/issues) 反馈。
## Vue / Vite 问题
Umi 4 新增了 Vite 模式和 Vue 支持，可能存在 edge case ，若发现问题可即时在 [issue](https://github.com/umijs/umi/issues) 反馈。
## `history` 中取的 pathname 为什么和 `useLocation` 中的不一样
这种情况是在项目配置了 `base` 。 `history.location.pathname` 取到的值是浏览器地址中的 `pathname`，它是包含 `base` 的；而路由相关 hooks 取到的值是**前端路由**定义中的 `pathname`，它是不包含 `base` 的。[参考](../guides/routes#location-信息)。
## 调整产物的压缩编码格式
默认 js / css 的压缩器 `esbuild` 会采用 `ascii` 格式编码压缩，这可能导致中文字符被转码，增大产物体积。
可通过配置调整到 `utf8` 编码，防止字符被转换：
```ts
// .umirc.ts
export default {
jsMinifierOptions: { charset: 'utf8' },
cssMinifierOptions: { charset: 'utf8' }
}
```
或通过切换压缩器来解决：
```ts
// .umirc.ts
export default {
jsMinifier: 'terser',
cssMinifier: 'cssnano'
}
```
## devServer 选项怎么配置
Umi 4 不再支持配置 `devServer` 选项，但你可以通过以下方式找到替代：
1. [`proxy`](../api/config#proxy) 选项配置代理，可通过 `onProxyReq` 修改请求头信息，可参考 [#10760](https://github.com/umijs/umi/issues/10760#issuecomment-1471158059) 。
2. 编写 [项目级插件](../guides/use-plugins#项目级插件) ，插入 express 中间件以实现对请求的修改，可参考 [#10060](https://github.com/umijs/umi/issues/10060#issuecomment-1471519707) 。
---
### Docs Docs Introduce Introduce.En US (`docs/docs/docs/introduce/introduce.en-US.md`)
---
order: 1
toc: content
translated_at: '2024-03-17T09:52:32.853Z'
---
# Introduction to Umi
## What is Umi?
Umi, pronounced as "Wu Mi" in Chinese, is an extensible enterprise-level front-end application framework. Umi is based on routing, supporting both configuration-based routing and convention-based routing, ensuring the completeness of routing features and further extending functionalities based on this. Accompanied by a plugin system with a complete lifecycle, it covers every lifecycle from the source code to the build product, supporting various functional extensions and business needs.
Umi is the underlying front-end framework of Ant Group, serving directly or indirectly over 10,000 applications, including Java, Node, H5 Wireless, Hybrid applications, pure front-end assets applications, CMS applications, Electron applications, Serverless applications, and more. It has served our internal users well and many external users, including Taobao system, Feizhu, Alibaba Cloud, ByteDance, Tencent, Koubei, Meituan, etc. In ByteDance's [research report](https://zhuanlan.zhihu.com/p/403206195) in 2021, Umi was the choice of 25.33% of developers.
Umi has many interesting features, such as:
1. **Enterprise-level**, considering more in terms of security, stability, best practices, and constraint ability
2. **Plugin-based**, everything can be modified, and Umi itself is also composed of plugins
3. **MFSU**, a Webpack packaging solution faster than Vite
4. Complete routing based on React Router 6
5. The fastest request by default
6. SSR & SSG
7. Stable white-box performance with ESLint and Jest
8. Framework-level integration of React 18
9. Best practices for Monorepo
...
## When Not to Use Umi?
If your project,
1. Needs to support IE 8 or lower browsers
2. Needs to support React versions below 16.8.0
3. Needs to run in environments below Node 14
4. Has strong webpack customization needs and subjective willingness
5. Needs to choose different routing solutions
...
Umi might not be suitable for you.
## Why Not?
### create-react-app
create-react-app is a scaffolding tool and not the same type as meta frameworks like Umi, next.js, remix, ice, modern.js, etc. Scaffolding can quickly start a project, which is sufficient for individual projects, but not enough for teams. Because using scaffolding is like spilt water; once it starts, it cannot iterate. Meanwhile, the encapsulation and abstraction that scaffolding can do are very limited.
### next.js
If SSR is needed, next.js is a very good choice (of course, Umi also supports SSR); but if only CSR is needed, Umi would be a better choice. By comparison, Umi has better extensibility; and Umi offers many more down-to-earth features, such as configuration-based routing, patch scheme, integration of antd, micro frontends, internationalization, permissions, etc.; at the same time, Umi is more stable, because it locks all dependencies that can be locked and proactively updates regularly. A certain subversion of Umi will not fail to run due to reinstallation of dependencies.
### remix
Remix is a framework I really like, and Umi 4 has copied (learned) a lot from it. But Remix is a Server framework, its built-in loaders and actions run on the server side, so it requires certain deployment environments. Umi applies loaders, actions, and the request mechanism of Remix to both the client and server side, not only making server requests fast but also achieving theoretically fastest values for pure CSR projects. At the same time, Remix is based on esbuild for packaging, which may not be suitable for projects with compatibility requirements or especially large dependencies.
---
### Docs Docs Introduce Introduce (`docs/docs/docs/introduce/introduce.md`)
---
order: 1
toc: content
---
# Umi 介绍
## Umi 是什么？
Umi，中文发音为「乌米」，是可扩展的企业级前端应用框架。Umi 以路由为基础，同时支持配置式路由和约定式路由，保证路由的功能完备，并以此进行功能扩展。然后配以生命周期完善的插件体系，覆盖从源码到构建产物的每个生命周期，支持各种功能扩展和业务需求。
Umi 是蚂蚁集团的底层前端框架，已直接或间接地服务了 10000+ 应用，包括 Java、Node、H5 无线、离线（Hybrid）应用、纯前端 assets 应用、CMS 应用、Electron 应用、Serverless 应用等。他已经很好地服务了我们的内部用户，同时也服务了不少外部用户，包括淘系、飞猪、阿里云、字节、腾讯、口碑、美团等。在 2021 年字节的[调研报告](https://zhuanlan.zhihu.com/p/403206195)中，Umi 是其中 25.33% 开发者的选择。
Umi 有很多非常有意思的特性，比如。
1、**企业级**，在安全性、稳定性、最佳实践、约束能力方面会考虑更多
2、**插件化**，啥都能改，Umi 本身也是由插件构成
3、**MFSU**，比 Vite 还快的 Webpack 打包方案
4、基于 React Router 6 的完备路由
5、默认最快的请求
6、SSR & SSG
7、稳定白盒性能好的 ESLint 和 Jest
8、React 18 的框架级接入
9、Monorepo 最佳实践
...
## 什么时候不用 Umi？
如果你的项目，
1、需要支持 IE 8 或更低版本的浏览器
2、需要支持 React 16.8.0 以下的 React
3、需要跑在 Node 14 以下的环境中
4、有很强的 webpack 自定义需求和主观意愿
5、需要选择不同的路由方案
...
Umi 可能不适合你。
## 为什么不是？
### create-react-app
create-react-app 是脚手架，和 Umi、next.js、remix、ice、modern.js 等元框架不是同一类型。脚手架可以让我们快速启动项目，对于单一的项目够用，但对于团队而言却不够。因为使用脚手架像泼出去的水，一旦启动，无法迭代。同时脚手架所能做的封装和抽象都非常有限。
### next.js
如果要做 SSR，next.js 是非常好的选择（当然，Umi 也支持 SSR）；而如果只做 CSR，Umi 会是更好的选择。相比之下，Umi 的扩展性会更好；并且 Umi 做了很多更贴地气的功能，比如配置式路由、补丁方案、antd 的接入、微前端、国际化、权限等；同时 Umi 会更稳定，因为他锁了能锁的全部依赖，定期主动更新。某一个子版本的 Umi，不会因为重装依赖之后而跑不起来。
### remix
Remix 是我非常喜欢的框架，Umi 4 从中抄（学）了不少东西。但 Remix 是 Server 框架，其内置的 loader 和 action 都是跑在 server 端的，所以会对部署环境会有一定要求。Umi 将 loader、action 以及 remix 的请求机制同时运用到 client 和 server 侧，不仅 server 请求快，纯 CSR 的项目请求也可达到理论的最快值。同时 Remix 基于 esbuild 做打包，可能不适用于对兼容性有要求或者依赖尺寸特别大的项目。
---
### Docs Docs Introduce Philosophy.En US (`docs/docs/docs/introduce/philosophy.en-US.md`)
---
order: 2
toc: content
translated_at: '2024-03-17T09:51:30.781Z'
---
# Design Philosophy
Umi has gone from 1 to 4, experimenting with many things, both successes and failures. We have gradually accumulated these successful experiences, guiding us on how to build a robust enterprise-level framework.
The design philosophy includes:
1. Technological Convergence
2. Plugins and Plugin Collections
3. Best Practices
4. Enterprise-Level
5. import all from umi
6. Compile-Time Framework
7. Dependency Prepacking
8. Fast by Default
9. Constraints and Openness
Below, we introduce the first five points, while the last four points (6-9) had a detailed share at the SEE Conf on January 8, 2022, see [SEE Conf: Umi 4 Design Philosophy Manuscript](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146).
## Technological Convergence
Technological convergence is particularly important for teams, encompassing two meanings: 1) convergence of technology stacks and 2) convergence of dependencies. Convergence of technology stacks refers to the plethora of technology stacks available in the community, with numerous choices for each technical direction, such as data flows which alone could number over 100, and how developers should make their choice; After converging the technology stack, it's also necessary to converge dependencies, as the projects of developers within a team should not have many fragmented dependencies, each of which comes with an upgrading cost.
We hope that once developers depend on Umi, they no longer need to worry about dependencies like babel, webpack, postcss, react, react-router, etc., and by depending on @umijs/max, they need not be concerned with dependencies and technology stacks of developing mid-end projects.
## Plugins and Plugin Collections
Umi satisfies different scenarios and business needs through the mechanism of plugins and plugin collections. A plugin is to extend a function, whereas a plugin collection is to extend a category of business. For example, to support vue, we could have `@umijs/preset-vue`, including build and runtime related to vue; to support the H5 application type, there could be `@umijs/preset-h5`, aggregating H5 related functionalities together.
As an analogy, plugin collections are similar to babel's presets and eslint's configs.
## Best Practices
Best practice is what we believe to be the best way to do something at the moment. The subject is us, so it could be relatively subjective. For instance, in aspects like routing, patch solutions, data flow, requests, permissions, internationalization, micro-frontends, icons usage, editor usage, charts, forms, etc., Umi will offer our best practices. Most of these practices come from internal practices and discussions at Ant Group, with some from the community. They are subjective and time-sensitive, so there might be relatively frequent iterations.
The need for best practices arises, 1) because there are too many solutions in the community to choose from, and 2) many people lack the energy, experience, or even willingness to make choices. Especially for non-professional front-end developers, having choices is better than having none, regardless of what those choices might be.
## Enterprise-Level
The npm community is "deteriorating" with political, malicious, advertisement, and job-seeking packages frequently appearing. Thus, how to ensure your project won’t “crash overnight” is an unavoidable issue for frameworks providing services to enterprises.
Umi achieves this by locking down versions, prepacking dependencies, hacking eslint to lock eslint's dependencies, and using configuration to lock down babel patch dependencies, so that Umi won't crash after you reinstall node_modules, aiming to be "Still Usable in Ten Years".
## import all from umi
Many may be hearing about this for the first time. import all from umi means all imports come from `umi`. For instance, dva is not `import { connect } from 'dva'`, but `import { connect } from 'umi'`, exported from Umi. The methods exported not only come from Umi itself but also from Umi plugins.
```ts
// A large number of plugins provide additional exports for umi
import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi';
```
The advantage is that Umi manages a large number of dependencies so users don’t need to manually install them; at the same time, developers will also have fewer import statements in their code.
---
### Docs Docs Introduce Philosophy (`docs/docs/docs/introduce/philosophy.md`)
---
order: 2
toc: content
---
# 设计思路
Umi 从 1 做到 4，试错了很多东西，也试对了不少。这些试对的点我们逐渐沉淀下来，就成为指引我们如何做好企业级框架的思路。
设计思路包括，
1、技术收敛
2、插件和插件集
3、最佳实践
4、企业级
5、import all from umi
6、编译时框架
7、依赖预打包
8、默认快
9、约束与开放
下面仅介绍 1-5 的 5 点，剩下 6-9 的 4 点在 2022.1.8 的 SEE Conf 中有过详细分享，详见[《SEE Conf: Umi 4 设计思路文字稿》](https://mp.weixin.qq.com/s?__biz=MjM5NDgyODI4MQ%3D%3D&mid=2247484533&idx=1&sn=9b15a67b88ebc95476fce1798eb49146)。
## 技术收敛
技术收敛对团队而言尤其重要，他包含两层含义，1）技术栈收敛 2）依赖收敛。技术栈收敛指社区那么多技术栈，每个技术方向都有非常多选择，比如数据流应该就不下 100 种，开发者应该如何选择；收敛了技术栈之后还需要收敛依赖，团队中，开发者的项目不应该有很多细碎的依赖，每一个依赖都附带着升级成本。
我们希望开发者依赖 Umi 之后就无需关心 babel、webpack、postcss、react、react-router 等依赖，而依赖 @umijs/max 之后无需再关心开发中台项目的依赖和技术栈。
## 插件和插件集
Umi 通过提供插件和插件集的机制来满足不同场景和业务的需求。插件是为了扩展一个功能，而插件集是为了扩展一类业务。比如要支持 vue，我们可以有 `@umijs/preset-vue`，包含 vue 相关的构建和运行时；比如要支持 h5 的应用类型，可以有 `@umijs/preset-h5`，把 h5 相关的功能集合到一起。
如果要类比，插件集和 babel 的 preset，以及 eslint 的 config 都类似。
## 最佳实践
最佳实践是我们认为做某件事当下最好的方式，主语是我们，所以会相对比较主观。比如路由、补丁方案、数据流、请求、权限、国际化、微前端、icons 使用、编辑器使用、图表、表单等方面，Umi 都会给出我们的最佳实践。这些最佳实践大部分来自蚂蚁集团内部的实践和讨论，也有部分来自社区。他们是主观和时间敏感的，所以可能会有相对比较频繁的迭代。
之所以需要最佳实践，1）是社区太多方案选择，2）是很多人没有选择的精力和经验甚至意愿。尤其是针对非专业的前端，有选择比没选择好，不管这个选择如何。
## 企业级
npm 社区「世风日下」，涉政包、恶意包、广告求职包频出，所以如何确保不会「睡一觉醒来项目挂了」是面对企业生成提供服务的框架绕不开的一个点。
Umi 通过写死版本、依赖预打包、通过 eslint hack 锁定 eslint 依赖，通过配置锁定 babel 补丁依赖等方式，让 Umi 不会在你重装 node_modules 之后就挂掉，并以此来实现「十年后依旧可用」。
## import all from umi
很多人可能都第一次听到。import all from umi 意思是所有 import 都来自 `umi`。比如 dva 不是 `import { connect } from 'dva'`，而是 `import { connect } from 'umi'`，从 Umi 中导出。导出的方法不仅来自 Umi 自身，还来自 Umi 插件。
这是两年前 Umi 3 加的功能，最近发现 Remix、prisma、vitekit 等框架和工具都有类似实现。
```ts
// 大量插件为 umi 提供额外导出内容
import { connect, useModel, useIntl, useRequest, MicroApp, ... } from 'umi';
```
这带来的好处是。通过 Umi 将大量依赖管理起来，用户无需手动安装；同时开发者在代码中也会少很多 import 语句。
---
### Docs Docs Introduce Upgrade To Umi 4.En US (`docs/docs/docs/introduce/upgrade-to-umi-4.en-US.md`)
---
order: 4
toc: content
translated_at: '2024-03-17T09:50:41.558Z'
---
# Upgrade to Umi 4
## Upgrade Steps
Upgrading to Umi 4 can be completed in just a few easy steps, which can simply be described as - "Reinstall dependencies, modify configuration":
1. **Dependency Handling**
2. **Start Command**
3. **Upgrading Non-Official Plugins**
4. **Configuration Layer Migration**
5. **Code Layer Modifications**
### Dependency Handling
Your project's `package.json` needs to upgrade Umi and replace the corresponding Umi plugins.
If `umi@3` was developed using a combination of `umi` + `@umijs/preset-react`, then you can directly upgrade using the new `max`.
```diff
{
"devDependencies": {
+ "@umijs/max": "^4.0.0",
- "umi": "^3.0.0",
- "@umijs/preset-react": "^1.2.2"
}
}
```
Delete `node_module`, then execute `npm install` to reinstall dependencies.
### Start Command
If using `@umijs/max`, you can replace `umi` with the `max` command, such as `max dev`, `max build`, etc.
`umi@4` moved some pre-project operations to the `setup` command, such as `umi g tmp` commands in umi@3, which need to be replaced with `umi setup`
`package.json`
```diff
{
"scripts": {
- "build": "umi build",
+ "build": "max build",
- "postinstall": "umi g tmp",
+ "postinstall": "max setup",
- "start": "umi dev",
+ "start": "max dev",
}
}
```
### Upgrading Non-Official Plugins
For some non-Umi official Umi plugins used in the project, please contact the relevant authors to update them in a timely manner according to [plugin api changes](../api/plugin-api).
When migrating the project, you can first turn off references to the corresponding plugin packages, such as temporarily commenting out the `plugins` in the configuration, and removing all dependencies starting with `umi-plugin-`, `@umijs/plugin-`, and `@umijs/preset-` in package.json.
### Configuration Layer Migration
**Configurations provided by max** are as follows in `config/config.ts`:
> It’s worth noting that some rules that were conventionally enabled by plugins need to be explicitly configured in `umi@4`, as we want less 'black box' behavior in `umi@4`.
```typescript
import { defineConfig, utils } from 'umi';
export default defineConfig({
model: {},
antd: {},
request: {},
initialState: {},
mock: {
include: ['src/pages/**/_mock.ts'],
},
dva: {},
layout: {
// https://umijs.org/docs/max/layout-menu#configuration-at-build-time
title: 'UmiJS',
locale: true,
},
// https://umijs.org/zh-CN/plugins/plugin-locale
locale: {
// default zh-CN
default: 'zh-CN',
antd: true,
// default true, when it is true, will use `navigator.language` overwrite default
baseNavigator: true,
},
});
```
**Configurations with differences** are as follows in `config/config.ts`:
```typescript
import { defineConfig, utils } from 'umi';
export default defineConfig({
- fastRefresh: {},
+ fastRefresh: true,
dva: {
// The parameter hmr is no longer supported
- hmr: true,
},
// Default webpack5
- webpack5: {},
})
```
### Code Layer Modifications
Umi 4 upgrades `react-router@5` to `react-router@6`, so there are some differences in the use of related api.
Props are empty objects by default, the following properties cannot be taken directly from props
#### children
```typescript
import { Outlet } from 'umi';
;
```
Mainly needs modifications in the global layout
Such as `layouts/index.tsx`:
```diff
import React from 'react';
+ import { Outlet } from 'umi';
export default function Layout(props) {
return (
- { props.children }
+
);
}
```
Change the way that route components rendered with `React.cloneElement`, for example:
```diff
import React from 'react';
+ import { Outlet } from 'umi';
export default function RouteComponent(props) {
return (
);
}
```
#### location
> It’s recommended to use useLocation in components or hooks, and window.location elsewhere.
```diff
export default function Page(props) {
+ const { location } = window;
return (
- { props.location }
+ { location }
);
}
```
Or
```diff
+ import { useLocation } from 'umi';
export default function Page(props) {
+ let location = useLocation();
return (
- { props.location }
+ { location }
);
}
```
#### match
```diff
+ import { useMatch } from 'umi';
export default function Page(props) {
+ const match = useMatch({ path: 'list/search/:type' });
return (
- { props.match }
+ { match }
);
}
```
In the use of class component components:
```diff
import { matchPath } from 'umi';
class Page extends Component {
+ match = matchPath({ path: 'list/search/:type' }, window.location.pathname);
state = {}
render() {
return (
- {this.props.match.type}
+ {this.match.type}
)
}
}
```
For more `Umi` related [api](https://umijs.org/docs/api/api)
Pay attention to the difference in match data:
```
// match v5
isExact: true
params: {}
path: "/users/abc"
url: "/users/abc"
// match v6
params:{ }
pathname: "/list/search/articles"
pathnameBase: "/list/search/articles"
pattern: {path: 'list/search/:type'}
```
For more changes and API updates, please refer to [react-router@6](https://reactrouter.com/docs/en/v6/api#uselocation)
After completing the above operations, execute `max dev`, and visit [http://localhost:8000](http://localhost:8000), please verify all functions meet expectations.
If your project cannot start normally, you may need to do the following:
## Configuration Changes
TODO
## FAQ
### Can't find query in location?
Query in location is no longer supported, later it’s recommended to use [search](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
```diff
- const { query } = history.location;
+ import { parse } from 'query-string';
+ const query = parse(history.location.search);
```
### Can't find *.d file, or its reference
In `umi@3`, importing would automatically find the corresponding `.d.ts` file, such as:
`import { ButtonType } from './button';`
If there is a `.button.d.ts` file, it will correctly execute in `umi@3`, but it will cause an error in umi@4, you may need more standardized type references.
```diff
- import { ButtonType } from './button';
+ import type { ButtonType } from './button.d';
```
---
### Docs Docs Introduce Upgrade To Umi 4 (`docs/docs/docs/introduce/upgrade-to-umi-4.md`)
---
order: 4
toc: content
---
# 升级到 Umi 4
## 升级步骤
升级到 Umi 4 只需要简单的几步操作就能完成，简单的描述整个过程就是 - “重装依赖，修改配置”：
1. **依赖处理**
2. **启动命令**
3. **非官方插件升级**
4. **配置层迁移**
5. **代码层修改**
### 依赖处理
项目的 `package.json` 需要升级 Umi，并替换掉对应的 Umi 插件。
如果 `umi@3` 中是使用 `umi` + `@umijs/preset-react` 的组合进行开发的，那可以直接使用新版的 `max` 直接升级。
```diff
{
"devDependencies": {
+ "@umijs/max": "^4.0.0",
- "umi": "^3.0.0",
- "@umijs/preset-react": "^1.2.2"
}
}
```
删除 `node_module`，执行下 `npm install` 重装依赖。
### 启动命令
如果使用了 `@umijs/max` 可以使用 `max` 命令来替换 `umi`，`max dev`，`max build` 等。
`umi@4` 将一些项目前置操作放到了 `setup` 命令中，如 umi@3 中的 `umi g tmp` 等命令，需要使用 `umi setup` 替换
`package.json`
```diff
{
"scripts": {
- "build": "umi build",
+ "build": "max build",
- "postinstall": "umi g tmp",
+ "postinstall": "max setup",
- "start": "umi dev",
+ "start": "max dev",
}
}
```
### 非官方插件升级
在项目中用到的一些非 Umi 官方提供的 Umi 插件，请联系相关作者及时根据[插件 api 变动](../api/plugin-api)。
项目迁移时可先关闭对相应插件包的引用，如临时注释配置中的 `plugins`，移除 package.json 中以 `umi-plugin-`，`@umijs/plugin-` 和 `@umijs/preset-` 开头的所有依赖。
### 配置层迁移
**max 提供的的配置项**如下 `config/config.ts` ：
> 需要注意的是，之前的一些插件约定开启的规则，在 `umi@4` 中几乎都要通过显式的配置开启，因为希望在 `umi@4` 中有更少的“黑盒”。
```typescript
import { defineConfig, utils } from 'umi';
export default defineConfig({
model: {},
antd: {},
request: {},
initialState: {},
mock: {
include: ['src/pages/**/_mock.ts'],
},
dva: {},
layout: {
// https://umijs.org/docs/max/layout-menu#构建时配置
title: 'UmiJS',
locale: true,
},
// https://umijs.org/zh-CN/plugins/plugin-locale
locale: {
// default zh-CN
default: 'zh-CN',
antd: true,
// default true, when it is true, will use `navigator.language` overwrite default
baseNavigator: true,
},
});
```
**存在差异的配置项**如下 `config/config.ts` ：
```typescript
import { defineConfig, utils } from 'umi';
export default defineConfig({
- fastRefresh: {},
+ fastRefresh: true,
dva: {
// 不再支持 hmr 这个参数
- hmr: true,
},
// 默认 webpack5
- webpack5: {},
})
```
### 代码层修改
Umi 4 中将 `react-router@5` 升级到 `react-router@6`，所以路由相关的一些 api 存在着使用上的差异。
props 默认为空对象，以下属性都不能直接从 props 中取出
#### children
```typescript
import { Outlet } from 'umi';
;
```
主要在全局 layout 中需要修改
如 `layouts/index.tsx`：
```diff
import React from 'react';
+ import { Outlet } from 'umi';
export default function Layout(props) {
return (
- { props.children }
+
);
}
```
使用了 `React.cloneElement` 方式渲染的路由组件改造，示例
```diff
import React from 'react';
+ import { Outlet } from 'umi';
export default function RouteComponent(props) {
return (
);
}
```
或者
```diff
+ import { useLocation } from 'umi';
export default function Page(props) {
+ let location = useLocation();
return (
- { props.location }
+ { location }
);
}
```
#### match
```diff
+ import { useMatch } from 'umi';
export default function Page(props) {
+ const match = useMatch({ path: 'list/search/:type' });
return (
- { props.match }
+ { match }
);
}
```
在 class component 组件中的使用方式:
```diff
import { matchPath } from 'umi';
class Page extends Component {
+ match = matchPath({ path: 'list/search/:type' }, window.location.pathname);
state = {}
render() {
return (
- {this.props.match.type}
+ {this.match.type}
)
}
}
```
更多 `Umi` 相关 [api](https://umijs.org/docs/api/api)
需要注意 match 数据的差异：
```
// match v5
isExact: true
params: {}
path: "/users/abc"
url: "/users/abc"
// match v6
params:{ }
pathname: "/list/search/articles"
pathnameBase: "/list/search/articles"
pattern: {path: 'list/search/:type'}
```
更多改动和 api 变更，请查阅 [react-router@6](https://reactrouter.com/docs/en/v6/api#uselocation)
完成以上操作后，执行下 `max dev`，访问 [http://localhost:8000](http://localhost:8000)，请验证所有功能都符合预期。
如果你的项目无法正常启动，你可能还需要做如下操作：
## 配置变更
TODO
## FAQ
### location 中的 query 找不到？
location 中的 query 不再支持了，后续推荐用 [search](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
```diff
- const { query } = history.location;
+ import { parse } from 'query-string';
+ const query = parse(history.location.search);
```
### \*.d 文件找不到，或者它的引用找不到
在 `umi@3` 中通过 `import` 会自动找到同名的 `.d.ts` 文件，如：
`import { ButtonType } from './button';`
如果存在 `.button.d.ts` 文件，在 `umi@3` 中会正确执行，但是在 umi@4 中会发生报错，你可能需要更加规范的引用类型。
```diff
- import { ButtonType } from './button';
+ import type { ButtonType } from './button.d';
```
---
### Docs Docs Max Access.En US (`docs/docs/docs/max/access.en-US.md`)
---
order: 7
toc: content
translated_at: '2024-03-17T09:49:43.250Z'
---
# Permissions
## How to Enable
Configuring activation. Requires `src/access.ts` to provide permission configuration.
```ts
export default {
access: {},
// access plugin depends on the initial State so it needs to be enabled at the same time
initialState: {},
};
```
## Introduction
We have agreed that `src/access.ts` is our permission definition file, which needs to export a function by default. The method will be executed when the project is initialized. This method needs to return an object, where each value of the object corresponds to a defined permission. As shown below:
```js
// src/access.ts
export default function (initialState) {
const { userId, role } = initialState;
return {
canReadFoo: true,
canUpdateFoo: role === 'admin',
canDeleteFoo: (foo) => {
return foo.ownerId === userId;
},
};
}
```
Where `initialState` is the data provided by the initialization state plugin `initial-state`, you can use this data to initialize your user permissions.
## Configuration
### Extended Routing Configuration
With the [layout](./layout-menu) plugin, you can easily implement permission control for some pages. As shown below, users can access the page only if they have the canReadPageA permission (defined in `src/access.ts`). Otherwise, it will render the default permission error page built into the Layout plugin by default.
```ts
export const routes = [
{
path: '/pageA',
component: 'PageA',
access: 'canReadPageA', // Some key of the permission definition return value
},
];
```
### Custom Permission Page Configuration
As mentioned above, to configure a custom permission page, you need to define it in `src/app.tsx`.
```tsx
export const layout: RunTimeLayoutConfig = () => {
return {
// Customize the 403 page
unAccessible:
'unAccessible'
,
// Customize the 404 page
noFound:
'noFound'
,
};
};
```
#### access
- Type: `string`
The corresponding permission name.
## API
### useAccess
We provide a hook for obtaining permission-related information in components, as shown below:
```js
import React from 'react';
import { useAccess } from 'umi';
const PageA = (props) => {
const { foo } = props;
the access = useAccess();
if (access.canReadFoo) {
// If can read Foo, then...
}
return <>TODO;
};
export default PageA;
```
Combined with the `Access` component, it's easy to control the permissions of elements within pages.
### Access
You can use the `useAccess` hook and the `` component provided by the plugin to control permissions in your application. The `Access` component supports the following properties:
#### accessible
- Type: `boolean`
Whether permission is granted, usually obtained through `useAccess` and passed in.
#### fallback
- Type: `React.ReactNode`
The display when there is no permission, by default no content is displayed without permission.
### children
- Type: `React.ReactNode`
What is displayed when permission is granted.
A complete example is as follows:
```js
import React from 'react';
import { useAccess, Access } from 'umi';
const PageA = (props) => {
const { foo } = props;
const access = useAccess(); // members of access: canReadFoo, canUpdateFoo, canDeleteFoo
if (access.canReadFoo) {
// If can read Foo, then...
}
return (
Can not read foo content.
}
>
Foo content.
Can not update foo.}
>
Update foo.
Can not delete foo.}
>
Delete foo.
);
};
```
- The return value `access` of `useAccess()` is the set of permissions defined in `src/access.ts`, which can be used to control the flow of code execution within components.
- The `` component has two properties: `accessible` and `fallback`. When `accessible` is `true`, it will render the child component; when `accessible` is `false`, it will render the `ReactNode` corresponding to the `fallback` property.
---
### Docs Docs Max Access (`docs/docs/docs/max/access.md`)
---
order: 7
toc: content
---
# 权限
## 启用方式
配置开启。同时需要 `src/access.ts` 提供权限配置。
```ts
export default {
access: {},
// access 插件依赖 initial State 所以需要同时开启
initialState: {},
};
```
## 介绍
我们约定了 `src/access.ts` 为我们的权限定义文件，该文件需要默认导出一个方法，导出的方法会在项目初始化时被执行。该方法需要返回一个对象，对象的每一个值就对应定义了一条权限。如下所示：
```js
// src/access.ts
export default function (initialState) {
const { userId, role } = initialState;
return {
canReadFoo: true,
canUpdateFoo: role === 'admin',
canDeleteFoo: (foo) => {
return foo.ownerId === userId;
},
};
}
```
其中 `initialState` 是通过初始化状态插件 `initial-state` 提供的数据，你可以使用该数据来初始化你的用户权限。
## 配置
### 扩展的路由配置
配合 [layout](./layout-menu) 插件你可以很简单的实现针对某些页面的权限控制。如下所示，只有拥有了 canReadPageA （在 `src/access.ts` 中定义）权限，用户才可以访问该页面。否则会默认渲染 Layout 插件内置的权限错误页面。
```ts
export const routes = [
{
path: '/pageA',
component: 'PageA',
access: 'canReadPageA', // 权限定义返回值的某个 key
},
];
```
### 自定义权限页面配置
上面说到默认渲染 Layout 插件内置的权限错误页面，如果想配置自定义权限页面需要在 `src/app.tsx` 中定义。
```tsx
export const layout: RunTimeLayoutConfig = () => {
return {
// 自定义 403 页面
unAccessible:
}
>
Foo content.
Can not update foo.}
>
Update foo.
Can not delete foo.}
>
Delete foo.
);
};
```
- `useAccess()` 的返回值 `access` 就是 `src/access.ts` 中定义的权限集合，可以利用它进行组件内代码执行流的控制。
- `` 组件拥有 `accessible` 和 `fallback` 两个属性，当 `accessible` 为 `true` 时会渲染子组件，当 `accessible` 为 `false` 会渲染 `fallback` 属性对应的 `ReactNode`。
---
### Docs Docs Max Analytics.En US (`docs/docs/docs/max/analytics.en-US.md`)
---
order: 14
toc: content
translated_at: '2024-03-17T09:48:57.403Z'
---
# Site Statistics
`@umijs/max` has built-in site statistics functionality, currently supporting [Google Analytics](https://analytics.google.com/analytics/web/) and [Baidu Analytics](https://tongji.baidu.com/web/welcome/login)
## How to Enable
Configure it to be enabled and enter the respective analytics service key as required.
Example:
```ts
{
analytics: {
ga_v2: 'G-abcdefg', // google analytics key (GA 4)
baidu: 'baidu_tongji_key',
// If you are using the old version GA v1, please use `ga` to configure
ga: 'ga_old_key'
}
}
```
### Environment Variables
The key for [Google Analytics 4](https://support.google.com/analytics/answer/10089681) can also be configured through the environment variable `GA_V2_KEY`, and the old version uses `GA_KEY`.
---
### Docs Docs Max Analytics (`docs/docs/docs/max/analytics.md`)
---
order: 14
toc: content
---
# 站点统计
`@umijs/max` 内置了站点统计的功能，目前支持 [Google Analytics](https://analytics.google.com/analytics/web/) 和[百度统计](https://tongji.baidu.com/web/welcome/login)
## 启用方式
配置开启，按照需求配置进对应的统计服务的 key 即可。
举例：
```ts
{
analytics: {
ga_v2: 'G-abcdefg', // google analytics 的 key (GA 4)
baidu: 'baidu_tongji_key',
// 若你在使用 GA v1 旧版本，请使用 `ga` 来配置
ga: 'ga_old_key'
}
}
```
### 环境变量
[Google Analytics 4](https://support.google.com/analytics/answer/10089681) 的 key 也可以通过环境变量 `GA_V2_KEY` 来配置，旧版本为 `GA_KEY` 。
---
### Docs Docs Max Antd.En US (`docs/docs/docs/max/antd.en-US.md`)
---
order: 3
toc: content
translated_at: '2024-03-17T09:48:51.045Z'
---
# antd
Integration of the antd component library.
## How to Enable
Configure to enable, example:
```ts
// config/config.ts
export default {
antd: {
// configProvider
configProvider: {},
// themes
dark: true,
compact: true,
// babel-plugin-import
import: true,
// less or css, default less
style: 'less',
// shortcut of `configProvider.theme`
// used to configure theme token, antd v5 only
theme: {},
// antd valid for version 5.1.0 or higher, default: undefined
appConfig: {},
// Transform DayJS to MomentJS
momentPicker: true,
// Add StyleProvider for legacy browsers
styleProvider: {
hashPriority: 'high',
legacyTransformer: true,
},
},
};
```
## Introduction
Includes the following features:
1. Built-in [antd](https://ant.design/), the current built-in version is `^4.0.0`
2. On-demand compilation based on [babel-plugin-import](https://github.com/ant-design/babel-plugin-import)
3. When using antd@4, you can switch to the dark theme with one click, see the image below
## Configuration
### Build-time Configuration
Note: Build-time configuration will go through JSON conversion, so here you can only set configurations that conform to the JSON format. For function configurations like `algorithm`, set them at [Runtime Configuration](#runtime-configuration).
#### dark
Enables dark theme.
- Type: `boolean`
- Default: `false`
#### compact
Enables compact theme.
- Type: `boolean`
- Default: `false`
For example:
```ts
export default {
antd: {
dark: true,
compact: true,
},
};
```
Dark theme activation is only supported with antd version 4. Compact theme is supported with `antd@>4.1.0`.
#### import
- Type: `boolean`
Configure `antd`'s `babel-plugin-import` for on-demand loading.
#### style
- Type: `"less" | "css"`
- Default: `less`
Configure the use of `antd` styles, default is `less`.
#### configProvider
- Type: `object`
Configure `antd`'s `configProvider`.
#### theme
- Type: `object`
Configure theme token for `antd@5`, equivalent to setting `configProvider.theme`, and this configuration item has higher priority.
**Note: This configuration is only available for antd v5**
#### appConfig
- Type: `object`
Configure the App wrapper component for `antd`, please note that for `antd@5.1.0 ~ 5.2.3`, it can only be enabled through `appConfig: {}`, and only `antd >=5.3.0` supports more App configuration projects.
**Note: This configuration is only available for antd v5.1.0 and above**
#### momentPicker
- Type: `boolean`
Configure whether `antd`'s `DatePicker`, `TimePicker`, `Calendar` components use `moment` as the date processing library, default is `false`.
**Note: This configuration is only available for antd v5 and above**
#### styleProvider
- Type: `object`
Configure `antd`'s `StyleProvider` component, which is used to support legacy browsers, such as IE11. When your project is configured with `legacy` or `targets` that include `ie`, it will automatically be downgraded, no manual configuration required.
With antd 5.17.0 and above, set `styleProvider: { layer: true }` to place component styles in `@layer antd` and lower their priority. Also set `antd.configProvider: {}` (or keep your existing configuration) to enable an inner `ConfigProvider` for icon styles. Set `layer: false` to explicitly disable it; leaving it unset preserves the default or inherited `StyleProvider` behavior.
**Note:**
1. This configuration is only available for antd v5 and above.
2. The downgrade of CSS relies on [`@ant-design/cssinjs`](https://ant.design/docs/react/compatible-style-cn). If you have explicitly installed `antd`, please also install and ensure that your `@ant-design/cssinjs` version corresponds correctly with `antd`.
### Runtime Configuration
In the runtime configuration of `app.ts(x)`, you can modify the values of antd's `ConfigProvider`. Before using this feature, **make sure you have enabled the `antd.configProvider` option**, otherwise changes to `ConfigProvider` will not take effect:
```ts
// .umirc.ts
antd: {
configProvider: {}
}
```
For example, to configure antd 5's theme preset algorithm and the maximum number of `message` notifications:
```ts
// app.ts
import { RuntimeAntdConfig } from 'umi';
import { theme } from 'antd';
export const antd: RuntimeAntdConfig = (memo) => {
memo.theme ??= {};
memo.theme.algorithm = theme.darkAlgorithm; // Configure the preset dark algorithm for antd5
memo.appConfig = {
message: {
// Configure the maximum number of messages displayed, when exceeding the limit, the earliest messages will be automatically closed
maxCount: 3,
}
}
return memo;
};
```
### Dynamically Switch Global Configuration
**Note: This feature is only available for antd v5**
Use `useAntdConfig` / `useAntdConfigSetter` methods to dynamically get and modify antd's `ConfigProvider` configuration, which can typically be used to dynamically modify themes.
Note: This feature depends on `ConfigProvider`, please also enable `configProvider: {}`.
```tsx
import { Layout, Space, Button, version, theme, MappingAlgorithm } from 'antd';
import { useAntdConfig, useAntdConfigSetter } from 'umi';
const { darkAlgorithm, defaultAlgorithm } = theme;
export default function Page() {
const setAntdConfig = useAntdConfigSetter();
const antdConfig = useAntdConfig();
return (
isDarkTheme
{
// 此配置会与原配置深合并
setAntdConfig({
theme: {
algorithm: [
data ? darkAlgorithm : defaultAlgorithm,
],
},
});
// or
setAntdConfig((config) => {
const algorithm = config.theme!.algorithm as MappingAlgorithm[];
if (algorithm.includes(darkAlgorithm)) {
config.theme!.algorithm = [defaultAlgorithm]
} else {
config.theme!.algorithm = [darkAlgorithm];
}
return config;
});
}}
>
);
}
```
使用 `setAntdConfig` 可以动态修改 [antd@5 ConfigProvider](https://ant.design/components/config-provider-cn) 组件支持的所有属性。
## FAQ
### 如何使用 antd 的其他版本？
在项目中安装你需要的 antd 版本。
---
### Docs Docs Max Charts.En US (`docs/docs/docs/max/charts.en-US.md`)
---
order: 4
toc: content
translated_at: '2024-03-17T09:39:12.613Z'
---
# Charts
The Umi team recommends using [Ant Design Charts](https://charts.ant.design/) or [Pro Components](https://procomponents.ant.design/) in line with Ant Design to add visualization charts 📈 to your project.
This tutorial will provide you with some common use cases.
## Ant Design Charts
Ant Design Charts is a React implementation of the [AntV](https://antv.vision/en) project, developed by the data visualization team of Ant Group.
You can install the complete Ant Design Charts package:
```bash
pnpm install @ant-design/charts
```
You can also just include the sub-packages you use, for example:
```bash
# Install statistical chart package
pnpm install @ant-design/plots
```
In the example usage below, we will keep imports to a minimum.
You can also directly read the complete [Getting Started documentation](https://charts.ant.design/en/docs/manual/getting-started) and [Chart Examples](https://charts.ant.design/en/examples/gallery) of Ant Design Charts.
### Line Chart
Now, we need to create a line chart to display [these data](https://gw.alipayobjects.com/os/bmw-prod/1d565782-dde4-4bb6-8946-ea6a38ccf184.json).
First, include the statistical chart package:
```bash
pnpm install @ant-design/plots
```
Write code to fetch the data (omitted below):
```tsx
import { useState, useEffect } from 'react';
const DemoLine = () => {
const [data, setData] = useState([]);
useEffect(() => {
asyncFetch();
}, []);
const asyncFetch = () => {
fetch('https://gw.alipayobjects.com/os/bmw-prod/1d565782-dde4-4bb6-8946-ea6a38ccf184.json')
.then((response) => response.json())
.then((json) => setData(json))
.catch((error) => {
console.log('fetch data failed', error);
});
};
};
```
Thus, we have obtained the data and saved the JSON object's content to `data`. Each data object is like:
```json
{
"Date": "2010-01",
"scales": 1998,
}
```
Display the data on the line chart:
```tsx
import React from 'react';
import { Line } from '@ant-design/plots';
const DemoLine: React.FC = () => {
// fetch data
const config = {
data,
padding: 'auto',
xField: 'Date',
yField: 'scales',
xAxis: {
// type: 'timeCat',
tickCount: 5,
},
smooth: true,
};
return ;
};
```
In this, the `Date` attribute in `data` will serve as the X-axis horizontal axis of the line chart, and the `scales` attribute will serve as the Y-axis vertical axis for drawing.
The complete line chart code and effect can be viewed on [this page](https://charts.ant.design/en/examples/line/basic#spline).
### Column Chart
Now, we need to display the page load time through a column chart.
First, include the statistical chart package:
```bash
pnpm install @ant-design/plots
```
Suppose we have the following `data`:
```ts
const data = [
{
type: '0-1 seconds',
value: 0.55,
},
{
type: '1-3 seconds',
value: 0.21,
},
{
type: '3-5 seconds',
value: 0.13,
},
{
type: '5+ seconds',
value: 0.11,
},
];
```
Especially, for the case of `5+ seconds`, we want to mark it with a bright color. Then we can write the column chart code as follows:
```tsx
import React from 'react';
import { Column } from '@ant-design/plots';
const DemoColumn: React.FC = () => {
// fetch data
const paletteSemanticRed = '#F4664A';
const brandColor = '#5B8FF9';
const config = {
data,
xField: 'type',
yField: 'value',
seriesField: '',
color: ({ type }) => {
if (type === '5+ seconds') {
return paletteSemanticRed;
}
return brandColor;
},
legend: false,
xAxis: {
label: {
autoHide: true,
autoRotate: false,
},
},
};
return ;
};
```
The complete column chart code and effect can be viewed on [this page](https://charts.ant.design/en/examples/column/basic#color).
### Word Cloud
Now, we need to display the names of some countries in the world in a word cloud manner. The more populous the country, the larger the font size of its name in the word cloud.
First, include the statistical chart package:
```bash
pnpm install @ant-design/plots
```
Get the [`data`](https://gw.alipayobjects.com/os/antfincdn/jPKbal7r9r/mock.json) containing country population figures. It looks like:
```json
{
"country": "China",
"value": 1383220000,
"category": "asia",
}
```
Render the data to get the word cloud:
```tsx
import React from 'react';
import { WordCloud } from '@ant-design/plots';
const DemoWordCloud: React.FC = () => {
// fetch data
const config = {
data,
wordField: 'country',
weightField: 'value',
color: '#122c6a',
interactions: [
{
type: 'element-active',
},
],
state: {
active: {
style: {
lineWidth: 2,
},
},
},
};
return ;
};
```
The complete word cloud code and effect can be viewed on [this page](https://charts.ant.design/en/examples/more-plots/word-cloud#basic).
### Dot Map
Now, we need to display the distribution of cities and districts in our country on the map in the form of dots.
First, include the map package:
```bash
pnpm install @ant-design/maps
```
Get the [`data`](https://gw.alipayobjects.com/os/antfincdn/g5hIthhKlr/quanguoshixianweizhi.json) containing all district data. It looks like:
```json
{
"list": [
{
"lnglat": [
116.258446,
37.686622
],
"name": "Jing County",
"style": 2
},
// ...
]
}
```
Where, `style` of `0` stands for municipal city, `1` for county-level city, and `2` for district.
Render the data to get the dot map:
```tsx
import React from 'react';
import { DotMap } from '@ant-design/maps';
const DemoDotMap: React.FC = () => {
// fetch data
const config = {
map: {
type: 'mapbox',
style: 'dark',
zoom: 3,
center: [107.4976, 32.1697],
pitch: 0,
},
source: {
data,
parser: {
type: 'json',
coordinates: 'lnglat',
},
},
size: 4,
color: {
field: 'style',
value: ({ style }) => {
if (style == 0) {
return '#14B4C9';
} else if (style == 1) {
return '#3771D9';
} else {
return '#B8EFE2';
}
},
},
legend: {
type: 'category',
position: 'bottomleft',
items: [
{
color: '#14B4C9',
value: 'Municipal city',
},
{
color: '#3771D9',
value: 'County-level city',
},
{
color: '#B8EFE2',
value: 'District',
},
],
},
};
return ;
};
```
The complete dot map code and effect can be viewed on [this page](https://charts.ant.design/en/examples/map-dot/map-scatter#distribution-cities).
## Pro Components
Pro Components are aimed at mid-to-background applications, offering a higher degree of abstraction on top of Ant Design, providing a higher-level design specification to help developers quickly build high-quality pages.
You should import the sub-packages you use as needed:
```bash
# Import advanced table
pnpm install @ant-design/pro-table
# Import advanced list
pnpm install @ant-design/pro-list
```
You can also directly read Pro Components' complete [Getting Started documentation](https://procomponents.ant.design/docs/getting-started), [Table Examples](https://procomponents.ant.design/components/table) and [List Examples](https://procomponents.ant.design/components/list).
The examples below will assume you have already imported the sub-packages you will use.
### Pro Table Advanced Table
Now, you need to quickly build a table containing members and related information.
Member information is as follows:
```ts
const realNames = ['Ma Baba', 'Zhang Sanfeng', 'Fei Peng', 'Xu Changqing'];
const nickNames = ['Baba', 'Junbao', 'Jingtian', 'Mr. Xu'];
const emails = ['baba@antfin.com', 'junbao@antfin.com', 'jingtian@antfin.com', 'xvzhangmen@antfin.com'];
const phones = ['18800001234', '13900002345', '17200003456', '17800004567'];
```
Define a `Member` type:
```ts
export type Member = {
id: number;
realName: string;
nickName: string;
email: string;
phone: string;
};
```
Process member information to build a `Member` array:
```ts
const memberList: Member[] = [];
for (let i = 0; i < realNames.length; i++) {
memberList.push({
id: `${102047 + i}`,
realName: realNames[i],
nickName: nickNames[i],
email: emails[i],
phone: phones[i],
});
}
```
Pass the array to Pro Table to quickly build the table:
```tsx
import React from 'react';
import type { ProColumns } from '@ant-design/pro-table';
import ProTable from '@ant-design/pro-table';
// resolve member info list
const MemberList: React.FC = () => {
const columns: ProColumns[] = [
{
dataIndex: 'realName',
title: 'Name',
},
{
dataIndex: 'nickName',
title: 'Nickname',
},
{
dataIndex: 'email',
title: 'Account',
},
{
dataIndex: 'phone',
title: 'Phone number',
},
{
title: 'Action',
dataIndex: 'x',
valueType: 'option',
render: (_, record) => {
return [Edit, Remove];
},
},
];
return (
columns={columns}
request={(params, sorter, filter) => {
console.log(params, sorter, filter);
return Promise.resolve({
data: memberList,
success: true,
});
}}
rowKey="id"
pagination={{
showQuickJumper: true,
}}
toolBarRender={false}
search={false}
/>
);
}
```
The complete table code and effect can be viewed on [this page](https://procomponents.ant.design/components/table).
### Pro List Advanced List
Now, you need to quickly build a list containing test information.
Test information is as follows:
```ts
export type Test = {
id: number;
name: string;
image: string;
desc: string;
};
const testList: Test[] = [
{
id: 9903,
name: 'Yuque\'s Sky',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: 'Covered all test cases for the login module',
},
{
id: 9904,
name: 'Ant Design',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: 'Covered all test cases, all scenarios have been verified under the Node 17 testing environment',
},
{
id: 9905,
name: 'Ant Group Experience Technology',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: 'Covered all testing requirements, all scenarios have been verified under the Ubuntu 14.04 testing environment',
},
{
id: 9906,
name: 'TechUI',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: 'Covered all testing requirements, all scenarios have been verified under MacOS testing environment',
},
];
```
Pass the test information to Pro List to quickly build the list:
```tsx
import React from 'react';
import { Button } from 'antd';
import ProList from '@ant-design/pro-list';
// resolve test info list
const MemberList: React.FC = () => {
return (
toolBarRender={() => {
return [
,
];
}}
rowKey="id"
headerTitle="Test Results"
dataSource={testList}
showActions="hover"
showExtra="hover"
metas={{
title: {
dataIndex: 'name',
},
avatar: {
dataIndex: 'image',
},
description: {
dataIndex: 'desc',
},
actions: {
render: (text, row) => [
Link,
Alert,
View,
],
},
}}
/>
);
}
```
The complete list code and effect can be viewed on [this page](https://procomponents.ant.design/components/list).
---
### Docs Docs Max Charts (`docs/docs/docs/max/charts.md`)
---
order: 4
toc: content
---
# 图表
Umi 团队推荐使用与 Ant Design 一脉相承的 [Ant Design Charts](https://charts.ant.design/) 或 [Pro Components](https://procomponents.ant.design/) 来为您的项目添加可视化图表 📈。
本教程将为您提供一些常见的使用案例。
## Ant Design Charts
Ant Design Charts 是 [AntV](https://antv.vision/zh) 项目的 React 实现，由蚂蚁集团数据可视化团队开发。
您可以安装完整的 Ant Design Charts 包：
```bash
pnpm install @ant-design/charts
```
也可以仅引入使用到的子包，例如：
```bash
# 安装统计图表包
pnpm install @ant-design/plots
```
在下面的使用示例中，我们将最小化引入。
您也可以直接阅读 Ant Design Charts 完整的[上手文档](https://ant-design-charts.antgroup.com/manual/getting-started)和[图表示例](https://ant-design-charts.antgroup.com/examples)。
### 曲线图
现在，我们需要将[这些数据](https://gw.alipayobjects.com/os/bmw-prod/1d565782-dde4-4bb6-8946-ea6a38ccf184.json)制作为一个曲线图展示出来。
首先，引入统计图表包：
```bash
pnpm install @ant-design/plots
```
编写代码获取数据（后略）：
```tsx
import { useState, useEffect } from 'react';
const DemoLine = () => {
const [data, setData] = useState([]);
useEffect(() => {
asyncFetch();
}, []);
const asyncFetch = () => {
fetch('https://gw.alipayobjects.com/os/bmw-prod/1d565782-dde4-4bb6-8946-ea6a38ccf184.json')
.then((response) => response.json())
.then((json) => setData(json))
.catch((error) => {
console.log('fetch data failed', error);
});
};
};
```
这样，我们获取到了数据，并将数据 JSON 对象的内容保存到 `data` 中去。每个数据对象形如：
```json
{
"Date": "2010-01",
"scales": 1998,
}
```
将数据展示到曲线图上：
```tsx
import React from 'react';
import { Line } from '@ant-design/plots';
const DemoLine: React.FC = () => {
// fetch data
const config = {
data,
padding: 'auto',
xField: 'Date',
yField: 'scales',
xAxis: {
// type: 'timeCat',
tickCount: 5,
},
smooth: true,
};
return ;
};
```
其中，`data` 中数据的 `Date` 属性将作为曲线图的 X 横坐标，`scales` 属性将作为曲线图的 Y 纵坐标绘图。
完整的曲线图代码和效果可查看[此页面](https://charts.ant.design/zh/examples/line/basic#spline)。
### 柱状图
现在，我们需要把页面加载的时间通过柱状图展示出来。
首先，引入统计图表包：
```bash
pnpm install @ant-design/plots
```
假设我们有如下 `data`：
```ts
const data = [
{
type: '0-1 秒',
value: 0.55,
},
{
type: '1-3 秒',
value: 0.21,
},
{
type: '3-5 秒',
value: 0.13,
},
{
type: '5+ 秒',
value: 0.11,
},
];
```
特别的，对于 `5+ 秒` 的情况，我们想要用鲜明的颜色标注出来。那么可以编写柱状图代码如下：
```tsx
import React from 'react';
import { Column } from '@ant-design/plots';
const DemoColumn: React.FC = () => {
// fetch data
const paletteSemanticRed = '#F4664A';
const brandColor = '#5B8FF9';
const config = {
data,
xField: 'type',
yField: 'value',
seriesField: '',
color: ({ type }) => {
if (type === '5+ 秒') {
return paletteSemanticRed;
}
return brandColor;
},
legend: false,
xAxis: {
label: {
autoHide: true,
autoRotate: false,
},
},
};
return ;
};
```
完整的柱状图代码和效果可查看[此页面](https://charts.ant.design/zh/examples/column/basic#color)。
### 词云
现在，我们需要把世界上部分国家的名字以词云的方式展示出来。国家的人数越多，词云上国家的名字字体越大。
首先，引入统计图表包：
```bash
pnpm install @ant-design/plots
```
获取包含国家人口数量的 [`data`](https://gw.alipayobjects.com/os/antfincdn/jPKbal7r9r/mock.json)。形如：
```json
{
"country": "China",
"value": 1383220000,
"category": "asia",
}
```
渲染数据，获得词云图：
```tsx
import React from 'react';
import { WordCloud } from '@ant-design/plots';
const DemoWordCloud: React.FC = () => {
// fetch data
const config = {
data,
wordField: 'country',
weightField: 'value',
color: '#122c6a',
interactions: [
{
type: 'element-active',
},
],
state: {
active: {
style: {
lineWidth: 2,
},
},
},
};
return ;
};
```
完整的词云图代码和效果可查看[此页面](https://charts.ant.design/zh/examples/more-plots/word-cloud#basic)。
### 散点地图
现在，我们需要将我国城市和区县分布在地图上以散点的形式展示出来。
首先，引入地图包：
```bash
pnpm install @ant-design/maps
```
获取包含所有区县数据的 [`data`](https://gw.alipayobjects.com/os/antfincdn/g5hIthhKlr/quanguoshixianweizhi.json)。形如：
```json
{
"list": [
{
"lnglat": [
116.258446,
37.686622
],
"name": "景县",
"style": 2
},
// ...
]
}
```
其中，`style` 为 `0` 表示为地级市，`1` 表示为县城市，`2` 表示为区县。
渲染数据，获得散点地图：
```tsx
import React from 'react';
import { DotMap } from '@ant-design/maps';
const DemoDotMap: React.FC = () => {
// fetch data
const config = {
map: {
type: 'mapbox',
style: 'dark',
zoom: 3,
center: [107.4976, 32.1697],
pitch: 0,
},
source: {
data,
parser: {
type: 'json',
coordinates: 'lnglat',
},
},
size: 4,
color: {
field: 'style',
value: ({ style }) => {
if (style == 0) {
return '#14B4C9';
} else if (style == 1) {
return '#3771D9';
} else {
return '#B8EFE2';
}
},
},
legend: {
type: 'category',
position: 'bottomleft',
items: [
{
color: '#14B4C9',
value: '地级市',
},
{
color: '#3771D9',
value: '县城市',
},
{
color: '#B8EFE2',
value: '区县',
},
],
},
};
return ;
};
```
完整的散点地图代码和效果可查看[此页面](https://charts.ant.design/zh/examples/map-dot/map-scatter#distribution-cities)。
## Pro Components
Pro Components 面向中后台类应用，对 Ant Design 进行了更高程度的抽象，提供了更上层的设计规范，能够助开发者快速搭建出高质量的页面。
您应当按需引入使用到的子包：
```bash
# 引入高级表格
pnpm install @ant-design/pro-table
# 引入高级列表
pnpm install @ant-design/pro-list
```
您也可以直接阅读 Pro Components 完整的[上手文档](https://procomponents.ant.design/docs/getting-started)，[表格示例](https://procomponents.ant.design/components/table)和[列表示例](https://procomponents.ant.design/components/list)。
下面的示例中将默认您已经引入了使用到的子包。
### Pro Table 高级表格
现在，您需要快速构建一个包含有成员和相关信息的表格。
成员信息如下：
```ts
const realNames = ['马巴巴', '张三丰', '飞蓬', '徐长卿'];
const nickNames = ['巴巴', '君宝', '景天', '姓徐的'];
const emails = ['baba@antfin.com', 'junbao@antfin.com', 'jingtian@antfin.com', 'xvzhangmen@antfin.com'];
const phones = ['18800001234', '13900002345', '17200003456', '17800004567'];
```
定义一个 `Member` 类型：
```ts
export type Member = {
id: number;
realName: string;
nickName: string;
email: string;
phone: string;
};
```
处理成员信息，构建一个 `Member` 数组：
```ts
const memberList: Member[] = [];
for (let i = 0; i < realNames.length; i++) {
memberList.push({
id: `${102047 + i}`,
realName: realNames[i],
nickName: nickNames[i],
email: emails[i],
phone: phones[i],
});
}
```
将数组传递给 Pro Table，快速构建表格：
```tsx
import React from 'react';
import type { ProColumns } from '@ant-design/pro-table';
import ProTable from '@ant-design/pro-table';
// resolve member info list
const MemberList: React.FC = () => {
const columns: ProColumns[] = [
{
dataIndex: 'realName',
title: '姓名',
},
{
dataIndex: 'nickName',
title: '昵称',
},
{
dataIndex: 'email',
title: '账号',
},
{
dataIndex: 'phone',
title: '手机号',
},
{
title: '操作',
dataIndex: 'x',
valueType: 'option',
render: (_, record) => {
return [编辑, 移除];
},
},
];
return (
columns={columns}
request={(params, sorter, filter) => {
console.log(params, sorter, filter);
return Promise.resolve({
data: memberList,
success: true,
});
}}
rowKey="id"
pagination={{
showQuickJumper: true,
}}
toolBarRender={false}
search={false}
/>
);
}
```
完整的表格代码和效果可查看[此页面](https://procomponents.ant.design/components/table)。
### Pro List 高级列表
现在，您需要快速构建一个包含测试信息的列表。
测试信息如下：
```ts
export type Test = {
id: number;
name: string;
image: string;
desc: string;
};
const testList: Test[] = [
{
id: 9903,
name: '语雀的天空',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: '覆盖了登录模块的所有测试用例',
},
{
id: 9904,
name: 'Ant Design',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: '覆盖了所有测试用例，所有的案例均已在 Node 17 测试环境验证完成',
},
{
id: 9905,
name: '蚂蚁集团体验科技',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: '覆盖了所有测试需求，所有的案例均已在 Ubuntu 14.04 测试环境验证完成',
},
{
id: 9906,
name: 'TechUI',
image:
'https://gw.alipayobjects.com/zos/antfincdn/efFD%24IOql2/weixintupian_20170331104822.jpg',
desc: '覆盖了所有测试需求，所有的案例均已在 MacOS 测试环境验证完成',
},
];
```
将测试信息传递给 Pro List，快速构建列表：
```tsx
import React from 'react';
import { Button } from 'antd';
import ProList from '@ant-design/pro-list';
// resolve test info list
const MemberList: React.FC = () => {
return (
toolBarRender={() => {
return [
,
];
}}
rowKey="id"
headerTitle="测试结果"
dataSource={testList}
showActions="hover"
showExtra="hover"
metas={{
title: {
dataIndex: 'name',
},
avatar: {
dataIndex: 'image',
},
description: {
dataIndex: 'desc',
},
actions: {
render: (text, row) => [
链路,
报警,
查看,
],
},
}}
/>
);
}
```
完整的列表代码和效果可查看[此页面](https://procomponents.ant.design/components/list)。
---
### Docs Docs Max Data Flow.En US (`docs/docs/docs/max/data-flow.en-US.md`)
---
order: 5
toc: content
translated_at: '2024-03-18T00:49:20.502Z'
---
# Data Stream
`@umi/max` has a built-in **data flow management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts), which is a lightweight data management solution based on the `hooks` paradigm. It can be used to manage global shared data in Umi projects.
## Configuration
e.g.
```ts
export default {
model: {
extraModels: ['src/models/userModel.ts'],
preferSourceNamespace: false,
sort: (a, b) => a.namespace.localeCompare(b.namespace),
},
};
```
### extraModels
- Type: `string[]`
- Default: `[]`
Configure `extraModels` to automatically add these Model files to the data stream management.
### preferSourceNamespace
- Type: `boolean`
- Default: `false`
Whether to resolve `namespace` from Model source (applies to both conventional Models and `extraModels`).
It is off by default so a business return field named `namespace` is not mistaken for the registry key. When enabled, the `namespace` declared in source takes precedence, which helps customize namespaces when sharing Models across a monorepo / packages.
```ts
// .umirc.ts
export default {
model: {
preferSourceNamespace: true,
// extraModels: ['../../packages/shared/src/models/tenant.ts'],
},
};
// model source
export default () => ({
namespace: 'businessTenant',
user: null,
});
// usage
useModel('businessTenant');
```
:::warning{title=Note}
After enabling this, do not return `namespace` as a normal business field; it will be parsed as the Model registry name. To customize the namespace for a single file only, append `#{"namespace":"xxx"}` to the path instead of turning this option on.
:::
### sort
- Type: `(a: Model, b: Model) => number`
- Default: `(a, b) => a.namespace.localeCompare(b.namespace)`
Configure `sort` to sort the Model based on the return value of the `sort` function.
## Getting Started
### Creating a Model
The data flow management plugin adopts a conventional directory structure. We agree that Model files can be introduced in the `src/models`, `src/pages/xxxx/models/` directories, and in `src/pages/xxxx/model.{js,jsx,ts,tsx}` files.
Model files can have one of four suffix formats: `.(tsx|ts|jsx|js)`. The **namespace** priority is as follows:
1. Path `#meta`: `path/to/model.ts#{"namespace":"xxx"}`
2. `namespace` in source: requires `preferSourceNamespace`
3. Path convention (default)
Path convention rules:
| Path | Namespace | Description |
| :--- |:--- | :--- |
| `src/models/count.ts` | `count` | Defining model in `src/models` directory does not support directory nesting |
| `src/pages/pageA/model.ts` | `pageA.model` | |
| `src/pages/pageB/models/product.ts` | `pageB.product` | |
| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | Definition in `pages/xxx/models` supports nested models |
A Model is essentially a custom `hook` with no "black magic" for the user to worry about.
When we need to access the global data in the Model, we can call the namespace directly. For example, for a Model file `userModel.ts`, its namespace is `userModel`.
Write a function with a default export:
```ts
// src/models/userModel.ts
export default function Page() {
const user = {
username: 'umi',
};
return { user };
};
```
This is a Model. What the plugin does is turn the state or data in it into **global data**, providing the same state or data to different components using that Model.
:::info{title=💡}
The Model file needs to export a function by default, which defines a `hook`. Files that do not conform to this standard will be filtered out and cannot be called by namespace.
:::
It's allowed to use other `hooks` in a Model. Take a counter as an example:
```ts
// src/models/counterModel.ts
import { useState, useCallback } from 'react';
export default function Page() {
const [counter, setCounter] = useState(0);
const increment = useCallback(() => setCounter((c) => c + 1), []);
const decrement = useCallback(() => setCounter((c) => c - 1), []);
return { counter, increment, decrement };
};
```
In real-world projects, we usually need to request backend interfaces to obtain the data we need. Now let's expand the previous example of fetching user information:
```ts
// src/models/userModel.ts
import { useState, useEffect } from 'react';
import { getUser } from '@/services/user';
export default function Page() {
const [user, setUser] = useState({});
const [loading, setLoading] = useState(true);
useEffect(() => {
getUser().then((res) => {
setUser(res);
setLoading(false);
});
}, []);
return {
user,
loading,
};
};
```
If you use [ahooks](https://ahooks.js.org) in your project, you can organize your code like this:
```ts
// src/models/userModel.ts
import { useRequest } from 'ahooks';
import { getUser } from '@/services/user';
export default function Page() {
const { data: user, loading: loading } = useRequest(async () => {
const res = await getUser();
if (res) {
return res;
}
return {};
});
return {
user,
loading,
};
};
```
### Using a Model
Now, you want to use a global Model in a certain component. Taking the user information as an example, you only need to call the `useModel` hook function:
```tsx
// src/components/Username/index.tsx
import { useModel } from 'umi';
export default function Page() {
const { user, loading } = useModel('userModel');
return (
{loading ? <>:
{user.username}
}
);
}
```
The `useModel()` method's argument is the Model's **namespace**.
:::info{title=💡}
If you use VSCode as the IDE for developing Umi projects, it's recommended to use it in conjunction with the [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model) plugin. It allows you to quickly jump to the file that defines the Model:
:::
## Performance Optimization
The `useModel()` method can accept an optional second parameter. When a component only needs to use part of the Model and is not interested in changes to other parameters, you can pass in a function to filter. Take the operation button for the counter as an example:
```tsx
// src/components/CounterActions/index.tsx
import { useModel } from 'umi';
export default function Page() {
const { add, minus } = useModel('counterModel', (model) => ({
add: model.increment,
minus: model.decrement,
}));
return (
);
};
```
The above component is not interested in the `counter` value in the counter Model, and only needs to use the `increment()` and `decrement()` methods provided by the Model. Therefore, we passed in a function as the second argument for the `useModel()` method, and its return value will be used as the return value of the `useModel()` method.
This way, we have filtered out the frequently changing `counter` value, avoiding the performance loss caused by the component's repetitive rendering.
## Global Initial State
`@umi/max` has a built-in **global initial state management** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts), which allows you to quickly build and access the global initial state of Umi projects within components.
The global initial state is a special Model.
The global initial state is created at the very beginning of the entire Umi project. Write the export method `getInitialState()` in `src/app.ts`, and its return value will become the global initial state. For example:
```ts
// src/app.ts
import { fetchInitialData } from '@/services/initial';
export async function getInitialState() {
const initialData = await fetchInitialData();
return initialData;
}
```
Now, various plugins and your defined components can directly access this global initial state through `useModel('@@initialState')` as shown below:
```tsx
import { useModel } from 'umi';
export default function Page() {
const { initialState, loading, error, refresh, setInitialState } =
useModel('@@initialState');
return <>{initialState};
};
```
| Object Property | Type | Description |
| --- | --- | --- |
| `initialState` | `any` | The return value of the exported `getInitialState()` method |
| `loading` | `boolean` | Whether the `getInitialState()` or `refresh()` method is in progress. Before the initial state is obtained for the first time, the rendering of other parts of the page will be **blocked** |
| `error` | `Error` | If an error occurs while running the exported `getInitialState()` method, the error message |
| `refresh` | `() => void` | Re-execute the `getInitialState` method and obtain a new global initial state |
| `setInitialState` | `(state: any) => void` | Manually set the value of `initialState`, after manually setting it, `loading` will be set to `false` |
## Qiankun Parent-Child Communication
`@umi/max` has a built-in **Qiankun Micro-Frontend** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts), which allows micro-applications to obtain the data Model passed from the parent application through the `useModel('@@qiankunStateFromMaster')` method, thereby achieving communication between parent and child applications.
For specific usage, please refer to the [micro-frontend's parent-child communication chapter](./micro-frontend#parent-child-communication).
## API
### `useModel`
`useModel()` is a hook function that provides the ability to use a Model. It accepts two parameters:
| Parameter | Type | Description |
| --- | --- | --- |
| `namespace` | `String` | The namespace of the Model file |
| `updater` | `(model: any) => any` | Optional parameter. Passing in a function, the return value of which is the Model state or data currently needed by the component, and it serves as the return value of the `useModel()` method. It plays a significant role in optimizing component performance. |
```tsx
// src/components/AdminInfo/index.tsx
import { useModel } from 'umi';
export default () => {
const { user, fetchUser } = useModel('adminModel', (model) => ({
user: model.admin,
fetchUser: model.fetchAdmin,
}));
return <>hello;
};
```
---
### Docs Docs Max Data Flow (`docs/docs/docs/max/data-flow.md`)
---
order: 5
toc: content
---
# 数据流
`@umi/max` 内置了**数据流管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts)，它是一种基于 `hooks` 范式的轻量级数据管理方案，可以在 Umi 项目中管理全局的共享数据。
## 配置
e.g.
```ts
export default {
model: {
extraModels: ['src/models/userModel.ts'],
preferSourceNamespace: false,
sort: (a, b) => a.namespace.localeCompare(b.namespace),
},
};
```
### extraModels
- Type: `string[]`
- Default: `[]`
配置 `extraModels` 后，插件会自动将这些 Model 文件添加到数据流管理中。
### preferSourceNamespace
- Type: `boolean`
- Default: `false`
是否从 Model 源码中解析 `namespace`（同时作用于约定式 Model 与 `extraModels`）。
默认关闭，避免把业务返回值里的 `namespace` 字段误当作注册名。开启后优先使用源码中的 `namespace`，便于 monorepo / 跨包共享 Model 时自定义命名空间。
```ts
// .umirc.ts
export default {
model: {
preferSourceNamespace: true,
// extraModels: ['../../packages/shared/src/models/tenant.ts'],
},
};
// model 源码
export default () => ({
namespace: 'businessTenant',
user: null,
});
// 使用
useModel('businessTenant');
```
:::warning{title=注意}
开启后请勿再把 `namespace` 当作普通业务字段返回；它会被解析为 Model 注册名。若仅需个别文件自定义命名空间，也可在路径后追加 `#{"namespace":"xxx"}`，无需打开此开关。
:::
### sort
- Type: `(a: Model, b: Model) => number`
- Default: `(a, b) => a.namespace.localeCompare(b.namespace)`
配置 `sort` 后，插件会根据 `sort` 函数返回的值对 Model 进行排序。
## 开始使用
### 创建 Model
数据流管理插件采用约定式目录结构，我们约定可以在 `src/models`, `src/pages/xxxx/models/`目录中，和 `src/pages/xxxx/model.{js,jsx,ts,tsx}` 文件引入 Model 文件。
Model 文件允许使用 `.(tsx|ts|jsx|js)` 四种后缀格式，**命名空间（namespace）** 优先级如下：
1. 路径 `#meta`：`path/to/model.ts#{"namespace":"xxx"}`
2. 源码中的 `namespace`：需开启 `preferSourceNamespace`
3. 路径约定推导（默认）
路径约定规则如下。
| 路径 | 命名空间 | 说明 |
| :--- |:--- | :--- |
| `src/models/count.ts` | `count` | `src/models` 目录下不支持目录嵌套定义 model |
| `src/pages/pageA/model.ts` | `pageA.model` | |
| `src/pages/pageB/models/product.ts` | `pageB.product` | |
| `src/pages/pageB/models/fruit/apple.ts` | `pageB.fruit.apple` | `pages/xxx/models` 下 model 定义支持嵌套定义 |
所谓的 Model，就是一个自定义的 `hooks`，没有任何使用者需要关注的“黑魔法”。
当我们需要获取 Model 中的全局数据时，调用该命名空间即可。例如，对于 Model 文件 `userModel.ts`，它的命名空间为 `userModel`。
编写一个默认导出的函数：
```ts
// src/models/userModel.ts
export default () => {
const user = {
username: 'umi',
};
return { user };
};
```
这就是一个 Model。插件所做的工作就是将其中的状态或数据变成了**全局数据**，不同的组件在使用该 Model 时，拿到的是同一份状态或数据。
:::info{title=💡}
Model 文件需要默认导出一个函数，此函数定义了一个 `hook`。对于不符合此规范的文件，将会被过滤掉，并无法通过命名空间调用。
:::
Model 中允许使用其它 `hooks`，以计数器为例：
```ts
// src/models/counterModel.ts
import { useState, useCallback } from 'react';
export default function Page() {
const [counter, setCounter] = useState(0);
const increment = useCallback(() => setCounter((c) => c + 1), []);
const decrement = useCallback(() => setCounter((c) => c - 1), []);
return { counter, increment, decrement };
};
```
在项目实践中，我们通常需要请求后端接口，来获取所需的数据。现在让我们来扩展前面获取用户信息的例子：
```ts
// src/models/userModel.ts
import { useState, useEffect } from 'react';
import { getUser } from '@/services/user';
export default function Page() {
const [user, setUser] = useState({});
const [loading, setLoading] = useState(true);
useEffect(() => {
getUser().then((res) => {
setUser(res);
setLoading(false);
});
}, []);
return {
user,
loading,
};
};
```
如果您在项目中使用了 [ahooks](https://ahooks.js.org)，可以像这样组织您的代码：
```ts
// src/models/userModel.ts
import { useRequest } from 'ahooks';
import { getUser } from '@/services/user';
export default function Page() {
const { data: user, loading: loading } = useRequest(async () => {
const res = await getUser();
if (res) {
return res;
}
return {};
});
return {
user,
loading,
};
};
```
### 使用 Model
现在，您想要在某个组件中使用全局的 Model。以用户信息为例，只需要调用 `useModel` 这一钩子函数：
```tsx
// src/components/Username/index.tsx
import { useModel } from 'umi';
export default function Page() {
const { user, loading } = useModel('userModel');
return (
{loading ? <>:
{user.username}
}
);
}
```
其中，`useModel()` 方法传入的参数为 Model 的**命名空间**。
:::info{title=💡}
如果您使用 VSCode 作为 Umi 项目开发的 IDE，推荐搭配 [@umijs/plugin-model](https://marketplace.visualstudio.com/items?itemName=litiany4.umijs-plugin-model)插件使用。它允许您快速跳转到定义 Model 的文件：
:::
## 性能优化
`useModel()` 方法可以接受可选的第二个参数，当组件只需要使用 Model 中的部分参数，而对其它参数的变化不感兴趣时，可以传入一个函数进行过滤。以实现计数器的操作按钮为例：
```tsx
// src/components/CounterActions/index.tsx
import { useModel } from 'umi';
export default function Page() {
const { add, minus } = useModel('counterModel', (model) => ({
add: model.increment,
minus: model.decrement,
}));
return (
);
};
```
上面的组件并不关心计数器 Model 中的 `counter` 值，只需要使用 Model 提供的 `increment()` 和 `decrement()` 方法。于是我们传入了一个函数作为 `useModel()` 方法的第二个参数，该函数的返回值将作为 `useModel()` 方法的返回值。
这样，我们过滤掉了 `counter` 这一频繁变化的值，避免了组件重复渲染带来的性能损失。
## 全局初始状态
`@umi/max` 内置了**全局初始状态管理**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts)，允许您快速构建并在组件内获取 Umi 项目全局的初始状态。
全局初始状态是一种特殊的 Model。
全局初始状态在整个 Umi 项目的最开始创建。编写 `src/app.ts` 的导出方法 `getInitialState()`，其返回值将成为全局初始状态。例如：
```ts
// src/app.ts
import { fetchInitialData } from '@/services/initial';
export async function getInitialState() {
const initialData = await fetchInitialData();
return initialData;
}
```
现在，各种插件和您定义的组件都可以通过 `useModel('@@initialState')` 直接获取到这份全局的初始状态，如下所示：
```tsx
import { useModel } from 'umi';
export default function Page() {
const { initialState, loading, error, refresh, setInitialState } =
useModel('@@initialState');
return <>{initialState};
};
```
| 对象属性 | 类型 | 介绍 |
| --- | --- | --- |
| `initialState` | `any` | 导出的 `getInitialState()` 方法的返回值 |
| `loading` | `boolean` | `getInitialState()` 或 `refresh()` 方法是否正在进行中。在首次获取到初始状态前，页面其他部分的渲染都会**被阻止** |
| `error` | `Error` | 如果导出的 `getInitialState()` 方法运行时报错，报错的错误信息 |
| `refresh` | `() => void` | 重新执行 `getInitialState` 方法，并获取新的全局初始状态 |
| `setInitialState` | `(state: any) => void` | 手动设置 `initialState` 的值，手动设置完毕会将 `loading` 置为 `false` |
## Qiankun 父子应用间通信
`@umi/max` 内置了 **Qiankun 微前端**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)，当使用数据流插件时，它允许微应用通过 `useModel('@@qiankunStateFromMaster')` 方法获取父应用传递给子应用的数据 Model，进而实现父子应用间的通信。
具体的使用方法请查阅[微前端的父子应用通信章节](./micro-frontend#父子应用通信)。
## API
### `useModel`
`useModel()` 是一个钩子函数，提供了使用 Model 的能力。它接受两个参数：
| 参数 | 类型 | 介绍 |
| --- | --- | --- |
| `namespace` | `String` | Model 文件的命名空间 |
| `updater` | `(model: any) => any` | 可选参数。传入一个函数，函数的返回值为当前组件中需要使用到的 Model 状态或数据，并作为 `useModel()` 方法的返回值。对优化组件性能具有重要意义。 |
```tsx
// src/components/AdminInfo/index.tsx
import { useModel } from 'umi';
export default function Page() {
const { user, fetchUser } = useModel('adminModel', (model) => ({
user: model.admin,
fetchUser: model.fetchAdmin,
}));
return <>hello;
};
```
---
### Docs Docs Max Dva.En US (`docs/docs/docs/max/dva.en-US.md`)
---
order: 13
toc: content
translated_at: '2024-03-17T09:17:48.666Z'
---
# dva
## Why We Need State Management
React components are essentially built through JSX and styles according to the state to form the final UI. It is the change in state that actually dynamizes the page. For simple frontend applications, the application data management needs can be met by the component's own state plus the parent component passing state via props. However, when the application scales to a certain degree, it will lead to very complex states maintained within components. Coupled with the state transfer between components, data management can easily become chaotic. A minor modification can lead to unpredictable side effects.
Therefore, we need pure UI components that, apart from rendering logic, do not mix other logics (such as network requests). This requires us to find a way to extract business logic unrelated to rendering, forming an independent layer (which is managed by the model in the `src/models` folder in Umi) to manage. All components are downgraded to `stateless components` that solely depend on props for rendering. In this way, the UI layer no longer needs to worry about rendering unrelated logics and focuses on UI rendering. (Note: The components mentioned here mainly refer to the page components under page, whereas the components under component should be relatively universal components that should also rely solely on props for rendering, and they should not have a model. Data should be passed to them via props in the page components).
## Simple Data Sharing
For simple applications that do not require complex data flows, only some simple data sharing is needed. We recommend using [Middle Platform Best Practices Simple Data Flow](./data-flow).
## How Umi Manages State
As shown in the figure below, Umi has built in [Dva](https://dvajs.com) to provide a set of state management solutions:
Data is uniformly managed in the models of `src/models`, components strive not to maintain data as much as possible, but to associate with the data in the model through connect. When there is an operation on the page, an action is triggered to request the backend interface and modify the data in the model, separating the business logic into a cyclic closed loop, allowing the data to flow unidirectionally within it, making the application easier to maintain. This idea originally came from Facebook's [flux](http://facebook.github.io/flux/). Let's take a closer look at how to implement such logic in Umi.
### Configuring dva
First, you need to configure `dva: {}` to activate the dva plugin built into Umi.
### Adding a model
Umi will automatically mount the model definition in `src/models` by default, you just need to create a new file in the model folder to add a model to manage component states.
After 2.0, to better support the demand loading of mobile H5 projects and the organization of models in large projects, we will also default mount the model under a certain page folder, you can refer to [Directory Structure Explanation](../guides/directory-structure) for specific structure. However, it is worth noting that the namespace of the model is global, and you still need to ensure your namespace is unique (the default is the file name). For most projects, we recommend managing them uniformly in the model, without using this function.
The model writing refers to the following example:
```js
import { queryUsers, queryUser } from '../../services/user';
export default {
state: {
user: {},
},
effects: {
*queryUser({ payload }, { call, put }) {
const { data } = yield call(queryUser, payload);
yield put({ type: 'queryUserSuccess', payload: data });
},
},
reducers: {
queryUserSuccess(state, { payload }) {
return {
...state,
user: payload,
};
},
},
test(state) {
console.log('test');
return state;
},
};
```
### Connecting the Component and Model
After creating the model, you can conveniently connect the model and component together in the component through the ES6 [Decorator](http://es6.ruanyifeng.com/#docs/decorator). Then you can access the data in the model through `this.props.[modelName]` in the component. (In the corresponding model, the default namespace is the file name)
Component example is as follows:
```javascript
import React, { Component } from 'react';
import { connect } from 'umi';
@connect(({ user }) => ({
user,
}))
class UserInfo extends Component {
constructor(props) {
super(props);
}
render() {
return
{this.props.user.name}
;
}
}
export default UserInfo;
```
### Dispatching Events in Components
The connect method also adds `dispatch` to `this.props`, and you can call it to trigger the effects or reducer in the model to modify the data in the model when the user triggers a certain event. As shown below:
```javascript
import React, { Component } from 'react';
import { connect } from 'umi';
@connect(({ user }) => ({
user,
}))
class UserInfo extends Component {
constructor(props) {
super(props);
}
render() {
return (
);
}
}
export default UserInfo;
```
### Modifying Data
After dispatching an action, it will find an effect or reducer defined in the model according to the type in the action.
If it's an effect, it can request back-end data, and then trigger a reducer to modify the data. After the data is modified by the reducer, the component will update according to the latest data, thus completing a data flow.
## Documentation
### Model Definition
A model can define the following parts:
- namespace # The namespace of the model, uniquely identifying a model, can be omitted if it is the same as the file name
- state # Data in the model
- effects # Asynchronous actions, used to send asynchronous requests
- reducers # Synchronous actions, used to modify state
### Connect
`Connect` is used to associate a model and a component, adding related data and `dispatch` to the component's `props`. As shown below:
```jsx
import React, { Component } from 'react';
import { connect } from 'umi';
const mapModelToProps = allModels => {
return {
test: 'hello world',
// props you want connect to Component
};
};
@connect(mapModelToProps)
class UserInfo extends Component {
render() {
return
{this.props.test}
;
}
}
export default UserInfo;
```
It is recommended to call connect through annotation, which is equivalent to `export default connect(mapModelToProps)(UserInfo);`. Connect accepts a parameter, a method, where you receive all the model information and need to return the object to be added to props. In the example above, you can get the string 'hello world' through `this.props.test`.
### Dispatch
At the same time as using `connect` to associate the component and the model, the framework will also add a `this.props.dispatch` method. With this method, you can trigger an action to the model. As shown below:
```jsx
render () {
return
{
this.props.dispacth({
type: 'modelnamespace/actionname',
sometestdata: 'xxx',
othertestata: {},
}).then(() => {
// it will return a promise
// action success
});
}}>test
}
```
The actions triggered by `this.props.dispatch` are divided into two categories: effect and reducer. Below are more details on them.
### Reducer
Reducer is a function that handles the logic of modifying data (synchronously, cannot request back-end). It accepts state and action, returning the old or new state. That is: `(state, action) => state`.
#### Add, Delete, Modify
Taking todos as an example.
```javascript
exports default {
namespace: 'todos',
state: [],
reducers: {
add(state, { payload: todo }) {
return state.concat(todo);
},
remove(state, { payload: id }) {
return state.filter(todo => todo.id !== id);
},
update(state, { payload: updatedTodo }) {
return state.map(todo => {
if (todo.id === updatedTodo.id) {
return { ...todo, ...updatedTodo };
} else {
return todo;
}
});
},
},
};
```
#### Add, Delete, Modify Nested Data
It is recommended to keep at most one layer of nesting to maintain state flatness. Deep nesting makes reducer hard to write and maintain.
```javascript
app.model({
namespace: 'app',
state: {
todos: [],
loading: false,
},
reducers: {
add(state, { payload: todo }) {
const todos = state.todos.concat(todo);
return { ...state, todos };
},
},
});
```
Below is an example of deep nesting, which should be avoided as much as possible.
```javascript
app.model({
namespace: 'app',
state: {
a: {
b: {
todos: [],
loading: false,
},
},
},
reducers: {
add(state, { payload: todo }) {
const todos = state.a.b.todos.concat(todo);
const b = { ...state.a.b, todos };
const a = { ...state.a, b };
return { ...state, a };
},
},
});
```
### Effect
Effects are defined in the model. It is also a type of action, mainly used for asynchronous communication with the back-end. After requesting and receiving the necessary data from the back-end through effects, you can again send a reducer through the put method to modify the data.
Effect supports asynchronous request through ES6 [Generator function](http://es6.ruanyifeng.com/#docs/generator), see the example below:
```javascript
export default {
namespace: 'todos',
effects: {
*addRemote({ payload: todo }, { put, call }) {
yield call(addTodo, todo);
yield put({ type: 'add', payload: todo });
},
},
};
```
Actions defined in effects must be Generator functions defined through `*`, and asynchronous logic is triggered through the keyword `yield` in the function.
#### Effects
##### put
Used to trigger an action.
```javascript
yield put({ type: 'todos/add', payload: 'Learn Dva' });
```
##### call
Used to call asynchronous logic, supporting promise.
```javascript
const result = yield call(fetch, '/todos');
```
##### select
Used to get data from state.
```javascript
const todos = yield select(state => state.todos);
```
### loading
The framework will by default add a model with the namespace loading, containing information related to loading of asynchronous effects in this model, its state format is as follows:
```js
{
global: Boolean, // Whether there is really asynchronous request being sent
models: {
[modelnamespace]: Boolean, // The loading situation for each specific model
},
effects: {
[modelnamespace/effectname]: Boolean, // The loading situation for each specific effect
},
}
```
You can use this model to implement loading animations in components.
## Debugging
### redux
Since the underlying layer of dva is based on redux, you can install redux's [development tools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=zh-CN) to view the data and change records in the model.
## References
- [dva official website](https://dvajs.com/)
---
### Docs Docs Max Dva (`docs/docs/docs/max/dva.md`)
---
order: 13
toc: content
---
# dva
## 为什么需要状态管理
React 的组件只是通过 jsx 以及样式按照 state 构建最终的 UI，真正将页面动态化的实际上是 state 的变化实现的。对于简单的前端应用，在组件中通过组件自身的 state 加上父组件通过 props 状态的传递就能够满足应用数据管理的需求。但是当应用膨胀到一定程度后就会导致组件内维护的状态非常的复杂，加上组件之间状态的传递，很容易导致数据管理混乱。很小的修改都可能导致难以预料的副作用。
所以我们需要纯净的 UI 组件，除了渲染逻辑，不再杂糅其他（比如网络请求）。这样我们就要想办法把与渲染无关的业务逻辑抽离出来，形成独立的层（在 Umi 中就是 `src/models` 文件夹中所管理的 model ）去管理。让所有组件降级为`无状态组件`，仅仅依赖 props 渲染。这样 UI 层面就不需关心渲染无关的逻辑，专注做 UI 渲染。（注：这里说的组件主要是指 page 下面的页面组件，对于 component 下的组件本身就应该是比较通用的组件，更应该仅仅依赖 props 渲染，它们也不应该有 model，数据应该通过在页面组件中通过 props 传递过去）。
## 简单的数据共享
对于简单的应用，不需要复杂的数据流，只需要一些简单的数据共享。我们推荐使用 [中台最佳实践简易数据流](./data-flow) 。
## Umi 如何管理状态
如下图所示，Umi 内置了 [Dva](https://dvajs.com) 提供了一套状态管理方案：
数据统一在 `src/models` 中的 model 管理，组件内尽可能的不去维护数据，而是通过 connect 去关联 model 中的数据。页面有操作的时候则触发一个 action 去请求后端接口以及修改 model 中的数据，将业务逻辑分离到一个环形的闭环中，使得数据在其中单向流动。让应用更好维护。这样的思想最初来源于 Facebook 的 [flux](http://facebook.github.io/flux/)。接下来我们来具体看看如何在 Umi 中实现这样的逻辑。
### 配置 dva
首先你需要配置 `dva: {}` 打开 Umi 内置的 dva 插件。
### 添加 model
Umi 会默认将 `src/models` 下的 model 定义自动挂载，你只需要在 model 文件夹中新建文件即可新增一个 model 用来管理组件状态。
在 2.0 后，为了更好的支持移动端的 H5 项目的按需加载和大型项目的 model 组织，对于某个 page 文件夹下面的 model 我们也会默认挂载，具体结构可以参考[目录结构说明](../guides/directory-structure)。但是需要注意的是 model 的 namespace 是全局的，你仍然需要保证你的 namesapce 唯一（默认是文件名）。对于大部分的项目，我们推荐统一放到 model 中进行管理即可，不需要使用该功能。
model 的写法参考如下示例：
```js
import { queryUsers, queryUser } from '../../services/user';
export default {
state: {
user: {},
},
effects: {
*queryUser({ payload }, { call, put }) {
const { data } = yield call(queryUser, payload);
yield put({ type: 'queryUserSuccess', payload: data });
},
},
reducers: {
queryUserSuccess(state, { payload }) {
return {
...state,
user: payload,
};
},
},
test(state) {
console.log('test');
return state;
},
};
```
### 把组件和 model connect 在一起
新建完成 model 之后你就可以在组件中通过 ES6 的 [Decorator](http://es6.ruanyifeng.com/#docs/decorator) 方便的把 model 和组件 connect 到一起。然后你就可以在组件中通过`this.props.[modelName]`的方式来访问 model 中的数据了。（在对应的 model 中，默认 namespace 即为文件名）
组件如下示例：
```javascript
import React, { Component } from 'react';
import { connect } from 'umi';
@connect(({ user }) => ({
user,
}))
class UserInfo extends Component {
constructor(props) {
super(props);
}
render() {
return
{this.props.user.name}
;
}
}
export default UserInfo;
```
### 在组件中 dispatch 事件
connect 方法同时也会添加 `dispatch` 到 `this.props` 上，你可以在用户触发某个事件的时候调用它来触发 model 中的 effects 或者 reducer 来修改 model 中的数据。如下所示：
```javascript
import React, { Component } from 'react';
import { connect } from 'umi';
@connect(({ user }) => ({
user,
}))
class UserInfo extends Component {
constructor(props) {
super(props);
}
render() {
return (
{
this.props.dispacth({
type: 'modelnamespace/actionname',
sometestdata: 'xxx',
othertestata: {},
}).then(() => {
// it will return a promise
// action success
});
}}>test
}
```
通过 `this.props.dispatch` 触发的 action 分为 effect 和 reducer 两类，下面是对他们的更多细节说明。
### Reducer
reducer 是一个函数，用来处理修改数据的逻辑（同步，不能请求后端）。接受 state 和 action，返回老的或新的 state 。即：`(state, action) => state`。
#### 增删改
以 todos 为例。
```javascript
exports default {
namespace: 'todos',
state: [],
reducers: {
add(state, { payload: todo }) {
return state.concat(todo);
},
remove(state, { payload: id }) {
return state.filter(todo => todo.id !== id);
},
update(state, { payload: updatedTodo }) {
return state.map(todo => {
if (todo.id === updatedTodo.id) {
return { ...todo, ...updatedTodo };
} else {
return todo;
}
});
},
},
};
```
#### 嵌套数据的增删改
建议最多一层嵌套，以保持 state 的扁平化，深层嵌套会让 reducer 很难写和难以维护。
```javascript
app.model({
namespace: 'app',
state: {
todos: [],
loading: false,
},
reducers: {
add(state, { payload: todo }) {
const todos = state.todos.concat(todo);
return { ...state, todos };
},
},
});
```
下面是深层嵌套的例子，应尽量避免。
```javascript
app.model({
namespace: 'app',
state: {
a: {
b: {
todos: [],
loading: false,
},
},
},
reducers: {
add(state, { payload: todo }) {
const todos = state.a.b.todos.concat(todo);
const b = { ...state.a.b, todos };
const a = { ...state.a, b };
return { ...state, a };
},
},
});
```
### Effect
effects 是定义在 model 中的。它也是一种类型的 action，主要用于和后端的异步通讯。通过 effects 请求后端发送和接收必要的数据之后可以通过 put 方法再次发送一个 reducer 来修改数据。
effect 通过 ES6 中 [Generator 函数](http://es6.ruanyifeng.com/#docs/generator) 来支持通过顺序的代码实现异步的请求，示例如下：
```javascript
export default {
namespace: 'todos',
effects: {
*addRemote({ payload: todo }, { put, call }) {
yield call(addTodo, todo);
yield put({ type: 'add', payload: todo });
},
},
};
```
effects 中定义的 action 都必须是通过 `*` 定义的 Generator 函数，然后在函数中通过关键字 `yield` 来触发异步逻辑。
#### Effects
##### put
用于触发 action 。
```javascript
yield put({ type: 'todos/add', payload: 'Learn Dva' });
```
##### call
用于调用异步逻辑，支持 promise 。
```javascript
const result = yield call(fetch, '/todos');
```
##### select
用于从 state 里获取数据。
```javascript
const todos = yield select(state => state.todos);
```
### loading
框架会默认添加一个命名空间为 loading 的 model，该 model 包含 effects 异步加载 loading 的相关信息，它的 state 格式如下：
```js
{
global: Boolean, // 是否真正有异步请求发送中
models: {
[modelnamespace]: Boolean, // 具体每个 model 的加载情况
},
effects: {
[modelnamespace/effectname]: Boolean, // 具体每个 effect 的加载情况
},
}
```
你可以使用该 model 实现在组件中添加 loading 动画。
## 调试
### redux
dva 的底层是基于 redux，所以你可以安装 redux 的[开发者工具](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=zh-CN)用来查看 model 中的数据和变化的记录。
## 参考文章
- [dva 官网](https://dvajs.com/)
---
### Docs Docs Max I18n.En US (`docs/docs/docs/max/i18n.en-US.md`)
---
order: 8
toc: content
translated_at: '2024-03-17T09:15:38.373Z'
---
# Internationalization
`@umi/max` comes with the [Internationalization plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts), which easily integrates internationalization features into your Umi application.
## Getting Started
The internationalization plugin adopts a convention-based directory structure, where we conventionally import multilingual files in the `src/locales` directory.
The naming of multilingual files should follow this specification: `.(js|json|ts)`. Here, `` is a delimiter, which defaults to `-`, and can be configured through the `baseSeparator` option.
For example, if you need to introduce support for Simplified Chinese and English in your project, you can create `zh-CN.ts` and `en-US.ts` files in the `src/locales` directory:
```diff
src
+ locales
+ zh-CN.ts
+ en-US.ts
pages
```
Configure the internationalization plugin in `.umirc.ts`:
```ts
export default {
locale: {
// Default to using src/locales/zh-CN.ts as a multilingual file
default: 'zh-CN',
baseSeparator: '-',
},
};
```
For more introductions to configuration, see the [Configuring Plugins](#configuring-plugins) section.
Now, add your first multilingual content:
```ts
// src/locales/zh-CN.ts
export default {
welcome: '欢迎光临 Umi 的世界！',
};
```
```ts
// src/locales/en-US.ts
export default {
welcome: "Welcome to Umi's world!",
};
```
You can also use `.json` files to store multilingual content:
```json
// src/locales/zh-CN.json
{
"welcome": "欢迎光临 Umi 的世界！",
}
// src/locales/en-US.json
{
"welcome": "Welcome to Umi's world!",
}
```
Everything is ready, now you can use multilingual content in Umi. Leave it to our `` component, just pass in the previous `welcome` as the value of the parameter `id`:
```tsx
import { FormattedMessage } from 'umi';
export default function Page() {
return (
);
};
```
The rendered result is as follows:
```html
欢迎光临 Umi 的世界！
Welcome to Umi's world!
```
## Using in Component Parameters
In some cases, you need to pass multilingual content as a parameter to a certain component. This can be achieved through the `intl` object:
```tsx
import { Alert } from 'antd';
import { useIntl } from 'umi';
export default function Page() {
const intl = useIntl();
const msg = intl.formatMessage({
id: 'welcome',
});
return ;
};
```
At the bottom layer, the internationalization plugin is encapsulated based on [`react-intl`](https://github.com/formatjs/formatjs/tree/main/packages/react-intl) and supports all its interfaces. For details, see [this document](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md).
In the code above, we used the `useIntl()` interface provided by `react-intl` to initialize the `intl` object and called the [`formatMessage()`](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md#formatmessage) method of this object to format the string.
## Formatting Strings
You may want to dynamically interpolate in multilingual translations, so you can write multilingual content like this:
```ts
// src/locales/zh-CN.ts
export default {
user: {
welcome: '{name}，今天也是美好的一天！',
},
};
```
```ts
// src/locales/en-US.ts
export default {
user: {
welcome: '{name}, what a nice day!',
},
};
```
Above, we wrote special syntax `{name}`, which allows us to dynamically assign values at runtime:
```tsx
import { FormattedMessage } from 'umi';
export default function Page() {
return (
);
};
```
If you wish to achieve this through the `intl` object, you can do so by assigning it like this:
```tsx
import { useIntl } from 'umi';
export default function Page() {
const intl = useIntl();
the msg = intl.formatMessage(
{
id: 'user.welcome',
},
{
name: '张三',
},
);
return
{msg}
;
};
```
Note that the key-value pair object used for assignment should be passed as the second parameter of the `formatMessage()` method.
The rendered result is as follows:
```html
张三，今天也是美好的一天！
张三, what a nice day!
```
## Switching Languages
The preset `` component can help you quickly add the feature of switching languages to your project, just write it like this:
```tsx
import { SelectLang } from 'umi';
export default function Page() {
return ;
};
```
In many cases, you may need to write your own language-switching component. This is where the `setLocale()` interface comes in handy:
```ts
import { setLocale } from 'umi';
// Refresh the page when switching
setLocale('en-US');
```
When switching languages using this method, the current page will be refreshed by default. You can set its second parameter to `false` to switch languages without refreshing:
```ts
// Do not refresh the page when switching
setLocale('en-US', false);
```
If you need to switch to the default language, just call this method without passing any parameters:
```ts
// If your default language is zh-CN
// Then the following call has the same effect as setLocale('zh-CN')
setLocale();
```
## Multilingual Default Values
For the sake of page consistency, if Umi does not find the content corresponding to the `id` in the current multilingual file, it will directly render the `id` as the content on the page.
For example, if the following multilingual files are written:
```ts
// src/locales/zh-CN.ts
export default {
table: {
submit: '提交表单',
},
};
```
```ts
// src/locales/en-US.ts
export default {
// table: {
// submit: 'SUBMIT TABLE',
// },
};
```
With the following component:
```tsx
import { Button } from 'antd';
import { FormattedMessage } from 'umi';
export default function Page() {
return (
);
};
```
The rendered result is:
```html
```
Especially, if you need to give a default value without completing internationalization adaptation, you can use the `defaultMessage` parameter:
```tsx
import { Button } from 'antd';
import { FormattedMessage } from 'umi';
export default function Page() {
return (
);
};
```
When using the `formatMessage()` method, you can do the same:
```tsx
import { Button } from 'antd';
import { useIntl } from 'umi';
export default function Page() {
const intl = useIntl();
the msg = intl.formatMessage({
id: 'table.submit',
defaultMessage: 'SUBMIT TABLE',
});
return ;
};
```
Using `defaultMessage` to configure default values is not recommended as this will result in writing a large amount of repetitive internationalization content. The best case is that during your internationalization adaptation, ensure that each multilingual file contains all the keys used.
## Introduction to Common Interfaces
### `addLocale` Dynamically Add Language Support
Without creating and writing separate multilingual files, you can dynamically add language support at runtime using the `addLocale()` interface. It accepts three parameters:
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `name` | `String` | Key of the multilingual |
| `message` | `Object` | Multilingual content object |
| `options` | `Object` | `momentLocale` and `antd` configurations |
For example, if you want to dynamically introduce Traditional Chinese multilingual support, you can write code as follows:
```ts
import { addLocale } from 'umi';
import zhTW from 'antd/es/locale/zh_TW';
addLocale(
'zh-TW',
{
welcome: '歡迎光臨 Umi 的世界！',
},
{
momentLocale: 'zh-tw',
antd: zhTW,
},
);
```
### `getAllLocales` Get Multilingual List
You can get an array of all current multilingual options through the `getAllLocales()` interface, including multilingual options added through the `addLocale()` method. This interface defaults to looking for files in the `src/locales` directory that are like `zh-CN.(js|json|ts)` and returns the Key of the multilingual.
```ts
import { getAllLocales } from 'umi';
getAllLocales();
// [en-US, zh-CN, ...]
```
### `getLocale` Get the Currently Selected Language
You can get the currently selected language through the `getLocale()` interface:
```ts
import { getLocale } from 'umi';
getLocale();
// zh-CN
```
### `useIntl` Get `intl` Object
`useIntl()` is likely to be the most commonly used interface in your development. Through it, you can obtain the `intl` object, and further execute methods such as `formatMessage()` to achieve your diverse needs:
```json
// src/locales/en-US.json
{
"welcome": "Hi, {name}."
}
```
```ts
import { useIntl } from 'umi';
const intl = useIntl();
const msg = intl.formatMessage(
{
id: 'welcome',
},
{
name: 'Jackson',
},
);
console.log(msg);
// Hi, Jackson.
```
For more uses of the `intl` object, please refer to the [interface documentation of `react-intl`](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md).
### `setLocale` Set Language
You can dynamically set the current language using the `setLocale()` interface through programming. It has two parameters:
| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `lang` | `String` | The language to switch to |
| `realReload` | `Boolean` | Whether to refresh the page when switching, default is `true` to refresh |
```ts
import { setLocale } from 'umi';
// Refresh the page when switching
setLocale('en-US');
// Do not refresh the page when switching
setLocale('en-US', false);
```
## Configuring Plugins
You can configure the internationalization plugin in `.umirc.ts`. The default values are as follows:
```ts
export default {
locale: {
antd: false, // If `antd` is included in project dependencies, then default to true
baseNavigator: true,
baseSeparator: '-',
default: 'zh-CN',
title: false,
useLocalStorage: true,
},
};
```
The detailed introduction to the configuration is as follows:
| Configuration Item | Type | Default Value | Description |
| ------------------ | ---- | ------------- | ----------- |
| `antd` | `Boolean` | `false`; if the project contains `antd` dependency, then `true` | `antd` internationalization support. For more introduction, refer to [this document](https://ant.design/docs/react/i18n-cn). |
| `baseNavigator` | `Boolean` | `true` | Enable **browser language detection**. By default, the recognition of the current language environment follows: `localStorage` `umi_locale` value > browser detection > `default` set default language > `zh-CN` |
| `baseSeparator` | `String` | `-` | **Delimiter** between Language and Country. The default is `-`, resulting in languages and directory files like `zh-CN`, `en-US` and `sk`, etc. If specified as `_`, then `default` defaults to `zh_CN`. |
| `default` | `String` | `zh-CN` | **Default language** of the project. When a specific language is not detected, use the default language set by `default`. |
| `title` | `Boolean` | `false` | Enable [**title internationalization**](#title-internationalization). |
| `useLocalStorage` | `Boolean` | `true` | Automatically using `localStorage` to save the currently used language. |
### Title Internationalization
Add a `title` item in the route configuration to enable internationalization support, automatically converting the page title to the corresponding multilingual content.
For example, the multilingual files are written as follows:
```ts
// src/locales/zh-CN.ts
export default {
'site.title': 'Umi - 企业级 React 应用开发框架',
'about.title': 'Umi - 关于我',
};
```
```ts
// src/locales/en-US.ts
export default {
'site.title': 'Umi - Enterprise-level React Application Framework',
'about.title': 'Umi - About me',
};
```
Configure the route content as follows:
```ts
// .umirc.ts
export default {
title: 'site.title',
routes: [
{
path: '/',
component: 'Index',
},
{
path: '/about',
component: 'About',
title: 'about.title',
},
],
};
```
When visiting the page:
- `/` route. When the multilingual option is `zh-CN`, the page title is `Umi - 企业级 React 应用开发框架`; for `en-US`, the page title is `Umi - Enterprise-level React Application Framework`.
- `/about` route. When the multilingual option is `zh-CN`, the page title is `Umi - 关于我`; for `en-US`, the page title is `Umi - About me`.
## Runtime Expansion
The internationalization plugin allows you to expand and customize it at runtime.
### Custom `getLocale`
You can customize the logic of the `getLocale()` method for getting the page language, for example, by recognizing the link `?locale=en-US`, make `en-US` the language of the current page:
```ts
// src/app.ts
import qs from 'qs';
export const locale = {
getLocale() {
const { search } = window.location;
const { locale = 'zh-CN'} = qs.parse(search, { ignoreQueryPrefix: true });
return locale;
},
};
```
### Custom Option Configuration
Umi’s i18n is implemented based on `react-intl`.
When you need to configure more `react-intl` initialization options, you can configure them in `app.ts`. You can refer to the [react-intl documentation](https://formatjs.io/docs/react-intl/components) for specific configuration options
```js
// src/app.ts
import { RuntimeConfig } from '@umijs/max'
export const locale: RuntimeConfig['locale'] = {
textComponent: 'span',
onError: () => {
console.log('error handler...');
}
// locale: string
// formats: CustomFormats
// messages: Record | Record
// defaultLocale: string
// defaultFormats: CustomFormats
// timeZone?: string
// textComponent?: React.ComponentType | keyof React.ReactHTML
// wrapRichTextChunksInFragment?: boolean
// defaultRichTextElements?: Record>
// onError(err: string): void
}
```
## FAQ
### Why not use the `formatMessage` syntax sugar directly?
Although `formatMessage` is very convenient to use directly, it is detached from React's lifecycle. The most serious issue is that switching languages cannot trigger DOM re-rendering. To solve this problem, we need to refresh the browser when switching languages, which is a poor user experience. Therefore, we recommend using `useIntl` or `injectIntl`, which can achieve the same functionality.
---
### Docs Docs Max I18n (`docs/docs/docs/max/i18n.md`)
---
order: 8
toc: content
---
# 国际化
`@umi/max` 内置了[国际化插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/locale.ts)，它可以轻松地将国际化功能集成到你的 Umi 应用程序之中。
## 开始使用
国际化插件采用约定式目录结构，我们约定在 `src/locales` 目录下引入多语言文件。
多语言文件的命名需遵循此规范：`.(js|json|ts)`。其中，`` 为分隔符，默认为 `-`，可以通过 `baseSeparator` 项配置。
例如，如果您需要在项目中引入简体中文和英文的多语言支持，可以在 `src/locales` 目录下创建 `zh-CN.ts` 和 `en-US.ts` 两个文件：
```diff
src
+ locales
+ zh-CN.ts
+ en-US.ts
pages
```
在 `.umirc.ts` 中配置国际化插件：
```ts
export default {
locale: {
// 默认使用 src/locales/zh-CN.ts 作为多语言文件
default: 'zh-CN',
baseSeparator: '-',
},
};
```
关于配置的更多介绍可参见[配置插件](#配置插件)章节。
现在，添加您的第一条多语言内容：
```ts
// src/locales/zh-CN.ts
export default {
welcome: '欢迎光临 Umi 的世界！',
};
```
```ts
// src/locales/en-US.ts
export default {
welcome: "Welcome to Umi's world!",
};
```
您也可以使用 `.json` 文件来存放多语言的内容：
```json
// src/locales/zh-CN.json
{
"welcome": "欢迎光临 Umi 的世界！",
}
// src/locales/en-US.json
{
"welcome": "Welcome to Umi's world!",
}
```
一切就绪，现在您可以在 Umi 中使用多语言内容。交给我们的 `` 组件吧，只需要将前面的 `welcome` 作为参数 `id` 的值传入即可：
```tsx
import { FormattedMessage } from 'umi';
export default function Page() {
return (
```
## 切换语言
通过预设的 `` 组件可以帮助您快速地向项目中添加切换语言的功能，只需要像这样编写：
```tsx
import { SelectLang } from 'umi';
export default function Page() {
return ;
};
```
更多情况下，您可能需要自己编写切换语言的组件。这时就轮到 `setLocale()` 接口大显身手了：
```ts
import { setLocale } from 'umi';
// 切换时刷新页面
setLocale('en-US');
```
使用该方法切换语言时，默认情况下会刷新当前的页面。您可以设置它的第二个参数为 `false` 来实现无刷新切换语言：
```ts
// 切换时不刷新页面
setLocale('en-US', false);
```
如果需要切换为默认的语言，只需要调用此方法而不用传递任何参数：
```ts
// 如果您的默认语言为 zh-CN
// 那么以下调用具有与 setLocale('zh-CN') 同样的效果
setLocale();
```
## 多语言默认值
为了页面的一致性，当 Umi 没有在当前的多语言文件中找到 `id` 对应的内容时，它会直接将 `id` 渲染为页面上的内容。
例如，编写了如下多语言文件：
```ts
// src/locales/zh-CN.ts
export default {
table: {
submit: '提交表单',
},
};
```
```ts
// src/locales/en-US.ts
export default {
// table: {
// submit: 'SUBMIT TABLE',
// },
};
```
有如下组件：
```tsx
import { Button } from 'antd';
import { FormattedMessage } from 'umi';
export default function Page() {
return (
);
};
```
渲染的结果为：
```html
```
特别的，如果您需要在没有完成国际化适配的情况下，给出一个默认的值，可以使用 `defaultMessage` 参数：
```tsx
import { Button } from 'antd';
import { FormattedMessage } from 'umi';
export default function Page() {
return (
);
};
```
使用 `formatMessage()` 方法时，也可以这么做：
```tsx
import { Button } from 'antd';
import { useIntl } from 'umi';
export default function Page() {
const intl = useIntl();
const msg = intl.formatMessage({
id: 'table.submit',
defaultMessage: 'SUBMIT TABLE',
});
return ;
};
```
不推荐使用 `defaultMessage` 配置默认值，因为这会编写大量重复的国际化内容。最好的情况是，在您进行国际化适配时，确保了每个多语言文件中都包含所有用到的键。
## 常用接口介绍
### `addLocale` 动态添加多语言支持
无需创建并编写单独的多语言文件，使用 `addLocale()` 接口可以在运行时动态添加语言支持。它接受三个参数：
| 参数 | 类型 | 介绍 |
| --------- | -------- | ----------------------------- |
| `name` | `String` | 多语言的 Key |
| `message` | `Object` | 多语言的内容对象 |
| `options` | `Object` | `momentLocale` 和 `antd` 配置 |
例如，您想要动态引入繁体中文的多语言支持，可以编写代码如下：
```ts
import { addLocale } from 'umi';
import zhTW from 'antd/es/locale/zh_TW';
addLocale(
'zh-TW',
{
welcome: '歡迎光臨 Umi 的世界！',
},
{
momentLocale: 'zh-tw',
antd: zhTW,
},
);
```
### `getAllLocales` 获取多语言列表
通过 `getAllLocales()` 接口可以获取当前所有多语言选项的数组，包括通过 `addLocale()` 方法添加的多语言选项。该接口默认会在 `src/locales` 目录下寻找形如 `zh-CN.(js|json|ts)` 的文件，并返回多语言的 Key。
```ts
import { getAllLocales } from 'umi';
getAllLocales();
// [en-US, zh-CN, ...]
```
### `getLocale` 获取当前选择的语言
通过 `getLocale()` 接口可以获取当前选择的语言：
```ts
import { getLocale } from 'umi';
getLocale();
// zh-CN
```
### `useIntl` 获取 `intl` 对象
`useIntl()` 很有可能会是您开发中最常用的接口，通过它可以获取 `intl` 对象，并进一步执行 `formatMessage()` 等方法来实现您多元的需求：
```json
// src/locales/en-US.json
{
"welcome": "Hi, {name}."
}
```
```ts
import { useIntl } from 'umi';
const intl = useIntl();
const msg = intl.formatMessage(
{
id: 'welcome',
},
{
name: 'Jackson',
},
);
console.log(msg);
// Hi, Jackson.
```
关于 `intl` 对象的更多用法，请参阅 `react-intl` 的[接口文档](https://github.com/formatjs/formatjs/blob/main/website/docs/react-intl/api.md)。
### `setLocale` 设置语言
通过 `setLocale()` 接口可以使用编程的方法动态设置当前的语言。它有两个参数：
| 参数 | 类型 | 介绍 |
| ------------ | --------- | ------------------------------------------ |
| `lang` | `String` | 切换到的语言 |
| `realReload` | `Boolean` | 切换时是否刷新页面，默认为 `true` 刷新页面 |
```ts
import { setLocale } from 'umi';
// 切换时刷新页面
setLocale('en-US');
// 切换时不刷新页面
setLocale('en-US', false);
```
## 配置插件
您可以在 `.umirc.ts` 中配置国际化插件。默认值如下：
```ts
export default {
locale: {
antd: false, // 如果项目依赖中包含 `antd`，则默认为 true
baseNavigator: true,
baseSeparator: '-',
default: 'zh-CN',
title: false,
useLocalStorage: true,
},
};
```
配置的详细介绍如下：
| 配置项 | 类型 | 默认值 | 介绍 |
| --- | --- | --- | --- |
| `antd` | `Boolean` | `false`；如果项目包含 `antd` 依赖，则为 `true` | `antd` 的国际化支持。更多介绍可参见[此文档](https://ant.design/docs/react/i18n-cn)。 |
| `baseNavigator` | `Boolean` | `true` | 开启**浏览器语言检测**。默认情况下，当前语言环境的识别按照：`localStorage` 中 `umi_locale` 值 > 浏览器检测 > `default` 设置的默认语言 > `zh-CN` |
| `baseSeparator` | `String` | `-` | 语言（Language）与国家（Country） 之间的**分割符**。默认情况下为 `-`，返回的语言及目录文件为 `zh-CN`、`en-US` 和 `sk` 等。若指定为 `_`，则 `default` 默认为 `zh_CN`。 |
| `default` | `String` | `zh-CN` | 项目**默认语言**。当检测不到具体语言时，使用 `default` 设置的默认语言。 |
| `title` | `Boolean` | `false` | 开启[**标题国际化**](#标题国际化)。 |
| `useLocalStorage` | `Boolean` | `true` | 自动使用 `localStorage` 保存当前使用的语言。 |
### 标题国际化
在路由配置中添加 `title` 项即可启用国际化支持，自动将页面的标题转为对应的多语言内容。
例如，编写多语言文件如下：
```ts
// src/locales/zh-CN.ts
export default {
'site.title': 'Umi - 企业级 React 应用开发框架',
'about.title': 'Umi - 关于我',
};
```
```ts
// src/locales/en-US.ts
export default {
'site.title': 'Umi - Enterprise-level React Application Framework',
'about.title': 'Umi - About me',
};
```
配置路由内容如下：
```ts
// .umirc.ts
export default {
title: 'site.title',
routes: [
{
path: '/',
component: 'Index',
},
{
path: '/about',
component: 'About',
title: 'about.title',
},
],
};
```
访问页面时：
- `/` 路由。多语言选项为 `zh-CN` 时，页面标题为 `Umi - 企业级 React 应用开发框架`；为 `en-US` 时，页面标题为 `Umi - Enterprise-level React Application Framework`。
- `/about` 路由。多语言选项为 `zh-CN` 时，页面标题为 `Umi - 关于我`；为 `en-US` 时，页面标题为 `Umi - About me`。
## 运行时拓展
国际化插件允许您在运行时对它进行一些拓展与定制。
### 自定义 `getLocale`
您可以自定义获取页面语言 `getLocale()` 方法的逻辑，例如通过识别链接 `?locale=en-US`，将 `en-US` 作为当前页面的语言：
```ts
// src/app.ts
import qs from 'qs';
export const locale = {
getLocale() {
const { search } = window.location;
const { locale = 'zh-CN' } = qs.parse(search, { ignoreQueryPrefix: true });
return locale;
},
};
```
### 自定义选项配置
Umi 的 i18n 是基于 `react-intl` 实现的，
当您需要配置更多 `react-intl` 初始化选项的时候，可以在 `app.ts` 中配置，具体配置选项可以参考[react-intl 文档](https://formatjs.io/docs/react-intl/components)
```js
// src/app.ts
import { RuntimeConfig } from '@umijs/max'
export const locale: RuntimeConfig['locale'] = {
textComponent: 'span',
onError: () => {
console.log('error handler...');
}
// locale: string
// formats: CustomFormats
// messages: Record | Record
// defaultLocale: string
// defaultFormats: CustomFormats
// timeZone?: string
// textComponent?: React.ComponentType | keyof React.ReactHTML
// wrapRichTextChunksInFragment?: boolean
// defaultRichTextElements?: Record>
// onError(err: string): void
}
```
## FAQ
### 为什么不直接使用 `formatMessage` 这个语法糖？
虽然 `formatMessage` 直接使用起来会非常方便，但是它脱离了 React 的生命周期，最严重的问题就是切换语言时无法触发 DOM 的重新渲染。为了解决这个问题，我们切换语言时就需要刷新一下浏览器，用户体验很差。所以推荐大家使用 `useIntl` 或者 `injectIntl`，可以实现同样的功能。
---
### Docs Docs Max Introduce.En US (`docs/docs/docs/max/introduce.en-US.md`)
---
order: 1
toc: content
translated_at: '2024-03-17T09:02:46.141Z'
---
# Umi Max Introduction
Umi, as an extensible enterprise-level front end application framework, has already served 10,000+ applications within Ant Group, either directly or indirectly. Throughout the process of engineering practice, it has solved numerous common problems encountered in front end development, and these experiences have been accumulated into various Umi plugins. In order to make it more convenient for developers to utilize these plugins, we have integrated them into `@umijs/max` based on their open-source foundation. This allows developers to immediately obtain the same development experience as developing Umi applications within Ant Group through a scaffold.
## How to use
By selecting the `Ant Design Pro` template when using `create-umi`, you can use `@umijs/max` to create a project.
```bash {4}
$ npx create-umi@latest
? Pick Umi App Template › - Use arrow-keys. Return to submit.
Simple App
❯ Ant Design Pro
Vue Simple App
```
:::info{title=💡}
In Umi Max projects, use the command line `max{:bash}` instead of the original `umi{:bash}`, as shown below.
:::
```bash /max/
$ npx max g jest
```
Newly created projects come with the following plugins installed by default, which can be enabled as needed:
- [Access Control](./access)
- [Site Analytics](./analytics)
- [Ant Design (Antd)](./antd)
- [Charts](./charts)
- [dva](./dva)
- [Initial State](./data-flow#global-initial-state)
- [Data Flow](./data-flow)
- [Layout and Menu](./layout-menu)
- [Internationalization (i18n)](./i18n)
- [model](./data-flow)
- [Qiankun Micro-frontends](./micro-frontend)
- [Request Library](./request)
- [Tailwind CSS](./tailwindcss)
- [CSS-IN-JS](./styled-components)
- [Request Strategy](./react-query)
- [Global Data Store Strategy](./valtio)
- [Module Federation](./mf)
---
### Docs Docs Max Introduce (`docs/docs/docs/max/introduce.md`)
---
order: 1
toc: content
---
# Umi Max 简介
Umi 作为一个可扩展的企业级前端应用框架，在蚂蚁集团内部已经直接或间接地服务了 10000+ 应用。在工程实践的过程中，解决大量前端开发中开发中遇到的常见问题，这些经验累积成 Umi 各个插件。为了方便开发者更加方便的使用这些插件，在我们这些插件开源的基础上，直接将他们集成到一起，打造了 `@umijs/max`。 让开发者直接可以通过脚手架马上获得和蚂蚁集团开发 Umi 应用一样的开发体检。
## 如何使用
在使用 `create-umi` 选择 `Ant Design Pro` 模板，就能使用 `@umijs/max` 来创建项目了。
```bash {4}
$ npx create-umi@latest
? Pick Umi App Template › - Use arrow-keys. Return to submit.
Simple App
❯ Ant Design Pro
Vue Simple App
```
:::info{title=💡}
在 Umi Max 项目中命令行请使用 `max{:bash}`，而不是原来的 `umi{:bash}`，示例如下
:::
```bash /max/
$ npx max g jest
```
新建的项目默认安装以下插件, 可以按需开启：
- [权限](./access)
- [站点统计](./analytics)
- [Antd](./antd)
- [图表](./charts)
- [dva](./dva)
- [initial-state](./data-flow#全局初始状态)
- [数据流](./data-flow)
- [布局和菜单](./layout-menu)
- [国际化(多语言)](./i18n)
- [model](./data-flow)
- [乾坤微前端](./micro-frontend)
- [请求库](./request)
- [Tailwind CSS](./tailwindcss)
- [CSS-IN-JS](./styled-components)
- [请求方案](./react-query)
- [全局数据存储方案](./valtio)
- [Module Federation](./mf)
---
### Docs Docs Max Layout Menu.En US (`docs/docs/docs/max/layout-menu.en-US.md`)
---
order: 2
toc: content
translated_at: '2024-03-17T09:01:40.363Z'
---
# Layout and Menu
## How to Enable
Configure to enable.
```ts
// config/config.ts
export default {
layout: {
title: 'your app title',
},
};
```
## Introduction
To further reduce R&D costs, we have integrated the layout as a Umi plugin. With simple configurations, you can have the Ant Design Layout ([ProLayout](https://procomponents.ant.design/components/layout)), including the navigation and sidebar. Thus, users don't need to worry about the layout.
- The default is Ant Design's Layout [@ant-design/pro-layout](https://www.npmjs.com/package/@ant-design/pro-layout), supporting all of its configuration items.
- The top navigation/side menu is automatically generated based on the configuration in the route.
- Default support for 403/404 handling of routes and Error Boundary.
- Used in conjunction with the `access` [plugin](./access), it can control route permissions.
- Used in conjunction with the `initial-state` [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts) and [data flow](./data-flow) plugins, it can display default user login information.
> Want dynamic menus? See here [Advanced Usage of Menu](https://beta-pro.ant.design/docs/advanced-menu-cn)
## Configuration
### Build-time Configuration
The plugin can be enabled through the `layout` property in the `config/config.ts` configuration file.
```ts
import { defineConfig } from 'umi';
export default defineConfig({
layout: {
title: 'Ant Design',
locale: false, // Default is enabled, can be disabled if menu internationalization is not needed
},
});
```
#### title
- Type: `string`
- Default: `name` in package.json
The product name displayed in the upper left corner of the layout, the default value is the package name.
#### locale
- Type: `boolean`
- Default: `false`
Whether to start internationalization configuration. After enabling, the menu names configured in the route will be treated as the keys for menu name internationalization. The plugin will look for the corresponding text in the locales file for `menu.[key]`, with the default value as that key, and the value of the name field configured in the route is the corresponding key value. If the menu is a multi-level route, assuming a second-level route menu, then the plugin will look for the corresponding text in the locales file for `menu.[key].[key]`. This feature requires the configuration of [`i18n`](./i18n). Can be configured as `false` to disable if menu internationalization is not needed.
### Runtime Configuration
Runtime configuration is written in `src/app.tsx`, with the key as `layout`.
```tsx
import { RunTimeLayoutConfig } from '@umijs/max';
export const layout: RunTimeLayoutConfig = (initialState) => {
return {
// Commonly used properties
title: 'Ant Design',
logo: 'https://img.alicdn.com/tfs/TB1YHEpwUT1gK0jSZFhXXaAtVXa-28-27.svg',
// Default layout adjustments
rightContentRender: () => ,
footerRender: () => ,
menuHeaderRender: undefined,
// Other properties see: https://procomponents.ant.design/components/layout#prolayout
};
};
```
In addition to the plugin's unique configuration supported below, the runtime configuration supports all the build-time configurations and is passed through to [`@ant-design/pro-layout`](https://procomponents.ant.design/components/layout#prolayout).
#### title
- Type: `string`
- Default: `name` in package.json
The product name displayed in the upper left corner of the layout, the default value is the package name.
#### logo
- Type: `string`
- default: Ant Design Logo
The product logo displayed before the product name in the upper left corner.
#### logout
- Type: `(initialState: any) => void`
- Default: `null`
Used for the default Layout's UI in runtime configuration, handling the logout click logic, by default no action is taken.
> Note: By default, the logout button is not displayed in the upper right corner. It needs to be displayed in conjunction with the runtime configuration `app.ts(x)`'s `getInitialState` returning an object.
#### rightRender
- Type: `(initialState: any) => React.ReactNode`
- Default: Displays the username, avatar, logout-related components
`initialState` is the object returned by `getInitialState` in the runtime configuration `app.ts(x)`.
#### ErrorBoundary
- Type: `ReactNode`
- Default: Ant Design Pro's error page.
The component displayed after an error occurs.
### Extended Route Configuration
The Layout plugin, based on Umi's routing, encapsulates more configuration items, supporting more configuration capabilities. Newly added:
- Sidebar menu configuration.
- Layout route level display/hide related configuration.
- Configuration-style implementation of permission routes by combining with the permissions plugin.
Example as follows:
```typescript
// config/route.ts
export const routes: IBestAFSRoute[] = [
{
path: '/welcome',
component: 'IndexPage',
name: 'Welcome', // This notation is compatible
icon: 'testicon',
// For more features see
// https://beta-pro.ant.design/docs/advanced-menu
// ---
// Open in a new page
target: '_blank',
// Don't show the top bar
headerRender: false,
// Don't show the footer
footerRender: false,
// Don't show the menu
menuRender: false,
// Don't show the menu header
menuHeaderRender: false,
// Permission configuration, needs to be used with the plugin-access
access: 'canRead',
// Hide submenu
hideChildrenInMenu: true,
// Hide self and submenu
hideInMenu: true,
// Hide in breadcrumb
hideInBreadcrumb: true,
// Sub-items up, still displayed,
flatMenu: true,
},
];
```
#### name
- Type: `string`
The name displayed on the menu, if absent, that menu is not displayed.
#### icon
- Type: `string`
The antd icon displayed on the menu, to support on-demand loading, the layout plugin will automatically convert it into an Antd icon's dom. The supported types can be found in [antd icon](https://ant.design/components/icon-cn/). Examples:
```ts
// Line style
icon: 'home'; // Line style can be abbreviated
icon: 'HomeOutlined';
// Solid style
icon: 'HomeFilled';
// Two-tone style
icon: 'HomeTwoTone';
```
#### access
- Type: `string`
When used together with the `plugin-access` plugin.
The permissions plugin will match the access string configured by the user here with all of the user's permissions. If a matching item is found, and if the value of that permission is false, then when the user visits that route, a 403 page is displayed by default.
#### locale
- Type: `string`
The internationalization configuration for the menu, the internationalization key is `menu.${submenu-name}.${name}`.
#### flatMenu
- Type: `boolean`
Default is false. When true, this item is only hidden in the menu, and its sub-items are brought up and still displayed.
Flattening the menu, if you only want the sub-level menu to not display itself, it can be configured to true.
```tsx
const before = [{ name: '111' }, { name: '222', children: [{ name: '333' }] }];
// flatMenu = true
const after = [{ name: '111' }, { name: '222' }, { name: '333' }];
```
#### xxxRender
- Type: `boolean`
Setting xxxRender to false, some layout modules can be hidden
- `headerRender=false` Do not show the top bar
- `footerRender=false` Do not show the footer
- `menuRender=false` Do not show the menu
- `menuHeaderRender=false` Do not show the menu's title and logo
#### hideInXXX
- Type: `boolean`
hideInXXX can manage the rendering of the menu.
- `hideChildrenInMenu=true` Hide submenu
- `hideInMenu=true` Hide self and submenu
- `hideInBreadcrumb=true` Hide in breadcrumb
---
### Docs Docs Max Layout Menu (`docs/docs/docs/max/layout-menu.md`)
---
order: 2
toc: content
---
# 布局与菜单
## 启用方式
配置开启。
```ts
// config/config.ts
export default {
layout: {
title: 'your app title',
},
};
```
## 介绍
为了进一步降低研发成本，我们将布局通过 Umi 插件的方式内置，只需通过简单的配置即可拥有 Ant Design 的 Layout（[ProLayout](https://procomponents.ant.design/components/layout)），包括导航以及侧边栏。从而做到用户无需关心布局。
- 默认为 Ant Design 的 Layout [@ant-design/pro-layout](https://www.npmjs.com/package/@ant-design/pro-layout)，支持它全部配置项。
- 顶部导航/侧边栏菜单根据路由中的配置自动生成。
- 默认支持对路由的 403/404 处理和 Error Boundary。
- 搭配 `access` [插件](./access)一起使用，可以完成对路由权限的控制。
- 搭配 `initial-state` [插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/initial-state.ts) 和 [数据流](./data-flow) 插件一起使用，可以拥有默认用户登陆信息的展示。
> 想要动态菜单？查看这里 [菜单的高级用法](https://beta-pro.ant.design/docs/advanced-menu-cn)
## 配置
### 构建时配置
可以通过配置文件 `config/config.ts` 中的 `layout` 属性开启插件。
```ts
import { defineConfig } from 'umi';
export default defineConfig({
layout: {
title: 'Ant Design',
locale: false, // 默认开启，如无需菜单国际化可关闭
},
});
```
#### title
- Type: `string`
- Default: `name` in package.json
显示在布局左上角的产品名，默认值为包名。
#### locale
- Type: `boolean`
- Default: `false`
是否开始国际化配置。开启后路由里配置的菜单名会被当作菜单名国际化的 key，插件会去 locales 文件中查找 `menu.[key]`对应的文案，默认值为该 key，路由配置的 name 字段的值就是对应的 key 值。如果菜单是多级路由假设是二级路由菜单，那么插件就会去 locales 文件中查找 `menu.[key].[key]`对应的文案，该功能需要配置 [`i18n`](./i18n) 使用。如无需菜单国际化可配置 `false` 关闭。
### 运行时配置
运行时配置写在 `src/app.tsx` 中，key 为 `layout`。
```tsx
import { RunTimeLayoutConfig } from '@umijs/max';
export const layout: RunTimeLayoutConfig = (initialState) => {
return {
// 常用属性
title: 'Ant Design',
logo: 'https://img.alicdn.com/tfs/TB1YHEpwUT1gK0jSZFhXXaAtVXa-28-27.svg',
// 默认布局调整
rightContentRender: () => ,
footerRender: () => ,
menuHeaderRender: undefined,
// 其他属性见：https://procomponents.ant.design/components/layout#prolayout
};
};
```
除了下面的插件支持的特有配置外，运行时配置支持所有的构建时配置并透传给 [`@ant-design/pro-layout`](https://procomponents.ant.design/components/layout#prolayout)。
#### title
- Type: `string`
- Default: `name` in package.json
显示在布局左上角的产品名，默认值为包名。
#### logo
- Type: `string`
- default: Ant Design Logo
显示在布局左上角产品名前的产品 Logo。
#### logout
- Type: `(initialState: any) => void`
- Default: `null`
用于运行时配置默认 Layout 的 UI 中，点击退出登录的处理逻辑，默认不做处理。
> 注：默认在顶部右侧并不会显示退出按钮，需要在运行配置中配合运行时配置 `app.ts(x)` 中的 `getInitialState` 返回一个对象，才可以显示
#### rightRender
- Type: `(initialState: any) => React.ReactNode`
- Default: 展示用户名、头像、退出登录相关组件
`initialState` 是运行时配置 `app.ts(x)` 中的 `getInitialState` 返回的对象。
#### ErrorBoundary
- Type: `ReactNode`
- Default: Ant Design Pro 的错误页。
发生错误后展示的组件。
### 扩展的路由配置
Layout 插件会基于 Umi 的路由，封装了更多的配置项，支持更多配置式的能力。新增：
- 侧边栏菜单配置。
- 布局路由级别展示/隐藏相关配置。
- 与权限插件结合，配置式实现权限路由的功能。
示例如下：
```typescript
// config/route.ts
export const routes: IBestAFSRoute[] = [
{
path: '/welcome',
component: 'IndexPage',
name: '欢迎', // 兼容此写法
icon: 'testicon',
// 更多功能查看
// https://beta-pro.ant.design/docs/advanced-menu
// ---
// 新页面打开
target: '_blank',
// 不展示顶栏
headerRender: false,
// 不展示页脚
footerRender: false,
// 不展示菜单
menuRender: false,
// 不展示菜单顶栏
menuHeaderRender: false,
// 权限配置，需要与 plugin-access 插件配合使用
access: 'canRead',
// 隐藏子菜单
hideChildrenInMenu: true,
// 隐藏自己和子菜单
hideInMenu: true,
// 在面包屑中隐藏
hideInBreadcrumb: true,
// 子项往上提，仍旧展示,
flatMenu: true,
},
];
```
#### name
- Type: `string`
菜单上显示的名称，没有则不展示该菜单。
#### icon
- Type: `string`
菜单上显示的 antd 的 icon，为了按需加载 layout 插件会帮你自动转化为 Antd icon 的 dom。支持类型可以在 [antd icon](https://ant.design/components/icon-cn/) 中找到。示例：
```ts
// 线框风格
icon: 'home'; // outlined 线框风格可简写
icon: 'HomeOutlined';
// 实底风格
icon: 'HomeFilled';
// 双色风格
icon: 'HomeTwoTone';
```
兼容[icons](../../docs/api/config#icons)功能，打开icons功能后，可以使用图标集或者本地的图标。具体请参考icons功能的相关配置和使用方法。
#### access
- Type: `string`
当 Layout 插件配合 `plugin-access` 插件使用时生效。
权限插件会将用户在这里配置的 access 字符串与当前用户所有权限做匹配，如果找到相同的项，并当该权限的值为 false，则当用户访问该路由时，默认展示 403 页面。
#### locale
- Type: `string`
菜单的国际化配置，国际化的 key 是 `menu.${submenu-name}.${name}`。
#### flatMenu
- Type: `boolean`
默认为 false，为 true 时在菜单中只隐藏此项，子项往上提，仍旧展示。
打平菜单，如果只想要子级的 menu 不展示自己的，可以配置为 true。
```tsx
const before = [{ name: '111' }, { name: '222', children: [{ name: '333' }] }];
// flatMenu = true
const after = [{ name: '111' }, { name: '222' }, { name: '333' }];
```
#### xxxRender
- Type: `boolean`
xxxRender 设置为 false，即可不展示部分 layout 模块
- `headerRender=false` 不显示顶栏
- `footerRender=false` 不显示页脚
- `menuRender=false` 不显示菜单
- `menuHeaderRender=false` 不显示菜单的 title 和 logo
#### hideInXXX
- Type: `boolean`
hideInXXX 可以管理 menu 的渲染。
- `hideChildrenInMenu=true` 隐藏子菜单
- `hideInMenu=true` 隐藏自己和子菜单
- `hideInBreadcrumb=true` 在面包屑中隐藏
---
### Docs Docs Max Mf.En US (`docs/docs/docs/max/mf.en-US.md`)
---
order: 17
toc: content
translated_at: '2024-03-17T08:55:33.242Z'
---
# Module Federation Plugin
Using Module Federation functionality in Umi projects.
:::warning{title=🚨}
Module Federation functionality requires browser support for `Top Level Await` feature. Please pay attention to browser support ([Browser support status](https://caniuse.com/?search=top%20level%20await)) when using it in production environment.
:::
## Configuration
### Configuring the use of remote modules
@umijs/max projects
```ts
// .umirc.ts
import { defineConfig } from '@umijs/max';
const shared = {
react: {
singleton: true,
eager: true,
},
'react-dom': {
singleton: true,
eager: true,
},
};
export default defineConfig({
// Module Federation plugin is already built-in, just enable the configuration
mf: {
remotes: [
{
// Optional, if not configured, the current remotes[].name field is used
aliasName: 'mfNameAlias',
name: 'theMfName',
entry: 'https://to.the.remote.com/remote.js',
// Optional，will modify the publicPath of mf entry files to window[`mf_${name}EntryPath`]
runtimeEntryPath: {},
},
],
// Configure MF shared modules
shared,
},
});
```
Regular Umi projects
```ts
// .umirc.ts
import { defineConfig } from 'umi';
const shared = {
react: {
singleton: true,
eager: true,
},
'react-dom': {
singleton: true,
eager: true,
},
};
export default defineConfig({
plugins: ['@umijs/plugins/dist/mf'], // Import plugin
mf: {
remotes: [
{
// Optional, if not configured, the current remotes[].name field is used
aliasName: 'mfNameAlias',
name: 'theMfName',
entry: 'https://to.the.remote.com/remote.js',
},
],
// Configure MF shared modules
shared,
},
});
```
In the project, you can now use `import XXX from 'mfNameAlias/XXXX'` to use the content of remote modules.
#### Runtime remote module loading
If you need to decide the remote module's loading address at runtime (based on the running environment), you can configure it as follows:
```ts
// .umirc.ts
defineConfig({
mf: {
remotes: [
{
name: 'theMfName',
keyResolver: `(function(){
try {
return window.injectInfo.env || 'PROD'
} catch(e) {
return 'PROD'}
})()`,
entries: {
PRE: 'http://pre.mf.com/remote.js',
PROD: 'http://produ.mf.com/remote.js',
TEST: 'http://test.dev.mf.com/remote.js',
DEV: 'http://127.0.0.1:8000/remote.js',
},
},
],
shared,
},
});
```
- When using runtime remote module loading logic, do not configure `remotes[]#entry`, the plugin will prioritize this field.
- `keyResolver` is used to decide which key of `entries` to use at runtime; using an _Immediately Invoked Function Expression_ is recommended and can implement more complex functionality in the function. Does not support asynchronous functions.
- `keyResolver` can also use static values, configured as `keyResolver: '"PROD"'`
### Configuration for exporting remote modules
For the current project to provide remote modules, use the following configuration field for the module name
```ts
// .umirc.ts
// Extracting the variable is for consistent configuration with MFSU
const remoteMFName = 'remoteMFName';
defineConfig({
mf: {
name: remoteMFName,
// Optional, library type of remote module, if the module needs to be used in a Qiankun sub-application, the suggested value is recommended,
// Note that the name here must be consistent with the final MF module name
// library: { type: "window", name: "exportMFName" },
},
});
```
:::info{title=🚨}
The configured module name must be a valid Javascript variable name!
:::
The modules exported follow the convention, taking the directory names under `src/exposes` as the export items, and the export file is the index file under that directory, for example
```txt
src/exposes/
├── Button
│ └── index.jsx
├── Head
│ └── index.ts
└── Form
└── index.tsx
```
The corresponding Module Federation exposes are
```js
{
'./Button': 'src/exposes/Button/index.jsx',
'./Button': 'src/exposes/Head/index.ts',
'./Form' : 'src/exposes/Form/index.tsx',
}
```
### Disabling MF product hash
By default, when the user enables `hash: true`, the entry file in the MF product will automatically carry a hash, such as `remote.123abc.js`. You can disable it by setting `remoteHash: false` (resulting in `remote.js`), at which point you may need to modify nginx/CDN/gateway response header configuration to remove the cache for the `remote.js` file, otherwise the new build will not take effect.
Note: More harm without hash and recommended practices are detailed in [issue #11711](https://github.com/umijs/umi/issues/11711)
```ts
mf: {
remoteHash: false
}
```
## Runtime API
### When to use runtime API?
Configuring with `import()` can easily use the Module Federation functionality. However, consider using runtime API if you have the following needs:
- When loading a remote module fails, the page needs to use a fallback component
- The loading address of the remote module cannot be determined by a synchronous function (requires asynchronous call)
- The loading address and module name of the remote module need to be determined at runtime
### safeMfImport
A fail-safe remote module loading function, interface definition as follows:
```ts
safeMfImport(moduleSpecifier: string, fallback: any): Promise
```
Combined with `React.lazy` can implement lazy loading of remote modules
```ts
import { safeMfImport } from '@umijs/max';
import React, { Suspense } from 'react';
const RemoteCounter = React.lazy(() => {
return safeMfImport('remoteCounter/Counter', { default: () => 'Fallback' });
});
export default function Page() {
return (
);
};
```
:::info{title=🚨}
- Note that the fallback ***component*** needs to be wrapped in the object's `default` field to mimic a module.
- `remoteCounter/Counter` needs to correspond with the configuration.
:::
[Example code](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/safe-import.tsx)
### safeRemoteComponent
This API is a higher-order component that encapsulates `safeMfImport`, interface definition as follows:
```ts
safeRemoteComponent>
(opts: {
moduleSpecifier:string;
fallbackComponent: React.ComponentType; // Fallback component if remote component fails to load
loadingElement: React.ReactNode ; // Loading display for component loading
} ): T
```
Example:
```ts
const RemoteCounter = safeRemoteComponent>({
moduleSpecifier: 'remoteCounter/Counter',
fallbackComponent: () => 'fallbacked',
loadingElement: 'Loading',
});
export default function Page() {
return (
);
};
```
[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/safe-remote-component.tsx)
### rawMfImport
加载远端模块，接口如下。
```ts
rawMfImport(opts: {
entry: string;
remoteName: string;
moduleName: string;
}): Promise
```
示例
```ts
const RemoteCounter = React.lazy(() => {
return rawMfImport({
entry: 'http://localhost:8001/remote.js',
moduleName: 'Counter',
remoteName: 'remoteCounter',
});
});
```
[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/raw-mf-import.tsx)
### safeRemoteComponentWithMfConfig
封装了`rawMfImport`的 高阶组件：
```ts
type RawRemoteComponentOpts ={
mfConfig:{
entry:string;
remoteName: string;
moduleName: string;
};
fallbackComponent: ComponentType;
loadingElement: ReactNode;
}
safeRemoteComponentWithMfConfig>(opts: RawRemoteComponentOpts): T
```
示例
```ts
const RemoteCounter = safeRemoteComponentWithMfConfig<
React.FC<{ init?: number }>
>({
mfConfig: {
entry: 'http://localhost:8001/remote.js',
moduleName: 'Counter',
remoteName: 'remoteCounter',
},
fallbackComponent: () => 'raw Fallback',
loadingElement: 'raw Loading',
});
export default function Page() {
return ;
};
```
[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/raw-mf-component.tsx)
### registerMfRemote
动态的注册 Module Federation 模块远端配置。
```ts
type MFModuleRegisterRequest = { entry: string; remoteName: string; aliasName?:string; }
registerMfRemote (opts: MFModuleRegisterRequest): void
```
使用 `safeMfImport` 或者 `safeRemoteComponent` 时，`moduleSpecifier` 须是已经配置的远端模块。而 `rawMfImport` 的调用略啰嗦，可以使用 `registerMfRemote` 先注册，然后通过简洁的 `safeMfImport` 和 `safeRemoteComponent`。
```ts
registerMfRemote({
aliasName: 'registered',
remoteName: 'remoteCounter',
entry: 'http://127.0.0.1:8001/remote.js',
});
const RemoteCounter = React.lazy(() => {
return safeMfImport('registered/Counter', { default: null });
});
```
[示例代码](https://github.com/umijs/umi/blob/master/examples/mf-host/src/pages/register-then-import.tsx)
## 和 MFSU 一起使用
Module Federation 插件会根据插件配置自动修改 MFSU 的**默认**配置以使两个功能在开发阶段正常使用，原理介绍如下：
假设我们采用了如下 mf 插件的配置
```ts
// .umirc.ts
export default defineConfig({
mf: {
name: 'remoteMFName',
remotes: [
{
name: 'remote1',
entry: 'https://to.the.remote.com/remote.js',
},
{
aliasName: 'aliasRemote',
name: 'remote2',
entry: 'https://to.the.remote.com/remote2.js',
},
],
shared: {
react: {
singleton: true,
eager: true,
},
'react-dom': {
singleton: true,
eager: true,
},
}
},
});
```
那么对应最后生效的配置如下
```ts
{
mfsu: {
// mf 插件自动填充以下和 MFSU 兼容的默认配置
// 开启了 MFSU 也能在 DEV 阶段调试 MF 的模块
remoteName: 'remoteMFName',
remoteAliases: ['remote1', 'aliasRemote'],
shared: {
react: {
singleton: true,
eager: true,
},
'react-dom': {
singleton: true,
eager: true,
},
}
},
mf: {
name: 'remoteMFName',
remotes: [
{
name: 'remote1',
entry: 'https://to.the.remote.com/remote.js',
},
{
aliasName: 'aliasRemote',
name: 'remote2',
entry: 'https://to.the.remote.com/remote2.js',
},
],
shared: {
react: {
singleton: true,
eager: true,
},
'react-dom': {
singleton: true,
eager: true,
},
},
},
}
```
---
### Docs Docs Max Micro Frontend.En US (`docs/docs/docs/max/micro-frontend.en-US.md`)
---
order: 9
toc: content
translated_at: '2026-08-17T03:38:01.000Z'
---
# Micro Frontends
`@umi/max` has a built-in **Qiankun Micro Frontends** [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts), which can enable the Qiankun micro frontend development mode with one click, helping you easily integrate Qiankun micro applications in your Umi project, and build a production-ready micro frontend architecture system.
For more information about Qiankun Micro Frontends, please refer to [this page](https://qiankun.umijs.org/guide).
## Micro Frontend Example
As shown in the picture above: In the parent application, after switching routes through the navigation bar, the content displayed below comes from different child applications. Child applications support being opened independently; child applications also support arbitrary nesting among themselves.
Another more intuitive understanding: Both the parent and child applications are **independent front-end projects**. The parent application can introduce child applications internally, and child applications can also continue to introduce grandchild applications internally, and so on.
When an application can be introduced by other applications as a child application, it becomes what we call a micro application.
## Getting Started
:::success{title=🏆︎}
This tutorial assumes that you have a basic understanding of what micro frontends are, what Qiankun micro applications are, and how to use Qiankun micro applications.
:::
### Configure the Parent Application
First, you need to configure the parent application and register information related to the child applications so that the parent application can recognize and introduce the child applications internally.
There are mainly two ways to register child applications:
- Register child applications through the plugin.
- Register child applications at runtime.
#### Register Child Applications Through the Plugin
Modify the Umi configuration file of the parent application and add the following content:
```ts
// .umirc.ts
export default {
qiankun: {
master: {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
},
{
name: 'app2',
entry: '//localhost:7002',
},
],
},
},
};
```
Where `name` is the name of the child application, which is needed when introducing the child application; `entry` is the HTTP address where the child application is running; the full API of `master` object can be [seen here](#masteroptions).
#### Register Child Applications at Runtime
Modify the Umi configuration file of the parent application and add the following content:
```ts
// .umirc.ts
export default {
qiankun: {
master: {},
},
};
```
Modify the `src/app.ts` file of the parent application and export the `qiankun` object:
```ts
// src/app.ts
export const qiankun = {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
},
{
name: 'app2',
entry: '//localhost:7002',
},
],
};
```
### Configure the Child Application
Child applications need to export necessary lifecycle hooks for the parent application to call at the appropriate time.
Assuming your child application project is **developed based on Umi** and **the `qiankun` [plugin](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts) is introduced**. If not, you can follow [this tutorial](https://qiankun.umijs.org/guide/getting-started#sub-application) to configure.
:::warning{title="Utoopack compatibility"}
If the child application is built with utoopack and the parent application uses qiankun 2, upgrade qiankun in the parent application to `2.10.17-beta.0` or later. Earlier versions do not provide `document.currentScript` correctly while executing entry scripts, which prevents the child application from loading. For more details, see the Utoo blog post [When Turbopack Meets qiankun: Adapting Utoopack for Micro Frontends](https://utoo.land/en/docs/blog/utoopack-qiankun).
:::
Modify the Umi configuration file of the child application and add the following content:
```ts
// .umirc.ts
export default {
qiankun: {
slave: {},
},
};
```
This way, the micro frontend plugin will automatically create the necessary lifecycle hooks and methods for the Qiankun child application in the project, Easy as a cake！
### Introduce Child Applications
To introduce child applications in the parent application, the plugin provides three different implementation methods:
- Introduce child applications based on routing.
- Introduce child applications through the `` component.
- Introduce child applications through the `` component.
#### Introduce Child Applications Based on Routing
Manually configure the `routes` item in the `.umirc.ts` file by binding child applications through routing. When to use:
- When the child application contains a complete routing switching logic.
- When the routing of parent and child applications is interrelated.
Now, if we want to load child applications `app1` and `app2` on the `/app1/project` and `/app2` routes, respectively, we can configure the parent application's routing as follows:
```ts
// .umirc.ts
export default {
routes: [
{
path: '/',
component: '@/layouts/index.tsx',
routes: [
{
path: '/app1',
component: '@/layouts/app-layout.tsx',
routes: [
// Configure the route associated with micro application app1
{
// Adding a * wildcard means associating all sub-routes under /app1/project to the micro application app1
path: '/project/*',
microApp: 'app1',
},
],
},
// Configure the route associated with app2
{
path: '/app2/*',
microApp: 'app2',
},
],
},
],
};
```
After configuration, the base route of the child application will be set to the `path` configured in the main application at runtime.
For example, in the above configuration, we specified the path associated with app1 as `/app1/project`. Suppose there is a route configured as `/user` in app1. When we want to access the page corresponding to `/user` in the parent application, the browser's URL needs to be `base + /user`, which is the `/app1/project/user` path, otherwise, the child application will render a blank or 404 page because it cannot match the correct route.
The `qiankun` plugin extends the original Umi routing object and adds a `microApp` field, which is the `name` of the registered child application. After switching to the corresponding route, Umi will use the `` component to render this child application and replace the original route's `component`.
The extended Umi routing object API can be [seen here](#route).
#### Introduce Child Applications Through the `` Component
Load (or unload) child applications through the `` component. When to use:
- When the child application contains a complete routing switching logic.
- When the routing of parent and child applications is interrelated.
Now, if we want to introduce child application `app1` in a certain page of the parent application, we can write the code as follows:
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return ;
}
```
When using this method to introduce child applications, the routing of parent and child applications will correspond one-to-one. For example, when the parent application's routing is `/some/page`, the child application's routing will be the same as `/some/page`. When switching child application routing, the parent application will switch synchronously.
If the parent application's route includes a prefix, you can configure the `base` attribute to ensure that the routing of the parent and child applications correspond correctly. For example, when the parent application's route is `/prefix/router-path/some/page`, if we want the child application's route to be `/some/page`, we can modify the code as follows:
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return ;
}
```
#### Introduce Child Applications Through the `` Component
Load (or unload) child applications through the `` component. When to use:
- Only use the specified route of the child application.
- When the routing of parent and child applications is independent of each other.
The `` component is a variant of the `` component. You need to explicitly provide the `url` attribute as the route of the child application. When the route of the parent application changes, the route of the child application **will not change**.
Now, if we want to introduce child application `app2` inside a certain component of the parent application, with the route of the child application being `/some/page`, we can write the code as follows:
```tsx
import { MicroAppWithMemoHistory } from 'umi';
export default function Page() {
return ;
}
```
### Jumping Between Child Applications
If child applications are introduced **through the routing binding method**, inside other child applications, you can use `` to jump to the corresponding route. Take child applications `app1` and `app2` as examples:
```tsx
// In app1
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
{/* The jump link is /app2/home */}
);
}
```
In the above example, after clicking the button, the parent application's routing becomes `/app2/home`, rendering the page of child application `app2` with an internal routing of `/home`. Similarly, if you want to go back to child application app1 from child application app2, you can write the code as follows:
```tsx
// In app2
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
{/* The jump link is /app1/project/home */}
);
}
```
You can also jump from the child application to the specified route of the parent application:
```tsx
// In the child application
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
{/* The jump link is /table */}
);
}
```
## Child Application Lifecycle
Qiankun implemented some additional lifecycle hooks on the basis of single-spa. In the order of the micro application's lifecycle, the complete list of supported lifecycle hooks by Qiankun is as follows:
- `beforeLoad`, called **before the micro applications start fetching**. Initially, the micro application state is `NOT_LOADED`.
- [`load`](https://single-spa.js.org/docs/building-applications/#load), called **when the micro application is fetched**. The micro application state becomes `LOADING_SOURCE_CODE` when starting to fetch the micro application. If fetched successfully, the state becomes `NOT_BOOTSTRAPPED`; if the fetch fails, the state becomes `LOAD_ERROR`.
- [`bootstrap`](https://single-spa.js.org/docs/building-applications/#bootstrap), called **when the micro application finishes initializing**. The micro application state becomes `BOOTSTRAPPING` when starting to initialize the micro application. When initialization is finished, the state becomes `NOT_MOUNTED`.
- `beforeMount`, called **every time before the micro application starts mounting**.
- [`mount`](https://single-spa.js.org/docs/building-applications/#mount), called **every time when the micro application starts mounting**. The micro application state becomes `MOUNTING`.
- `afterMount`, called **every time when the micro application finishes mounting**. The micro application state becomes `MOUNTED`.
- `beforeUnmount`, called **every time before the micro application starts unmounting**.
- [`unmount`](https://single-spa.js.org/docs/building-applications/#unmount), called **every time when the micro application starts unmounting**. The micro application state becomes `UNMOUNTING`.
- `afterUnmount`, called **every time when the micro application finishes unmounting**. The micro application state becomes `NOT_MOUNTED`.
- [`unload`](https://single-spa.js.org/docs/building-applications/#unload), called **when the micro application is fully unloaded**. The micro application state becomes `NOT_LOADED`.
In addition, there is a special lifecycle hook `update`, which is effective only when introducing micro applications through the `` or `` component: it is called **manually when the micro application in the `MOUNTED` state is refreshed**. When starting to update, the micro application state becomes `UPDATING`; when the update is completed, the state becomes `MOUNTED` again.
You can refresh the child application manually like this:
```tsx
import { useRef } from 'react';
import { MicroApp } from 'umi';
export default function Page() {
const microAppRef = useRef();
// When this method is executed, the child application is updated
const updateMicroApp = () => {
microAppRef.current?.update();
};
return ;
}
```
When you need to add some custom logic in the lifecycle of the child application, you can configure it globally in the parent application as well as configure it individually in the child application.
### Parent Application Configures Lifecycle Hooks
Export the `qiankun` object in the `src/app.ts` of the parent application for global configuration. All child applications will implement these lifecycle hooks:
```ts
// src/app.ts
export const qiankun = {
lifeCycles: {
// For all child applications, print props information when mounting is finished
async afterMount(props) {
console.log(props);
},
},
};
```
### Child Application Configures Lifecycle Hooks
Export the `qiankun` object in the `src/app.ts` of the child application to implement lifecycle hooks. The child application supports configuring `bootstrap`, `mount`, and `unmount` hooks at runtime:
```ts
// src/app.ts
export const qiankun = {
// Before the application loads
async bootstrap(props) {
console.log('app1 bootstrap', props);
},
// Triggered before the application render
async mount(props) {
console.log('app1 mount', props);
},
// Triggered after the application unmounts
async unmount(props) {
console.log('app1 unmount', props);
},
};
```
## Communication Between Parent and Child Applications
There are two ways to implement communication between parent and child applications:
- Communication based on `useModel()`. This is the solution **recommended** by Umi.
- Communication based on configuration.
### Communication Based on `useModel()`
This communication method is based on the [data flow](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts) plugin, which is already integrated into the `@umi/max` solution.
This communication method requires the child application to be **developed based on Umi** and to **introduce the data flow plugin**.
For detailed introduction to this plugin, see [Data Flow Guide](./data-flow).
#### The Main Application Passes Data
If child applications are introduced through the routing method, you need to export a function named `useQiankunStateForSlave()` in the `src/app.ts` of the parent application. The return value of this function will be passed to the child application:
```ts
// src/app.ts
export function useQiankunStateForSlave() {
const [globalState, setGlobalState] = useState({
slogan: 'Hello MicroFrontend',
});
return {
globalState,
setGlobalState,
};
}
```
If child applications are introduced through the component method, directly pass the data as component parameters to the child application:
```tsx
import { useState } from 'react';
import { MicroApp } from 'umi';
export default function Page() {
const [globalState, setGlobalState] = useState({
slogan: 'Hello MicroFrontend',
});
return (
);
}
```
#### Child Application Consumes Data
The child application will automatically generate a global Model, whose namespace is `@@qiankunStateFromMaster`. Through the `useModel()` method, child applications are allowed to get and consume the data passed by the parent application in any component, as follows:
```tsx
import { useModel } from 'umi';
export default function Page() {
const masterProps = useModel('@@qiankunStateFromMaster');
return
{JSON.stringify(masterProps)}
;
}
```
Or you can obtain and consume the data passed by the parent application through the higher-order method `connectMaster()`, as shown below:
```tsx
import { connectMaster } from 'umi';
function MyPage(props) {
return
{JSON.stringify(props)}
;
}
export default connectMaster(MyPage);
```
The child application can also obtain and consume the `props` properties in the lifecycle hooks [configured according to the requirements](#child-application-configures-lifecycle-hooks).
Especially, when the parent application introduces the child application through the `` or `` component method, an additional `setLoading()` method will be passed to the child application. This allows the child application to execute this method at the appropriate time to mark the child application as loaded:
```tsx
const masterProps = useModel('@@qiankunStateFromMaster');
masterProps.setLoading(false);
// Or
function MyPage(props) {
props.setLoading(false);
}
connectMaster(MyPage);
```
When the child application finishes mounting and becomes `MOUNTED`, it will automatically be marked as loaded.
### Communication Based on Configuration
When [registering the child application](#configure-the-parent-application) in the parent application configuration, the `props` attribute can be passed, transferring data to the child application.
For example, modify the `src/app.ts` of the parent application's `qiankun` export method as follows:
```ts
// src/app.ts
export const qiankun = {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
props: {
accountOnClick: (event) => console.log(event),
accountName: 'Alex',
accountAge: 21,
},
},
],
};
```
The child application can obtain and use the passed `props` in lifecycle hooks by [implementing the corresponding lifecycle hooks](#child-application-configures-lifecycle-hooks) as needed.
## Custom Child Applications
When a loading indicator or error boundary is enabled for a child application, the child application receives an additional `wrapperClassName` CSS class. The rendered structure is as follows:
```tsx
```
### Child Application Loading Indicator
After this capability is enabled, a loading indicator is displayed automatically while the child application is loading. When the child application finishes mounting and reaches the `MOUNTED` state, the loading state ends and the child application content is displayed.
#### antd-based Loading Indicator
If your project uses antd, pass the `autoSetLoading` property to the child application to enable its loading indicator. The plugin automatically uses antd's [`` component](https://ant.design/components/spin) as the loader.
When introducing a child application through routing, configure it as follows:
```ts
// .umirc.ts
export default {
routes: [
{
path: '/app1',
microApp: 'app1',
microAppProps: {
autoSetLoading: true,
},
},
],
};
```
When introducing a child application through a component, pass `autoSetLoading` directly:
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return ;
}
```
#### Custom Loading Indicator
If your project does not use antd, or if you want to override the default loading style, provide a custom `loader` component for the child application.
Child applications introduced through routing support this option only in runtime configuration:
```tsx
// .app.tsx
import CustomLoader from 'src/components/CustomLoader';
export const qiankun = () => ({
routes: [
{
path: '/app1',
microApp: 'app1',
microAppProps: {
loader: (loading) => ,
},
},
],
});
```
When introducing a child application through a component, pass `loader` directly:
```tsx
import CustomLoader from '@/components/CustomLoader';
import { MicroApp } from 'umi';
export default function Page() {
return (
}
/>
);
}
```
The `loading` parameter is a `boolean`: `true` means that the child application is still loading, and `false` means that loading has finished.
To share one custom loading indicator across multiple child applications, configure `defaultLoader` in the parent application:
```ts
// .umirc.ts
qiankun: {
master: {
defaultLoader: '@/defaultLoader',
},
},
```
`defaultLoader` is a file path. By convention, place the file in the [src directory](../guides/directory-structure#src-directory). In Umi, `@` represents the `src` directory.
`defaultLoader` has the same implementation as `loader` and receives a `boolean` `loading` parameter.
```tsx
// defaultLoader.tsx
import { Spin } from 'antd';
export default function (loading: boolean) {
return ;
}
```
Note: `loader` takes precedence over `defaultLoader`.
### Child Application Error Handling
After this capability is enabled, error information is displayed automatically when a child application fails to load.
#### antd-based Error Boundary
If your project uses antd, pass the `autoCaptureError` property to the child application to enable error handling. The plugin automatically uses antd's [`` component](https://ant.design/components/result) as the error boundary.
For example, the displayed language automatically follows the Umi locale configuration:
When introducing a child application through routing, configure it as follows:
```ts
// .umirc.ts
export default {
routes: [
{
path: '/app1',
microApp: 'app1',
microAppProps: {
autoCaptureError: true,
},
},
],
};
```
When introducing a child application through a component, pass `autoCaptureError` directly:
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return ;
}
```
#### Custom Error Boundary
If your project does not use antd, or if you want to override the default error boundary style, provide a custom `errorBoundary` component for the child application.
Child applications introduced through routing support this option only in runtime configuration:
```tsx
// .app.tsx
import CustomErrorBoundary from '@/components/CustomErrorBoundary';
export const qiankun = () => ({
routes: [
{
path: '/app1',
microApp: 'app1',
microAppProps: {
errorBoundary: (error) => ,
},
},
],
});
```
When introducing a child application through a component, pass `errorBoundary` directly:
```tsx
import CustomErrorBoundary from '@/components/CustomErrorBoundary';
import { MicroApp } from 'umi';
export default function Page() {
return (
}
/>
);
}
```
The `error` parameter is an `Error` object.
To share one custom error boundary across multiple child applications, configure `defaultErrorBoundary` in the parent application:
```ts
// .umirc.ts
qiankun: {
master: {
defaultErrorBoundary: '@/defaultErrorBoundary',
},
},
```
`defaultErrorBoundary` is a file path. By convention, place the file in the [src directory](../guides/directory-structure#src-directory). In Umi, `@` represents the `src` directory.
`defaultErrorBoundary` has the same implementation as `errorBoundary` and receives an `Error` parameter.
```tsx
// defaultErrorBoundary.tsx
export default function (error: Error) {
return
{error?.message}
;
}
```
Note: `errorBoundary` takes precedence over `defaultErrorBoundary`.
## Micro App Cache keepAlive
When enabled, micro apps bound via routes keep their cache after you navigate away (powered by [`react-activation`](https://github.com/CJY0208/react-activation)), so state can be restored when you come back.
It is off by default. The plugin only wraps micro app routes with `KeepAlive` when enabled; **your app must mount `AliveScope` at the root** to own the cache lifecycle.
Full sample: [`examples/qiankun-keepalive`](https://github.com/umijs/umi/tree/master/examples/qiankun-keepalive) (master + `app1` / `app2`, tab bar, slave route `wrappers`).
### Configuration
```ts
// master .umirc.ts
export default {
plugins: ['umi-plugin-keep-alive'],
qiankun: {
keepAlive: true,
master: {
apps: [
{
// Must match slave package.json name and route microApp
name: 'app1',
entry: '//localhost:7001',
// Align with the route path prefix; injected as slave history.basename
base: '/app1',
},
],
},
},
routes: [
{ path: '/app1/*', microApp: 'app1' },
],
};
```
```ts
// slave package.json
{ "name": "app1" }
// slave .umirc.ts
const { name } = require('./package.json');
const isProd = process.env.NODE_ENV === 'production';
export default {
plugins: ['umi-plugin-keep-alive'],
qiankun: { slave: {} },
// Production assets/routes under /${name}/; in dev the master injects base
base: isProd ? `/${name}/` : '/',
publicPath: isProd ? `/${name}/` : '/',
routes: [
// Wrap every page with KeepAlive (umi wrappers become parent routes; use Outlet)
{ path: '/', component: 'index', wrappers: ['@/keepAlive/index'] },
{ path: '/about', component: 'about', wrappers: ['@/keepAlive/index'] },
],
};
```
### Mount AliveScope
Prefer [`umi-plugin-keep-alive`](https://github.com/alitajs/umi-plugin-keep-alive) (public `0.0.1-beta.34` with `react-activation@^0.13.4`): it mounts `AliveScope` and re-exports `KeepAlive` / `useAliveController` from `umi` / `@umijs/max`.
You can also wrap `AliveScope` in `app.tsx` via `rootContainer`. **Both master and slave need an AliveScope** (plugin or manual).
### Two cache layers
| Layer | Cache name | Role |
| --- | --- | --- |
| Master plugin | `` `qiankun_/${appName}/` `` | Caches the whole micro-app tree across app switches |
| Master tabs | `location.pathname` (e.g. `/app1/about`) | Empty `KeepAlive` only occupies a tab; real micro-app content renders outside |
| Slave wrappers | Slave `location.pathname` | Caches each page inside the micro app |
The tab bar should list caches **without** the `qiankun_` prefix; `qiankun_*` only holds the micro-app instance. After a slave clears its page caches, it can call `window.closeKeepAliveTab?.('qiankun_/app1/')` so the master drops that micro-app tree.
### Cache cleanup
```ts
import { useAliveController } from '@umijs/max';
const { dropScope } = useAliveController();
dropScope('qiankun_/app1/');
// or: window.closeKeepAliveTab?.('qiankun_/app1/');
```
### Pitfalls
:::warning{title=Important}
1. **`package.json` `name` must match `qiankun.master.apps[].name` and route `microApp`** (e.g. `app1` / `app2`). The cache key is `` `qiankun_/${name}/` ``; mismatches break tab close / cleanup.
2. **Align master `apps[].base` with the route prefix** (e.g. `base: '/app1'` with `path: '/app1/*'`); it is injected as the slave `history.basename`.
3. **Slave `base` / `publicPath` are env-specific**: production uses `` `/${name}/` ``; development usually uses `'/'` while the master injects the basename.
4. **React 18 requires `autoFreeze: false`**. With freeze on, restored micro apps often lose input/select state or become non-interactive. Generated micro-app `KeepAlive` already sets `autoFreeze={false}`; also disable it for any other `KeepAlive` you mount:
```ts
// master/slave app.tsx
import { KeepAlive } from 'react-activation';
KeepAlive.defaultProps = {
...(KeepAlive.defaultProps || {}),
autoFreeze: false,
};
```
5. **`KeepAlive` and `AliveScope` must share one `react-activation` instance**. Install `react-activation` in the app (or via `umi-plugin-keep-alive`). If KeepAlive resolves from a different copy than AliveScope, caching silently fails and state is lost on switch.
6. **Wrap every slave page with `wrappers`**, and render the page with `` inside the wrapper (do not rely on `props.children` only — umi wrappers become `isWrapper` parents, otherwise the page is blank).
7. **Master tabs**: for micro-app routes, use an empty `KeepAlive` with `name={location.pathname}` for the tab, and render `` (the micro app) **outside** that KeepAlive so paths like `/app1/about` get tabs without blocking master providers.
8. **`keepAlive` only applies to route-bound `microApp`**. For `` / ``, wrap `KeepAlive` yourself.
:::
## Environment Variables
If you have configuration that cannot be written explicitly in `.umirc.ts` or `src/app.ts`, store it in an environment variable file. For example, define the parent application's `.env` file as follows:
```plaintext
INITIAL_QIANKUN_MASTER_OPTIONS="{\"apps\":[{\"name\":\"app1\",\"entry\":\"//localhost:7001\"},{\"name\":\"app2\",\"entry\":\"//localhost:7002\"}]}"
```
Internally, the micro frontend plugin runs `JSON.parse(process.env.INITIAL_QIANKUN_MASTER_OPTIONS)` and merges the result with the existing configuration. The environment variable above is equivalent to the following merged configuration:
```ts
export default {
qiankun: {
master: {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
},
{
name: 'app2',
entry: '//localhost:7002',
},
],
// ...other configuration from .umirc.ts
},
},
};
```
When the same option exists in both places, such as `apps`, the value in `.umirc.ts` **overrides** the value from the environment variable.
Similarly, a child application can define the following `.env` file:
```plaintext
INITIAL_QIANKUN_SLAVE_OPTIONS="{\"enable\":false}"
```
This is equivalent to the following configuration:
```ts
export default {
qiankun: {
slave: {
enable: false,
// ...other configuration from .umirc.ts
},
},
};
```
## API
### QiankunOptions
| Property | Required | Description | Type | Default |
| --- | --- | --- | --- | --- |
| `master` | No | Parent application configuration | [`MasterOptions`](#masteroptions) | `undefined` |
| `slave` | No | Child application configuration | [`SlaveOptions`](#slaveoptions) | `undefined` |
| `keepAlive` | No | Whether to cache route-bound micro apps; see [Micro App Cache keepAlive](#micro-app-cache-keepalive) | `boolean` | `false` |
| `externalQiankun` | No | Whether to use an external qiankun dependency | `boolean` | `false` |
### MasterOptions
| Property | Required | Description | Type | Default |
| --- | --- | --- | --- | --- |
| `enable` | No | Enables the Qiankun micro application plugin; set it to `false` to disable the plugin | `boolean` | `undefined` |
| `apps` | Yes | Micro application configuration | [`App[]`](#app) | `undefined` |
| `routes` | No | Runtime routes for micro applications | [`Route[]`](#route) | `undefined` |
| `defaultErrorBoundary` | No | Default error boundary for child applications, specified as a file path | `string` | - |
| `defaultLoader` | No | Default loading indicator for child applications, specified as a file path | `string` | - |
| `sandbox` | No | Whether to enable sandbox mode | `boolean \| { strictStyleIsolation: boolean, experimentalStyleIsolation: boolean }` | `true` |
| `prefetch` | No | Whether to prefetch micro applications | `boolean \| 'all' \| string[] \| (( apps: RegistrableApp[] ) => { criticalAppNames: string[]; minorAppsName: string[] })` | `true` |
For more information about sandboxing and prefetching, see the [Qiankun API documentation](https://qiankun.umijs.org/api/#startopts).
### SlaveOptions
| Property | Required | Description | Type | Default |
| --- | --- | --- | --- | --- |
| `enable` | No | Enables the Qiankun micro application plugin; set it to `false` to disable the plugin | `boolean` | `undefined` |
### App
| Property | Required | Description | Type | Default |
| --- | --- | --- | --- | --- |
| `name` | Yes | Name of the micro application | `string` | - |
| `entry` | Yes | HTML address of the micro application | `string` | `{ script: string[], styles: [] }` |
| `credentials` | No | Whether to include cookies when fetching the micro application; see the [Qiankun FAQ](https://qiankun.umijs.org/faq/) | `boolean` | `false` |
| `props` | No | Data passed from the parent application to the micro application; see [Communication Between Parent and Child Applications](#communication-between-parent-and-child-applications) | `object` | `{}` |
### Route
| Property | Required | Description | Type | Default |
| --- | --- | --- | --- | --- |
| `path` | Yes | Route path | `string` | - |
| `microApp` | Yes | Name of the associated micro application | `string` | - |
| `microAppProps` | No | Micro application configuration | [`MicroAppProps`](#microappprops) | `{}` |
### MicroAppProps
| Property | Required | Description | Type | Default |
| --- | --- | --- | --- | --- |
| `autoSetLoading` | No | Automatically manages the micro application's loading state | `boolean` | `false` |
| `loader` | No | Custom loading-state component for the micro application | `(loading) => React.ReactNode` | `undefined` |
| `autoCaptureError` | No | Automatically captures micro application errors | `boolean` | `false` |
| `errorBoundary` | No | Custom error boundary component for the micro application | `(error: any) => React.ReactNode` | `undefined` |
| `className` | No | CSS class for the micro application | `string` | `undefined` |
| `wrapperClassName` | No | CSS class for the wrapper around the loader, error boundary, and micro application; applies only when a loader or error boundary is enabled | `string` | `undefined` |
## FAQ
### Child Application Lifecycle Hooks Load, but the Page Does Not Render
If the page reports no errors and the child application's root DOM node exists but is empty, the current URL most likely does not match any route in the child application.
For example, suppose the parent application contains this configuration:
```js
{
path: '/app1',
microApp: 'app1',
}
```
And the child application contains this route:
```js
{
path: '/user',
component: './User',
}
```
You must visit `/app1/user` to access the child application's user page.
---
### Docs Docs Max Micro Frontend (`docs/docs/docs/max/micro-frontend.md`)
---
order: 9
toc: content
---
# 微前端
`@umi/max` 内置了 **Qiankun 微前端**[插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)，它可以一键启用 Qiankun 微前端开发模式，帮助您轻松地在 Umi 项目中集成 Qiankun 微应用，构建出一个生产可用的微前端架构系统。
关于 Qiankun 微前端的更多介绍请参阅[此页面](https://qiankun.umijs.org/zh/guide)。
## 微前端示例
如上图所示：在父应用里，我们通过导航栏切换路由后，下方显示的内容来自于不同的子应用。子应用支持单独打开；子应用之间也支持任意的嵌套。
换一种更直观的理解方式：父应用和子应用其实都是**独立的前端项目**，父应用可以在内部引入子应用，子应用也可以在自己内部继续引入孙子应用，以此类推。
当应用能够作为子应用被其它应用引入的时候，它就成为了我们所说的微应用。
## 开始使用
:::success{title=🏆︎}
本教程假设您对什么是微前端，什么是 Qiankun 微应用，以及如何使用 Qiankun 微应用已经有了基本的了解。
:::
### 配置父应用
首先需要配置父应用，注册子应用的相关信息，这样父应用才能识别子应用并在内部引入。
注册子应用的方式主要有两种：
- 插件注册子应用。
- 运行时注册子应用。
#### 插件注册子应用
修改父应用的 Umi 配置文件，添加如下内容：
```ts
// .umirc.ts
export default {
qiankun: {
master: {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
},
{
name: 'app2',
entry: '//localhost:7002',
},
],
},
},
};
```
其中，`name` 为子应用的名称，在引入子应用时需要使用到它；`entry` 为子应用运行的 HTTP 地址；`master` 对象的完整 API 可[见此](#masteroptions)。
#### 运行时注册子应用
修改父应用的 Umi 配置文件，添加如下内容：
```ts
// .umirc.ts
export default {
qiankun: {
master: {},
},
};
```
修改父应用的 `src/app.ts` 文件，导出 `qiankun` 对象：
```ts
// src/app.ts
export const qiankun = {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
},
{
name: 'app2',
entry: '//localhost:7002',
},
],
};
```
### 配置子应用
子应用需要导出必要的生命周期钩子，供父应用在适当的时机调用。
假设您的子应用项目**基于 Umi 开发**且**引入了 `qiankun` [插件](https://github.com/umijs/umi/blob/master/packages/plugins/src/qiankun.ts)**。如果没有，可以按照[此教程](https://qiankun.umijs.org/zh/guide/getting-started#%E5%BE%AE%E5%BA%94%E7%94%A8)进行配置。
:::warning{title="Utoopack 兼容性"}
如果子应用使用 utoopack 构建，且主应用使用 qiankun 2，请将主应用的 qiankun 升级至 `2.10.17-beta.0` 或更高版本。更早的版本无法在执行入口脚本时正确提供 `document.currentScript`，会导致子应用加载失败。更多适配原理请参阅 Utoo 官网博客[《当 Turbopack 遇上 qiankun：Utoopack 的微前端适配实践》](https://utoo.land/zh/docs/blog/utoopack-qiankun)。
:::
修改子应用的 Umi 配置文件，添加如下内容：
```ts
// .umirc.ts
export default {
qiankun: {
slave: {},
},
};
```
这样，微前端插件会自动在项目中创建好 Qiankun 子应用所需的生命周期钩子和方法，Easy as a cake！
### 引入子应用
在父应用中引入子应用，插件提供了三种不同实现的方式：
- 路由绑定引入子应用。
- `` 组件引入子应用。
- `` 组件引入子应用。
#### 路由绑定引入子应用
手动配置 `.umirc.ts` 文件中的 `routes` 项，通过路由的方式绑定子应用。何时使用：
- 子应用包含完整的路由切换逻辑时。
- 父子应用路由相互关联时。
现在，我们想要在 `/app1/project` 和 `/app2` 路由分别加载子应用 `app1` 和 `app2`，可以配置父应用的路由如下：
```ts
// .umirc.ts
export default {
routes: [
{
path: '/',
component: '@/layouts/index.tsx',
routes: [
{
path: '/app1',
component: '@/layouts/app-layout.tsx',
routes: [
// 配置微应用 app1 关联的路由
{
// 带上 * 通配符意味着将 /app1/project 下所有子路由都关联给微应用 app1
path: '/project/*',
microApp: 'app1',
},
],
},
// 配置 app2 关联的路由
{
path: '/app2/*',
microApp: 'app2',
},
],
},
],
};
```
配置好后，子应用的路由 base 会在运行时被设置为主应用中配置的 `path`。
例如，在上面的配置中，我们指定了 app1 关联的 path 为 `/app1/project`，假如 app1 里有一个路由配置为 `/user`，当我们想在父应用中访问 `/user` 对应的页面时，浏览器的 url 需要是 `base + /user`，即 `/app1/project/user` 路径，否则子应用会因为无法匹配到正确的路由而渲染空白或 404 页面。
`qiankun` 插件拓展了 Umi 原有的路由对象，新增了 `microApp` 字段，它的值为注册子应用的 `name`。切换到对应路由后，Umi 将会使用 `` 组件渲染此子应用，并替换原来路由的 `component`。
拓展后的 Umi 路由对象 API [可见此](#route)。
#### `` 组件引入子应用
通过 `` 组件加载（或卸载）子应用。何时使用：
- 子应用包含完整的路由切换逻辑时。
- 父子应用路由相互关联时。
现在，我们想在父应用的某个页面中引入子应用 `app1`，可以编写代码如下：
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return ;
}
```
使用该方式引入子应用时，父子应用的路由将一一对应。例如，当父应用路由为 `/some/page` 时，子应用路由同样为 `/some/page`。切换子应用路由时，父应用将同步切换。
如果父应用的路由包含前缀，可以通过配置 `base` 属性保证父子应用的路由正确对应。例如，父应用路由为 `/prefix/router-path/some/page` 时，我们希望子应用的路由为 `/some/page`，可以修改代码如下：
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return ;
}
```
#### `` 组件引入子应用
通过 `` 组件加载（或卸载）子应用。何时使用：
- 仅使用子应用的指定路由时。
- 父子应用路由相互独立时。
`` 组件是 `` 组件的变体，您需要显式提供 `url` 属性作为子应用的路由。当父应用的路由发生变化时，子应用的路由**不会改变**。
现在，我们想在父应用的某个组件内部引入 `app2` 子应用，子应用的路由为 `/some/page`，可以编写代码如下：
```tsx
import { MicroAppWithMemoHistory } from 'umi';
export default function Page() {
return ;
}
```
### 子应用之间跳转
如果子应用通过**路由绑定的方式**引入，在其它子应用的内部，可以使用 `` 跳转到对应的路由。以子应用 `app1` 和 `app2` 为例：
```tsx
// 在 app1 中
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
{/* 跳转链接为 /app2/home */}
);
}
```
在上面的例子中，点击按钮后，父应用的路由变为 `/app2/home`，渲染子应用 `app2` 内部路由为 `/home` 的页面。同理，如果想要从子应用 app2 回到子应用 app1，可以编写代码如下：
```tsx
// 在 app2 中
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
{/* 跳转链接为 /app1/project/home */}
);
}
```
您也可以从子应用跳转到父应用的指定路由：
```tsx
// 在子应用中
import { MicroAppLink } from 'umi';
export default function Page() {
return (
<>
{/* 跳转链接为 /table */}
);
}
```
## 子应用生命周期
Qiankun 在 single-spa 的基础上实现了一些额外的生命钩子。按照微应用的生命周期顺序，Qiankun 支持的完整的生命钩子列表如下：
- `beforeLoad`，微应用**开始获取前**调用。最初，微应用为 `NOT_LOADED` 状态。
- [`load`](https://single-spa.js.org/docs/building-applications/#load)，微应用**获取完成时**调用。开始获取微应用时，微应用变成 `LOADING_SOURCE_CODE` 状态。若获取成功，微应用变成 `NOT_BOOTSTRAPPED` 状态；若获取失败，微应用变成 `LOAD_ERROR` 状态。
- [`bootstrap`](https://single-spa.js.org/docs/building-applications/#bootstrap)，微应用**初始化完成时**调用。开始初始化微应用时，微应用变成 `BOOTSTRAPPING` 状态。初始化完成时，微应用变成 `NOT_MOUNTED` 状态。
- `beforeMount`，微应用每次**开始挂载前**调用。
- [`mount`](https://single-spa.js.org/docs/building-applications/#mount)，微应用每次**开始挂载时**调用。微应用变成 `MOUNTING` 状态。
- `afterMount`，微应用每次**挂载完成时**调用。微应用变成 `MOUNTED` 状态。
- `beforeUnmount`，微应用每次**开始卸载前**调用。
- [`unmount`](https://single-spa.js.org/docs/building-applications/#unmount)，微应用每次**开始卸载时**调用。微应用变成 `UNMOUNTING` 状态。
- `afterUnmount`，微应用每次**卸载完成时**调用。微应用变成 `NOT_MOUNTED` 状态。
- [`unload`](https://single-spa.js.org/docs/building-applications/#unload)，微应用**卸载完成时**调用。微应用变成 `NOT_LOADED` 状态。
此外，还存在一个特殊的生命钩子 `update`，仅在使用 `` 或 `` 组件引入微应用时生效：状态为 `MOUNTED` 的微应用**手动刷新时**调用。开始更新时，微应用变成 `UPDATING` 状态；更新完成时，微应用变成 `MOUNTED` 状态。
您可以像这样手动刷新子应用：
```tsx
import { useRef } from 'react';
import { MicroApp } from 'umi';
export default function Page() {
const microAppRef = useRef();
// 执行此方法时，更新子应用
const updateMicroApp = () => {
microAppRef.current?.update();
};
return ;
}
```
当您需要在子应用的生命周期里添加一些自定义的逻辑时，既可以在父应用中进行全局配置，也可以在子应用中进行单独配置。
### 父应用配置生命周期钩子
在父应用的 `src/app.ts` 中导出 `qiankun` 对象进行全局配置，所有的子应用都将实现这些生命周期钩子：
```ts
// src/app.ts
export const qiankun = {
lifeCycles: {
// 所有子应用在挂载完成时，打印 props 信息
async afterMount(props) {
console.log(props);
},
},
};
```
### 子应用配置生命周期钩子
在子应用的 `src/app.ts` 中导出 `qiankun` 对象，实现生命周期钩子。子应用运行时仅支持配置 `bootstrap`、`mount` 和 `unmount` 钩子：
```ts
// src/app.ts
export const qiankun = {
// 应用加载之前
async bootstrap(props) {
console.log('app1 bootstrap', props);
},
// 应用 render 之前触发
async mount(props) {
console.log('app1 mount', props);
},
// 应用卸载之后触发
async unmount(props) {
console.log('app1 unmount', props);
},
};
```
## 父子应用通信
父子应用间的通信有两种实现的方法：
- 基于 `useModel()` 的通信。这是 Umi **推荐**的解决方案。
- 基于配置的通信。
### 基于 `useModel()` 的通信
该通信方式基于 [数据流](https://github.com/umijs/umi/blob/master/packages/plugins/src/model.ts) 插件，此插件已经内置于 `@umi/max` 解决方案当中。
该通信方式需要子应用**基于 Umi 开发**且**引入了该数据流插件**。
关于此插件的详细介绍可见[数据流指南](./data-flow)。
#### 主应用透传数据
如果通过路由的模式引入子应用，则需要在父应用的 `src/app.ts` 里导出一个名为 `useQiankunStateForSlave()` 的函数，该函数的返回值将传递给子应用：
```ts
// src/app.ts
export function useQiankunStateForSlave() {
const [globalState, setGlobalState] = useState({
slogan: 'Hello MicroFrontend',
});
return {
globalState,
setGlobalState,
};
}
```
如果通过组件的模式引入子应用，直接将数据以组件参数的形式传递给子应用即可：
```tsx
import { useState } from 'react';
import { MicroApp } from 'umi';
export default function Page() {
const [globalState, setGlobalState] = useState({
slogan: 'Hello MicroFrontend',
});
return (
);
}
```
#### 子应用消费数据
子应用会自动生成一个全局的 Model，其命名空间为 `@@qiankunStateFromMaster`。通过 `useModel()` 方法，允许子应用在任意组件中获取并消费父应用透传的数据，如下所示：
```tsx
import { useModel } from 'umi';
export default function Page() {
const masterProps = useModel('@@qiankunStateFromMaster');
return
{JSON.stringify(masterProps)}
;
}
```
或者可以通过高阶方法 `connectMaster()` 来获取并消费父应用透传的数据，如下所示：
```tsx
import { connectMaster } from 'umi';
function MyPage(props) {
return
;
}
```
注意：`errorBoundary` 的优先级高于 `defaultErrorBoundary`。
## 子应用缓存 keepAlive
开启后，主应用通过路由绑定的微应用在切换离开时会保留缓存（基于 [`react-activation`](https://github.com/CJY0208/react-activation)），再次进入可恢复状态。
默认关闭。插件只负责在开启时用 `KeepAlive` 包装微应用路由；**`AliveScope` 需由业务在根节点自行挂载**，以便统一管理缓存生命周期。
完整示例：[`examples/qiankun-keepalive`](https://github.com/umijs/umi/tree/master/examples/qiankun-keepalive)（主应用 + `app1` / `app2` 子应用、页签栏、子应用路由 `wrappers`）。
### 配置
```ts
// 主应用 .umirc.ts
export default {
plugins: ['umi-plugin-keep-alive'],
qiankun: {
keepAlive: true,
master: {
apps: [
{
// 必须与子应用 package.json 的 name、路由 microApp 一致
name: 'app1',
entry: '//localhost:7001',
// 建议与路由 path 前缀一致，供运行时注入子应用 history.basename
base: '/app1',
},
],
},
},
routes: [
{ path: '/app1/*', microApp: 'app1' },
],
};
```
```ts
// 子应用 package.json
{ "name": "app1" }
// 子应用 .umirc.ts
const { name } = require('./package.json');
const isProd = process.env.NODE_ENV === 'production';
export default {
plugins: ['umi-plugin-keep-alive'],
qiankun: { slave: {} },
// 生产环境资源/路由挂在 /${name}/；开发环境由主应用注入 base
base: isProd ? `/${name}/` : '/',
publicPath: isProd ? `/${name}/` : '/',
routes: [
// 每个页面路由单独包 KeepAlive（umi wrappers 会变成父路由，内部用 Outlet 渲染页面）
{ path: '/', component: 'index', wrappers: ['@/keepAlive/index'] },
{ path: '/about', component: 'about', wrappers: ['@/keepAlive/index'] },
],
};
```
### 挂载 AliveScope
推荐使用 [`umi-plugin-keep-alive`](https://github.com/alitajs/umi-plugin-keep-alive)（公开版可用 `0.0.1-beta.34`，依赖 `react-activation@^0.13.4`）：插件会挂载 `AliveScope`，并从 `umi` / `@umijs/max` 导出 `KeepAlive`、`useAliveController`。
也可在 `app.tsx` 用 `rootContainer` 自行包裹 `AliveScope`。**主应用与子应用都需要 AliveScope**（各自安装插件或自行挂载）。
### 两层缓存
| 层级 | 缓存名 | 作用 |
| --- | --- | --- |
| 主应用插件 | `` `qiankun_/${appName}/` `` | 缓存整个微应用树（切换子应用时保留状态） |
| 主应用页签 | `location.pathname`（如 `/app1/about`） | 空 `KeepAlive` 仅占页签；真实微应用内容渲染在外侧 |
| 子应用 wrappers | 子应用内的 `location.pathname` | 缓存子应用各个页面 |
页签栏应展示**非** `qiankun_` 前缀的缓存；`qiankun_*` 只负责挂住微应用实例。子应用清空自身页面缓存后，可调用 `window.closeKeepAliveTab?.('qiankun_/app1/')` 通知主应用卸载对应微应用树。
### 缓存清理
```ts
import { useAliveController } from '@umijs/max';
const { dropScope } = useAliveController();
dropScope('qiankun_/app1/');
// 或：window.closeKeepAliveTab?.('qiankun_/app1/');
```
### 注意事项（常见坑）
:::warning{title=务必注意}
1. **`package.json` 的 `name` 必须与 `qiankun.master.apps[].name`、路由 `microApp` 一致**（示例为 `app1` / `app2`）。缓存键为 `` `qiankun_/${name}/` ``，不一致会导致关页签、清理缓存对不上。
2. **主应用 `apps[].base` 与路由前缀对齐**（如 `base: '/app1'` 对应 `path: '/app1/*'`），运行时会注入子应用 `history.basename`。
3. **子应用 `base` / `publicPath` 区分环境**：生产用 `` `/${name}/` ``；开发一般用 `'/'`，由主应用注入 basename。
4. **React 18 必须关闭 `autoFreeze`**。开启 freeze 后，缓存回来的微应用里输入框/下拉等往往无法恢复或不可交互。插件生成的微应用 `KeepAlive` 已设 `autoFreeze={false}`；业务侧其它 `KeepAlive` 也要关闭，例如：
```ts
// 主/子应用 app.tsx
import { KeepAlive } from 'react-activation';
KeepAlive.defaultProps = {
...(KeepAlive.defaultProps || {}),
autoFreeze: false,
};
```
5. **`KeepAlive` 与 `AliveScope` 必须是同一份 `react-activation` 实例**。主应用需安装 `react-activation`（或通过 `umi-plugin-keep-alive` 引入）；若 KeepAlive 从插件绝对路径导入、AliveScope 从另一份包导入，缓存不会生效，切换后状态会丢。
6. **子应用路由用 `wrappers` 包每一页**，wrapper 内用 `` 渲染页面（不要只用 `props.children`，umi 的 wrapper 会变成 `isWrapper` 父路由，否则页面空白）。
7. **主应用页签**：在微应用路由上用「空 `KeepAlive` + `name={location.pathname}`」占位出 Tab，真实 ``（微应用）放在 KeepAlive 外面，才能既出 `/app1/about` 这类页签，又不挡主应用 Provider。
8. **`keepAlive` 仅作用于路由绑定的 `microApp`**。`` / `` 需自行包 `KeepAlive`。
:::
## 环境变量
如果您有一些不能显式编写在 `.umirc.ts` 或 `src/app.ts` 中的配置信息，可以将它们存放在环境变量文件中。例如编写父应用的环境变量文件 `.env` 如下：
```plaintext
INITIAL_QIANKUN_MASTER_OPTIONS="{\"apps\":[{\"name\":\"app1\",\"entry\":\"//localhost:7001\"},{\"name\":\"app2\",\"entry\":\"//localhost:7002\"}]}"
```
在内部，微前端插件会执行 `JSON.parse(process.env.INITIAL_QIANKUN_MASTER_OPTIONS)` 方法，然后将得到的结果与已有的配置信息合并。上面编写的环境变量，合并后相当于编写了如下配置信息：
```ts
export default {
qiankun: {
master: {
apps: [
{
name: 'app1',
entry: '//localhost:7001',
},
{
name: 'app2',
entry: '//localhost:7002',
},
],
// ... .umirc.ts 中其它的配置信息
},
},
};
```
需注意的是，当存在相同的配置项时，例如 `apps` 项，写在 `.umirc.ts` 中的配置项将**覆盖**环境变量中的配置项。
同理，对于子应用，可以编写环境变量 `.env` 文件如下：
```plaintext
INITIAL_QIANKUN_SLAVE_OPTIONS="{\"enable\":false}"
```
相当于编写了如下配置信息：
```ts
export default {
qiankun: {
slave: {
enable: false,
// ... .umirc.ts 中其它的配置信息
},
},
};
```
## API
### QiankunOptions
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `master` | 否 | 父应用配置 | [`MasterOptions`](#masteroptions) | `undefined` |
| `slave` | 否 | 子应用配置 | [`SlaveOptions`](#slaveoptions) | `undefined` |
| `keepAlive` | 否 | 是否缓存路由绑定的微应用，详见 [子应用缓存 keepAlive](#子应用缓存-keepalive) | `boolean` | `false` |
| `externalQiankun` | 否 | 是否使用外部 qiankun 依赖 | `boolean` | `false` |
### MasterOptions
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `enable` | 否 | 启用 Qiankun 微应用插件，设置为 `false` 时为不启用 | `boolean` | `undefined` |
| `apps` | 是 | 微应用配置 | [`App[]`](#app) | `undefined` |
| `routes` | 否 | 微应用运行时的路由 | [`Route[]`](#route) | `undefined` |
| `defaultErrorBoundary` | 否 | 子应用默认的错误捕获组件，值为文件路径 | `string` | - |
| `defaultLoader` | 否 | 子应用默认的加载动画，值为文件路径 | `string` | - |
| `sandbox` | 否 | 是否开启沙箱模式 | `boolean \| { strictStyleIsolation: boolean, experimentalStyleIsolation: boolean }` | `true` |
| `prefetch` | 否 | 是否启用微应用预加载 | `boolean \| 'all' \| string[] \| (( apps: RegistrableApp[] ) => { criticalAppNames: string[]; minorAppsName: string[] })` | `true` |
关于沙箱和预加载的介绍可见[此页面](https://qiankun.umijs.org/zh/api/#startopts)。
### SlaveOptions
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `enable` | 否 | 启用 Qiankun 微应用插件，设置为 `false` 时为不启用 | `boolean` | `undefined` |
### App
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `name` | 是 | 微应用的名称 | `string` |
| `entry` | 是 | 微应用的 HTML 地址 | `string` | `{ script: string[], styles: [] }` |
| `credentials` | 否 | 拉取微应用时同时拉取 Cookies，详见[此介绍](https://qiankun.umijs.org/zh/faq#%E5%A6%82%E4%BD%95%E8%A7%A3%E5%86%B3%E6%8B%89%E5%8F%96%E5%BE%AE%E5%BA%94%E7%94%A8-entry-%E6%97%B6-cookie-%E6%9C%AA%E6%90%BA%E5%B8%A6%E7%9A%84%E9%97%AE%E9%A2%98) | `boolean` | `false` |
| `props` | 否 | 父应用传递给微应用的数据，详见[父子应用通信章节](#父子应用通信) | `object` | `{}` |
### Route
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `path` | 是 | 路由 PATH | `string` |
| `microApp` | 是 | 关联的微应用名称 | `string` |
| `microAppProps` | 否 | 微应用的配置 | [`MicroAppProps`](#microappprops) | `{}` |
### MicroAppProps
| 属性 | 必填 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- | --- |
| `autoSetLoading` | 否 | 自动设置微应用的加载状态 | `boolean` | `false` |
| `loader` | 否 | 自定义的微应用加载状态组件 | `(loading) => React.ReactNode` | `undefined` |
| `autoCaptureError` | 否 | 自动设置微应用的错误捕获 | `boolean` | `false` |
| `errorBoundary` | 否 | 自定义的微应用错误捕获组件 | `(error: any) => React.ReactNode` | `undefined` |
| `className` | 否 | 微应用的样式类 | `string` | `undefined` |
| `wrapperClassName` | 否 | 包裹微应用加载组件、错误捕获组件和微应用的样式类，仅在启用加载组件或错误捕获组件时有效 | `string` | `undefined` |
## FAQ
### 子应用的生命周期钩子加载了，但是页面没有渲染
如果页面没有报错，且通过查看 DOM 发现子应用的根节点已经有了，只是内容是空，这种基本可以确定是因为当前 url 没有匹配到子应用的任何路由导致的。
比如我们在主应用中配置了：
```js
{
path: '/app1',
microApp: 'app1',
}
```
子应用的路由配置是：
```js
{
path: '/user',
component: './User',
}
```
那么我们必须通过 `/app1/user` 路径才能正常的访问到子应用的 user 页面。
---
### Docs Docs Max React Query.En US (`docs/docs/docs/max/react-query.en-US.md`)
---
order: 11
toc: content
translated_at: '2024-03-17T08:46:49.932Z'
---
# react-query
@umijs/max comes with the [react-query](https://tanstack.com/query/) request strategy (which is the same as @tanstack/react-query).
## How to enable
If using @umijs/max, enable by configuring.
```ts
export default {
reactQuery: {},
}
```
If using umi, first install the `@umijs/plugins` dependency, then enable through configuration.
```bash
$ pnpm i @umijs/plugins -D
```
```ts
export default {
plugins: ['@umijs/plugins/dist/react-query'],
reactQuery: {},
}
```
## Features
The plugin does a few things for you,
1. Enable react query's devtool in dev mode, which can be disabled with `reactQuery: { devtool: false }`, and the option is configured in app.ts through `export const reactQuery = { devtool }`.
2. Register a global QueryClient, which can be disabled with `reactQuery: { queryClient: false }`, and the option is configured in app.ts through `export const reactQuery = { queryClient }`.
3. Most of react-query's exports can be imported and used from `umi` or `@umijs/max`.
## Configuration
The following configurations can be done in `reactQuery`.
- `devtool`: boolean, whether to enable the official react query devtool, default `true`
- `queryClient`: boolean, whether to register a global QueryClient and QueryClientProvider, default `true`
For example:
```ts
export default {
reactQuery: {
devtool: false,
queryClient: false,
},
}
```
Note: The above two configurations need to be configured in `app.ts` at runtime.
## Runtime Configuration
Includes the following configurations.
- `devtool`: object
- `queryClient`: object
For example:
```ts
const API_SERVER = '/path/to/api/server';
export const reactQuery = {
devtool: {
initialIsOpen: true,
},
queryClient: {
defaultOptions: {
queries: {
queryFn: async ({ queryKey }) => {
const res = await fetch(`${API_SERVER}/${queryKey.join('/')}`);
if (res.status !== 200) {
throw new Error(res.statusText);
}
return res.json();
}
}
}
},
};
```
---
### Docs Docs Max React Query (`docs/docs/docs/max/react-query.md`)
---
order: 11
toc: content
---
# react-query
@umijs/max 内置了 [react-query](https://tanstack.com/query/)（和 @tanstack/react-query 是同一个）请求方案。
## 启用方式
如果是 @umijs/max，配置开启。
```ts
export default {
reactQuery: {},
}
```
如果是 umi，先安装 `@umijs/plugins` 依赖，再通过配置开启。
```bash
$ pnpm i @umijs/plugins -D
```
```ts
export default {
plugins: ['@umijs/plugins/dist/react-query'],
reactQuery: {},
}
```
:::info
注：在使用时，请务必检查关于 `refetchOnWindowFocus` 的配置项，详见 [运行时配置项](#运行时配置项) 。
:::
## 版本
默认使用的是 [TanStack Query](https://tanstack.com/query/latest) v4 版本，若需使用最新 v5 版本，手动安装 v5 版本的 `@tanstack/react-query` 与 `@tanstack/react-query-devtools` 依赖即可。
## 特性
插件帮你做了几件事，
1、dev 模式下开启 react query 的 devtool，可通过 `reactQuery: { devtool: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { devtool }` 配置。
2、注册全局的 QueryClient，可通过 `reactQuery: { queryClient: false }` 关闭，选项在 app.ts 里通过 `export const reactQuery = { queryClient }` 配置。
3、大部分 react-query 的导出可以从 `umi` 或 `@umijs/max` 里 import 使用。
## 配置项
可以在 `reactQuery` 中做以下配置。
- `devtool`: boolean，是否开启 react query 官方 devtool 工具，默认 `true`
- `queryClient`: boolean, 是否注册全局的 QueryClient 和 QueryClientProvider，默认 `true`
比如：
```ts
export default {
reactQuery: {
devtool: false,
queryClient: false,
},
}
```
注：以上两个配置的运行时配置需在 `app.ts` 里进行配置。
## 运行时配置项
包含以下配置。
- `devtool`：object
- `queryClient`: object
例子：
```ts
// src/app.ts
import { RuntimeReactQueryType } from 'umi';
export const reactQuery: RuntimeReactQueryType = {
devtool: {
initialIsOpen: true,
},
queryClient: {
defaultOptions: {
queries: {
// 🟡 此配置具有的表现往往令人出乎意料，若无特殊需求，请默认关闭
refetchOnWindowFocus: false,
},
},
},
};
```
注：绝大多数项目中，**你都应该默认设定 `refetchOnWindowFocus: false`** ，否则将引发出人意料的反复获取数据效果（这在 SWR 中被称为 [`revalidateOnFocus`](https://swr.vercel.app/zh-CN/docs/api#options) ）。
---
### Docs Docs Max Request.En US (`docs/docs/docs/max/request.en-US.md`)
---
order: 6
toc: content
translated_at: '2024-03-17T08:46:03.932Z'
---
# Request
`@umijs/max` has built-in plugin solution. It offers a unified network request and error handling solution based on [axios](https://axios-http.com/) and ahooks' `useRequest` from [ahooks](https://ahooks-v2.surge.sh).
```js
import { request, useRequest } from 'umi';
request;
useRequest;
```
## Configuration
### Build-time configuration
```js
export default {
request: {
dataField: 'data'
},
};
```
Build-time configuration allows configuring `dataField` for useRequest, with its default being `data`. This setting primarily facilitates direct data consumption by useRequest. If you wish to access the raw data returned by the backend when consuming data, configure `dataField` to `''` here.
For example, if your backend returns data in the following format.
```js
{
success: true,
data: 123,
code: 1,
}
```
Then useRequest can directly consume the `data`, which would be 123, instead of `{ success, data, code }`.
### Runtime configuration
In `src/app.ts`, you can customize the request settings for your project by configuring the request item.
```ts
import type { RequestConfig } from 'umi';
export const request: RequestConfig = {
timeout: 1000,
// other axios options you want
errorConfig: {
errorHandler(){
},
errorThrower(){
}
},
requestInterceptors: [],
responseInterceptors: []
};
```
Besides `errorConfig`, `requestInterceptors`, and `responseInterceptors`, other configurations are directly passed through to [axios](https://axios-http.com/docs/req_config)'s request configuration. **The rules configured here apply to all** `request` and `useRequest` **methods**.
The runtime configuration options of `plugin-request` are introduced below. At the end of this section, we will provide a complete runtime configuration example, describing its functionality in detail.
#### errorConfig
If you want to set a unified error handling scheme for your requests, you can configure it here.
`errorThrower` takes the data returned by your backend and needs to throw an error you define. You can process the backend data here as needed.
Our `request` will catch the error thrown by `errorThrower` and execute your `errorHandler` method, which accepts two arguments. The first argument is the caught error, and the second argument is the request's opts.
`errorHandler` and `errorThrower` need to be used together. A complete example is provided at the end of the document.
If you find this way of error handling too complicated, you can directly implement your error handling in the interceptors.
:::info{title=🚨}
`errorThrower` is implemented using `responseInterceptors`, triggered when `data.success` is `false`.
:::
#### requestInterceptors
Add request phase interceptors to the request method.
Pass in an array where each element is an interceptor. They will be registered on the axios instance in order. The syntax for writing interceptors is consistent with axios request interceptor. It needs to take the request config as an argument and return it.
We recommend using `RequestConfig`, which helps you write your interceptors in a standardized manner.
e.g.
```ts
const request: RequestConfig = {
requestInterceptors: [
// directly write a function as an interceptor
(url, options) =>
{
// do something
return { url, options }
},
// a tuple, the first element is the request interceptor, the second is the error handler
[(url, options) => {return { url, options }}, (error) => {return Promise.reject(error)}],
// array, omitting error handler
[(url, options) => {return { url, options }}]
]
}
```
Furthermore, to better accommodate umi-request, we allow umi-request interceptor syntax, even though it might not pass TypeScript's syntax check.
#### responseInterceptors
Add response phase interceptors to the request method.
Pass in an array where each element is an interceptor. They will be registered on the axios instance in order. The syntax for writing interceptors is consistent with axios response interceptor. It takes the axios response as an argument and returns it.
We recommend using `RequestConfig`, which helps you write your interceptors in a standardized manner.
e.g.
```ts
const request: RequestConfig = {
responseInterceptors: [
// directly write a function as an interceptor
(response) =>
{
// No need for asynchronous processing to read response body content, can directly read from data, some fields can be found in the config
const { data = {} as any, config } = response;
// do something
return response
},
// a tuple, the first element is the request interceptor, the second is the error handler
[(response) => {return response}, (error) => {return Promise.reject(error)}],
// array, omitting error handler
[(response) => {return response}]
]
}
```
**Note: We will register interceptors according to your array sequence, but their execution order follows axios's convention, with request interceptors added later executing first, and response interceptors added later executing last**
## API
### useRequest
The plugin has built-in [@ahooksjs/useRequest](https://ahooks-v2.js.org/hooks/async), allowing you to consume data simply and conveniently within components. The example is as follows:
```typescript
import { useRequest } from 'umi';
export default function Page() {
const { data, error, loading } = useRequest(() => {
return services.getUserList('/api/test');
});
if (loading) {
return
loading...
;
}
if (error) {
return
{error.message}
;
}
return
{data.name}
;
};
```
In the above code, `data` is not the data returned by your backend, but its internal `data`, (because the default build-time configuration is 'data')
It should be noted that ahooks has been updated to 3.0, but for making it less difficult for `umi@3` projects to upgrade, we continued to use ahooks 2.0
### request
By `import { request } from '@@/plugin-request'`, you can use the built-in request method.
`request` accepts `options` in addition to passing through all of [axios](https://axios-http.com/docs/req_config)'s config, we also added a few extra attributes `skipErrorHandler`, `getResponse`, `requestInterceptors` and `responseInterceptors`.
The example is as follows:
```typescript
request('/api/user', {
params: { name : 1 },
timeout: 2000,
// other axios options
skipErrorHandler: true,
getResponse: false,
requestInterceptors: [],
responseInterceptors: [],
}
```
When you want a particular request to skip error handling, you can achieve this by setting `skipErrorHandler` to `true`.
request returns the data from your backend by default, if you wish to receive the complete response structure from axios, it can be achieved by passing `{ getResponse: true }`.
`requestInterceptors` and `responseInterceptors` are written in the same way as the interceptors in runtime configuration, but the difference is that the interceptors registered here are "one-off". Furthermore, the interceptors written here will be registered after those in the runtime configuration.
**Note: When you have used errorHandler, the response interceptors registered here will be ineffective, because errorHandler will throw error**
### RequestConfig
This is an interface definition that can help you better configure runtime settings.
```typescript
import type { RequestConfig } from 'umi';
export const request:RequestConfig = {};
```
Note that you should add type when importing
## Cancel request
Cancel the request using the fetch API method -- `AbortController`.
```tsx
import { request } from '@umijs/max';
import { Button } from 'antd';
const controller = new AbortController();
const HomePage: React.FC = () => {
const fetchData = async () => {
const res = await request('/api/getData', {
method: 'GET',
signal: controller.signal
})
}
const cancelData = () => {
controller.abort();
}
return (
<>
);
};
export default HomePage;
```
## umi@3 to umi@4
In the upgrade from `umi@3` to `umi@4`, we discontinued umi-request and chose axios as the default request solution. Some functionality changes occurred in this switch.
### Changes in runtime configuration
Compared to `umi@3`, `umi@4`'s runtime configuration has undergone significant changes.
```diff
export const request: RequestConfig = {
errorConfig: {
++ errorHandler: () => {},
++ errorThrower: () => {}
-- errorPage: '',
-- adaptor: ()=>{},
};
-- middlewares: [],
++ requestInterceptors: [],
++ responseInterceptors: [],
... // Differences between umi-request and axios.
};
```
- umi-request's configuration items have become axios's configuration items.
- Removed the middlewares middleware. You can use axios's [interceptors](https://axios-http.com/docs/interceptors) to achieve the same functionality.
- errorConfig removed all original settings, adding errorHandler and errorThrower for unified error handling settings.
Replacing middleware. For a `umi@3` middleware, content before the `next()` method should be placed in `requestInterceptors`, while content after the `next()` method should be placed in `responseInterceptors`.
```ts
// Middleware
async function middleware(ctx, next) {
const { url, options } = req;
if (url.indexOf('/api') !== 0) {
ctx.req.url = `/api/v1/${url}`;
}
await next();
if (!ctx.res.success) {
// do something
}
}
// Interceptor
{
requestInterceptors:[
(config) => {
if (config.url.indexOf('/api') !== 0) {
config.url = `/api/v1/${url}`;
}
return config;
}
],
responseInterceptors: [
(response) => {
if(!response.data.success){
// do something
}
}
]
}
```
### Changes in request method parameters
[umi-request](https://github.com/umijs/umi-request#request-options) and [axios](https://axios-http.com/docs/req_config) have some differences in configuration items. You can compare them by referring to their respective documentation.
### GET request parameter serialization
[Umi@3](https://github.com/umijs/umi-request/blob/master/src/middleware/simpleGet.js) uses the same Key to serialize arrays by default. Umi@4 requests based on axios, by default, serialize in the form with brackets `[]`.
```tsx
// Umi@3
import { useRequest } from 'umi';
// a: [1,2,3] => a=1&a=2&a=3
// Umi@4
import { useRequest } from '@umijs/max';
// a: [1,2,3] => a[]=1&a[]=2&a[]=3
```
If you wish to maintain the Umi@3 form, you can do so:
```ts
// src/app.[ts|tsx]
/** @doc https://github.com/sindresorhus/query-string#arrayformat-1 */
+ import queryString from 'query-string';
export const request: RequestConfig = {
+ paramsSerializer(params) {
+ return queryString.stringify(params);
+ },
...
}
```
## Runtime configuration example
Here's a complete example of runtime configuration, to help you better customize the request scheme for your project.
```
/* Detailed source-code truncated for AI context efficiency. */
```
The above example's error handling scheme is derived from `umi@3`'s built-in error handling. In this version, we removed it to allow users greater freedom in customizing their error handling schemes. If you still want to use it, you can paste this runtime configuration into your project.
You can also write your own error handling through response interceptors, **not limited to errorConfig**.
---
--- METRICS ---
- Files Extracted: 99
- Estimated Token Budget: ~166999 tokens
- Canonical Reference: https://codewiki.google/github.com/umijs/umi
>
```
### `src` Directory
#### .umi Directory
:::warning{title=🛎️}
**Do not commit `.umi` temporary files to the git repository, already ignored by default in `.gitignore`.**
:::
Temporary file directory during development, such as entry files, routes, etc., will be temporarily generated here.
#### .umi-production Directory
:::warning{title=🛎️}
**Do not commit `.umi-production` temporary files to the git repository, already ignored by default in `.gitignore`.**
:::
Temporary file directory during build, such as entry files, routes, etc., will be temporarily generated here.
#### app.[ts|tsx]
[Runtime configuration](../api/runtime-config) file, where you can extend runtime capabilities, such as modifying routes, modifying the render method, etc.
The logic brought by runtime configuration runs in the browser. Therefore, when there are remote configurations, dynamic content, etc., which are not certain during local development and cannot be hardcoded, it is necessary to dynamically obtain them when the project is actually run in the browser.
#### layouts/index.tsx
Global layout, will be effective under all routes by default. For example, with the following route relationship:
```
[
{ path: '/', component: '@/pages/index' },
{ path: '/users', component: '@/pages/users' },
]
```
The output will be:
```jsx
If you don't know what you can contribute, you can search TODO or FIXME in the source code.
---
### Docs Docs Introduce Contributing (`docs/docs/docs/introduce/contributing.md`)
---
order: 3
toc: content
---
# 参与贡献
❤️ Loving Umi and want to get involved? Thanks!
## 环境准备
### Node.js 和 pnpm
开发 Umi 需要 Node.js 18+ 和 `pnpm` v8。
推荐使用 [Volta](https://volta.sh/) 来管理 Node.js 和 pnpm 版本。并且需要设置 `VOLTA_FEATURE_PNPM` 环境变量来启用 pnpm 支持。
```bash
export VOLTA_FEATURE_PNPM=1
```
### Clone 项目
```bash
$ git clone git@github.com:umijs/umi.git
$ cd umi
```
### 安装依赖并构建
```bash
$ pnpm i && pnpm build
```
## 开发 Umi
### 启动 dev 命令
本地开发 Umi 必开命令，用于编译 `src` 下的 TypeScript 文件到 `dist` 目录，同时监听文件变更，有变更时增量编译。
```bash
$ pnpm dev
```
如果觉得比较慢，也可以只跑特定 package 的 `pnpm dev` 命令，比如。
```bash
$ cd packages/umi
$ pnpm dev
```
### 跑 Example
`examples` 目录下保存了各种用于测试的例子，跑 example 是开发 Umi 时确认功能正常的常用方式。每个 example 都配了 dev 脚本，所以进入 example 然后执行 `pnpm dev` 即可。
```bash
$ cd examples/boilerplate
$ pnpm dev
```
如果要用 vite 模式跑，加 `--vite` 参数，
```bash
$ pnpm dev --vite
```
### 测试
目前跑测试很快，10s+ 就完成了。推荐本地跑一遍再提 PR，减少 Round Trip。
```bash
$ pnpm test
...
Test Suites: 1 skipped, 43 passed, 43 of 44 total
Tests: 6 skipped, 167 passed, 173 total
Snapshots: 0 total
Time: 13.658 s
Ran all test suites.
```
如果需要只跑部分文件的用例，用 `pnpm jest`，因为 `pnpm test` 是开了 turborepo 功能的。
比如，
```bash
$ pnpm jest packages/plugin-docs/src/compiler.test.ts
```
## 贡献 Umi 文档
Umi 的文档由 Umi@4 和 `@umijs/plugin-docs` 插件实现，本质上就是一个 Umi 项目。在根目录执行如下命令即可开始 Umi 文档的开发：
```bash
# 启用 Umi 文档开发
# 首次启动时编译耗时较长，请耐心等待
$ pnpm docs:dev
```
打开指定的端口号，即可实时查看文档更新的内容，以及 `@umijs/plugin-docs` 插件开发的成果。
### 撰写 Umi 文档
Umi 文档的编写基于 MDX 格式。MDX 是 Markdown 格式的拓展，允许您在撰写 Umi 文档时插入 JSX 组件。
:::success{title=🏆︎}
撰写 **文档（Document）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-doc/components` 目录下找到。撰写 **博客（Blog）** 时，可用的组件可以在 `packages/plugin-docs/client/theme-blog/components` 目录下找到。
:::
Umi 文档的代码高亮基于 [`Rehype Pretty Code`](https://github.com/atomiks/rehype-pretty-code)，完整的能力和使用说明请移步它的[官方文档](https://rehype-pretty-code.netlify.app)。
在根目录执行如下命令可以格式化仓库中已有的 Umi 文档：
```bash
$ pnpm format:docs
```
格式化文档后，建议**仅提交您撰写或修改的 Umi 文档**。不同文档贡献者的写作风格有一定的差异，格式化以后不一定能保留原来期望的样式。
### 参与 Umi 文档插件开发
新建一个终端，执行如下命令：
```bash
$ cd packages/plugin-docs
$ pnpm dev:css
```
现在，当您修改了 `tailwind.css` 文件或在开发时修改了 TailwindCSS 样式类时，会自动编译并生成 `tailwind.out.css` 样式表文件。
Umi 会监听 `docs` 和 `packages/plugin-docs/client` 目录下文件的变化，而不会监听 `packages/plugin-docs/src` 目录。
:::info{title=💡}
如果您需要编译 `packages/plugin-docs/src` 中的文件，请移动到 `packages/plugin-docs` 目录下执行 `pnpm build` 命令，然后重启开发。
:::
在根目录执行如下命令可以格式化 Umi 文档插件的代码：
```bash
$ pnpm format:plugin-docs
```
在根目录执行如下命令可以构建 Umi 文档：
```bash
$ pnpm s
```
## 新增 package
新增 package 有封装脚本，无需手动复制 `package.json` 等文件：
```bash
# 创建 package 目录
$ mkdir packages/foo
# 初始化 package 开发
$ pnpm bootstrap
```
## 更新依赖
> 不推荐非 Core Maintainer 做大量依赖更新。因为涉及依赖预打包，有较多需注意的点。
执行 `pnpm dep:update` 可更新依赖。
```bash
$ pnpm dep:update
```
由于 Umi 有针对依赖做预打包处理，更新依赖后还需检查更新的依赖是否为 devDependencies 并且有对此做依赖预打包。如果有，需要在对应 package 下执行 `pnpm build:deps` 并指定依赖，用于更新预打包的依赖文件。
```bash
$ pnpm build:deps --dep webpack-manifest-plugin
```
## 发布
只有 Core Maintainer 才能执行发布。Umi 已切换到 npm Trusted Publishing/OIDC，本地发布命令只负责 bump version、生成 release commit/tag 并推送，不再直接执行 `npm publish`。
```bash
$ pnpm release
```
推送后，GitHub Actions 的 Release workflow 会通过 OIDC 获取 npm 发布权限，执行 `pnpm release:publish`，并带上 `--provenance` 将 package 发布到 npm。
## 通过 dist-tag 回滚
比如要回滚到 4.0.81 。
```bash
$ pnpm -rc --filter "./packages/**" exec pnpm dist-tag add \$PNPM_PACKAGE_NAME@4.0.81 latest
```
## 加入 Contributor 群
提交过 Bugfix 或 Feature 类 PR 的同学，如果有兴趣一起参与维护 Umi，可先用钉钉扫下方二维码（注明 github id）加我钉钉，然后我会拉到群里。
Solution: Configure `SOCKET_SERVER=127.0.0.1:${port}` to start the project
```bash
SOCKET_SERVER=http://127.0.0.1:8000 pnpm dev
```
## Error evaluating function `round`: argument must be a number
Solution: In the new version of less, `/` is recognized as property shorthand by default. To restore the old behavior (where `/` was used as a calculation symbol by default), configure `lessLoader: { math: 'always' }`.
## The layout configuration option in routes does not take effect
The layout configuration has been moved to `app.ts`, see [Runtime Config > layout](https://umijs.org/docs/api/runtime-config#layout)
## Where did document.ejs go and how do I customize the HTML template
In addition to the injection through the configuration of external [script](https://umijs.org/docs/api/config#scripts), [css](https://umijs.org/docs/api/config#styles), you can also use the project-level plugin to more flexibly modify HTML products, see: [issuecomment-1151088426](https://github.com/umijs/umi-next/issues/868#issuecomment-1151088426)
## Why are external js files configured in scripts by default inserted after umi.js
React only starts running after the page has fully loaded, so inserting after `umi.js` will not affect the project.
If you need to insert it before `umi.js`, see [issuecomment-1176960539](https://github.com/umijs/umi/issues/8442#issuecomment-1176960539)
## How do I code split with Umi4?
Umi 4 splits code by page by default. If you feel the need for further optimization, you can use sub-package strategies or manual splitting, see: [Code Splitting Guide](../../blog/code-splitting)
If you have the requirement to pack all js products into a single `umi.js` file, please disable [dynamicImport](#can-i-disable-dynamicimport).
## Where did _layout.tsx go and how do I nest routes?
Umi 4 uses react-router v6, and nested route content is displayed through `
## What is Umi?
Umi, pronounced as "Wu Mi" in Chinese, is an extensible enterprise-level front-end application framework. Umi is based on routing, supporting both configuration-based routing and convention-based routing, ensuring the completeness of routing features and further extending functionalities based on this. Accompanied by a plugin system with a complete lifecycle, it covers every lifecycle from the source code to the build product, supporting various functional extensions and business needs.
Umi is the underlying front-end framework of Ant Group, serving directly or indirectly over 10,000 applications, including Java, Node, H5 Wireless, Hybrid applications, pure front-end assets applications, CMS applications, Electron applications, Serverless applications, and more. It has served our internal users well and many external users, including Taobao system, Feizhu, Alibaba Cloud, ByteDance, Tencent, Koubei, Meituan, etc. In ByteDance's [research report](https://zhuanlan.zhihu.com/p/403206195) in 2021, Umi was the choice of 25.33% of developers.
Umi has many interesting features, such as:
1. **Enterprise-level**, considering more in terms of security, stability, best practices, and constraint ability
When introducing a child application through routing, configure it as follows:
```ts
// .umirc.ts
export default {
routes: [
{
path: '/app1',
microApp: 'app1',
microAppProps: {
autoCaptureError: true,
},
},
],
};
```
When introducing a child application through a component, pass `autoCaptureError` directly:
```tsx
import { MicroApp } from 'umi';
export default function Page() {
return