# mui-form-hook

**Repository Path**: luoanb/mui-form-hook

## Basic Information

- **Project Name**: mui-form-hook
- **Description**: mui & react-form-hook 
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-05-17
- **Last Updated**: 2023-02-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CLI

Turborepo starter with **pnpm**

This is an official starter turborepo.

# Apps and Packages

- `mui-form-hook`: 基于 mui 和 react-form-hook 的自定义 hook
- `web`: the Test of mui-form-hook
- `ui`: nothing
- `docs`: nothing
- `eslint-config-base`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`)
- `tsconfig`: `tsconfig.json`s used throughout the monorepo

# PeerDependencies

请确保您的代码仓库中已经存在以下依赖

```JSON
"peerDependencies": {
  "@types/react": "^17.0.0 || ^18.0.0",
  "react": "^17.0.0 || ^18.0.0",
  "react-dom": "^17.0.0 || ^18.0.0",
  "react-hook-form": "^7.30.0",
  "@mui/icons-material": "^5.4.2",
  "@mui/material": "^5.4.2",
  "@mui/x-data-grid": "^5.8.0"
},
```

# Useage 使用

- Download 下载

```
  yarn add @ztech/mui-form
```

- Example 示例

```jsx
import React from 'react'
import { Button } from '@mui/material'
import { useFormComponent } from '@ztech/mui-form/packages/mui-form-hook/react'


/** 类型声明 */
export interface NChangeWardBedInput {
  wardBedId?: string | undefined
  changeTime?: Date
  iHid?: string | undefined
}

/** 获取默认表单值 */
export const getDefaultFormData = () =>
  ({
    /** 转入床位Id */
    wardBedId: '',
    /** 换床时间 */
    changeTime: new Date(),
    /** 住院信息id */
    iHid: ''
  } as NChangeWardBedInput)

export const Test = () => {
  // 创建表单及其相关组件和api(和 useForm入参相同)
  const { FormText, handleSubmit } = useFormComponent<NChangeWardBedInput>({
    // 设置默认值
    defaultValues: getDefaultFormData()
  })
  return (
    <div>
      <FormText
        name="iHid" // 绑定表单属性
        variant="outlined" // TextField 样式继承
        rules={{ required: '请输入' }} // 定义验证规则
      />
      <FormText
        name="wardBedId"
        variant="outlined"
        rules={{ required: '请输入' }}
      />
      <Button
        // 在这里提交表单 handleSubmit和react-form-hook保持一致
        // 事实上 useFormComponent完全继承了useForm的api
        onClick={handleSubmit((data) => console.log(data))}
      >
        提交
      </Button>
    </div>
  )
}
```

# Develop 开发

@mui-form/hook 提供了开发的方法让开发者可以进行二次开发，便于丰富 Form 的组件。

- 其他表单组件如果需集成的 useFormComponent 中，需要实现 useFormComponent 规定的参数，具体参数属性如下：

  ```ts
  /** Form表单组件入参基本参数
   * @param TValue 组件绑定的数据类型
   */
  export type IFormComponentPropsBase<TValue = any, TItem = null> = {
    /** 错误状态 */
    error?: boolean;
    /** 组件下提示文本 */
    helperText?: string | JSX.Element;
    /** 组件内提示 */
    label?: string | JSX.Element;
    /** 表单值 */
    value?: TValue;
    /** 更新值 */
    onChange?: IChange<TValue>;
    /** 用于Select同时绑定多个Form属性
     * @description 如果需要使用otherNames属性绑定多个属性, 请实现该方法
     */
    onItemChange?: IChange<TItem>;
  };
  ```

- 开发流程

1. 定义组件参数 建议用类型 *IFormComponentProps*处理组件入参，它规定了上述规范的参数，同时继承用户自定义的参数。

   ```ts
   // IFormComponentProps需要三个泛型参数
   // <TProps> 自定义组件参数
   // <TV> value的类型
   // <TI> item的类型 (下拉选择框等的单项数据类型)
   export type IMyNewComponetProps<TV = any, TI = any> = IFormComponentProps<
     MuiComponetProps,
     TV,
     TI
   >;
   ```

2. 实现组件
   ```jsx
   const MyNewComponet = ({...props}:IMyNewComponetProps)=>{
     // ... 具体的实现内容
     return (
       <MuiComponet
         {...props}
       >)
   }
   ```
   可以参考 [组件源码](./components/)
3. 把组件附加到 useFormComponent 中,使用**withControllerFields**
   ```jsx
   const { formProps } = useFormComponent({
     defaultValues: getDefaultFormDat(),
   });
   const FormComponent = withControllerFields(MyNewComponet, { formProps });
   ```

# API 接口参数介绍

详细介绍了库提供的相关组件和 hook

## HOOK

### useFormComponent 主 hook

### withControllerFields 注入 Controller 工具

## BaseComponent 基础组件

- BaseComponent 都需要实现以下通用属性，这是表单组件需要的通用实现：

```ts
/** Form表单组件入参基本参数
 * @param TValue 组件绑定的数据类型
 */
