.NET MAUI에서 SVG 사용하기: SVG를 보관하고 PNG 참조하기

.NET MAUI의 번들 이미지 작업 흐름에서 SVG를 사용하려면 SVG는 프로젝트에 보관하고 XAML이나 C#에서는 생성된 PNG 이름을 참조하세요. MAUI는 빌드 중 벡터 소스를 처리합니다. 따라서 추가한 파일이 compass.svg여도 compass.png를 가리키는 Image가 올바를 수 있습니다. Microsoft의 프로젝트 이미지 안내는 이 변환을 설명합니다.

파일 이름은 설명되지만 디자인에 관한 질문은 남습니다. MAUI는 어떤 크기를 생성해야 하며 이후 무엇을 확인해야 할까요? 작은 나침반 엠블럼 하나를 소스, 프로젝트 메타데이터, 표시 선언 순서로 살펴보세요.

빌드를 따라 소스 확인하기

편집 가능한 SVG와 패키지에 포함된 이미지는 역할이 다릅니다. 나중에 도형, 여백, 색상을 조정할 수 있도록 소스를 보관하세요. 표시하는 뷰에서는 생성된 이름을 사용하세요.

Image 컨트롤 문서는 대상 밀도의 이미지들이 앱 패키지에 들어가고 운영체제가 적절한 해상도를 선택한다고 설명합니다. SVG 마스터를 유지한다고 이 특정 작업 흐름이 뷰에 런타임에 해석되는 SVG 문서 자체를 전달하는 것은 아닙니다.

경계가 명확한 작은 SVG 추가하기

이 직접 만든 예제를 Resources/Images/compass.svg로 저장하세요.

<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
  <circle cx="48" cy="48" r="34" fill="none" stroke="#173e52" stroke-width="8"/>
  <path d="M58 28L52 52L28 58Z" fill="#ed765e"/>
</svg>

고리는 투명한 중심을 남기고 산호색 바늘은 별도 도형입니다. 이런 세부 요소는 가져온 뒤 구체적으로 확인할 대상을 제공합니다. 선언된 치수와 정사각형 viewBox도 원하는 구도를 명확히 합니다. 벡터 도형과 SVG 안에 포함된 비트맵의 차이는 SVG 파일 안내를 참고하세요.

프로젝트에서 파일의 빌드 작업이 MauiImage인지 확인하세요. Microsoft는 Resources/Images 폴더를 일반적인 위치로 설명합니다. XML을 추가하기 전에 기존 프로젝트 항목을 살펴보세요. 프로젝트가 이미 와일드카드로 해당 폴더를 포함할 수 있습니다. 프로젝트 이미지 설정은 위치와 빌드 작업을 설명합니다.

기존 항목을 한 번만 갱신하기

기존 MauiImage 와일드카드가 이미 나침반 파일을 포함한다면 그 포함 선언 뒤에 다음 메타데이터 갱신을 넣으세요.

<ItemGroup>
  <MauiImage Update="Resources\Images\compass.svg" BaseSize="48,48" />
</ItemGroup>

Update는 이미 존재하는 항목의 메타데이터를 바꿉니다. 누락된 파일을 항목 목록에 추가하지 않습니다. 프로젝트에 일치하는 포함 선언이 없다면 MauiImage 빌드 작업이나 명시적인 Include로 파일을 한 번 추가하세요. Microsoft의 MSBuild Item 참조는 이 작업들을 구분합니다.

이렇게 하면 이미지 누락 문제를 해결하면서 Include 항목을 반복 추가하는 흔한 시도를 피할 수 있습니다. 먼저 파일이 포함되어 있는지 확인한 다음 메타데이터를 바꾸세요.

PNG를 참조하고 표시 영역 설정하기

기존 MAUI 페이지나 레이아웃 안에 다음 선언을 넣으세요.

