Skip to content

Commit fbb0da5

Browse files
xlornexlorne
committed
update README.md
1 parent 50e7421 commit fbb0da5

2 files changed

Lines changed: 58 additions & 221 deletions

File tree

‎README.md‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,35 @@ interface CardLayout {
8686
}
8787
```
8888

89-
### 5. 刷新组件
89+
### 5. Header 和 Footer
90+
91+
支持在表单头部和底部渲染自定义内容：
92+
93+
```typescript
94+
interface FormViewProps {
95+
header?: React.ReactNode; // 表单头部内容
96+
footer?: React.ReactNode; // 表单底部内容
97+
}
98+
```
99+
100+
- `header`: 渲染在表单内容上方的区域，可用于放置标题、说明文字等
101+
- `footer`: 渲染在表单内容下方的区域，可用于放置提交按钮、操作栏等
102+
103+
### 6. 表单提交（onFinish）
104+
105+
支持表单提交事件处理：
106+
107+
```typescript
108+
interface FormViewProps {
109+
onFinish?: (values: any, formCode?: string) => void;
110+
}
111+
```
112+
113+
- 当表单提交时触发
114+
- 返回表单数据和表单编码
115+
- 支持主表单和子表单
116+
117+
### 7. 刷新组件
90118

91119
通过增加字段 `version` 版本号来触发组件的重新渲染：
92120

@@ -112,7 +140,7 @@ form.refreshFields(['field1', 'field2']);
112140
form.refreshFields(['field1'], 'sub_form_code');
113141
```
114142

115-
### 6. 表单实例控制
143+
### 8. 表单实例控制
116144

117145
提供丰富的表单操作方法：
118146

@@ -174,7 +202,23 @@ const meta = {
174202
]
175203
};
176204

205+
// 基础用法
177206
<FormView meta={meta} />;
207+
208+
// 带 header、footer 和 onFinish 的完整用法
209+
<FormView
210+
meta={meta}
211+
header={<div className="form-header">用户信息登记表</div>}
212+
footer={
213+
<div className="form-footer">
214+
<Button type="primary" htmlType="submit">提交</Button>
215+
<Button>取消</Button>
216+
</div>
217+
}
218+
onFinish={(values, formCode) => {
219+
console.log('表单提交数据:', values, '表单编码:', formCode);
220+
}}
221+
/>;
178222
```
179223

180224
### 4. 开发模式
@@ -213,6 +257,9 @@ pnpm build
213257
| meta | FormMeta | 表单元数据定义 |
214258
| form | FormInstance | 表单实例 |
215259
| onValuesChange | (values: any) => void | 值变化回调 |
260+
| onFinish | (values: any, formCode?: string) => void | 表单提交回调 |
261+
| header | React.ReactNode | 表单头部内容 |
262+
| footer | React.ReactNode | 表单底部内容 |
216263
| review | boolean | 是否预览模式 |
217264
| validators | FormFieldValidator[] | 验证规则数组 |
218265
| events | FormEvent[] | 事件定义数组 |

‎packages/form-engine/README.md‎

Lines changed: 9 additions & 219 deletions
Original file line numberDiff line numberDiff line change
@@ -1,233 +1,23 @@
1-
[![npm](https://img.shields.io/npm/v/@coding-form/form-engine.svg)](https://www.npmjs.com/package/@coding-form/form-engine)
2-
# Form Engine
1+
# Rslib project
32

4-
一个基于 React 的动态表单引擎，支持表单动态渲染、字段验证、事件处理和布局控制。
3+
## Setup
54

6-
## 项目结构
7-
8-
```
9-
coding-form/
10-
├── packages/
11-
│ └── form-engine/ # 核心表单视图库
12-
│ ├── src/
13-
│ │ ├── form/ # 表单组件
14-
│ │ ├── factory/ # 表单项工厂
15-
│ │ ├── register/ # 组件注册中心
16-
│ │ ├── store/ # Redux 状态管理
17-
│ │ ├── context/ # React Context
18-
│ │ ├── instance/ # 表单实例控制
19-
│ │ ├── presenters/ # 表单展示层
20-
│ │ ├── validate/ # 表单验证
21-
│ │ ├── event/ # 事件处理
22-
│ │ ├── layout/ # 布局系统
23-
│ │ ├── hooks/ # 自定义 Hooks
24-
│ │ └── types/ # TypeScript 类型定义
25-
│ └── dist/ # 构建输出
26-
├── apps/ # 示例应用
27-
│ ├── app-pc/ # PC 端示例
28-
│ └── app-mobile/ # 移动端示例
29-
└── package.json # 工作区配置
30-
```
31-
32-
## 核心功能
33-
34-
### 1. 动态表单渲染
35-
36-
通过元数据（Meta）动态生成表单，支持：
37-
- 多种数据类型：`STRING`, `INTEGER`, `LONG`, `DOUBLE`, `BOOLEAN`
38-
- 字段属性：名称、编码、类型、默认值、提示等
39-
- 嵌套子表单（subForms）
40-
41-
### 2. 表单验证
42-
43-
```typescript
44-
interface FormFieldValidator {
45-
target: FieldKey; // 校验目标字段
46-
validator: (instance: FormInstance, value: any) => boolean | string;
47-
}
48-
```
49-
50-
- 支持自定义验证规则
51-
- 异步验证支持
52-
- 隐藏字段自动跳过验证
53-
54-
### 3. 事件系统
55-
56-
支持表单事件绑定和处理：
57-
58-
```typescript
59-
interface FormEvent {
60-
type: 'load' | 'change' | 'blur'; // 事件类型
61-
target: FieldKey; // 事件目标
62-
event: (formInstance: FormInstance, value: any) => void;
63-
}
64-
```
65-
66-
- `load`: 表单加载时触发
67-
- `change`: 字段值变化时触发
68-
- `blur`: 字段失去焦点时触发
69-
70-
### 4. 布局控制
71-
72-
支持卡片布局和默认布局：
73-
74-
```typescript
75-
interface FormLayout {
76-
formCode: string;
77-
type: 'card';
78-
props: CardLayout
79-
}
80-
81-
interface CardLayout {
82-
title: string;
83-
layout: 'horizontal' | 'vertical';
84-
fields: FieldLayout[];
85-
mainFields: string[];
86-
}
87-
```
88-
89-
### 5. 刷新组件
90-
91-
通过增加字段 `version` 版本号来触发组件的重新渲染：
92-
93-
```typescript
94-
interface StateField {
95-
version?: number; // 版本号，每次刷新时递增
96-
}
97-
```
98-
99-
- `refreshFields`: 刷新指定字段，触发组件重新渲染
100-
- 支持单个字段或字段数组
101-
- 支持主表单和子表单
102-
- 通过递增 `version` 值实现强制刷新
103-
104-
```typescript
105-
// 刷新单个字段
106-
form.refreshFields('field_code');
107-
108-
// 刷新多个字段
109-
form.refreshFields(['field1', 'field2']);
110-
111-
// 刷转子表单字段
112-
form.refreshFields(['field1'], 'sub_form_code');
113-
```
114-
115-
### 6. 表单实例控制
116-
117-
提供丰富的表单操作方法：
118-
119-
```typescript
120-
// 获取/设置字段值
121-
getFieldValue(name: string, formCode?: string)
122-
getFieldsValue(formCode?: string)
123-
setFieldValue(name: string, value: any, formCode?: string)
124-
setFieldsValue(values: any, formCode?: string)
125-
126-
// 表单操作
127-
resetFields(nameList?: string[], formCode?: string)
128-
validateFields(nameList?: string[], formCode?: string)
129-
submit(formCode?: string)
130-
131-
// 动态控制
132-
hiddenFields(hidden: boolean, nameList: string[]|string, formCode?: string)
133-
requiredFields(required: boolean, nameList: string[]|string, formCode?: string)
134-
refreshFields(nameList: string[]|string, formCode?: string) // 刷新字段，触发重新渲染
135-
```
136-
137-
## 快速开始
138-
139-
### 1. 安装依赖
5+
Install the dependencies:
1406

1417
```bash
1428
pnpm install
1439
```
14410

145-
### 2. 注册表单组件
146-
147-
```tsx
148-
import { FormRegistry } from '@coding-form/form-engine';
149-
import YourFormComponent from './YourFormComponent';
150-
import formInstanceFactory from './formInstanceFactory';
151-
152-
FormRegistry.getInstance().register(YourFormComponent, formInstanceFactory);
153-
```
154-
155-
### 3. 使用表单视图
156-
157-
```tsx
158-
import { FormView } from '@coding-form/form-engine';
159-
160-
const meta = {
161-
name: '用户信息',
162-
code: 'user_form',
163-
fields: [
164-
{
165-
id: '1',
166-
name: '姓名',
167-
code: 'name',
168-
type: 'text_input',
169-
dataType: 'STRING',
170-
hidden: false,
171-
required: true,
172-
placeholder: '请输入姓名'
173-
}
174-
]
175-
};
11+
## Get started
17612

