Flutter 튜토리얼 76편: Widget Previewer와 기타 도구

Why#

NOTE

전체 앱을 실행하지 않고 개별 위젯만 확인할 수 있다면 어떨까요? Widget Previewer는 Chrome 브라우저에서 위젯을 실시간으로 렌더링합니다.

디자인 시스템이나 재사용 컴포넌트를 만들 때 특히 유용합니다. 앱의 특정 화면까지 네비게이션할 필요 없이 바로 위젯을 확인할 수 있습니다.

What#

NOTE

Widget Previewer는 @Preview 어노테이션을 사용해서 위젯을 미리봅니다. Flutter 3.35 이상에서 사용할 수 있으며, IDE 지원은 Flutter 3.38 이상이 필요합니다.

현재는 실험적 기능이며 API가 변경될 수 있습니다.

How#

TIP

@Preview 어노테이션 사용하기

1
import 'package:flutter/widget_previews.dart';
2
import 'package:flutter/material.dart';
3

4
@Preview(name: 'My Sample Text')
5
Widget mySampleText() {
6
  return const Text('Hello, World!');
7
}

IDE에서 열기

IDE	방법
VS Code	사이드바에서 “Flutter Widget Preview” 탭 열기
Android Studio	사이드바에서 “Flutter Widget Preview” 탭 열기

커맨드라인에서 실행하기

1
flutter widget-preview start

Preview 커스터마이징

1
@Preview(
2
  name: 'Button - Light',
3
  group: 'Buttons',
4
  brightness: Brightness.light,
5
  size: Size(200, 100),
6
)
7
Widget buttonPreview() => const MyButton();

파라미터	설명
name	미리보기 이름
group	관련 미리보기 그룹화
size	크기 제약
brightness	라이트/다크 모드
wrapper	래퍼 위젯 지정
theme	테마 데이터 제공

여러 설정으로 미리보기

1
@Preview(
2
  group: 'Brightness',
3
  name: 'Example - light',
4
  brightness: Brightness.light,
5
)
6
@Preview(
7
  group: 'Brightness',
8
  name: 'Example - dark',
9
  brightness: Brightness.dark,
10
)
11
Widget buttonPreview() => const ButtonShowcase();

Watch out#

WARNING

Widget Previewer는 몇 가지 제한 사항이 있습니다.

지원되지 않는 기능:

• 네이티브 플러그인
• dart:io, dart:ffi 라이브러리

Flutter Web으로 빌드되기 때문에 플랫폼 네이티브 API에 접근할 수 없습니다.

에셋 경로 주의:

1
// 잘못된 예
2
'assets/my_image.png'
3

4
// 올바른 예 (패키지 기반 경로)
5
'packages/my_package_name/assets/my_image.png'

결론: Widget Previewer로 전체 앱 실행 없이 위젯을 빠르게 확인할 수 있습니다.

Why#

NOTE

위젯의 속성을 바꾸려면 코드를 직접 수정해야 합니다. Property Editor는 시각적 인터페이스에서 위젯 속성을 바로 편집할 수 있게 합니다.

Flutter Inspector와 Hot Reload와 함께 사용하면 실시간으로 변경 사항을 확인할 수 있습니다.

What#

NOTE

Property Editor는 IDE 도구로, 위젯의 생성자 인자를 시각적으로 표시하고 편집합니다. Flutter 3.32 이상에서 사용할 수 있습니다.

How#

TIP

Property Editor 사용하기

1. IDE에서 Property Editor 패널을 엽니다.
2. 코드에서 위젯 생성자 호출 위치에 커서를 놓습니다.
3. Property Editor가 해당 위젯의 속성을 표시합니다.

1
@override
2
Widget build(BuildContext context) {
3
  return Text(
4
    'Hello World!',
5
    overflow: TextOverflow.clip,  // 커서를 여기에
6
  );
7
}

속성 유형별 편집 방법

속성 유형	편집 방법
String, double, int	텍스트 입력 후 Tab 또는 Enter
bool	드롭다운에서 true/false 선택
enum	드롭다운에서 값 선택
객체 (TextStyle 등)	직접 지원 안 됨, 소스 코드에서 편집

