Form#

여러 입력 필드를 묶어 유효성 검증을 수행하는 폼 컴포넌트입니다.

Live Preview#

class FormDefaultExample extends StatelessComponent {
  const FormDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return CoForm(
      children: [
        CoFormField(
          label: 'Username',
          child: CoTextField(
            placeholder: Component.text('Username'),
            onChanged: (_) {},
          ),
        ),
        CoFormField(
          label: 'Email',
          child: CoTextField(
            placeholder: Component.text('Email'),
            onChanged: (_) {},
          ),
        ),
        CoButton(
          variant: CoreButtonVariant.primary,
          onPressed: () {},
          child: Component.text('Submit'),
        ),
      ],
    );
  }
}

class FormDefaultExample extends StatelessWidget {
  const FormDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return CoForm(
      children: [
        CoFormField(
          label: 'Username',
          child: CoTextField(placeholder: const Text('Username')),
        ),
        CoFormField(
          label: 'Email',
          child: CoTextField(placeholder: const Text('Email')),
        ),
        CoButton(
          variant: CoreButtonVariant.primary,
          onPressed: () {},
          child: const Text('Submit'),
        ),
      ],
    );
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 여러 입력 필드의 유효성 검증을 한꺼번에 관리할 때
• 제출 전 사용자 입력을 검증하고 에러 피드백을 제공할 때
• 필드 간 상호 의존적인 검증이 필요할 때 (비밀번호 확인 등)

대신 다른 컴포넌트를 사용하세요:

• Input: 단일 입력 필드만 필요하고 폼 검증이 불필요할 때
• Dialog: 간단한 확인 입력은 다이얼로그 내에서 직접 처리할 때

기본 사용법 (Basic Usage)#

CoForm(
  children: [
    CoFormField(
      label: '이름',
      required: true,
      child: CoTextField(placeholder: Text('홍길동')),
    ),
    CoFormField(
      label: '이메일',
      child: CoTextField(placeholder: Text('example@email.com')),
    ),
    CoButton(
      variant: CoreButtonVariant.primary,
      onPressed: handleSubmit,
      child: Text('제출'),
    ),
  ],
)

CoForm(
  onSubmit: handleSubmit,
  children: [
    CoFormField(
      label: '이름',
      required: true,
      child: CoTextField(placeholder: text('홍길동')),
    ),
    CoFormField(
      label: '이메일',
      child: CoTextField(placeholder: text('example@email.com')),
    ),
    CoButton(
      variant: CoreButtonVariant.primary,
      onPressed: handleSubmit,
      child: text('제출'),
    ),
  ],
)

Props / Parameters#

CoForm#

CoFormField#

변형 (Variants)#

에러 상태#

CoFormField(
  label: '이메일',
  error: '올바른 이메일을 입력하세요',
  required: true,
  child: CoTextField(placeholder: Text('이메일')),
)

설명 텍스트#

CoFormField(
  label: '비밀번호',
  description: '8자 이상, 대소문자 및 숫자를 포함하세요',
  child: CoTextField(placeholder: Text('비밀번호')),
)

비활성화#

CoFormField(
  label: '이름',
  enabled: false,
  child: CoTextField(placeholder: Text('수정 불가')),
)

동작 스펙 (Behavior)#

유효성 검증 모드 (Flutter)#

FormController (Flutter)#

FormController로 폼 상태를 프로그래밍 방식으로 관리할 수 있습니다.

final controller = FormController();

// 값 접근
final name = controller.getValue(nameKey);
final allValues = controller.values;

// 에러 확인
final errors = controller.errors;
final nameError = controller.getSyncError(nameKey);

// 재검증
controller.revalidate(context, FormValidationMode.submitted);

Validator 시스템 (Flutter)#

검증기를 연산자로 조합할 수 있습니다.

// AND: 모든 조건 충족
final validator = NotEmptyValidator() & LengthValidator(min: 8);

// OR: 하나 이상 충족
final validator = EmailValidator() | PhoneValidator();

// NOT: 조건 반전
final validator = ~ForbiddenWordsValidator();

내장 검증기: NotEmptyValidator, LengthValidator, SafePasswordValidator, CompareWith<T> (크로스 필드 비교), ConditionalValidator<T> (커스텀 조건)

사용 가이드라인 (Usage Guidelines)#

✅ Do#

CoFormField(
  label: '이름',
  required: true,
  child: CoTextField(placeholder: Text('홍길동')),
)

❌ Don't#

CoFormField(
  label: '이름',
  // required 표시 없음
  child: CoTextField(placeholder: Text('이름')),
)

✅ Do#

CoFormField(
  label: '비밀번호',
  error: '8자 이상, 대소문자 및 숫자를 포함하세요',
  child: CoTextField(placeholder: Text('비밀번호')),
)

❌ Don't#

CoFormField(
  label: '비밀번호',
  error: '유효하지 않은 비밀번호',
  child: CoTextField(placeholder: Text('비밀번호')),
)

접근성 (Accessibility)#

키보드 인터랙션#

스크린 리더#

• Flutter: CoFormField의 label이 입력 필드와 자동 연결. 에러 발생 시 에러 메시지가 실시간으로 읽힘
• Web: <label> 요소의 네이티브 접근성 자동 처리

크로스 플랫폼 차이점 (Platform Differences)#

관련 컴포넌트 (Related Components)#

• Input: 텍스트 입력 필드. CoFormField로 감싸 라벨/에러 표시
• Select: 드롭다운 선택. 폼 필드로 사용 가능
• Checkbox: 체크박스 입력. 약관 동의 등에 활용
• Button: 폼 제출 버튼

조합 예제#

// 회원가입 폼 패턴
CoForm(
  children: [
    CoFormField(
      label: '이름',
      required: true,
      child: CoTextField(placeholder: Text('홍길동')),
    ),
    CoFormField(
      label: '이메일',
      required: true,
      child: CoTextField(placeholder: Text('example@email.com')),
    ),
    CoFormField(
      label: '비밀번호',
      required: true,
      description: '8자 이상, 대소문자 및 숫자를 포함하세요',
      child: CoTextField(placeholder: Text('비밀번호')),
    ),
    CoButton(
      variant: CoreButtonVariant.primary,
      onPressed: handleSignUp,
      child: Text('가입하기'),
    ),
  ],
)