177-
<FormView meta={meta} />;
178-
```
179-
180-
### 4. 开发模式
13+
Build the library:
18114

18215
```bash
183-
# 监听构建 form-view
184-
pnpm watch:form-view
185-
186-
# 运行 PC 示例应用
187-
pnpm dev:app-pc
188-
189-
# 运行移动端示例应用
190-
pnpm dev:app-mobile
16+
pnpm run build
19117
```
19218

193-
### 5. 构建
19+
Build the library in watch mode:
19420

19521
```bash
196-
pnpm build
197-
```
198-
199-
## 技术栈
200-
201-
- **React 18** - UI 框架
202-
- **TypeScript** - 类型系统
203-
- **Redux Toolkit** - 状态管理
204-
- **React Redux** - React 绑定
205-
- **Rslib** - 构建工具
206-
207-
## API 参考
208-
209-
### FormView 组件属性
210-
211-
| 属性 | 类型 | 说明 |
212-
|------|------|------|
213-
| meta | FormMeta | 表单元数据定义 |
214-
| form | FormInstance | 表单实例 |
215-
| onValuesChange | (values: any) => void | 值变化回调 |
216-
| review | boolean | 是否预览模式 |
217-
| validators | FormFieldValidator[] | 验证规则数组 |
218-
| events | FormEvent[] | 事件定义数组 |
219-
| layouts | FormLayout[] | 布局定义数组 |
220-
221-
### 数据类型
222-
223-
| 类型 | 说明 |
224-
|------|------|
225-
| STRING | 字符串 |
226-
| INTEGER | 整数 |
227-
| LONG | 长整数 |
228-
| DOUBLE | 小数 |
229-
| BOOLEAN | 布尔值 |
230-
231-
## 许可证
232-
233-
[LICENSE](./LICENSE)
22+
pnpm run dev
23+
```

0 commit comments

Comments
 (0)