This article has not been translated yet. Want to help us out? Click the Edit this doc on GitHub at the end of the page.

插件开发

在 Umi 中，插件实际上就是一个 JS 模块，你需要定义一个插件的初始化方法并默认导出。如下示例：

export default (api) => {
  // your plugin code here
};

需要注意的是，如果你的插件需要发布为 npm 包，那么你需要发布之前做编译，确保发布的代码里面是 ES5 的代码。

该初始化方法会收到 api 参数，Umi 提供给插件的接口都是通过它暴露出来的。

插件示例

以下我们通过完成一个简单的需求，来进一步了解 Umi 的插件开发

需求

Umi 约定式路由中的表现是主路由，对应到 index 路由，即访问 http://localhost:8000 实际上访问到的页面是 src/pages/index，有时候我们在开发过程中会遇到，希望修改主路由的情况，比如希望路由 / 访问的是 src/pages/home。

初始化插件

你可以通过 create-umi 直接创建一个 Umi 插件的脚手架：

yarn create umi --plugin
? Select the boilerplate type plugin
? What's the plugin name? umi-plugin-main-path
? What's your plugin used for? config umi main path
? What's your email? 448627663@qq.com
? What's your name? xiaohuoni
? Which organization is your plugin stored under github? alitajs
? Select the development language TypeScript
? Does your plugin have ui interaction(umi ui)? No
   create package.json
   create .editorconfig
   create .fatherrc.ts
   create .gitignore
   create .prettierignore
   create .prettierrc
   create CONTRIBUTING.md
   create example/.gitignore
   create example/.umirc.ts
   create example/app.jsx
   create example/app.tsx
   create example/package.json
   create example/pages/index.css
   create example/pages/index.jsx
   create example/pages/index.tsx
   create example/tsconfig.json
   create example/typing.d.ts
   create README.md
   create src/index.ts
   create test/fixtures/normal/pages/index.css
   create tsconfig.json
✨ File Generate Done

安装 node 模块

$ yarn

你也可以使用 npm install ，因为有编写测试，所以安装了 puppeteer，如果你安装失败，可能需要科学上网，或者使用淘宝源。

Umi@3 插件命名特性

在 Umi@3 中，当插件使用 @umijs 或者 umi-plugin 开头，只要安装就会被默认使用，所以如果你的插件名以上述规则命名，你就不需要在 config 文件中显式使用你的插件，如果你的插件命名不满足上述规则，那你只需要在 config 中显示使用即可。

import { defineConfig } from 'umi';

export default defineConfig({
  plugins: ['you-plugin-name'],
});

此次示例中我们的插件名是 umi-plugin-main-path 。

实战演练

首先我们先看一下，初始化脚手架中的代码，如果使用这个插件，那么就会打印日志 use plugin，然后使用 modifyHTML api 在 body 上添加了 h1 的内容。更多插件 api ，请查阅Plugins Api。

export default function (api: IApi) {
  api.logger.info('use plugin');

  api.modifyHTML(($) => {
    $('body').prepend(`<h1>hello umi plugin</h1>`);
    return $;
  });

}

为我们的插件增加一个配置，使用 describe 注册配置。

api.describe({
    key: 'mainPath',
    config: {
      schema(joi) {
        return joi.string();
      },
    },
  });

增加我们插件的主逻辑

if (api.userConfig.mainPath) {
    api.modifyRoutes((routes: any[]) => {
      return resetMainPath(routes, api.config.mainPath);
    });
  }

这里需要注意的是，我们在判断时取的是 api.userConfig，而在 api 的回调中使用的是 api.config，你可以理解为 api.userConfig 是配置中的值， api.config 是插件修改后的值，这里可以是任意插件修改。

在演示中使用我们的插件：

在 example/.umirc.ts 中增加配置

import { defineConfig } from 'umi';

export default defineConfig({
  plugins: [require.resolve('../lib')],
  mainPath:'/home'
});

新建 page 页面，新建 example/pages/home.tsx

import React from 'react';
import styles from './index.css';

export default () => (
  <div className={styles.normal}>
    <h2>Home Page!</h2>
  </div>
);

查看效果

yarn start
Starting the development server...

✔ Webpack
  Compiled successfully in 20.73s

  App running at:
  - Local:   http://localhost:8000 (copied to clipboard)
  - Network: http://192.168.50.236:8000

浏览器访问 http://localhost:8000 就可以访问到 home ，要访问之前的 index 页面，要通过 http://localhost:8000/index。

为插件编写测试

一般 Umi 插件的测试，我们都是采用结果测试的方案，只看最终运行效果。这里我们使用的是 test-umi-plugin，它也有一定的约定，指定 fixtures 之后，他会自动执行文件夹下的 test 文件。

在 test/fixtures/normal/.umirc.ts 中增加配置

export default {
  plugins: [require.resolve('../../../lib')],
  mainPath: '/home'
}

新建 page 页面，新建 test/fixtures/normal/pages/home.tsx

import React from 'react';
import styles from './index.css';

export default () => (
  <div className={styles.normal}>
    <h2>Home Page!</h2>
  </div>
);

修改测试用例 test/fixtures/normal/test.ts

export default async function ({ page, host }) {
  await page.goto(`${host}/`, {
    waitUntil: 'networkidle2',
  });
  const text = await page.evaluate(
    () => document.querySelector('h1').innerHTML,
  );
  expect(text).toEqual('Home Page');
};

执行测试

$ yarn test
$ umi-test
  console.log
    [normal] Running at http://localhost:12401

 PASS  test/index.e2e.ts (10.219s)
  ✓ normal (1762ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        11.057s
Ran all test suites.
✨  Done in 14.01s.

本次示例的完整代码在 umi-plugin-main-path。

UmiJS