Form

Form 기본 컨셉

mint-ui 에서의 form 처리는 기본적으로 양방향 데이터 바인딩을 지원하기 위해 만들어졌습니다.

Form 에 data object 를 바인딩하면 사용자입력이 별도의 처리없이 자동으로 data 에 반영됩니다.

export function FormBasic(){

  const [data, setData] = useState({
    aaa:'a',
    bbb:'b',
  })

  return <Frame>
    <div>data.aaa = {data.aaa}</div>
    <div>data.bbb = {data.bbb}</div>
    <div>---------------------</div>
    <Form data={data} setData={setData}>
      <Flex flexGap="10px">
        <span>aaa : <Input targetId='aaa' /></span> {/* data.aaa 와 바인딩 */}
        <span>bbb : <Input targetId='bbb' /></span> {/* data.bbb 와 바인딩 */}
      </Flex>
    </Form>
  </Frame>
}

Form 컴포넌트 하위에 Input 과 같은 form 요소가 존재하면 내부적으로 Context API 로 처리되기 때문에 children 의 어느 위치에 있어도 바인딩이 가능합니다.

속성 설명

data

data = T

form 과 바인딩할 object 타입의 state 객체입니다. data 에 있는 값을 기반으로 form 요소에 표시되고, 또 사용자입력이 data 를 업데이트 시킵니다.

(optional) setData

setData = (data:T)=>void

data state 를 업데이트 하는 함수입니다.
이 함수가 제공되지 않으면 사용자입력이 data 를 업데이트 하지 못합니다.

(optional) formId

formId?:string;

Form 컴포넌트 내부의 form 엘리멘트의 id 값입니다. 이 값을 기준으로 formId 기반 로직이 동작합니다.

(optional) onFormSubmit

onFormSubmit = FormSubmit<T> = (data:T)=>void

Form 컴포넌트 내부의 form 엘리멘트의 submit 이벤트에 동작합니다. 일반 form submit 과 다른점은 파라미터로 data:T 가 제공된다는 점입니다.

(optional) useMintFormValidation

useMintFormValidation = boolean

form 의 기본 validate 를 무시하고 mint-ui 의 커스텀 validate 체계를 따르게 합니다.

이걸 사용하는 이유는 form 에 내장되어 있는 validate 체계에 더하여 커스텀 유효성 체크를 지원하기 위해서 입니다. useMintFormValidation 를 사용하면 기본 form 체크외에 아래와 같은 체크를 추가로 할 수 있습니다.

export function FormMintValidate(){

  const [data, setData] = useState({
    aaa:'',
  })

  const [msg, setMsg] = useState('');

  return <Frame>
    <div>data.aaa = {data.aaa}</div>
    <div>validate message = {msg}</div>
    <div>---------------------</div>
    <Form formId="my-form" data={data} setData={setData} useMintFormValidation 
    onFormInvalid={(targetId:keyof T, validationMessage:string)=>{
      setMsg(validationMessage);
    }}>
      <Flex flexGap="10px">
        <span>숫자만입력 : <Input targetId='aaa' validValue={(target:HTMLInputElement|HTMLTextAreaElement, value:string|number, onSubmit:boolean, formDefaultShowMessage)=>{
          
          // submit 이 아니면 유효성 체크 안함
          if(!onSubmit){
            return undefined;
          }
          
          // 유효성 체크
          let msg:string|undefined = undefined;
          if(String(value).length < 1 || String(value).length > 3){
            msg = '3자리까지 입력!!!'
          }else if(Number.isNaN(Number(value))){
            msg = '숫자만 입력!!!'
          }
          
          // 메시지 팝업
          msg && formDefaultShowMessage(msg, target);

          // onFormInvalid 로 메시지 리턴
          return msg;

        }} /></span> {/* data.aaa 와 바인딩 */}
      </Flex>
    </Form>
    <Button type="submit" form="my-form" >전송</Button>
  </Frame>
}

onSubmit 일때만 숫자 3자리까지 입력 가능하도록 체크합니다.

(optional) onFormInvalid

onFormInvalid = FormInvalid<T> = (targetId:keyof T, validationMessage:string)=>void

useMintFormValidation 값이 true 일때 form submit 결과가 오류인 경우 호출됩니다. 오류 대상의 targetId 와 오류메시지가 함께 파라미터로 제공됩니다.

(optional) disableNativeForm

disableNativeForm = boolean

이 옵션이 true 이면 내부적으로 form element 를 제거합니다. form 의 특성을 제거하고 양방향 바인딩 기능만 사용하고 싶을때 쓸 수 있습니다.

(optional) mintFormToastConfig

mintFormToastConfig = ToastProp

useMintFormValidation 값이 true 일때 form validate 에 사용되는 Toast 컴포넌트를 커스터마이징 할 수 있습니다.

자세한 내용은 Toast 컴포넌트를 참조하세요.