<Image Source="compass.png"
       WidthRequest="48"
       HeightRequest="48"
       Aspect="AspectFit"
       SemanticProperties.Description="Compass" />

.png 확장자는 의도적입니다. 너비와 높이는 정사각형 표시 영역을 요청하고 AspectFit은 그 안에서 전체 이미지가 보이게 합니다. 일러스트레이션이 직사각형이라면 정사각형을 채우도록 늘이지 말고 알맞은 표시 영역을 사용하세요. Microsoft의 Image 크기 조절 참조는 맞춤, 자르기, 늘이기를 구분합니다.

나침반 코드는 직접 만든 설정 예제이며 기록된 기기 렌더링 테스트가 아닙니다. 자신의 대상 프로젝트에서 빌드하고 결과 뷰를 살펴보세요. 올바른 파일 이름만으로 특정 아트워크가 의도대로 렌더링되었음을 입증할 수는 없습니다.

BaseSize와 레이아웃 크기는 다른 문제를 해결합니다

BaseSize="48,48"은 MAUI가 밀도별 이미지를 도출하는 기준 치수를 제공합니다. 명시적인 기준 크기가 없으면 MAUI는 SVG 자체의 치수를 사용합니다. Microsoft는 이미지 크기 조절에서 두 규칙을 모두 설명합니다.

이 예제의 소스 그림은 96×96 좌표 공간을 사용하고 요청된 기준 크기와 뷰는 48×48입니다. 이 숫자는 의도적으로 정한 작성 값이며 빌드에서 측정한 출력 치수가 아닙니다. 크기 조절 시 고리는 비율을 유지해야 합니다.

나중에 같은 엠블럼을 훨씬 큰 뷰에 사용한다면 빌드 크기를 검토하고 그 사용 사례도 확인하세요. WidthRequest를 바꿔도 소스 아트워크나 빌드 메타데이터가 편집되지는 않습니다. 반대로 BaseSize를 바꿔도 SVG 내부의 빈 여백은 제거되지 않습니다. 뷰 크기는 올바른데 그 안에서 엠블럼 자체가 너무 작아 보인다면 소스의 그림 경계를 줄이세요.

Resize="false"를 일반적인 선명도 해결책으로 사용하지 마세요. 이 파이프라인에서 벡터 이미지 크기 조절을 비활성화합니다. 문서화된 크기 조절 옵션을 따라 그 동작이 목적일 때만 선택하세요.

누락되거나 예상과 다른 이미지를 순서대로 확인하기

1. 파일 이름과 프로젝트 항목을 확인하세요. compass.svg 같은 소문자 이름을 사용하고 같은 이름의 다른 이미지가 있는지 확인하세요. Microsoft의 이름 지정 규칙은 고유 이미지 이름과 Android 호환 문자를 요구합니다.
2. 뷰의 소스를 확인하세요. 번들 SVG 작업 흐름에서는 XAML 또는 C#에 compass.png를 사용하세요.
3. 원하는 표시 영역과 기준 크기를 비교하세요. 뷰 크기 변경과 빌드 크기 변경은 서로 다른 위치에서 처리합니다.
4. 아트워크 자체를 살펴보세요. 고리 중심이 여전히 뚫려 있나요? 산호색 바늘이 구분되나요? 엠블럼이 중앙에 있나요, 아니면 보이지 않는 소스 여백이 한쪽으로 밀어내나요?

칠을 바꾸는 이미지 메타데이터도 살펴보세요. 프로젝트 이미지 안내는 색조와 배경색용 TintColor 및 Color를 설명합니다. 이 두 색상 예제에서는 모양을 바꾸려는 의도가 없다면 설정하지 마세요. 투명한 구멍이 사라졌는지 더 쉽게 알아볼 수 있도록 실제 페이지 배경에서 이미지를 확인하세요.

런타임에 SVG 동작이 필요한 경우

