이미지

2025-04-01

.NET 다중 플랫폼 앱 UI(.NET MAUI) Image 로컬 파일, URI 또는 스트림에서 로드할 수 있는 이미지를 표시합니다. 애니메이션 GIF를 비롯한 표준 플랫폼 이미지 형식이 지원되며 로컬 SVG(확장 가능한 벡터 그래픽) 파일도 지원됩니다. .NET MAUI 앱 프로젝트에 이미지를 추가하는 방법에 대한 자세한 내용은 .NET MAUI 앱 프로젝트이미지 추가를 참조하세요.

Image 다음 속성을 정의합니다.

Aspect형식의 Aspect이미지의 크기 조정 모드를 정의합니다.
IsAnimationPlaying는 bool형식의 애니메이션 GIF가 재생 중인지 아니면 중지되었는지를 결정합니다. 이 속성의 기본값은 false.
bool형식의 IsLoading이미지의 로드 상태를 나타냅니다. 이 속성의 기본값은 false.
bool형식의 IsOpaque렌더링 엔진이 렌더링하는 동안 이미지를 불투명하게 처리할 수 있는지 여부를 나타냅니다. 이 속성의 기본값은 false.
Source은(는) ImageSource형식으로 이미지의 원본을 지정합니다.

이러한 속성은 BindableProperty 개체에 의해 지원됩니다. 즉, 스타일을 지정하고 데이터 바인딩의 대상이 될 수 있습니다.

메모

글꼴 아이콘 데이터를 FontImageSource 개체로 지정하여 Image 글꼴 아이콘을 표시할 수 있습니다. 자세한 내용은 표시 글꼴 아이콘을 참조하세요.

ImageSource 클래스는 다른 원본에서 이미지를 로드하는 데 사용할 수 있는 다음 메서드를 정의합니다.

FromFile은(는) 로컬 파일에서 이미지를 읽는 FileImageSource을 반환합니다.
FromUri는 지정된 URI에서 이미지를 다운로드하고 읽는 UriImageSource을 반환합니다.
FromStream은 이미지 데이터를 제공하는 스트림에서 이미지를 읽는 StreamImageSource을 반환합니다.

XAML에서 파일 이름 또는 URI를 Source 속성의 문자열 값으로 지정하여 파일 및 URI에서 이미지를 로드할 수 있습니다. XAML의 스트림에서 사용자 지정 태그 확장을 통해 이미지를 로드할 수도 있습니다.

중요하다

레이아웃에 의해 Image 크기가 제한되거나 Image HeightRequest 또는 WidthRequest 속성이 지정되지 않는 한 이미지가 전체 해상도로 표시됩니다.

앱에 앱 아이콘 및 시작 화면을 추가하는 방법에 대한 자세한 내용은 앱 아이콘 및 시작 화면참조하세요.

로컬 이미지 로드

이미지를 프로젝트의 Resources\Images 폴더로 끌어 앱 프로젝트에 추가할 수 있습니다. 여기서 빌드 작업은 mauiImage 자동으로 설정됩니다. 빌드 시 벡터 이미지의 크기는 대상 플랫폼 및 디바이스에 대한 올바른 해상도로 조정되고 앱 패키지에 추가됩니다. 이는 플랫폼이 서로 다른 이미지 해상도를 지원하고 운영 체제가 디바이스의 기능에 따라 런타임에 적절한 이미지 해상도를 선택하기 때문에 필요합니다.

Android 리소스 명명 규칙을 준수하려면 모든 로컬 이미지 파일 이름은 소문자여야 하고 문자 문자로 시작하고 끝나야 하며 영숫자 또는 밑줄만 포함해야 합니다. 자세한 내용은 developer.android.com 앱 리소스 개요를 참조하세요.

중요하다

.NET MAUI는 SVG 파일을 PNG 파일로 변환합니다. 그러므로 .NET MAUI 앱 프로젝트에 SVG 파일을 추가할 때, 그 파일은 XAML 또는 C#에서 .png 확장자로 참조되어야 합니다.

