{"id":25435618,"url":"https://github.com/nickzone/ke-form","last_synced_at":"2025-10-28T09:46:30.535Z","repository":{"id":35048991,"uuid":"199975249","full_name":"nickzone/ke-form","owner":"nickzone","description":"通用配置化表单组件","archived":false,"fork":false,"pushed_at":"2023-03-03T04:56:52.000Z","size":2566,"stargazers_count":6,"open_issues_count":49,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-12-13T23:47:40.937Z","etag":null,"topics":["antd","from","react"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nickzone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-01T04:16:12.000Z","updated_at":"2024-08-23T11:27:40.000Z","dependencies_parsed_at":"2023-02-14T19:45:59.119Z","dependency_job_id":null,"html_url":"https://github.com/nickzone/ke-form","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzone%2Fke-form","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzone%2Fke-form/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzone%2Fke-form/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nickzone%2Fke-form/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nickzone","download_url":"https://codeload.github.com/nickzone/ke-form/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238915904,"owners_count":19551794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antd","from","react"],"created_at":"2025-02-17T07:30:34.114Z","updated_at":"2025-10-28T09:46:30.465Z","avatar_url":"https://github.com/nickzone.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## 说明\n\n一个支持配置化的表单（支持表单字段分组）组件，适用以下场景：\n\n* 想要快速使用 `配置（json）` 初始化一个支持多种内置字段类型的表单。\n\n* 想要对表单字段进行 `分组` 展示和分别调整布局，设置分组标题。\n\n* 想要通过配置（json）声明式定义一些简单的 `字段联动` 效果。\n\n* 对于没有的字段，能够快速 `扩展` 自定义字段。\n\n[在线示例](https://codesandbox.io/s/currying-violet-ppoh76)\n\n## 安装\n\n```bash\nnpm install ke-form\n```\n\n## 使用\n\n```js\nimport React , { Component } from 'react';\nimport { render } from 'react-dom';\nimport KeForm from 'ke-form';\n\n// 表单配置，包括字段、布局、分组等\nconst formConfig = {\n    fields: [{ // fields\n        type: 'input',\n        name: 'firstname',\n        label: 'First Name',\n    }]\n};\n\n// 表单初始值\nconst formData={\n    firstname: 'tom'\n};\n\n// 表单上下文\nconst formContext={ \n    ucid: '1000000000'\n};\n\nrender(\n    \u003cKeForm\n        formConfig={formConfig} // 表单配置，必传，生效一次\n        formData={formData} // 表单初始值，可选\n        formContext={formContext} // 表单上下文，可选\n        onCreate={(form) =\u003e {console.log(form)}} // 获取可交互表单实例，用于获取表单值，修改配置等\n    /\u003e, document.body);\n```\n\n## API\n\n### props\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| formConfig | 表单配置，包括字段、布局、分组等 | object | - |\n| formData | 表单初始值，{字段名: 字段值} map格式 | object | - |\n| formContext | 表单上下文，用于向表单传入额外的数据，可被表单部件，如字段部件访问 | object | - |\n| onCreate | 表单创建回调函数，用于和表单进行交互，比如获取表单值 | (form) =\u003e void | - |\n\n### props.formConfig 表单配置\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| style | 表单布局,默认纵向布局,详细配置见后文 | object | - |\n| groups | 表单分组，当表单字段非常多，需要通过分组展示时适用 | array | - |\n| fields | 表单字段，详见后文 | array | [] |\n| ajax | 数据加载函数，供内部组件需要获取数据依赖时调用 | (url) =\u003e promise.then(data) | - |\n\n### props.formConfig.style 表单样式\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| itemCol | 表单栅格布局，同 [Antd.Col](https://ant.design/components/grid-cn/#Col) | object | - | \n| labelCol | 标签栅格布局，同 [Antd.Form](https://ant.design/components/form-cn/#API) | object | - |\n| wrapperCol | 表单元素栅格布局，同 [Antd.Form](https://ant.design/components/form-cn/#API) | object | - |\n\n### props.formConfig.groups[i] 表单分组\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| name | 分组key，必填 | string | - |\n| title | 分组标题 | string | '' |\n| style | 分组样式,继承并覆盖上文 `props.formConfig.style` 配置 | object | - |\n\n### props.formConfig.fields[i] 表单元素\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| group | 分组key，当配置了分组时适用，表明字段所在分组 | string | - |\n| type | 字段类型，每种表单字段对应一种type,详见下文 | string | 'input' | \n| name | 字段键值 | string | - | \n| label | 字段label | string | '' | \n| visible | 字段是否可见 | boolean | true | \n| disabled | 字段是否可编辑 | boolean | false |\n| props || self(旧) | antd 原生组件属性,注意不要设置和 value 相关的属性，可能引起异常 | object | - |  \n| rules | 字段验证规则，配置同 [Ant.Form](https://ant.design/components/form-cn/#%E6%A0%A1%E9%AA%8C%E8%A7%84%E5%88%99) | array | - |\n| placeholder | 字段提示占位符 | string | 组件提供默认值，类似 \"请填入 label\" |\n| style | 字段布局，继承并覆盖 `props.formConfig.style` 和 `props.formConfig.group[i].style` 配置,实现更细粒度的样式控制 | object | - |\n| remote | 字段远程数据加载，比如某些字段需要根据其他字段动态加载选项 | object: `{url:string,dependFields:array}` | - |\n| remote.url | 字段数据加载url，支持模版语法,${a}表示取字段 name === a 的当前值, ${context.a} 表示取传入 formContext.a 的值| string: `/getOptions?field1=${field1}\u0026ucid=${context.ucid}` | '' |\n| remote.dependFields | 数据依赖，当form初始化和字段重置时，根据该依赖决定是否加载新的选项数据 | array: [\"field1\",\"field2\"] | [] |\n| dependEvents | 字段联动配置，基于事件模型实现，描述监听目标字段发生值改变时，当前字段如何联动改变 | array: [{target, type, handler}] | - |\n| dependEvents[i].target | 所监听目标字段key值 | string | '' |\n| dependEvents[i].type | 所监听目标字段值值改变类型 | string: `change` (值改变：默认)| 'change' |\n| dependEvents[i].value | 所监听目标字段值值改变类型 | any： 当字段值改变等于此值时，触发联动 | - |\n| dependEvents[i].handle | 触发当前字段回调事件 | string: `reset` (重置值和重置选项) ,  `show / hide` (切换显示隐藏), `disable / enable` (切换可编辑) | 'reset' |\n\n### props.formConfig.fields[i].type 表单元素类型\n\n对于每种字段类型，除了支持上述公共 Api ,因为字段本身是基于 antd 表单组件实现的，所以能够支持相应属性，需通过 `props` 配置属性传入, 不要传入 `value` 和 `onChange` 等与表单值有关的属性，会引起状态管理异常。\n\n- text 纯文本\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| props | - | object  | - |\n\n- input 文本框\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| props | 可传入 [Antd.Input](https://ant.design/components/input-cn/#Input) 原生属性 | object  | - |\n\n- textarea 多行文本框\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| props | 可传入 [Antd.Input.TextArea](https://ant.design/components/input-cn/#Input.TextArea) 原生属性 | object  | - |\n\n- select 选择器\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| options | 选项 | array: [{key: value}] | - |\n| props | 可传入 [Antd.Select](https://ant.design/components/select-cn/#Select-props) 原生属性 | object  | - |\n\n- datepicker  日期选择器\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| props | 可传入 [Antd.DatePicker](https://ant.design/components/date-picker-cn/#%E5%85%B1%E5%90%8C%E7%9A%84-API) 原生属性 | object | - |\n\n- checkbox 多选框\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| options | 选项 | array: [{key: value}] | - |\n| props | 可传入 [Antd.Checkbox.Group](https://ant.design/components/checkbox-cn/#Checkbox-Group) 原生属性 | object  | - |\n\n- radio 单选框\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| options | 选项 | array: [{key: value}] | - |\n| props | 可传入 [Antd.Radio.Group](https://ant.design/components/radio-cn/#RadioGroup) 原生属性 | object  | - |\n\n- switch 开关\n\n| 参数 | 说明 | 类型 | 默认值 |\n| ---- | ---- | ---- | ------ |\n| props | 可传入 [Antd.Switch](https://ant.design/components/switch-cn/#API) 原生属性 | object  | - |\n\n### props.formConfig.ajax 选项数据加载\n\n配置内部组件加载数据用到的ajax函数,需适配如下语法:\n  \n```js\nformConfig.ajax(url).then(data); // data 是转化后的最终数据,这些数据会被内部组件应用\n```\n\n- props.formData 表单初始值\n\n用于初始化表单默认值, `{key:value}` 格式。\n\n```js\n{\n    field_name: 'field_value',\n    // ...\n}\n```\n\n- props.onCreate(form) 表单回调函数\n\n\u003e 原理：在底层实现上，回调参数 `form` 为 `antd` `Form.create` 方法创建表单得到的实例对象\n  [this.props.form](https://ant.design/components/form-cn/#Form.create(options)) ，\n  本组件对其方法进行了扩展,以支持配置能力，扩展参数有：\n\n| 参数 | 说明 | 类型 |\n| ---- | ---- | ---- |\n| form.onValuesChange | 任一表单域的值发生改变时的回调，是对 `Form.create({onValuesChange})` 的封装，去掉第一个回调参数 | (changedValues, allValues) =\u003e void |\n| form.onFieldsChange | 当字段值（包括 error）发生改变时触发，是对 `Form.create({onFieldsChange})` 的封装，去掉第一个回调参数 | (changedFields, allFields) =\u003e void |\n| form.setFieldsVisible | 修改字段的可见性 | ({fieldname: visible:boolean `or` (current) =\u003e boolean})|\n| form.setFieldsDisabled | 修改字段的可编辑性 | ({fieldname: disabled:boolean `or` (current) =\u003e boolean})|\n| form.setFieldsRules | 修改字段的校验规则 | ({fieldname: rules:array `or` (current) =\u003e array}) |\n| form.setFieldsConfig | 批量修改字段的配置属性('type', 'name', 'remote', 'dependEvents' 不支持运行时修改) | ({[fieldName]: {[prop: newValue or (oldValue) =\u003e value  ]}})|\n\n### props.formContext 表单业务上下文数据\n\n- 上下文数据对象，可被表单内部组件访问，比如远程数据加载器，\n  根据配置的`remote.url`属性能够通过 `http://${context.userid}` 的方式动态填充 `props.formContext.userid` 数据。\n- 扩展字段内部访问，通过 `props.context`方式访问。\n\n## FAQ\n\n### 对于不支持的字段，如何快速扩展？\n\n提供方法 `plugin('field','fieldType', Component, options?:{initialValue? = ''})` 扩展字段，事实上内置字段也是通过该方法进行扩展的。\n\n扩展字段可访问组件内部的方法，并需要实现指定接口，比如内置 `input` 类型的实现如下：\n\n```js\n// ====== input.js ======\nimport React, { Component } from 'react';\nimport { Input } from 'antd';\n\nexport default class FieldInput extends Component {\n  render() {\n    // `this.props.config` 获取当前字段配置对象 \n    // `this.props.value`, `this.props.onChange` 实现数据双向绑定\n    // `this.props.form` 能够获取当前表单对象实例 ,从而向上与整个表单互动\n    // `this.props.context` 能够获取当前表单上下文数据对象  \n    let {\n      value, \n      onChange, \n      config: { label, disabled, placeholder, props } \n    } = this.props;\n\n    placeholder = placeholder || '请输入' + label;\n\n    const _props = {\n      disabled,\n      placeholder,\n      value,\n      onChange,\n      ...props\n    }\n\n    return (\n      \u003cInput {..._props}/\u003e\n    )\n  }\n}\n// ====== / input.js ======\n\n// ===== index.js ======\nimport React, { Component } from 'react';\nimport render from 'react-dom';\nimport Keform , { plugin } from 'ke-form';\nimport Input from './input.js';\n\n// 注册 input 类型\nplugin('field', 'input', Input, {\n  initialValue: '' // 默认值是空字符串，所以本例也可以不指定\n});\n\nexport default class App extends Component{\n  render () {\n    return  \u003cKeform formConfig={{fields: [{type: ‘input’, name: 'fristname'}]}}/\u003e\n  }\n}\n// ===== /index.js ======\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickzone%2Fke-form","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnickzone%2Fke-form","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnickzone%2Fke-form/lists"}