{"id":21195618,"url":"https://github.com/qiqiboy/react-mui-formutil","last_synced_at":"2026-04-06T03:03:41.367Z","repository":{"id":57334374,"uuid":"146723522","full_name":"qiqiboy/react-mui-formutil","owner":"qiqiboy","description":"Happy to use react-formutil in the project based on @mui/material ^_^ ","archived":false,"fork":false,"pushed_at":"2025-03-07T02:51:59.000Z","size":1254,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-06T16:48:48.477Z","etag":null,"topics":["javascript","material-ui","react","react-component","react-form","react-formutil","react-library"],"latest_commit_sha":null,"homepage":"http://github.boy.im/react-mui-formutil/demo/","language":"TypeScript","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/qiqiboy.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-30T08:59:10.000Z","updated_at":"2025-03-07T02:52:03.000Z","dependencies_parsed_at":"2025-03-19T02:47:37.865Z","dependency_job_id":null,"html_url":"https://github.com/qiqiboy/react-mui-formutil","commit_stats":{"total_commits":23,"total_committers":3,"mean_commits":7.666666666666667,"dds":0.4782608695652174,"last_synced_commit":"68fee7222bce7c0cb11f584947be3fd7977d5765"},"previous_names":["qiqiboy/react-material-formutil"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Freact-mui-formutil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Freact-mui-formutil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Freact-mui-formutil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qiqiboy%2Freact-mui-formutil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qiqiboy","download_url":"https://codeload.github.com/qiqiboy/react-mui-formutil/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248766687,"owners_count":21158302,"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":["javascript","material-ui","react","react-component","react-form","react-formutil","react-library"],"created_at":"2024-11-20T19:29:14.879Z","updated_at":"2026-04-06T03:03:36.343Z","avatar_url":"https://github.com/qiqiboy.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# react-mui-formutil\n\n[![npm](https://img.shields.io/npm/v/react-mui-formutil.svg?style=flat)](https://npm.im/react-mui-formutil)\n[![peerDependencies](https://img.shields.io/npm/dependency-version/react-mui-formutil/peer/react.svg?color=yellowgreen)](https://reactjs.org)\n[![definitionTypes](https://img.shields.io/npm/types/react-mui-formutil.svg)](https://github.com/qiqiboy/react-mui-formutil/blob/master/index.d.ts)\n[![gzip](https://img.shields.io/bundlephobia/minzip/react-mui-formutil.svg)](https://npm.im/react-mui-formutil)\n[![download](https://img.shields.io/npm/dm/react-mui-formutil.svg)](https://npm.im/react-mui-formutil)\n[![issues](https://img.shields.io/github/issues/qiqiboy/react-mui-formutil.svg)](https://github.com/qiqiboy/react-mui-formutil/issues)\n[![license](https://img.shields.io/github/license/qiqiboy/react-mui-formutil.svg)](https://github.com/qiqiboy/react-mui-formutil/blob/master/LICENSE)\n[![github](https://img.shields.io/github/last-commit/qiqiboy/react-mui-formutil.svg)](https://github.com/qiqiboy/react-mui-formutil)\n[![github](https://img.shields.io/github/release-date/qiqiboy/react-mui-formutil.svg)](https://github.com/qiqiboy/react-mui-formutil/releases)\n[![github](https://img.shields.io/github/commit-activity/m/qiqiboy/react-mui-formutil.svg)](https://github.com/qiqiboy/react-mui-formutil/commits/master)\n[![github](https://img.shields.io/github/stars/qiqiboy/react-mui-formutil.svg?style=social)](https://github.com/qiqiboy/react-mui-formutil)\n\nHappy to use react-formutil in the project based on `@mui/material` ^\\_^\n\n在 [@mui/material](https://github.com/mui-org/@mui/material) 项目，结合[react-formutil](https://github.com/qiqiboy/react-formutil) 来快速构建表单。\n\n\u003e **如果你在使用其他 react-组件库，可以查阅：**\n\u003e\n\u003e 1. ant-design [`react-antd-formutil`](https://github.com/qiqiboy/react-antd-formutil) [![npm](https://img.shields.io/npm/v/react-antd-formutil.svg?style=flat)](https://npm.im/react-antd-formutil)\n\u003e 1. react-bootstrap [`react-bootstrap-formutil`](https://github.com/qiqiboy/react-bootstrap-formutil) [![npm](https://img.shields.io/npm/v/react-bootstrap-formutil.svg?style=flat)](https://npm.im/react-bootstrap-formutil)\n\u003e 1. react-md [`react-md-formutil`](https://github.com/qiqiboy/react-md-formutil) [![npm](https://img.shields.io/npm/v/react-md-formutil.svg?style=flat)](https://npm.im/react-md-formutil)\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n- [安装 Installation](#安装-installation)\n- [使用 Usage](#使用-usage)\n    + [`\u003cFormControl /\u003e`](#formcontrol-)\n        * [`name`](#name)\n        * [`label`](#label)\n        * [`helperText`](#helpertext)\n        * [`noStyle`](#nostyle)\n        * [`$defaultValue`](#defaultvalue)\n        * [`$validators`](#validators)\n        * [`$parser`](#parser)\n        * [`$formatter`](#formatter)\n        * [`checked` `unchecked`](#checked-unchecked)\n        * [`validMessage`](#validmessage)\n        * [`$validateLazy`](#validatelazy)\n        * [`valuePropName` `changePropName` `focusPropName` `blurPropName`](#valuepropname-changepropname-focuspropname-blurpropname)\n        * [`getValueFromEvent`](#getvaluefromevent)\n        * [`errorLevel`](#errorlevel)\n    + [`\u003cCheckboxGroup /\u003e`](#checkboxgroup-)\n    + [`setErrorLevel(level)`](#seterrorlevellevel)\n    + [`支持的组件`](#支持的组件)\n        * [`Autocomplete`](#autocomplete)\n        * [`Checkbox`](#checkbox)\n        * [`Radio button`](#radio-button)\n        * [`Rating`](#rating)\n        * [`Select`](#select)\n        * [`Slider`](#slider)\n        * [`Switch`](#switch)\n        * [`TextField`](#textfield)\n        * [`ToggleButton`](#togglebutton)\n        * [`Date/Time pickers`](#datetime-pickers)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n### 安装 Installation\n\n[![react-mui-formutil](https://nodei.co/npm/react-mui-formutil.png?compact=true)](https://npm.im/react-mui-formutil)\n\n```bash\n# npm\nnpm install react-mui-formutil --save\n\n# yarn\nyarn install react-mui-formutil\n```\n\n### 使用 Usage\n\n\u003e `react-material-formutil` 整合了 `react-formutil` 的组件，所以可以直接从`react-material-formutil`中导出所需要的\n\u003e `react-formutil` 组件。不用单独从 `react-formutil` 中导出。\n\n```typescript\nimport React, { Component } from 'react';\nimport { withForm, FormControl, $Formutil } from 'react-mui-formutil';\nimport { Box, TextField } from '@mui/material'; // 导入mui的TextField组件\n\ninterface MyFormProps {\n    $formutil: $Formutil;\n}\nconst MyForm: React.FC = () =\u003e {\n    const onSubmit = ev =\u003e {\n        ev.preventDefault();\n\n        // ...\n    };\n\n    return (\n        \u003cBox component=\"form\" noValidate onSubmit={onSubmit}\u003e\n            \u003cFormControl label=\"Username\" name=\"username\" fullWidth\u003e\n                \u003cTextField /\u003e\n            \u003c/FormControl\u003e\n\n            \u003cButton fullWidth type=\"submit\"\u003e\n                submit\n            \u003c/Button\u003e\n        \u003c/Box\u003e\n    );\n};\n\nexport default withForm(MyForm);\n```\n\n`FormControl`是 `react-mui-formuitl` 中提供的用于标单项交互的组件，`withForm`是`react-formutil`的组件（没错，你可以直接从`react-material-formutil`中导出`react-formutil`的组件啦）。\n\n只需要将`@mui/material`的表单类组件，嵌套在`FormControl`下，即可实现自动的表单状态同步。\n\n#### `\u003cFormControl /\u003e`\n\n要实现将`@mui/material`的表单组件的值能同步到 `react-formutil` 的状态中，需要通过 `FormControl` 这个组件来实现中间态绑定。\n\n`FormControl`类似`@mui/material`中的同名组件，但是它基于`react-formutil`实现了表单状态的收集与同步。你应当在`react-formutil`表单中总是使用这个新的`FormControl`。\n\n\u003e `FormControl`下只允许放置一个表单组件，不允许多个。\n\n##### `name`\n\n设置输入项的 name 值，表单项将会以 name 作为 key 收集到 formutil 的状态中。支持嵌套语法 _（同`react-formutil`的`Field`同名参数，可以参考 [name](https://github.com/qiqiboy/react-formutil#name)）_\n\n##### `label`\n\n设置 label，你也可以传入`Typography`或者其他节点对象以实现 label 样式自定义。\n\n```typescript\n\u003cFormControl name=\"name\" label=\"Username\"\u003e\n    \u003cTextField /\u003e\n\u003c/FormControl\u003e\n\n// 如果要自定义label的样式，可以这样：\n\u003cFormControl name=\"name\" label={\u003cTypography variant=\"h5\" sx={{ mb:1 }}\u003eUsername\u003c/Typography\u003e}\u003e\n    \u003cTextField /\u003e\n\u003c/FormControl\u003e\n```\n\n##### `helperText`\n\n设置 `helperText`，你也可以直接传递各类节点对象以实现样式自定义。\n\n```typescript\n\u003cFormControl name=\"name\" helperText=\"Please type your name\"\u003e\n    \u003cTextField /\u003e\n\u003c/FormControl\u003e\n\n//or\n\n\u003cFormControl name=\"name\" helperText={\u003cBox component=\"span\" sx={{ fontWeight: 700 }}\u003ePlease type your name\u003c/Box\u003e}\u003e\n    \u003cTextField /\u003e\n\u003c/FormControl\u003e\n```\n\n##### `noStyle`\n\n`noStyle`可以用来控制是否输出`FormControl`的额外的样式元素。缺省情况下默认值为`false`。这在一些需要组合使用的场景下非常有用！\n\n当`noStyle`为`true`时，将会只渲染字段节点本身，但是其表单状态依然会被处理收集。此时，如果其存在父级嵌套的`FormControl`，那么其表达校验状态将会传递给父级的`FormControl`来展现。\n\n这对于连续的紧凑型表单元素将非常有用！可以避免校验错误描述信息都堆叠在一起! **但是没有额外的样式显示，包括表单校验状态都无法显示了。此时可以在其外层包裹一层不带`name`的`FormGroup`，这些`noStyle`的表单项就会把他们自身的状态向上进行注册显示了！**\n\n但是有以下几点需要注意：\n\n1. 最外层的`FormControl`不能设置`name`属性，否则将不会被当作子级的校验状态容器\n2. 内层的`FormControl`需要添加相应的`name`值（向表单控制器注册自身）以及`noStyle`属性（不渲染额外的样式，避免和上层冲突）\n\n```typescript\n// 这里不能设置name\n\u003cFormControl label=\"姓名\"\u003e\n    \u003cGrid container spacing={2}\u003e\n        {/* 与普通的FormControl用法一致，只是多了个noStyle */}\n        \u003cGrid item xs={6}\u003e\n            \u003cFormGroup name=\"first_name\" required validMessage={{ required: 'First name reuqired!' }} noStyle\u003e\n                \u003cTextField label=\"姓\" /\u003e\n            \u003c/FormGroup\u003e\n        \u003c/Grid\u003e\n        \u003cGrid item xs={6}\u003e\n            \u003cFormGroup name=\"last_name\" required validMessage={{ required: 'Last name reuqired!' }} noStyle\u003e\n                \u003cTextField label=\"名\" /\u003e\n            \u003c/FormGroup\u003e\n        \u003c/Grid\u003e\n    \u003c/Grid\u003e\n\u003c/FormControl\u003e\n```\n\n以上运行示例请参考 [示例 demo4](http://github.boy.im/react-mui-formutil/demo/)\n\n##### `$defaultValue`\n\n设置该表单项的默认值 _（同`react-formutil`的`Field`同名参数，可以参考[$defaultvalue](https://github.com/qiqiboy/react-formutil#defaultvalue)）_\n\n##### `$validators`\n\n设置校验方法 _（同`react-formutil`的`Field`同名参数 , 可以参考\n[$validators](https://github.com/qiqiboy/react-formutil#validators)）_\n\n\u003e 同 react-formutil 的 EasyField，FormControl 也内置了同样的校验规则：\n\n\u003e -   `required` 必填 `required`\n\u003e -   `maxLength` 。最大输入长度，有效输入时才会校验 `maxLength=\"100\"`\n\u003e -   `minLength` 最小输入长度，有效输入时才会校验 `minLength=\"10\"`\n\u003e -   `max` 最大输入数值，仅支持 Number 比较。有效输入时才会校验 `max=\"100\"`\n\u003e -   `min` 最小输入数值，仅支持 Number 比较。有效输入时才会校验 `min=\"10\"`\n\u003e -   `pattern` 正则匹配。有效输入时才会校验 `pattern={/^\\d+$/}`\n\u003e -   `enum` 枚举值检测。有效输入时才会校验 `enum={[1,2,3]}`\n\u003e -   `checker` 自定义校验函数。`checker={value =\u003e value \u003e 10 \u0026\u0026 value \u003c 100 || ' 输入比如大于 10 小与 100'}`\n\n注：校验属性的值为 `null` 时表示不进行该校验\n\n内置的校验规则无需再次声明，除非规则不符合预期，需要替换，则可以通过`$validators` 传递同名校验方法即可替换默认的。另外，内置的校验规则，如果校验不通过，会尝试去 `validMessage` 匹配错误信息。\n\n##### `$parser`\n\n设置输入的值收集到 formutil 状态中时的过滤处理。默认为`value =\u003e value`\n\n```javascript\n\u003cFormControl $parser={value =\u003e parseInt(value)}\u003e\n    \u003cInput /\u003e\n\u003c/FormControl\u003e\n```\n\n##### `$formatter`\n\n设置 formutil 中的值渲染到输入组件上时的过滤处理。默认为`value =\u003e value`\n\n```javascript\n\u003cFormControl $formatter={value =\u003e '$' + value}\u003e\n    \u003cInput /\u003e\n\u003c/FormControl\u003e\n```\n\n##### `checked` `unchecked`\n\n对于 `\u003cSwitch /\u003e` `\u003cCheckbox /\u003e` `\u003cRadio /\u003e` 这三种组件，其值默认是 checked 属性，为布尔值。可以通过`checked`\n`unchecked`来设置 checked 状态时所要映射的值：\n\n```javascript\n\u003cFormControl checked=\"yes\" unchecked=\"no\"\u003e\n    \u003cSwitch /\u003e\n\u003c/FormControl\u003e\n```\n\n该示例中， 当 Switch 为开时，获取的值将为 yes。\n\n##### `validMessage`\n\n设置校验结果的错误信息。\n\n```javascript\n\u003cFormControl\n    name=\"username\"\n    required\n    validMessage={{\n        required: '请输入用户名'\n    }}\u003e\n    \u003cInput /\u003e\n\u003c/FormControl\u003e\n```\n\n##### `$validateLazy`\n\n可以用来优化表单的校验速度，请参考： [`$validateLazy`](https://github.com/qiqiboy/react-formutil#validatelazy)\n\n##### `valuePropName` `changePropName` `focusPropName` `blurPropName`\n\n该四个参数可以用来设置绑定到组件上的值或者值变动、是否聚焦等事件回调。该项一般不需要设置，`FormControl` 已经针对 `@mui/material`\n中的所有 `data-entry` 型组件做了兼容处理。\n\n对于一些特殊场景，例如不需要同步 `focus`、`blur`，则可以通过将该值设为`{null}`来禁用：\n\n```javascript\n//禁用focus、blur状态同步\n\u003cFormControl focusPropName={null} blurPropName={null} name=\"username\"\u003e\n    \u003cInput /\u003e\n\u003c/FormControl\u003e\n```\n\n##### `getValueFromEvent`\n\n请参考 [`getValueFromEvent()`](https://github.com/qiqiboy/react-formutil/blob/master/README.md#getvaluefromevent)\n\n##### `errorLevel`\n\n用来覆盖全局的 errorLevel 设置。参考[`setErrorLevel(level)`](#seterrorlevellevel)\n\n#### `\u003cCheckboxGroup /\u003e`\n\n`@mu/material` 提供了`RadioGroup`组件，但是却并没有提供相应的`CheckboxGroup`。所以，它来了。\n\n```javascript\n\u003cFormControl name=\"checkboxgroup\" required label=\"Checkbox group\"\u003e\n    \u003cCheckboxGroup\u003e\n        \u003cFormControlLabel value=\"apple\" control={\u003cCheckbox /\u003e} label=\"Apple\" /\u003e\n        \u003cFormControlLabel value=\"peach\" control={\u003cCheckbox /\u003e} label=\"Peach\" /\u003e\n    \u003c/CheckboxGroup\u003e\n\u003c/FormControl\u003e\n```\n\n#### `setErrorLevel(level)`\n\n`setErrorLevel` 该方法可以用来全局设置错误信息何时出现，有三个级别可以设置：\n\n-   `0` 当`$dirty` `$touched` `invalid` 都为 true 时\n-   `1` 当`$dirty` `invalid` 都为 true 时\n-   `2` 当`invalid` 为 true 时\n\n默认值为 `1`\n\n```javascript\nimport { setErrorLevel } from 'react-antd-formutil';\n\nsetErrorLevel(0);\n```\n\n#### `支持的组件`\n\n##### [`Autocomplete`](https://mui.com/zh/material-ui/react-autocomplete/)\n\n##### [`Checkbox`](https://mui.com/zh/material-ui/react-checkbox/)\n\n##### [`Radio button`](https://mui.com/zh/material-ui/react-radio-button/)\n\n##### [`Rating`](https://mui.com/zh/material-ui/react-rating/)\n\n##### [`Select`](https://mui.com/zh/material-ui/react-select/)\n\n##### [`Slider`](https://mui.com/zh/material-ui/react-slider/)\n\n##### [`Switch`](https://mui.com/zh/material-ui/react-switch/)\n\n##### [`TextField`](https://mui.com/zh/material-ui/react-text-field/)\n\n##### [`ToggleButton`](https://mui.com/zh/material-ui/react-toggle-button/)\n\n##### [`Date/Time pickers`](https://mui.com/zh/x/react-date-pickers/getting-started/)\n\n需要注意的是，日期、时间选择器组件的`value`和`onChange`的 ts 类型声明为必须，但是实际在配合`react-mui-formutil`使用时是无需指定的。为了避免报错，可以指定最小空值即可:\n\n```typescript\n\u003cFormControl name=\"datepicker.datepicker\" required fullWidth sx={{ mb: 2 }}\u003e\n    \u003cDatePicker value={null} onChange={() =\u003e {}} label=\"DatePicker\" renderInput={params =\u003e \u003cTextField {...params} /\u003e} /\u003e\n\u003c/FormControl\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqiqiboy%2Freact-mui-formutil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqiqiboy%2Freact-mui-formutil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqiqiboy%2Freact-mui-formutil/lists"}