export type IFormComponentPropsBase<TValue = any, TItem = null> = {
  /** 错误状态 */
  error?: boolean;
  /** 组件下提示文本 */
  helperText?: string | JSX.Element;
  /** 组件内提示 */
  label?: string | JSX.Element;
  /** 表单值 */
  value?: TValue;
  /** 更新值 */
  onChange?: IChange<TValue>;
  /** 用于Select同时绑定多个Form属性
   * @description 如果需要使用otherNames属性绑定多个属性, 请实现该方法
   */
  onItemChange?: IChange<TItem>;
};
```

### BaseFormSearch 搜索(可用于表单)

### BaseSelect 选择框

### MuiFormSearch 搜索(受控)

### BaseFormCheckbox 复选框

### BaseFormSwitch 开关

### Region 地区选择

## FormComponent 表单组件

- 表单组件由 **useFormComponent 方法** 方法返回；
- 表单组件继承自基础组件(**BaseComponent**)，所以拥有对应的 BaseComponent 的相关所有属性；
- 表单组件继承 react-hook-form 的**Controller**，所以拥有 Controller 组件的所有属性;

```typescript
{
    name: TName;
    rules?: Omit<RegisterOptions<TFieldValues, TName>, 'valueAsNumber' | 'valueAsDate' | 'setValueAs' | 'disabled'>;
    shouldUnregister?: boolean;
    defaultValue?: UnpackNestedValue<FieldPathValue<TFieldValues, TName>>;
    control?: Control<TFieldValues>;
}
```

- 表单组件其他附加属性

```typescript
{
    /** 默认错误提示 */
    defaultErrorMessage?: string | JSX.Element
    /** 同时绑定多个Form属性
      * @description 如果需要使用otherNames属性绑定多个属性, 请在原始组件中实现onItemChange方法
      */
    otherNames?: {[itemProperty]:formName}
  }
```

- 表单组件内部已经托管属性: error,helperText,value,onChange,control；这些属性无须重新赋值，但开发者显示赋值将覆盖托管值

### FormText

请参考@mui/material/TextField

### FormSelect

请参考 BaseSelect

### FormSearch

请参考 MuiFormSearch

### FormCheckbox

请参考 BaseFormCheckbox

### FormSwitch

请参考 BaseFormSwitch

### FormRegion

请参考 Region

## OtherComponent 其他组件

一些基础组件

### DropDownInput 输入下拉基础组件

### MuiDataGrid DataGrid

### MuiSearch 搜索(非受控)

### MuiDialog MUI 弹窗（二次封装）

---

> 参数说明

|   参数名    | 是否必填 |                类型                | 默认值 | 描述                                                                                           |
| :---------: | :------: | :--------------------------------: | :----: | :--------------------------------------------------------------------------------------------- |
|    open     |   true   |              boolean               |        | 控制弹窗的打开状态                                                                             |
| handleClose |   true   |              Function              |        | 当组件请求关闭时触发回调,function(event: object, reason: string) => void event：回调的事件源。 |
|   scroll    |  false   |            `body paper`            | paper  | 确定滚动对话框的容器。                                                                         |
|  maxWidth   |  false   |       `xs sm md lg xl false`       | false  | 确定对话框的最大宽度。对话框宽度随着屏幕的大小而增加。设置为 false 禁用 maxWidth。             |
| titleColor  |  false   |           `white green`            | white  | 弹窗标题的背景色                                                                               |
|    title    |  false   |      `string React.ReactNode`      |        | 弹窗的标题展示                                                                                 |
|  children   |  false   |          React.ReactNode           |        | 弹窗 Content 区域内容填充                                                                      |
| actionsList |  false   | `React.ReactNode[] ButtonProps[] ` |        | 弹窗 Actions 区域内容填充                                                                      |

---

> 使用说明

---

- 使用 import 引入即可

```
  import { MuiDialog } from '@ztech/mui-form/packages/mui-form-hook/react'
```

- 具体使用方法

```jsx
const [isOpen, SETisOpen] = useState(false);

// 弹窗标题 组件形式加入
const CustomTitle = () => {
  return <div>这是弹窗标题</div>;
};

// 组件形式
const actionList: React.ReactNode[] = [
  <Button
    size="small"
    variant="outlined"
    onClick={() => {
      console.log("取消");
      SETisOpen(false);
    }}
  >
    取消
  </Button>,
  <Button size="small" variant="contained">
    确定
  </Button>,
];
// 对象数据形式
const actionList2: ButtonProps[] = [
  { size: "small", variant: "outlined", children: "取消" },
  {
    size: "small",
    variant: "contained",
    children: "确定",
    onClick: () => {
      console.log("确定");
      SETisOpen(false);
    },
  },
];

// children组件作为 Content 内容填充
const ContentFill = () => {
  return <div>这是children组件作为 Content 内容填充</div>;
};

/** 
    <UseDialog 
      open={isOpen} 
      handleClose={() => SETisOpen(false)}
      scroll='body'
      maxWidth='md'
      titleColor='white'
      // title='弹窗标题'
      title={<CustomTitle />}
      //actionsList={actionList}
      actionsList={actionList2}
      children={<ContentFill />}
    />
  */

//  或

<UseDialog
  open={isOpen}
  handleClose={() => SETisOpen(false)}
  scroll="body"
  maxWidth="md"
  titleColor="white"
  // title='弹窗标题'
  title={<CustomTitle />}
  //actionsList={actionList}
  actionsList={actionList2}
>
  <ContentFill />
</UseDialog>;
```