flutter-widget-ui

name	flutter-widget-ui
description	Flutter 위젯 UI 작성 패턴 — StatelessWidget 선호, `const` 최적화, `ListenableBuilder`로 ViewModel 관찰, `ListView.builder`/`IndexedStack`, 공용 컴포넌트 재사용, 접근성(Semantics), 다이얼로그·스낵바 처리. "위젯 만들기", "UI 만들기", "StatelessWidget", "ListView", "ListenableBuilder", "Scaffold", "스낵바", "다이얼로그", "디자인 토큰", "공용 컴포넌트" 같은 표현에 트리거합니다.

Flutter 위젯 UI 패턴

핵심 원칙

UI는 바보다. Screen 위젯은 state 와 onAction 을 받아 렌더링과 사용자 인터랙션만 담당한다. 비즈니스 로직, 데이터 변환, 네트워크 호출은 전부 ViewModel/UseCase/Data 레이어에서 끝난다. Screen 안에는 로직이 없어야 테스트와 디자인 리뷰가 쉬워진다.

---

StatelessWidget을 기본으로

이 프로젝트의 거의 모든 화면은 StatelessWidget 이다. 상태는 ViewModel(ChangeNotifier)이 보관하고 ListenableBuilder 가 구독한다. StatefulWidget 은 다음 경우에만 쓴다:

• 위젯 생애주기 안에서만 의미 있는 로컬 UI 상태 (TextEditingController, ScrollController, TabController, 애니메이션 컨트롤러).
• initState / dispose 가 꼭 필요한 구독·리소스 초기화.

앱 전반 상태는 전부 ViewModel 로 옮긴다.

---

const 를 최대한 활용하라

생성자 호출 앞의 const 는 리빌드 시 동일 인스턴스가 재사용되게 해 준다. 정적 위젯, 리터럴 스타일, SizedBox(height: N) 등 거의 모든 정적 노드에 const 를 붙인다.

const SizedBox(height: 10),
const ChefProfile(),
const Icon(Icons.share, size: 20),

하위 위젯이 const 생성자를 갖도록 작성해 재사용 경로를 열어준다.

---

ViewModel 구독 — ListenableBuilder

Root 위젯에서 ViewModel 변화를 구독할 때의 표준 패턴은 ListenableBuilder. builder 안에서만 viewModel.state 를 읽어 불필요한 리빌드 범위를 줄인다.

return ListenableBuilder(
  listenable: viewModel,
  builder: (context, _) {
    final state = viewModel.state;
    if (state.isLoading) return const Center(child: CircularProgressIndicator());
    return IngredientScreen(state: state, onAction: viewModel.onAction);
  },
);

Screen 은 ListenableBuilder 를 몰라야 한다. 그 책임은 Root.

---

리스트 — ListView.builder

항목 수가 작더라도 고정 리스트는 Column 대신 ListView.builder 를 써서 확장에 대비한다.

ListView.builder(
  itemCount: state.ingredients.length,
  itemBuilder: (context, index) {
    return Column(
      children: [
        IngredientItem(ingredient: state.ingredients[index]),
        const SizedBox(height: 10),
      ],
    );
  },
)

큰 리스트이거나 키가 필요한 경우 itemBuilder 가 반환하는 위젯에 Key(item.id.toString()) 를 넣어 재배치/삭제 시 상태가 섞이지 않게 한다.

탭 간 전환에서 상태를 보존하고 싶다면 IndexedStack 이 깔끔하다:

IndexedStack(
  index: state.selectedTabIndex,
  children: [IngredientList(state: state), ProcedureList(state: state)],
)

---

공용 컴포넌트 재사용

이 프로젝트는 lib/core/presentation/components/ 에 디자인 시스템 격 위젯이 모여 있다. 새 화면에서 비슷한 버튼/카드/입력이 필요하면 먼저 이 디렉터리를 뒤진다. 예:

• BigButton, MediumButton, SmallButton
• SearchInputField, InputField
• FilterButton, FilterButtons, RatingButton
• RecipeCard, NewRecipeCard, DishCard, IngredientRecipeCard, RecipeGridItem
• TwoTab, ChefProfile, IngredientItem, ProcedureItem

없으면 같은 디렉터리에 새 컴포넌트를 추가한다. 두 번 이상 쓸 일이 있는 UI만 공용으로 올리고, 한 화면 전용이라면 해당 feature 폴더에 보조 위젯으로 둔다.

디자인 토큰은 lib/ui/color_styles.dart, lib/ui/text_styles.dart 에 있으므로 raw 색/폰트를 쓰지 않고 토큰을 재사용한다.

