Skip to content

Commit fe10424

Browse files
xlornexlorne
committed
update version
1 parent 17212a4 commit fe10424

1 file changed

Lines changed: 218 additions & 8 deletions

File tree

‎packages/form-engine/README.md‎

Lines changed: 218 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,233 @@
1-
# Rslib project
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
23

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

5-
Install the dependencies:
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. 安装依赖
6140

7141
```bash
8142
pnpm install
9143
```
10144

11-
## Get started
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';
12159

13-
Build the library:
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+
};
176+
177+
<FormView meta={meta} />;
178+
```
179+
180+
### 4. 开发模式
14181

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

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

21195
```bash
22-
pnpm run dev
196+
pnpm build
23197
```
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)

0 commit comments

Comments
 (0)