示例

index.js

// 普通的 umi 插件写法，新增 api.onUISocket 和 api.addUIPlugin 接口

export default api => {

// 处理 socket 通讯数据

api.onUISocket(({ action, send, log }) => {

// 通过 action 处理

// 处理完后 send 数据到客户端

send({ type, payload });

// 过程中的日志通过 log 打到客户端

log(`Adding block Foo/Bar...`);

});

// 添加编辑态的插件

api.addUIPlugin(require.resolve('./dist/client.umd'));

};

ui.js(通过 father-build 打包到 dist/ui.umd.js)

// 这个文件打 umd 到 ./dist/client.umd.js，external react、react-dom 和 antd，用 father-build 很容易打出来

export default api => {

const {

// 调用服务端方法

callRemote,

} = api;

function Blocks() {

return

Blocks

;

}

// 添加 panel，类似 vscode 点击左边的 Icon 后切换 Panel

api.addPanel({

title: '区块管理',

icon: 'home',

path: '/blocks',

component: Blocks,

// 顶部右侧按钮

actions: [

{

title: '打开配置文件',

// antd Button type

type: 'default',

// 点击后的 action

action: {

type: '@@actions/openConfigFile',

payload: {

projectPath: api.currentProject.path,

}

},

onClick: () => {},

},

],

});

// 更多功能...

};

服务端接口

可访问 所有插件接口和属性，以下是几个与 UI 相关 API。

api.onUISocket

处理 socket 数据相关，比如：

api.onUISocket(({ type, payload }, { log, send, success, failure }) => {

if (type === 'config/fetch') {

send({ type: `${type}/success`, payload: getConfig() });

}

});

注：

按约定，如果客户端用 api.callRemote 调用服务端接口，处理完数据需 send 加 /success 或 /failure 后缀的数据表示成功和失败。

send({ type, payload })

向客户端发送消息。

success(payload)

send({ type: `${type}/success` }) 的快捷方式。

failure(payload)

send({ type: `${type}/failure` }) 的快捷方式。

progress(payload)

send({ type: `${type}/progress` }) 的快捷方式。

log(level, message)

在控制台和客户端同时打印日志。

示例：

log('info', 'abc');

log('error', 'abc');

api.addUIPlugin

注册 UI 插件，指向客户端文件。

api.addUIPlugin(require.resolve('./dist/ui'));

注：

文件需是 umd 格式(例如 ./dist/ui.umd.js)

客户端接口

api.callRemote()

调服务端接口，并等待 type 加上 /success 或 /failure 消息的返回。若有进度的返回，可通过 onProgress 处理回调。

参数如下：

api.callRemote({

// 接口名称

type: string;

// 传入参数

payload: object;

// 监听服务端推送来的数据

onProgress: (data) => void;

// 是否建立长久连接

keep: boolean;

})

示例：

import React from 'react';

const { useState } = React;

// 组件 props api 从插件传入

export default (props) => {

const { api } = props;

const [progress, setProgress] = useState(0);

const handleClick = async () => {

await api.callRemote({

type: 'org.umi.plugin.bar.create',

payload: {

id: 'id',

},

onProgress: async (data) => {

useState(data);

}

})

}

return (

)

}

注：

callRemote 会自动带上 lang 属性，供服务端区分语言

有 keep 属性，则不会在 success 或 failure 后清除掉

api.listenRemote()

监听 socket 请求，有消息时通过 onMessage 处理回调。

返回一个 unlisten 函数，用于取消监听。

示例：

const unlisten = api.listenRemote({

// 接口名称

type: 'org.umi.plugin.foo',

onMessage: (data) => {

// 函数处理

}

});

// 组件卸载时可调用，取消监听

unlisten();

api.send()

发送消息到服务端。

api.addDashboard()

添加入口卡片到『总览』页

调用参数如下：

(dashboard: IDashboard | IDashboard[]) => void;

interface IDashboard {

/** card key 唯一标识，约定格式为：org.umi.dashboard.card.${key} */

key: string;

/** card 标题 */

title: ReactNode;

/** card 描述 */

description: ReactNode;

/** icon 图标 */

icon: ReactNode;

/** icon 图标背景色，默认为 #459BF7 */

backgroundColor?: string;

/** card body */

content: ReactNode | ReactNode[];

/** card 右侧区域扩展 */

right?: ReactNode;

/** 栅格，默认为 { xl: 6, sm: 12, lg: 12, xs: 24 } */

span?: Partial

/** default 6 */

xl: number;

/** default 12 */

sm: number;

/** default 12 */

lg: number;

/** default 24 */

xs: number;

}>;

}

示例：

import React from 'react';

import { ControlFilled } from '@ant-design/icons';

export default () => {

api.addDashboard({

key: 'org.umi.dashboard.card.testId',

title: '卡片标题',

description: '卡片描述',

icon: ,

content: [

alert('部署成功')}>

一键部署

,

],

});

}

