{"id":15782500,"url":"https://github.com/dpzxsm/taro-vform","last_synced_at":"2025-03-14T09:33:10.940Z","repository":{"id":184747457,"uuid":"637771167","full_name":"dpzxsm/taro-vform","owner":"dpzxsm","description":"一个基于Taro3.0的表单管理组件，轻量级。支持useForm，异步校验、表单复杂的联动","archived":false,"fork":false,"pushed_at":"2023-05-09T02:42:04.000Z","size":321,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-11T19:59:45.224Z","etag":null,"topics":["form","hooks","react","taro","taro3","useform"],"latest_commit_sha":null,"homepage":"","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/dpzxsm.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,"governance":null}},"created_at":"2023-05-08T11:26:35.000Z","updated_at":"2024-06-28T08:26:43.000Z","dependencies_parsed_at":"2023-07-30T02:47:07.135Z","dependency_job_id":null,"html_url":"https://github.com/dpzxsm/taro-vform","commit_stats":null,"previous_names":["dpzxsm/taro-vform"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpzxsm%2Ftaro-vform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpzxsm%2Ftaro-vform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpzxsm%2Ftaro-vform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dpzxsm%2Ftaro-vform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dpzxsm","download_url":"https://codeload.github.com/dpzxsm/taro-vform/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":221454674,"owners_count":16824684,"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":["form","hooks","react","taro","taro3","useform"],"created_at":"2024-10-04T19:07:53.982Z","updated_at":"2024-10-25T19:40:42.144Z","avatar_url":"https://github.com/dpzxsm.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# taro-vform [![npm version](https://badge.fury.io/js/taro-vform.svg)](https://badge.fury.io/js/taro-vform)\n\n这是一个基于 React 的表单库，专为 Taro 3.0 小程序开发而设计。它提供了一组易于使用的表单管理组件和hooks，以帮助您快速创建并管理表单。\n\n## 特性\n\n- 提供了一个通用的表单管理组件\n- 支持表单校验和错误提示\n- 支持自定义表单组件和校验规则\n- 支持表单数据双向绑定和动态表单\n- 支持表单数据源管理\n- 支持表单值、是否可见、数据源的联动\n- 支持各种第三方组件库，例如@nutui/nutui-react-taro taro-ui@3.0\n\n## 安装\n\n通过 npm 安装：\n\n```\nnpm install --save taro-vform\n```\n\n通过 yarn 安装：\n\n```\nyarn add taro-vform\n```\n\n## 注意\n如果taro配置中开启了webpack5 并且开启了prebundle，请关闭prebundle或者排除掉taro-vform\n```\ncompiler: {\n  type: 'webpack5',\n    prebundle: {\n    enable: true,\n      exclude: [\"taro-vform\"]\n  }\n}\n```\n\n## 简单使用\n\n导入组件\n\n```javascript\nimport VForm from 'taro-vform';\n\nconst VFormItem = VForm.Item;\n```\n\n在 render 方法中渲染表单：\n\n```javascript\n\u003cVForm onFinish={handleSubmit}\u003e\n  \u003cVFormItem name='name' label='姓名' required\u003e\n    \u003cInput/\u003e\n  \u003c/VFormItem\u003e\n  \u003cVFormItem name='phone' label='手机号' required\u003e\n    \u003cInput/\u003e\n  \u003c/VFormItem\u003e\n  \u003cButton type='primary' formType='submit'\u003e\n    提交\n  \u003c/Button\u003e\n\u003c/VForm\u003e\n```\n\n在 handleSubmit 方法中处理表单提交：\n\n```javascript\nfunction handleSubmit(values) {\n  console.log(data); // { name: '', phone: '' }\n  // 处理表单提交逻辑\n}\n```\n\n## 表单校验\n\n```javascript\n// 正则校验\n\u003cVFormItem name='phone' label='手机号' rules={[{ pattern: /^1[3456789]\\d{9}$/, message: '请输入正确的手机号' },]}\u003e\n  \u003cInput/\u003e\n\u003c/VFormItem\u003e\n\n// 长度校验\n\u003cVFormItem name='name' label='姓名' rules={[{ type: \"string\", max: 5, message: '最多只能填写5个字符' },]}\u003e\n  \u003cInput/\u003e\n\u003c/VFormItem\u003e\n```\n\n更多使用方法请求参考 [async-validator](https://github.com/yiminghe/async-validator)\n\n## 远程数据源\n\n```javascript\n\u003cVFormItem name='job' label='职业' remoteSource={{ url: \"/api/job/options\", formatResult: res =\u003e res }}\u003e\n  \u003cSelect/\u003e\n\u003c/VFormItem\u003e\n```\n\n## 表单联动\n\n```javascript\n\u003cVFormItem name='account' label='账号'\u003e\n  \u003cInput/\u003e\n\u003c/VFormItem\u003e\n\u003cVFormItem name='password' label='密码'\u003e\n  \u003cInput/\u003e\n\u003c/VFormItem\u003e\n// 当账号和密码都不为空时，才显示验证码的表单项\n\u003cVFormItem name='code' label='验证码'\n           dependency={{\n             visible: {\n               related: [\"account\", \"password\"],\n               get: (values) =\u003e !!(values.account \u0026\u0026 values.password)\n             }\n           }}\u003e\n  \u003cInput/\u003e\n\u003c/VFormItem\u003e\n```\n\n## 单个表单项维护多个字段\n```javascript\n\u003cVFormItem name={[\"startTime\", \"endTime\"]} label='时间范围'\u003e\n  \u003cDateRangePicker/\u003e\n\u003c/VFormItem\u003e\n```\n\n## 支持hooks\n```javascript\nconst form = Form.useForm();\n// 获取当前表单的值\nconst values = form.getFieldsValue();\n// 获取表单错误信息\nconst errors = form.getFieldsError();\n// 校验表单\nform.validateFields().then(values =\u003e {}).catch(errors =\u003e {});\n// 直接提交表单，如果没有使用button来提交表单，可以直接用这个函数来提交\nform.submit();\n\n```\n\n## VForm\n\n| Prop 名称          | 类型          | 描述                                                                   | 默认值   |\n|------------------|-------------|----------------------------------------------------------------------|-------|\n| `children`       | `ReactNode` | 包含表单项的任意react元素                                                      | 无     |\n| `colon`          | `bool`      | 是否在表单项标签后面显示冒号。                                                      | false |\n| `form`           | `any`       | 您可以通过该属性传递表单实例，并使用它的方法来控制表单，通过Form.useFrom可以创建form实例，不传递则使用默认的form实例 | -     |\n| `initialValues`  | `any`       | 表单的初始值。可以是一个普通对象或一个返回普通对象的函数。                                        | -     |\n| `onFinish`       | `func`      | 当表单提交成功后触发的回调函数。                                                     | -     |\n| `onFinishFailed` | `func`      | 当表单提交失败后触发的回调函数。                                                     | -     |\n| `onReset`        | `any`       | 当表单重置时触发的回调函数。可以是一个函数或一个返回函数的函数。                                     | -     |\n| `onValuesChange` | `function`  | 当表单项的值发生变化时触发的回调函数。                                                  | -     |\n\n## VForm.Item\n\n| 属性名                | 类型                                        | 描述                                                                         | 默认值      |\n|--------------------|-------------------------------------------|----------------------------------------------------------------------------|----------|\n| `children`         | `ReactNode\\|func`                         | 表单组件或者一个函数返回一个表单组件，函数可以返回null                                              | 无        |\n| `colon`            | `bool`                                    | 是否在表单项标签后面显示冒号。                                                            | `false`  |\n| `dependency`       | Record\u003cString, [Dependency](#Dependency)\u003e | 表单项的依赖关系。可以包含 `source`、`value` 和 `visible` 三个属性                            | 无        |\n| `hideLabel`        | `bool`                                    | 是否隐藏表单项的标签。                                                                | `false`  |\n| `initialSource`    | `array`                                   | 表单项的初始源数据。                                                                 | `[]`     |\n| `initialValue`     | `any`                                     | 表单项的初始值。                                                                   | 无        |\n| `initialVisible`   | `bool`                                    | 表单项的初始可见状态。                                                                | `true`   |\n| `inlineLabel`      | `bool`                                    | 是否将表单项的标签和控件放在同一行。                                                         | `false`  |\n| `label`            | `any`                                     | 表单项的标签。                                                                    | 无        |\n| `name`             | `strring\\|array`                          | 表单项的名称，可以为数组，如果是数组，则表示该表单项有多个字段                                            | 无        |\n| `remoteSource`     | [RemoteSource](#RemoteSource)             | 表单项的远程数据源。                                                                 | 无        |\n| `remoteSourceDeps` | `array\\|function`                         | 表示远程数据源的依赖项。可以是一个函数或一个数组, 依赖项变化时会触发数据源更新                                   | 无        |\n| `required`         | `bool`                                    | 表单项是否必填，相当于 rules=[{ required: true }] 的简洁写法                               | 无        |\n| `rules`            | `array`                                   | 表单项的验证规则，参考 [async-validator](https://github.com/yiminghe/async-validator) | `[]`     |\n| `valuePropName`    | `string`                                  | 表单项的值属性名称。                                                                 | `value`  |\n| `sourcePropName`   | `string`                                  | 表单项的源数据属性名称。                                                               | `source` |\n\n## Dependency\n\n| 属性名     | 类型         | 描述                       |\n|---------|------------|--------------------------|\n| related | `arrary`   | 表单依赖的值，如果表单值变化，则会触发get函数 |\n| get     | `function` | 返回相应依赖属性的值，参数是表单的当前值     |\n\n## RemoteSource\n\n请求接口默认使用Taro.request，支持Taro.request的所有参数，如果需要适配自己封装的请求方法或者是其他第三方请求库，参考[此处](#VFormregisterCustomRequest)\n\n| 属性名          | 类型       | 描述        |\n|--------------|----------|-----------|\n| url          | `string` | 服务器接口地址   |\n| data         | `object` | 请求的参数     |\n| method       | `string` | HTTP 请求方法 |\n| formatResult | `method` | 数据源格式化函数  |\n\n## VForm.useForm\n\n| 属性名               | 类型         | 描述                |\n|-------------------|------------|-------------------|\n| errors            | `object`   | 一个包含表单每个字段错误信息的对象 |\n| errorsArr         | `array`    | 所有错误信息的数组         |\n| values            | `object`   | 一个包含表单每个字段值的对象    |\n| resetFields       | `function` | 重置表单所有字段的值和状态     |\n| validateFields    | `function` | 验证表单所有字段          |\n| getFieldDecorator | `function` | 生成一个表单项的装饰器函数     |\n| setFieldValue     | `function` | 设置某个表单项的值         |\n| setFieldsValue    | `function` | 批量设置表单项的值         |\n| setFieldSource    | `function` | 设置某个表单项的数据源       |\n| setFieldVisible   | `function` | 设置某个表单项的可见性       |\n| getFieldsValue    | `function` | 获取所有表单项的值         |\n| getFieldValue     | `function` | 获取某个表单项的值         |\n| getFieldSource    | `function` | 获取某个表单项的数据源       |\n| getFieldVisible   | `function` | 获取某个表单项的可见性       |\n| getFieldsError    | `function` | 获取所有表单项的错误信息      |\n| getFieldError     | `function` | 获取某个表单项的错误信息      |\n| setFields         | `function` | 批量设置表单项的值和状态      |\n| isFieldTouched    | `function` | 判断某个表单项是否被触碰过     |\n| isFieldsTouched   | `function` | 判断所有表单项是否被触碰过     |\n| submit            | `function` | 直接提交表单            |\n\n## VForm.registerCustomRequest\n\n```javascript\nimport VForm from 'taro-vform';\n\nfunction customRequest(options) {\n    // 必须返回一个promise对象\n    return new Promise((resolve, reject) =\u003e {\n    })\n}\n\nVForm.registerCustomRequest(customRequest)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpzxsm%2Ftaro-vform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdpzxsm%2Ftaro-vform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdpzxsm%2Ftaro-vform/lists"}