파일 이름 지정 및 배치에 대한 이러한 규칙을 준수하면 다음 XAML에서 이미지를 로드하고 표시할 수 있습니다.

<Image Source="dotnet_bot.png" />

해당하는 C# 코드는 다음과 같습니다.

Image image = new Image
{
    Source = ImageSource.FromFile("dotnet_bot.png")
};

ImageSource.FromFile 메서드에는 string 인수가 필요하며 파일에서 이미지를 읽는 새 FileImageSource 개체를 반환합니다. 파일 이름을 Image.Source 속성에 대한 string 인수로 지정할 수 있는 암시적 변환 연산자도 있습니다.

Image image = new Image { Source = "dotnet_bot.png" };

원격 이미지 로드

URI를 Source 속성 값으로 지정하여 원격 이미지를 다운로드하고 표시할 수 있습니다.

<Image Source="https://aka.ms/campus.jpg" />

해당하는 C# 코드는 다음과 같습니다.

Image image = new Image
{
    Source = ImageSource.FromUri(new Uri("https://aka.ms/campus.jpg"))
};

ImageSource.FromUri 메서드에는 Uri 인수가 필요하며 Uri이미지를 읽는 새 UriImageSource 개체를 반환합니다. 문자열 기반 URI에 대한 암시적 변환도 있습니다.

Image image = new Image { Source = "https://aka.ms/campus.jpg" };

이미지 캐싱

다운로드한 이미지의 캐싱은 기본적으로 사용하도록 설정되며 캐시된 이미지는 1일 동안 저장됩니다. 이 동작은 UriImageSource 클래스의 속성을 설정하여 변경할 수 있습니다.

UriImageSource 클래스는 다음 속성을 정의합니다.

Uri형식 Uri은 표시를 위해 다운로드할 이미지의 URI를 나타냅니다.
TimeSpan형식의 CacheValidity이미지가 로컬로 저장되는 기간을 지정합니다. 이 속성의 기본값은 1일입니다.
CachingEnabled, bool유형의, 이미지 캐싱이 사용되는지 여부를 정의합니다. 이 속성의 기본값은 true.

이러한 속성은 BindableProperty 개체에 의해 지원됩니다. 즉, 스타일을 지정하고 데이터 바인딩의 대상이 될 수 있습니다.

특정 캐시 기간을 설정하려면 Source 속성을 CacheValidity 속성을 설정하는 UriImageSource 개체로 설정합니다.

<Image>
    <Image.Source>
        <UriImageSource Uri="https://aka.ms/campus.jpg"
                        CacheValidity="10:00:00:00" />
    </Image.Source>
</Image>

해당하는 C# 코드는 다음과 같습니다.

Image image = new Image();
image.Source = new UriImageSource
{
    Uri = new Uri("https://aka.ms/campus.jpg"),
    CacheValidity = new TimeSpan(10,0,0,0)
};

이 예제에서 캐싱 기간은 10일로 설정됩니다.

스트림에서 이미지 로드

ImageSource.FromStream 메서드를 사용하여 스트림에서 이미지를 로드할 수 있습니다.

Image image = new Image
{
    Source = ImageSource.FromStream(() => stream)
};

중요하다

이미지 캐싱은 ImageSource.FromStream 메서드를 사용하여 스트림에서 이미지를 로드할 때 Android에서 사용하지 않도록 설정됩니다. 이는 적절한 캐시 키를 만들 데이터가 없기 때문입니다.

글꼴 아이콘 로드

FontImage 태그 확장을 사용하면 ImageSource표시할 수 있는 모든 보기에 글꼴 아이콘을 표시할 수 있습니다. FontImageSource 클래스와 동일한 기능을 제공하지만 보다 간결한 표현을 제공합니다.

FontImage 태그 확장은 다음 속성을 정의하는 FontImageExtension 클래스에서 지원됩니다.

