Flutter SVG 이미지: 에셋 번들 포함, 크기 설정, 확인
Flutter에 SVG 에셋을 추가하고 번들 경로를 맞추며 위젯 치수를 설정하고 색상과 의미를 확인하세요. 로딩 문제와 지원하지 않는 아트워크를 구분하세요.
목차
Flutter에서 SVG 에셋을 표시하려면 flutter_svg를 추가하고 pubspec.yaml에 파일을 선언한 뒤 SvgPicture.asset으로 같은 경로를 불러오세요. 위젯에 치수나 적절한 레이아웃 제약을 지정하고 앱에서 아트워크를 살펴보세요. 패키지의 에셋 생성자는 이 로딩 방식을 설명합니다.
두 질문을 분리하세요. 앱이 원하는 파일을 불러왔나요? 렌더러가 원하는 아트워크를 재현했나요? 그림을 다시 내보내도 에셋 키 오타는 고쳐지지 않습니다. 키를 고쳐도 지원하지 않는 효과가 단순화되지는 않습니다.
이 안내는 직접 만든 언덕과 태양 일러스트레이션으로 확인을 간단하게 합니다. 코드는 문서화된 API를 따르며 컴파일된 앱 테스트 보고가 아닙니다.
확인할 수 있는 작은 소스로 시작하기
Flutter 프로젝트에 assets/illustrations/hills.svg를 만드세요.
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 48">
<circle cx="49" cy="11" r="6" fill="#e99b30"/>
<path d="M4 42L24 14L44 42Z" fill="#167d8d"/>
<path d="M28 42L43 23L60 42Z" fill="#233b63"/>
</svg>소스에는 겹치는 삼각형 언덕 두 개와 분리된 황금빛 태양이 있습니다. 명시적인 채우기를 사용하고 텍스트나 연결 이미지가 없으며 태양과 언덕 사이에 눈에 보이는 틈이 있습니다. 이 세부 요소들이 앱을 확인할 짧은 수용 기준을 제공합니다.
나중에 자신의 아트워크를 추가할 때도 이 단순한 파일의 사본을 유지하세요. 작은 소스는 작동하지만 대체 파일은 실패한다면 전체 로딩 설정을 바꾸기 전에 구조를 비교하세요.
Flutter SVG 에셋은 Android VectorDrawable XML과도 다른 전달 방식입니다. 대상이 네이티브 Android drawable이라면 두 파일 형식을 서로 바꿔 쓸 수 있다고 취급하지 말고 Android VectorDrawable 준비 안내를 사용하세요.
패키지를 추가하고 정확한 파일 선언하기
Flutter 프로젝트 루트에서 공식 설치 명령을 사용하세요.
flutter pub add flutter_svg그런 다음 pubspec.yaml의 기존 flutter: 섹션 아래에 다음 에셋 항목을 추가하세요.
flutter:
assets:
- assets/illustrations/hills.svg두 번째 flutter: 섹션을 만들지 말고 현재 설정에 항목을 합치세요. 표시된 들여쓰기를 유지하세요. Flutter의 에셋 문서는 경로를 pubspec.yaml 기준으로 정의하고 나열된 파일이 앱 번들에 들어가는 방식을 설명합니다.
파일 이름, 선언, Dart 호출에서 철자, 대소문자, 디렉터리 구조를 동일하게 사용하세요. 첫 확인에서는 넓은 폴더 항목보다 명시적인 파일 항목이 비교하기 쉽습니다. 나중에 디렉터리를 선언한다면 Flutter 문서에 따라 디렉터리 항목은 바로 아래 파일만 포함하며 중첩 디렉터리에는 별도 항목이 필요합니다.
에셋 설정을 바꾼 뒤 평소 개발 작업 흐름으로 앱을 다시 빌드하고 실행하세요. 편집기에 보이는 파일이 보고 있는 앱에 이미 포함되었다고 가정하지 마세요.
정의된 상자에 아트워크 불러오기
위젯을 포함하는 Dart 파일에 다음 가져오기를 추가하세요.
import 'package:flutter/material.dart';
import 'package:flutter_svg/flutter_svg.dart';화면의 적절한 위치에 다음 위젯을 배치하세요.
SvgPicture.asset(
'assets/illustrations/hills.svg',
width: 128,
height: 96,
fit: BoxFit.contain,
semanticsLabel: 'Sun above two hills',
errorBuilder: (context, error, stackTrace) =>
const Text('Illustration unavailable'),
)상자는 소스 비율을 따릅니다. 더 작은 크기를 시도하기 전에 분리된 태양, 언덕의 두 색상, 바깥 여백을 확인하세요. 그다음 실제 컴포넌트에 필요한 치수를 사용하세요. 위 숫자는 예제이며 최소 크기나 성능 권장값이 아닙니다.
생성자 문서는 로딩이 예상치 못하게 레이아웃을 바꾸지 않도록 명시적 치수나 크기를 확정하는 레이아웃 제약을 권장합니다. 상자 안에서 아트워크가 너무 작아 보이면 위젯 치수뿐 아니라 viewBox의 빈 공간도 확인하세요.
라벨은 독립된 이 그림의 목적을 설명합니다. semanticsLabel API는 이를 그림의 의미 라벨과 연결합니다. 이미 의미를 전달하는 텍스트 옆의 장식 이미지에는 대신 의미 정보에서 그림을 제외하는 것을 고려하세요. 생성자의 excludeFromSemantics 옵션은 라벨보다 우선합니다. 각 도형에 따로 라벨을 붙이기보다 전체 컴포넌트가 음성으로 전달하는 의미를 검토하세요.
로딩 자리 표시자와 오류 구분하기
로딩 표시는 SVG가 받아들여졌다는 증거가 아닙니다. 패키지는 가져오기 또는 디코딩 중 placeholderBuilder를 제공하며 현재 errorBuilder API는 이미지 로딩 실패 시 위젯을 제공합니다.
위 예제는 짧은 텍스트 대체 표시를 사용합니다. 개발 중에는 Dart 경로를 의도적으로 존재하지 않는 파일 이름으로 바꿔 실패를 알아볼 수 있는지 확인하세요. 계속하기 전에 올바른 경로로 복원하세요. 이는 그림 자체를 바꾸지 않고 실패 표시를 테스트합니다.
그런 다음 실제 소스를 테스트하세요. 여전히 실패하면 진단 출력을 살펴보고 먼저 선언된 경로를 비교하세요. 다른 SVG가 우연히 표시되는 네트워크 예제가 로컬 파일의 번들 포함이나 기능 지원을 입증하지는 않습니다.
팔레트를 유지할지 색조를 적용할지 결정하기
언덕이 청록색과 남색을, 태양이 황금빛을 유지해야 한다면 colorFilter를 설정하지 마세요. 의도적인 단색 처리에는 다음 같은 필터를 추가하세요.
colorFilter: const ColorFilter.mode(
Color(0xFF175CD3),
BlendMode.srcIn,
),패키지는 이 색조 패턴을 설명합니다. Flutter의 BlendMode 참조는 srcIn이 대상의 불투명도를 사용하고 색상 채널은 무시한다고 설명합니다. 따라서 단색 색조는 소스 팔레트의 구분을 없앱니다. 이는 디자인 선택이며 색상 보존을 위한 수정이 아닙니다.
언덕에서는 겹친 두 삼각형의 대비를 잃으면 일러스트레이션을 알아보기 어려워지는지 확인하세요. 영역을 구분해야 한다면 원래 팔레트를 유지하세요. 패키지는 선택적 대체용 ColorMapper도 설명하지만 불일치를 진단하는 동안에는 더 단순한 필터 없는 경우로 시작하세요.
파일이 불러와진 후에만 기능 단순화하기
flutter_svg 문서는 CSS 지원이 불완전하므로 Illustrator에서 내보낼 때 프레젠테이션 속성을 권장하고 외부 연결 이미지보다 포함 이미지를 권장합니다. 컴파일러 기반 호환성 확인도 제공합니다. 복잡한 에셋을 조사할 때 자체 Flutter/Dart 환경에서 그 확인을 따르세요.
브라우저 미리보기는 원하는 모양의 유용한 기준이지만 패키지에서 모든 SVG 기능이 동일하게 렌더링됨을 입증하지는 않습니다. 원본 아트워크를 보관하고 사본을 한 번에 한 변경씩 단순화하세요.
| 관찰한 현상 | 다음 비교 |
|---|---|
| 아무것도 나타나지 않음 | 에셋 키, 선언, 대체 표시, 진단 출력 |
| 단순한 언덕은 표시되지만 다른 그림은 안 됨 | 소스 구조와 렌더러 호환성 |
| 모든 영역이 한 색이 됨 | 소스 채우기 편집 전에 위젯 색상 필터 |
| 상자 안의 그림이 아주 작음 | ViewBox 여백과 레이아웃 제약 |
| 텍스트가 다르거나 사라짐 | 글꼴 의존성과 원하는 텍스트 처리 |
| 컴포넌트 크기에서 세부 요소 누락 | 원본 도형, 겹침, 사용 가능한 공간 |
소스에 글자가 있다면 앱 텍스트로 유지할지 고정 아트워크로 둘지 결정하세요. SVG 글꼴 변경 안내는 모양이 텍스트 및 글꼴 처리에 의존할 수 있는 이유를 설명합니다. 에셋 경로 문제를 해결하려고 라벨을 추적하지 마세요.
UI 에셋군에서는 시각적 크기와 간격을 함께 비교하세요. UI 키트 아이콘 준비 안내는 일관성 확인에 도움이 됩니다.
소스 복원이 필요할 때 벡터화 사용하기
깨끗한 기존 SVG는 유지하세요. 사진이나 질감 있는 배경은 적절한 래스터 에셋으로 전달하는 것이 나을 수 있습니다. 확장자를 바꿔도 유용한 벡터 도형이 되지는 않습니다.
단순한 일러스트레이션이 거친 PNG로만 남았다면 PerfectVector의 PNG에서 SVG로 변환 작업 흐름으로 편집 가능한 후보를 준비할 수 있습니다. 아트워크 부분을 자르고 미리보기에서 누락된 도형과 원치 않는 배경 영역을 살펴본 뒤 SVG를 다운로드하세요. 파일을 앱 번들에 추가하고 로딩, 팔레트, 크기, 의미 확인을 반복하세요.
언덕 예제에서는 분리된 태양과 두 색상의 경사면 구분을 확인하세요. 파일에 의도한 구조가 있는지 확인하세요. 포함된 래스터 안내는 SVG 파일에 여전히 픽셀이 들어 있을 수 있는 이유를 설명합니다.
최적화 전략을 선택하기 전에 앱에서 에셋을 판단하세요. 이 작업 흐름은 SVG가 PNG보다 작거나 빠르다는 일반적 보장을 하지 않습니다.
아트워크를 .NET MAUI 앱에서도 재사용한다면 MAUI 소스에서 PNG로의 작업 흐름을 따르세요. 프로젝트는 SVG 마스터를 보관하지만 뷰는 빌드 중 준비된 PNG를 참조합니다.
FAQ
Flutter에 SVG 이미지를 추가하려면 어떻게 하나요? flutter_svg를 추가하고 pubspec.yaml에 SVG 에셋을 선언한 뒤 SvgPicture.asset으로 같은 경로를 불러오세요. 치수나 적절한 제약을 설정하고 결과를 확인하세요.
로컬 SVG가 나타나지 않는 이유는 무엇인가요? 먼저 에셋 선언, 정확한 경로, 로딩 오류, 레이아웃을 확인하세요. 단순한 소스가 작동하면 실패한 아트워크의 구조와 지원 기능을 비교하세요.
모든 색상이 같아진 이유는 무엇인가요? 단색 srcIn 색상 필터는 보이는 팔레트를 색조로 대체합니다. 원래 색상을 구분해야 한다면 필터를 제거하세요.
Flutter용으로 PNG를 SVG로 바꿔야 하나요? 아닙니다. 아트워크에 맞으면 적절한 래스터 에셋을 사용하세요. 단순한 래스터 소스에서 편집 가능한 도형을 복원할 때 벡터화는 선택 사항입니다.
Sources
- flutter_svg — 설치 — 패키지 설치와 Dart 가져오기.
- Flutter — 에셋과 이미지 추가하기 — 에셋 선언, 경로, 번들 포함.
- flutter_svg — SvgPicture.asset — 에셋 로딩, 치수, 맞춤, 의미 제어.
- flutter_svg — errorBuilder — 로딩 자리 표시자와 구분되는 실패 표시.
- flutter_svg — semanticsLabel — 그림의 의미상 목적.
- Flutter — BlendMode — 불투명도 기반 srcIn 색상 처리.
- flutter_svg — 패키지 문서 — 색조, 선택적 색상 매핑, 내보내기 안내, 호환성 확인.
선언한 에셋 하나로 시작하고 앱에서 경로, 팔레트, 크기, 의미를 확인하세요. 래스터 일러스트레이션 복원이 필요하다면 SVG 후보 파일을 준비하고 도형을 살펴본 뒤 에셋군에 추가하기 전에 같은 확인을 수행하세요.