api.addPanel()

添加客户端插件入口及路由，调用此方法会在 Umi UI 中增加一级菜单。

调用参数有：

api.addPanel({

// 插件路由

path: string;

// 组件

component: ReactNode;;

// 图标，同 antd icon

icon: IconType | string;

// 全局操作按钮，位于插件面板右上角

actions?: ReactNode | React.FC | {

// 标题

title: string;

// 按钮样式

type?: 'default' | 'primary';

// 与 callRemote 参数一致

action?: IAction;

// 额外的点击事件

onClick?: () => void;

}[];

// 实验室插件，开启后插件会加入到实验室中，默认 false

beta?: boolean;

});

示例：

// ui.(jsx|tsx)

import React from 'react';

import Template from './ui/index';

export default (api) => {

api.addPanel({

title: '插件模板',

path: '/plugin-bar',

icon: 'environment',

// api 透传至组件

component: () => ,

});

};

添加插件全局操作区(动态修改全局操作区，参考 api.addLocales()

添加全局国际化信息。

例如：

添加国际化字段

// ui.(jsx|tsx)

import React from 'react';

import Template from './ui/index';

export default (api) => {

// 你也可以在顶部

// import zh from './your-locale/zh.js'

// import en from './your-locale/en.js'

// { 'zh-CN': zh, 'en-US': en }

api.addLocales({

'zh-CN': {

'org.sorrycc.react.name': '陈成',

},

'en-US': {

'org.sorrycc.react.name': 'chencheng',

},

});

};

api.intl.*

使用国际化，使用 api.getLocale()

返回当前语言，zh-CN、en-US 等。

api.hooks.*

集成 UI 开发中常用 hooks，更多 API 见 [http://hooks.umijs.org/]。

例如：

import React from 'react';

export default (api) => {

const { useDebounceFn } = api.hooks;

const [value, setValue] = useState(0);

const { run } = useDebounceFn(() => {

setValue(value + 1);

}, 500);

const Component = (

)

api.addPanel({

title: '插件模板',

path: '/plugin-bar',

icon: 'environment',

component: Component,

});

};

api.showLogPanel()

打开 Umi UI 底部日志栏。

api.hideLogPanel()

隐藏 Umi UI 底部日志栏。

api.moment

api.event

api.TwoColumnPanel

两栏布局组件

比如：

const { TwoColumnPanel } = api;

function Configuration() {

return (

sections={[

{

// 访问 /${插件路由}?active=${key}

// 可定位到具体插件的具体面板

key?: 'basic',

title: '基本配置', description,

icon: '',

component: C1

},

{

key?: 'config',

title: 'umi-plugin-react 配置',

description,

icon: '',

component: C2

},

]}

/>

);

}

api.addPanel({

component: Configuration,

});

api.Terminal

参数如下：

interface ITerminalProps {

/** Terminal title */

title?: ReactNode;

className?: string;

terminalClassName?: string;

/** defaultValue in Terminal */

defaultValue?: string;

/** terminal init event */

onInit?: (ins: XTerminal, fitAddon: any) => void;

/** https://xtermjs.org/docs/api/terminal/interfaces/iterminaloptions/ */

config?: ITerminalOptions;

onResize?: (ins: XTerminal) => void;

[key: string]: any;

}

示例：

使用终端实例，调用日志输出函数：

import React, { useState } from 'react'

export default (api) => {

const { Terminal } = api;

function Component() {

let terminal;

const handleClick = () => {

terminal.write('Hello World');

}

return (

);

}

api.addPanel({

component: Component,

});

}

终端更多用法见 文档

api.DirectoryForm

目录选择表单控件

参数如下：

interface IDirectoryForm {

/** path, default */

value?: string;

onChange?: (value: string) => void;

}

示例：

import React from 'react';

import { Form } from 'antd';

export default () => {

const [form] = Form.useForm();

return (

form={form}

onFinish={values => {

console.log('values', values)

}}

initialValues={{

baseDir: cwd,

}}

>

label={null}

name="baseDir"

rules={[

{

validator: async (rule, value) => {

await validateDirPath(value);

},

},

]}

>

)

}

api.StepForm

步骤表单组件

使用示例：

api.Field

配置表单组件，结合 antd 4.x 一起使用，简化表单组件，使用配置式生成表单。

api.Field 参数如下：

interface IFieldProps {

/** 表单类型 */

/** 具体类型有："string" | "boolean" | "object" | "string[]" | "object[]" | "list" | "textarea" | "any" */

type: IConfigTypes;

/** 表单 字段名，通过 `.` 来确定字段之间的联动关系 */

name: string;

/** 可选列表，只用在 type 为 object */

defaultValue?: IValue;

/** 主要用于数组表单类型，提供可选值列表 */

options?: string[];

/** antd 4.x form 实例 */

form: object;

/** antd label, 如果是 object，则使用内置的 组件 */

/** object 参数有 { title: string, description: string, link?: string } */

label: string | ReactNode | IFieldLabel;

/** 控件大小, 默认是 default */

size?: 'default' | 'small' | 'large';

/** 其它类型与 Form.Item 一致 */

[key: string]: any;

}

interface IFieldLabel {

/** label title */

title: string;

/** label description */

description: string;

/** description detail link */

link: string;

}

例如，联动示例 ：

import { Form } from 'antd'

const { TwoColumnPanel } = api;

function Configuration() {

const [form] = Form.useForm();

return (

form={form}

onFinish={values => {

console.log('valuesvalues', values);

}}

initialValues={{

'parent.child2': ['**/a.js', '**/b.js'],

'parent.child3': '',

'parent2.child': 'Method1',

}}

>

form={form}

name="parent.child2"

label="Speed-string[]"

type="string[]"

/>

form={form}

name="parent2.child"

label="Config-list"

type="list"

options={['Method1', 'Method2']}

/>

form={form}

name="parent2.child2"

label="Config-list"

type="object"

options={['Target1', 'Target2']}

/>

{({ getFieldsValue }) =>

{JSON.stringify(getFieldsValue(), null, 2)}

}

Submit

);

}

api.addPanel({

component: Configuration,

});

api.ConfigForm

配置表单页面，对 api.notify()

调用 Umi UI 通知栏，若用户停留在当前浏览器窗口，通知栏样式为 antd Notification，否则为系统原生通知栏。

传入参数：

{

title: string;

message: string;

/** notify type, default info */

type?: 'error' | 'info' | 'warning' | 'success';

subtitle?: string;

/** URL to open on click */

open?: string;

/**

* The amount of seconds before the notification closes.

* Takes precedence over wait if both are defined.

*/

timeout?: number;

}

比如：

const { notify } = api;

notify({

/** 前提已经调用过 api.addLocales 添加 key */

title: 'org.umi.ui.blocks.notify.title',

message: '可以不使用国际化',

type: 'success',

});

api.redirect()

项目详情内的路由跳转，在不同插件之间进行跳转。

示例：

const { redirect } = api;

export default () => (

onClick={() => redirect('/project/select')}

>

跳转到项目列表

);

api.currentProject

获取当前项目基本信息，信息包括：

{

// KEY

key?: string;

// 应用名

name?: string;

// 应用路径

path?: string;

}

示例：

const { currentProject } = api;

export default () => (

);

api.debug()

debug API。

调试插件的时候，localStorage 修改为 debug: umiui:UIPlugin*。就可以看到所有插件的 debug 信息。

使用(以配置管理插件为例)：

export default () => {

const { debug } = api;

// 声明插件 namespace

const _log = api.debug.extend('configuration');

_log('Hello UI Configuration');

}

如果需要调试 mini 版日志，再增加一个 debugMini: umiui。

不建议在插件里使用 console.log 调用。

api.getCwd()

获取 Umi UI 启动时的路径。

示例：

const cwd = await api.getCwd();

// "/private/tmp/xxxx"

api.getSharedDataDir()

获取当前项目的临时目录。

示例：

const dir = await api.getSharedDataDir();

// "/Users/xxxxx/.umi/ui/shared-data/5bc6bd"

api.detectLanguage()

获取当前项目的语言类型。

示例：

const language = await api.detectLanguage();

// "JavaScript" | "TypeScript"

api.detectNpmClients()

获取当前项目可能在用的 npm 客户端数组。

示例：

const npmClients = await api.detectNpmClients();

// ["tnpm", "ayarn", "npm", "yarn"]

api.addConfigSection()

添加配置区块。

示例：

api.addConfigSection({

key: 'umi-plugin-react',

title: 'umi-plugin-react 配置',

description: '配置 dva、antd、按需加载、国际化等',

icon: (

src="https://img.alicdn.com/tfs/TB1aqdSeEY1gK0jSZFMXXaWcVXa-64-64.png"

width={32}

height={32}

/>

),

component: () =>

,

});

api.isMini() / api.mini

获取当前环境是否是 Umi UI mini。

示例：

const isMini = api.isMini(); // true / false

// or const isMini = api.mini

api.showMini()

打开 Umi UI mini 窗口(mini 环境下启用)。

api.hideMini()

关闭 Umi UI mini 窗口(mini 环境下启用)。

api.setActionPanel()

运行时动态修改右上角全局操作区，与 React 中 setState 类似。

参数如下：

示例：

// ui.(jsx|tsx)

import React from 'react';

export default (api) => {

// init Action

const ActionComp = () => (

)

api.addPanel({

title: '插件模板',

path: '/plugin-bar',

icon: 'environment',

actions: [

ActionComp

]

// api 透传至组件

component: () => {

const handleClick = () => {

// 类似于 React 中 setState

api.setActionPanel((actions) => {

return [

...actions,

() => alert('hello')}>New Button

]

})

}}

}

return (

添加一个新操作按钮

)

},

});

};