Stacked - Form Basics

📝 Form Basics (폼 기본 사용법)

Stacked는 폼(Form)을 쉽게 다루기 위해 @FormView 애너테이션을 제공합니다.
이 기능을 통해 텍스트 필드 컨트롤, 검증(validation), 상태 관리 등을 자동화할 수 있어요.

---

✅ 목표

• TextField 값을 ViewModel에서 쉽게 접근하고
• validation, focus 제어 등을 간편하게 처리하는 것

---

1️⃣ @FormView 애너테이션 사용하기

먼저 View 클래스 위에 @FormView를 선언합니다:

@FormView(fields: [
  FormTextField(name: 'email'),
  FormTextField(name: 'password', isPassword: true),
])
class LoginView extends StackedView<LoginViewModel> {
  ...
}

• name: 텍스트 필드 이름 (ViewModel에서 사용할 변수명)
• isPassword: 비밀번호 입력 필드 여부

---

2️⃣ build_runner로 코드 생성

flutter pub run build_runner build --delete-conflicting-outputs

→ 이 명령어를 실행하면 _form_view.form.dart 파일이 생성됩니다.

---

3️⃣ 자동 생성된 필드와 컨트롤러 사용하기

class LoginView extends StackedView<LoginViewModel> with $LoginView {
  @override
  void onViewModelReady(LoginViewModel viewModel) {
    syncFormWithViewModel(viewModel);
  }

  @override
  Widget builder(BuildContext context, LoginViewModel viewModel, Widget? child) {
    return Column(
      children: [
        TextField(controller: emailController),
        TextField(controller: passwordController, obscureText: true),
      ],
    );
  }
}

• emailController, passwordController 등은 자동 생성됨
• syncFormWithViewModel()을 호출하면 ViewModel과 양방향 바인딩이 연결됨

---

4️⃣ ViewModel에서 필드값 접근

class LoginViewModel extends FormViewModel {
  void submit() {
    print(emailValue);     // 입력된 이메일
    print(passwordValue);  // 입력된 비밀번호
  }
}

• FormViewModel을 상속하면 자동으로 emailValue, passwordValue 등이 생성됩니다.

---

5️⃣ 추가 기능들

기능	설명
setFormStatus()	폼 상태 갱신 수동 트리거
isFormValid	전체 폼 유효성 검사 결과
clearForm()	폼 초기화
disposeForm()	메모리 정리 (보통 dispose()에서 호출됨)

---

📌 요약

요소	설명
@FormView	필드 정의를 위한 애너테이션
build_runner	자동 코드 생성
syncFormWithViewModel()	View ↔ ViewModel 바인딩 연결
FormViewModel	값 접근 및 폼 제어 기능 제공

---

✅ Stacked Form의 장점

• 컨트롤러와 FocusNode 자동 생성
• 상태/값 추적이 쉬움
• ViewModel에서 폼 유효성 체크 가능
• 복잡한 폼도 깔끔하게 관리 가능

---

알아보면 좋을 내용

• validation 커스터마이징, 폼 초기값 설정, 여러 폼 필드 간 상호작용 구현

출처 : Stacked 공식 문서 - Form Basics