위젯 빌더 총정리 — builder vs pageBuilder, FutureBuilder 등

builder란 뭐냐

미리 만든 위젯을 넣는 게 아니라, **"필요한 순간에 위젯을 만들어 내는 함수"**를 넘기는 패턴이다. React의 render prop(자식을 함수로 받아 그리는 것)과 가장 비슷하다.

Builder(builder: (context) => Text("..."))  // context가 필요한 순간에 만들어 냄

라우터의 builder vs pageBuilder

go_router의 GoRoute에서 둘 중 하나를 쓴다:

	언제	반환
`builder`	보통 (기본)	그냥 화면 위젯
`pageBuilder`	화면 전환 애니메이션을 직접 지정할 때	Page 객체(전환 방식 포함)

// builder: 그냥 화면만
GoRoute(builder: (c, s) => DetailPage())

// pageBuilder: 아래→위 슬라이드 같은 전환을 직접 정의
GoRoute(pageBuilder: (c, s) => CustomTransitionPage(
  child: DetailPage(),
  transitionsBuilder: (c, anim, _, child) => SlideTransition(...),
))

즉 기본 전환이면 builder, 전환 애니메이션을 커스텀하면 pageBuilder.

이름에 Builder가 붙은 다른 위젯들

이것들은 다 "어떤 상황이 되면 그에 맞게 화면을 만들어 주는" 빌더다:

위젯	언제 다시 그리나	React 비유
FutureBuilder	비동기(Future) 결과 도착 시	React Query 구독
StreamBuilder	스트림 값이 올 때마다	구독 기반 렌더
ValueListenableBuilder	ValueNotifier 값 바될 때	useState 변경 시
LayoutBuilder	부모 크기가 정해질 때 (반응형)	ResizeObserver
Consumer (Riverpod)	구독한 provider 값 바될 때	useSelector 부분 구독

공통점: "지금 당장"이 아니라 "특정 조건이 되는 순간"에 화면 일부를 다시 그리기 위해 함수(builder)를 미리 건네둔다. 그래서 필요한 부분만 다시 그려 성능에 유리하다.