@wangcongcong/dynamic-form
v1.2.3
Published
```bash npm i @wangcongcong/dynamic-form ``` 目前的稳定版本是 1.0.9
Readme
组件安装
npm i @wangcongcong/dynamic-form目前的稳定版本是 1.0.9
组件使用
1. 引入组件
import { DynamicForm } from "@wangcongcong/dynamic-form";
import type { FieldItem } from '@wangcongcong/dynamic-form';
import '@wangcongcong/dynamic-form/dist/dynamic-form.css';2. 使用组件
<DynamicForm
formData={formData}
onSubmit={(val) => {
console.log('最终提交:', val)
}}
onCancel={() => {
console.log('取消');
}}
title="组合表单"
layoutInline={false}
/>2.1 组件属性
| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| formData | FieldItem[] | 是 | 表单字段配置数组 |
| onSubmit | (values: Record<string, any>) => void | 否 | 表单提交回调函数，返回表单数据 |
| onCancel | () => void | 否 | 取消按钮点击回调函数 |
| formDisabled | boolean | 否 | 是否禁用整个表单 |
| inputer | any | 否 | 输入器配置，用于自定义输入行为 |
| layoutInline | boolean | 否 | 表单布局方式，true=同行排列，false=垂直排列 |
| title | string | 否 | 表单标题 |
| cancelText | string | 否 | 取消按钮文本 |
| okText | string | 否 | 确认按钮文本 |
3. 配置数据
formData: FieldItem[] = [];FieldType: 'text' | 'select' | 'radio' | 'textarea' | 'file' | 'checkbox' | 'datePicker' | 'dynamicFormItem' | 'timePicker' | 'datePickerRegion' | 'dynamicFormItemLic' | 'switch' | 'timeSheet' | 'rangeInput' | 'rangeNumber' | 'tagInput'; // 表单字段支持类型OptionItem {
id: string;
text: string;
value?: string;
}数组对象的属性支持：
FieldItem {
key: string; // 字段key
type: FieldType; // 字段类型
value: string; // label名称
defaultValue?: any; // 默认值
required?: boolean; // 是否必填
multiple?: boolean; // 是否多选
options?: OptionItem[]; // 下拉选项
disabled?: boolean; // 是否禁用
isInline?: boolean; // 是否行内显示
labelAlign?: 'left' | 'right'; // label对齐方式
labelMinWidth?: string; // label最小宽度
colSpan?: number; // 用于一行显示多个时的布局 默认24
isUseOptionsId?: boolean; // options 默认使用text作为value，可以指定id
isUsedFirstOption?: boolean; // 是否使用第一个选项作为默认值 仅应用于api获取的options 固定的可以配合defaultValue使用
// timePicker 相关的属性
format?: string;
minuteStep?: 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 15 | 20 | 30;
// 'rangeInput' | 'rangeNumber' 范围输入相关的属性
unit?: string; // 单位 用于范围输入
min?: number | undefined; // 最小值
max?: number | undefined; // 最大值
placeholder?: [string, string]; // 输入框提示语
collspanGroupNameTemp?: string; // 折叠分组名称 第一层折叠分组 支持组合也支持独立使用
cardGroupNameTemp?: string; // 卡片分组名称 第二层卡片分组 支持组合也支持独立使用
fetchOptionsAllFlag?: boolean; // 获取下拉数据后 避免重复加载 添加联动参数 与 fetchOptionsAll关联
fetchOptionsAll?: (formValues?: any) => Promise<OptionItem[]>; // 动态加载全部选项
fetchOptions?: (formValues?: any) => Promise<OptionItem[]>; // 动态加载选项
fetchOptionsLinkage?: (formValues?: any, data?:any) => Promise<OptionItem[]>; // 动态加载联动子选项
visibleWhen?: (formValues: any) => boolean; // 控制显示
visibleWhenOption?: (dict?:any, formValues?: any) => Promise<OptionItem[]>; // 控制选项显示
requiredWhen?: (formValues: any) => boolean; // 控制是否必填
pattern?: RegExp; // 自定义正则校验
patternMessage?: string; // 匹配失败时的提示信息
requireAllOptions?: boolean; // 是否必须全选所有选项
fetchOptionsLazy?: (searchText: string) => Promise<OptionItem[]>; // 带搜索参数的懒加载
search?: boolean; // 下拉框是否启用搜索
getInitialValueFromApi?: () => Promise<any>; // 字段初始默认值
getInitialValueByField?: {
dependencyKey: string | string[]; // 被依赖字段 key
handler: (value: any, obj?: any) => Promise<any>; // 接口请求，入参是 key 字段值
}; // 根据其它字段触发赋值
asyncValidate?: (value: any) => Promise<void>; // 请求 api 校验
fetchDefaultFormValues?: (formValues?: any) => Promise<any>; // api获取表单默认值进行填充 --- 一个表单可以绑定一个key上获取全部表单的默认值
onChangeFetchDefaultValuesAndHiddenFields?: (formValues?: any,text?: any) => Promise<any>; // api获取表单默认值进行填充并隐藏字段 需要传递页面数据作为参数
}4. 组件能力
4.1 字段类型
| 类型 | 说明 | 支持属性 |
|------|------|---------|
| text | 单行文本输入 | defaultValue, disabled, placeholder |
| textarea | 多行文本输入 | defaultValue, disabled, placeholder |
| select | 下拉选择 | options, multiple, search, disabled |
| radio | 单选按钮组 | options, disabled |
| checkbox | 复选框组 | options, multiple, disabled, requireAllOptions |
| datePicker | 日期选择 | format, minuteStep, disabled |
| datePickerRegion | 日期范围选择 | format, minuteStep, disabledDate, disabledDateTime |
| timePicker | 时间选择 | format, minuteStep, disabled |
| switch | 开关 | - |
| file | 文件上传 | multiple, file_type, file_content_size, max_count |
| rangeInput | 范围文本输入 | unit, placeholder |
| rangeNumber | 范围数字输入 | unit, min, max, placeholder |
| tagInput | 标签输入 | - |
4.2 布局能力
| 属性 | 说明 | 示例 |
|------|------|------|
| layoutInline | 表单级布局：true=同行排列，false=垂直排列 | layoutInline={false} |
| isInline | 字段级布局：覆盖表单级设置 | isInline: true |
| colSpan | 栅格宽度（一般使用12或者24），用于一行显示多个字段 | colSpan: 12（占一半宽度） |
| labelAlign | label 对齐方式 | 'left' 或 'right' |
| labelMinWidth | label 最小宽度 | '100px' |
4.3 数据联动
| 属性 | 说明 |
|------|------|
| fetchOptions | 根据表单数据动态加载下拉选项 |
| fetchOptionsAll | 一次性加载所有下拉选项（带防重复标识） |
| fetchOptionsLazy | 搜索时懒加载下拉选项 |
| fetchOptionsLinkage | 下拉选项联动加载 |
| visibleWhenOption | 根据条件动态控制选项显示 |
| getInitialValueByField | 监听其他字段变化触发接口赋值 |
4.4 字段显隐控制
| 属性 | 说明 |
|------|------|
| visibleWhen | 根据表单值控制字段显示/隐藏 |
| requiredWhen | 根据表单值控制字段是否必填 |
| onChangeFetchDefaultValuesAndHiddenFields | 接口返回数据后自动填充并隐藏字段 |
4.5 校验能力
| 属性 | 说明 |
|------|------|
| required | 必填校验 |
| pattern | 自定义正则校验 |
| patternMessage | 正则校验失败提示 |
| asyncValidate | 异步 API 校验（失去焦点时触发） |
| requireAllOptions | 多选时必须全选所有选项 |
4.6 数据初始化
| 属性 | 说明 |
|------|------|
| defaultValue | 字段默认值 |
| isUsedFirstOption | 使用 options 第一个选项作为默认值 |
| getInitialValueFromApi | 接口获取字段初始值 |
| fetchDefaultFormValues | 接口获取整个表单的默认值 |
4.7 分组能力
| 属性 | 说明 |
|------|------|
| collspanGroupNameTemp | 折叠分组（第一层），多个字段可组合 |
| cardGroupNameTemp | 卡片分组（第二层），支持折叠+卡片组合 |
5.示例
CDN 引入
1. 通过 CDN 引入
<!-- 1. 引入组件 CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@wangcongcong/dynamic-form@latest/dist/dynamic-form.css">
<!-- 2. 引入 React -->
<script crossorigin src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<!-- 3. 引入 ReactDOM -->
<script crossorigin src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
<!-- 4. 引入 Ant Design -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/antd.min.js"></script>
<!-- 5. 引入组件 JS（必须放在最后） -->
<script src="https://cdn.jsdelivr.net/npm/@wangcongcong/dynamic-form@latest/dist/index.js"></script>2. CDN 使用示例
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Dynamic Form CDN 示例</title>
<!-- 组件 CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@wangcongcong/dynamic-form@latest/dist/dynamic-form.css">
<!-- React -->
<script crossorigin src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<!-- ReactDOM -->
<script crossorigin src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>
<!-- Ant Design -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/antd.min.js"></script>
<!-- 组件 JS（必须放在最后） -->
<script src="https://cdn.jsdelivr.net/npm/@wangcongcong/dynamic-form@latest/dist/index.js"></script>
</head>
<body>
<div id="root"></div>
<script>
const { DynamicForm } = window.DynamicForm;
const { createRoot } = ReactDOM;
// 表单配置数据
const formData = [
{
key: 'name',
type: 'text',
value: '姓名',
required: true
},
{
key: 'gender',
type: 'select',
value: '性别',
options: [
{ id: '1', text: '男' },
{ id: '2', text: '女' }
],
required: true
}
];
// 使用组件
const root = createRoot(document.getElementById('root'));
root.render(
React.createElement(DynamicForm, {
formData: formData,
onSubmit: function(val) {
console.log('最终提交:', val);
},
title: 'CDN 组合表单',
layoutInline: false
})
);
</script>
</body>
</html>版本说明
- 最新版本: 使用
@latest标签自动获取最新版本 - 指定版本: 将
@latest替换为具体版本号，如@1.0.9 - CDN 地址: 使用 jsDelivr CDN 服务