Hot Reload와 함께 사용하기

VS Code 설정:

1
{
2
  "files.autoSave": "afterDelay",
3
  "dart.flutterHotReloadOnSave": "all"
4
}

Android Studio 설정:

1. Settings > Tools > Actions on Save에서 자동 저장 활성화
2. Settings > Languages & Frameworks > Flutter에서 “Perform hot reload on save” 체크

속성 라벨 이해하기

• “set”: 코드에서 명시적으로 설정된 속성
• “default”: 현재 값이 기본값과 같음

둘 다 표시되면 해당 인자를 제거해도 동작이 같습니다.

Watch out#

WARNING

Property Editor는 복잡한 객체 속성을 직접 편집하지 못합니다.

1
// Property Editor에서 편집 불가
2
style: TextStyle(fontSize: 16),
3
padding: EdgeInsets.all(8),

이런 속성은 소스 코드에서 직접 수정해야 합니다.

결론: Property Editor로 간단한 속성을 빠르게 편집하고 실시간으로 확인할 수 있습니다.

Why#

NOTE

Flutter는 빠르게 발전하면서 API가 변경되거나 deprecated됩니다. 수십 개의 파일에서 deprecated API를 수동으로 찾아 수정하는 것은 비효율적입니다.

Flutter Fix는 이 과정을 자동화합니다.

What#

NOTE

Flutter Fix는 deprecated API를 자동으로 감지하고 수정하는 도구입니다. IDE에서 개별 수정하거나 커맨드라인에서 프로젝트 전체를 한 번에 수정할 수 있습니다.

IDE에서는 “quick-fix”(IntelliJ/Android Studio) 또는 “code action”(VS Code)으로 불립니다.

How#

TIP

IDE에서 개별 수정하기

Android Studio / IntelliJ:

1. deprecated API에 전구 아이콘이 나타납니다.
2. 전구를 클릭하면 수정 제안이 표시됩니다.
3. 제안을 클릭하면 코드가 업데이트됩니다.

VS Code:

1. 에러 위에 마우스를 올리고 “Quick Fix” 링크를 클릭합니다.
2. 또는 커서를 에러 위치에 놓고 Cmd+. (macOS) 또는 Ctrl+. (Windows/Linux)를 누릅니다.
3. 수정 제안을 선택합니다.

프로젝트 전체 수정하기

1
# 변경될 내용 미리보기
2
dart fix --dry-run
3

4
# 모든 수정 적용
5
dart fix --apply

예시

1
$ dart fix --dry-run
2
Computing fixes in myapp (dry run)...
3

4
lib/main.dart
5
  RawScrollbar - deprecated_member_use - 3 fixes
6
  Brightness - deprecated_member_use - 1 fix
7

8
4 fixes in 1 file

1
$ dart fix --apply
2
Applying fixes...
3
lib/main.dart
4
  RawScrollbar - deprecated_member_use - 3 fixes
5
  Brightness - deprecated_member_use - 1 fix
6
4 fixes made in 1 file

Watch out#

WARNING

dart fix --apply를 실행하기 전에 반드시 --dry-run으로 변경 사항을 확인하세요. 자동 수정이 예상과 다르게 동작할 수 있습니다.

버전 관리 시스템을 사용 중이라면 커밋 후에 실행하는 것이 안전합니다.

결론: Flutter Fix로 deprecated API를 자동으로 찾아 수정할 수 있습니다.

Why#

NOTE

팀에서 코드 스타일이 다르면 리뷰 시간이 늘어납니다. “들여쓰기를 2칸으로 해야 하나, 4칸으로 해야 하나?” 같은 논쟁보다 코드 동작에 집중하는 것이 좋습니다.

자동 포맷팅은 일관된 스타일을 강제하고 논쟁을 줄입니다.

What#

NOTE

Flutter는 dart format 명령어를 통해 Dart 스타일 가이드에 맞게 코드를 자동 포맷팅합니다. IDE에서도 저장 시 자동 포맷팅을 설정할 수 있습니다.

How#

TIP

VS Code에서 포맷팅

1
{
2
  "editor.formatOnSave": true
3
}

또는 우클릭 > Format Document를 선택합니다.