글꼴 아이콘이 속한 글꼴 패밀리인 string형식의 FontFamily.
글꼴 아이콘의 유니코드 문자 값은 string형식의 Glyph입니다.
Color형식의 Color 글꼴 아이콘을 표시할 때 사용할 색입니다.
double형식의 Size, 렌더링된 글꼴 아이콘의 크기(디바이스 독립적 단위)입니다. 기본값은 30입니다. 또한 이 속성은 명명된 글꼴 크기로 설정할 수 있습니다.

메모

XAML 파서에서는 FontImageExtension 클래스를 FontImage약어로 사용할 수 있습니다.

Glyph 속성은 FontImageExtension콘텐츠 속성입니다. 따라서 중괄호로 표현된 XAML 태그 식의 경우 첫 번째 인수인 경우 식의 Glyph= 부분을 제거할 수 있습니다.

다음 XAML 예제에서는 FontImage 태그 확장을 사용하는 방법을 보여 줍니다.

<Image BackgroundColor="#D1D1D1"
       Source="{FontImage &#xf30c;, FontFamily=Ionicons, Size=44}" />

이 예제에서는 Ionicons 글꼴 패밀리의 XBox 아이콘을 약식 버전의 FontImageExtension 클래스 이름을 사용하여 Image에 표시합니다.

FontImage 태그 확장의 스크린샷

아이콘의 유니코드 문자가 XAML에서 이스케이프로 처리되어야 하므로 \uf30c은 이 됩니다.

FontImageSource 개체에서 글꼴 아이콘 데이터를 지정하여 글꼴 아이콘을 표시하는 방법에 대한 자세한 내용은 표시 글꼴 아이콘참조하세요.

FontImageSource 개체에서 글꼴 아이콘 데이터를 지정하여 글꼴 아이콘을 표시할 수 있습니다. 자세한 내용은 표시 글꼴 아이콘을 참조하세요.

애니메이션 GIF 로드

.NET MAUI에는 애니메이션이 적용된 작은 GIF 표시 지원이 포함되어 있습니다. 이 작업은 Source 속성을 애니메이션 GIF 파일로 설정하여 수행됩니다.

<Image Source="demo.gif" />

중요하다

.NET MAUI의 애니메이션 GIF 지원에는 파일을 다운로드하는 기능이 포함되어 있지만 애니메이션 GIF의 캐싱 또는 스트리밍은 지원하지 않습니다.

기본적으로 애니메이션 GIF가 로드되면 재생되지 않습니다. 애니메이션 GIF가 재생 중인지 중지되는지 여부를 제어하는 IsAnimationPlaying 속성의 기본값이 false있기 때문입니다. 따라서 애니메이션 GIF가 로드되면 IsAnimationPlaying 속성이 true설정될 때까지 재생되지 않습니다. IsAnimationPlaying 속성을 false다시 설정하여 재생을 중지할 수 있습니다. 이 속성은 GIF가 아닌 이미지 원본을 표시할 때 영향을 주지 않습니다.

이미지 크기 조정 제어

Aspect 속성은 표시 영역에 맞게 이미지의 크기를 조정하는 방법을 결정하며 Aspect 열거형의 멤버 중 하나로 설정해야 합니다.

AspectFit - 이미지가 전체적으로 표시 영역에 맞도록 하기 위해, 이미지의 비율에 따라 폭이 넓거나 세로가 길 경우, 위/아래 또는 측면에 빈 공간이 추가되어 이미지를 상자형으로 설정합니다.
AspectFill - 가로 세로 비율을 유지하면서 표시 영역을 채우도록 이미지를 클립합니다.
Fill - 표시 영역을 완전히 정확하게 채우도록 이미지를 늘입니다. 이로 인해 이미지가 왜곡될 수 있습니다.
Center - 가로 세로 비율을 유지하면서 표시 영역의 이미지를 가운데에 옵니다.

다음을 통해 공유

이미지

로컬 이미지 로드

원격 이미지 로드

이미지 캐싱

스트림에서 이미지 로드

글꼴 아이콘 로드

애니메이션 GIF 로드

이미지 크기 조정 제어

피드백

추가 리소스