Text('1 serve', style: TextStyles.smallerTextRegular.copyWith(color: ColorStyles.gray3)),

---

다이얼로그와 스낵바

다이얼로그/스낵바는 BuildContext 가 필요하므로 Root 위젯의 인터랙션 콜백에서 띄운다. ViewModel 은 "어떤 메뉴가 선택됐다"는 Action 만 알면 된다.

// ingredient_root.dart
IngredientScreen(
  state: viewModel.state,
  onAction: viewModel.onAction,
  onTapMenu: (menu) {
    switch (menu) {
      case IngredientMenu.share:
        showDialog(
          context: context,
          builder: (_) => ShareDialog(
            link: 'app.Recipe.co/jollof_rice',
            onTapCopyLink: (link) {
              viewModel.onAction(IngredientAction.onTapShareMenu(link));
              Navigator.pop(context);
              ScaffoldMessenger.of(context).showSnackBar(
                const SnackBar(content: Text('Link Copied', textAlign: TextAlign.center)),
              );
            },
          ),
        );
      // ...
    }
  },
),

요령: 다이얼로그 닫기와 상태 반영을 같이 해야 한다면 콜백 안에서 viewModel.onAction(...) → Navigator.pop(context) → 후속 UI 표시 순서로.

---

Scaffold 구성 관례

• Scaffold → AppBar → SafeArea → Padding(horizontal: 30) → Column 이 이 프로젝트의 기본 골격 (ingredient_screen.dart 참고). 수평 패딩을 SafeArea 안쪽에 두어 노치 회피와 일관 여백을 동시에 얻는다.
• AppBar 의 actions 는 PopupMenuButton 으로 메뉴를 꽂고, 각 PopupMenuItem 은 onTap 에서 Screen이 받은 콜백(onTapMenu)을 호출한다.

---

텍스트 필드

TextField / TextFormField 값은 로컬 컨트롤러 + ViewModel Action 로 이중화한다. 사용자 입력마다 Action 을 디스패치해 상태에 기록한다. 지속이 필요 없는 순수 로컬이라면 StatefulWidget + TextEditingController 만으로도 충분하다.

TextField(
  onChanged: (value) => onAction(SearchAction.onQueryChange(value)),
)

---

접근성

• 의미 있는 이미지/아이콘에는 Semantics(label: '...') 또는 IconButton(tooltip: '...') 을 달아 스크린리더 사용자를 배려한다.
• 텍스트 크기 변경에 대비해 고정 height 대신 Padding + mainAxisSize / Expanded 로 레이아웃을 구성한다.
• 터치 타깃은 최소 48×48 논리 픽셀. 작은 아이콘 버튼은 IconButton 이나 InkWell + 충분한 padding 으로 감싼다.

---

성능 요령

• const 생성자 적극 사용.
• 리스트 아이템에 무거운 계산이 있으면 itemBuilder 밖에서 미리 수행 (예: 포매팅은 UI 모델에 이미 반영).
• 애니메이션은 AnimatedBuilder / TweenAnimationBuilder / ImplicitlyAnimatedWidget 으로 리빌드 범위를 좁힌다. 프레임마다 부모 Scaffold 를 재빌드하지 않도록 애니메이션 영역을 작은 위젯으로 분리.
• 큰 이미지는 cacheWidth/cacheHeight 로 디코딩 크기를 제한한다.

---

체크리스트 — 새 Screen 위젯

• StatelessWidget 으로 선언하고 state, onAction 만 파라미터로 받는다
• Root 에서 전달된 네비게이션/다이얼로그 콜백이 있다면 추가 파라미터로 받는다
• 정적 자식은 전부 const
• 리스트는 ListView.builder, 탭 전환은 IndexedStack 검토
• 공용 컴포넌트(core/presentation/components)를 먼저 사용, 없으면 추가
• 색/폰트는 ColorStyles, TextStyles 사용
• BuildContext 가 필요한 효과(다이얼로그·스낵바·내비게이션)는 Root 에서 처리

---

안티 패턴

• ❌ Screen 안에서 getIt<...>() 호출 → Root 가 주입해야 한다.
• ❌ Screen 안에서 context.push(...) 직접 호출 → 콜백으로 위임.
• ❌ setState 로 앱 상태를 관리 → ViewModel 로 올려라.
• ❌ 매직 넘버 색상/폰트 직접 사용 → ColorStyles / TextStyles 를 쓴다.
• ❌ Column + 수동 스크롤 — 항목이 많아질 수 있으면 ListView.builder.
• ❌ const 생략으로 동일 위젯이 매 프레임 재생성.