Android Studio / IntelliJ에서 포맷팅

• macOS: Cmd + Option + L
• Windows/Linux: Ctrl + Alt + L

저장 시 자동 포맷팅: Settings > Languages & Frameworks > Flutter에서 “Format code on save” 체크

커맨드라인에서 포맷팅

1
# 특정 파일 포맷팅
2
dart format lib/main.dart
3

4
# 전체 프로젝트 포맷팅
5
dart format .
6

7
# 여러 경로 포맷팅
8
dart format lib/ test/

Watch out#

WARNING

자동 포맷팅이 줄 길이를 80자로 제한하는 경우가 있습니다. 이는 Dart 스타일 가이드의 권장 사항입니다.

긴 줄이 여러 줄로 나뉘어도 기능에는 영향이 없습니다.

결론: 자동 포맷팅으로 일관된 코드 스타일을 유지하고 리뷰 시간을 줄입니다.

Why#

NOTE

Hot Reload는 Flutter의 핵심 생산성 기능입니다. 코드를 수정하면 앱을 재시작하지 않고 1초 이내에 변경 사항이 반영됩니다.

하지만 모든 변경 사항이 Hot Reload로 반영되지는 않습니다. 언제 Hot Reload가 작동하고 언제 Hot Restart가 필요한지 이해해야 합니다.

What#

NOTE

Hot Reload는 수정된 코드를 Dart VM에 주입하고 위젯 트리를 다시 빌드합니다. 앱의 상태는 유지되므로 로그인한 상태에서 UI를 수정해도 다시 로그인할 필요가 없습니다.

Hot Reload vs Hot Restart vs Full Restart

기능	단축키	상태	설명
Hot Reload	r / Cmd+\	유지	코드 변경만 반영
Hot Restart	R / Shift+Cmd+\	초기화	앱 상태 리셋
Full Restart	중지 후 재실행	초기화	네이티브 코드 포함 재컴파일

How#

TIP

Hot Reload 실행하기

IDE에서:

• 파일 저장 (자동 Hot Reload 설정 시)
• Hot Reload 버튼 클릭

커맨드라인에서:

1
flutter run
2
# 앱 실행 후 터미널에서 'r' 입력

Hot Reload가 작동하는 경우

• build() 메서드 내부 변경
• 위젯 속성 변경
• 함수 로직 변경

Hot Restart가 필요한 경우

변경 유형	이유
main() 수정	앱 진입점은 재실행 필요
initState() 수정	초기화 로직은 재실행 필요
전역 변수 초기값	정적 필드는 지연 초기화됨
enum을 class로 변경	타입 변경은 재시작 필요
제네릭 타입 변경	타입 시그니처 변경
네이티브 코드 수정	Full Restart 필요

상태가 유지되는 것의 장단점

1
// 변경 전
2
final sampleData = [
3
  Item(name: 'Item 1'),
4
  Item(name: 'Item 2'),
5
];
6

7
// 변경 후 - Hot Reload로 반영되지 않음
8
final sampleData = [
9
  Item(name: 'New Item 1'),  // 초기값 변경
10
  Item(name: 'New Item 2'),
11
];

final 변수의 초기값을 바꾸면 Hot Reload로 반영되지 않습니다. const로 바꾸거나 getter를 사용하면 해결됩니다.

1
// 해결책 1: const 사용
2
const foo = 2;
3
const bar = foo;
4

5
// 해결책 2: getter 사용
6
const foo = 2;
7
int get bar => foo;

Watch out#

WARNING

Hot Reload가 실패하는 경우

1. 컴파일 에러: 코드에 문법 오류가 있으면 Hot Reload가 거부됩니다.
2. 앱 종료: 앱이 백그라운드에서 종료되면 연결이 끊어집니다.
3. CupertinoTabView의 builder: 알려진 버그로 Hot Reload가 적용되지 않습니다.

에러 메시지 예시:

1
Hot reload was rejected:
2
'/path/to/project/lib/main.dart': error: line 33 pos 5: unbalanced ')'

이 경우 해당 라인의 오류를 수정하면 됩니다.

결론: Hot Reload의 작동 원리와 제한 사항을 이해하면 효율적인 개발이 가능합니다.