다운로드한 SVG 콘텐츠, 상호작용 경로, 런타임 편집에는 별도의 구현 결정이 필요합니다. 위의 번들 이미지 안내는 그러한 작업의 지원을 입증하지 않습니다.

예를 들어 Vapolia SVG 샘플 프로젝트는 자체 SvgImage 및 SvgImageSource 컨트롤과 포함 리소스 설정을 설명합니다. 이는 다른 로딩 계약입니다. 도입하기 전에 실제 파일로 렌더러의 지원 기능과 대상 플랫폼을 평가하세요. 일반 Image 선언에서 파일 확장자를 바꾼다고 렌더러가 설치되지는 않습니다.

같은 아트워크도 Flutter의 SVG 이미지 작업 흐름, SwiftUI의 에셋 카탈로그, Android VectorDrawable 가져오기에서는 다른 설정이 필요합니다. 소스 마스터를 재사용하되 각 대상 환경의 규칙을 따르세요.

PNG만 남은 경우 벡터 마스터 준비하기

나침반이나 로고가 PNG로만 있다면 MAUI 프로젝트에 추가하기 전에 PerfectVector로 편집 가능한 SVG 아트워크를 만들 수 있습니다. PNG를 SVG로 변환한 뒤 편집기에서 고리의 구멍, 작은 분리된 조각, 간격을 살펴보세요. 이후 크기나 색상 변경을 위해 깨끗한 마스터를 보관하세요.

벡터화는 MauiImage 선언을 수정하거나 번들 이미지 파이프라인을 런타임 SVG 파서로 바꾸지 않습니다. 소스가 이미 편집 가능한 SVG라면 프로젝트 설정이나 그림을 직접 다루세요. 사진과 질감 있는 아트워크는 래스터 이미지로 더 유용할 수 있습니다. 앱이 SVG 소스를 받는다는 이유만으로 추적하면 별도의 아트워크 판단이 추가됩니다.

FAQ

SVG를 추가했는데 PNG를 참조하는 이유는 무엇인가요? .NET MAUI는 빌드 중 번들 SVG 이미지 소스를 PNG로 변환합니다. 프로젝트에는 SVG를 보관하고 XAML 또는 C#에서 PNG 파일 이름을 참조하세요.

BaseSize가 Image 컨트롤 크기를 설정하나요? BaseSize는 밀도별 빌드 이미지를 도출하는 기준 치수를 설정합니다. 뷰의 레이아웃과 크기 요청이 표시 영역을 제어합니다.

BaseSize를 바꾸려면 다른 MauiImage Include를 추가해야 하나요? 와일드카드를 포함하여 파일이 이미 포함되었는지 확인하세요. 기존 항목의 메타데이터 변경에는 Update를, 항목을 추가해야 할 때만 Include를 사용하세요.

앱 빌드 후 다운로드한 SVG도 이렇게 불러오나요? 번들 이미지 작업 흐름은 런타임 SVG 다운로드와 파싱을 다루지 않습니다. 그 요구 사항에는 런타임 렌더링 방식을 선택하고 테스트하세요.

Sources

1. Microsoft — .NET MAUI 앱 프로젝트에 이미지 추가하기 — SVG에서 PNG로의 처리, 이미지 항목, 파일 이름, 기준 크기, 빌드 메타데이터.
2. Microsoft — Image — 로컬 이미지 참조, 대상 밀도 선택, 뷰 크기, 크기 조절 동작.
3. Microsoft — Item 요소(MSBuild) — Include로 항목을 추가하는 것과 Update로 기존 메타데이터를 바꾸는 것의 차이.
4. Vapolia — SVG 샘플 — 별도의 런타임 SVG 컨트롤과 리소스 로딩 작업 흐름.

래스터로만 있는 앱 엠블럼을 다루고 있나요? PNG를 편집 가능한 SVG로 변환하고 구멍과 간격을 확인한 뒤 마스터를 MAUI에 추가하여 대상 앱에서 생성된 이미지를 살펴보세요.