Flutter 3.16 업데이트 후 Material 3 마이그레이션 작업

배경

회사 플러터 앱을 3.13에서 3.16으로 업데이트했다. Material 3가 기본 테마로 적용되면서 일부 UI가 예상과 다르게 렌더링되는 문제가 발생했다.

주요 변경사항

AppBar 높이 변경

Material 3에서 AppBar의 기본 높이가 달라졌다. 기존에 하드코딩된 패딩 값들이 어긋나면서 레이아웃이 깨졌다.

// 기존
AppBar(
  title: Text('Title'),
)

// Material 3 대응
AppBar(
  title: Text('Title'),
  toolbarHeight: 64, // 명시적 지정
)

NavigationBar 교체

BottomNavigationBar가 deprecated되고 NavigationBar로 전환을 권장한다.

NavigationBar(
  selectedIndex: _currentIndex,
  onDestinationSelected: (index) {
    setState(() => _currentIndex = index);
  },
  destinations: const [
    NavigationDestination(
      icon: Icon(Icons.home_outlined),
      selectedIcon: Icon(Icons.home),
      label: '홈',
    ),
    // ...
  ],
)

색상 시스템 조정

ColorScheme 생성 방식이 변경되어 일부 커스텀 색상이 적용되지 않았다.

ThemeData(
  useMaterial3: true,
  colorScheme: ColorScheme.fromSeed(
    seedColor: Colors.blue,
    brightness: Brightness.light,
  ).copyWith(
    primary: customPrimary,
    secondary: customSecondary,
  ),
)

점진적 마이그레이션 전략

전체를 한번에 바꾸기엔 리스크가 커서 useMaterial3: false로 되돌리고 화면별로 점진적으로 적용하기로 했다. 2024년 1분기까지 완전 전환 목표다.

참고

• Flutter 3.16 릴리즈 노트
• Material Design 3 가이드라인
• migration guide 문서가 생각보다 부실해서 실제 코드 뜯어보며 해결했다.