docs/docs/en/flow-engine/ui-schema.md
UI Schema is the protocol NocoBase uses to describe frontend components, based on Formily Schema 2.0 in a JSON Schema-like style. In FlowEngine, the uiSchema field in registerFlow uses this syntax to define the UI for configuration panels.
interface ISchema {
type: 'void' | 'string' | 'number' | 'object' | 'array';
name?: string;
title?: any;
// Wrapper component
['x-decorator']?: string;
// Wrapper component props
['x-decorator-props']?: any;
// Component
['x-component']?: string;
// Component props
['x-component-props']?: any;
// Display state, defaults to 'visible'
['x-display']?: 'none' | 'hidden' | 'visible';
// Component's child content
['x-content']?: any;
// Children node schema
properties?: Record<string, ISchema>;
// The following are only used for field components
// Field reactions
['x-reactions']?: SchemaReactions;
// Field UI interaction mode, defaults to 'editable'
['x-pattern']?: 'editable' | 'disabled' | 'readPretty';
// Field validation
['x-validator']?: Validator;
// Default data
default?: any;
}
All native HTML tags can be converted to schema notation:
{
type: 'void',
'x-component': 'h1',
'x-content': 'Hello, world!',
}
Equivalent JSX:
<h1>Hello, world!</h1>
Children components are written in properties:
{
type: 'void',
'x-component': 'div',
'x-component-props': { className: 'form-item' },
properties: {
title: {
type: 'string',
'x-component': 'input',
},
},
}
Equivalent JSX:
<div className={'form-item'}>
<input name={'title'} />
</div>
The type of the node:
type SchemaTypes = 'string' | 'object' | 'array' | 'number' | 'boolean' | 'void';
The schema name. The name of a child node is the key in properties:
{
name: 'root',
properties: {
child1: {
// No need to write name here
},
},
}
The node title, typically used as the label for form fields.
The component name. Can be a native HTML tag or a registered React component:
{
type: 'void',
'x-component': 'h1',
'x-content': 'Hello, world!',
}
Component props:
{
type: 'void',
'x-component': 'Table',
'x-component-props': {
loading: true,
},
}
Wrapper component. The x-decorator + x-component combination allows placing two components in a single schema node — reducing structural complexity and improving reusability.
For example, in form scenarios, FormItem serves as the decorator:
{
type: 'void',
'x-component': 'div',
properties: {
title: {
type: 'string',
'x-decorator': 'FormItem',
'x-component': 'Input',
},
content: {
type: 'string',
'x-decorator': 'FormItem',
'x-component': 'Input.TextArea',
},
},
}
Equivalent JSX:
<div>
<FormItem>
<Input name={'title'} />
</FormItem>
<FormItem>
<Input.TextArea name={'content'} />
</FormItem>
</div>
The display state of the component:
| Value | Description |
|---|---|
'visible' | Show the component (default) |
'hidden' | Hide the component, but data remains visible |
'none' | Hide both the component and its data |
The interaction mode of field components:
| Value | Description |
|---|---|
'editable' | Editable (default) |
'disabled' | Not editable |
'readPretty' | Read-pretty mode — for example, a text input component renders as <input /> in edit mode and <div /> in read-pretty mode |
In plugin development, uiSchema is primarily used in registerFlow configuration panels. Each field is typically wrapped with 'x-decorator': 'FormItem':
MyModel.registerFlow({
key: 'flow1',
on: 'beforeRender',
steps: {
editTitle: {
title: 'Edit Title',
uiSchema: {
title: {
type: 'string',
title: 'Title',
'x-decorator': 'FormItem',
'x-component': 'Input',
},
showBorder: {
type: 'boolean',
title: 'Show Border',
'x-decorator': 'FormItem',
'x-component': 'Switch',
},
color: {
type: 'string',
title: 'Color',
'x-decorator': 'FormItem',
'x-component': 'Select',
enum: [
{ label: 'Red', value: 'red' },
{ label: 'Blue', value: 'blue' },
{ label: 'Green', value: 'green' },
],
},
},
handler(ctx, params) {
ctx.model.props.title = params.title;
ctx.model.props.showBorder = params.showBorder;
ctx.model.props.color = params.color;
},
},
},
});
:::tip Tip
v2 is compatible with the uiSchema syntax, but its use cases are limited — it is mainly used in Flow configuration panels to describe form UI. For most runtime component rendering, it is recommended to use Antd components directly.
:::
| Component | x-component | type | Description |
|---|---|---|---|
| Single-line text | Input | string | Basic text input |
| Multi-line text | Input.TextArea | string | Multi-line text area |
| Number | InputNumber | number | Number input |
| Switch | Switch | boolean | Boolean toggle |
| Dropdown select | Select | string | Requires enum for options |
| Radio | Radio.Group | string | Requires enum for options |
| Checkbox | Checkbox.Group | string | Requires enum for options |
| Date | DatePicker | string | Date picker |