스케일, 테마, 고대비 등에 맞춘 이미지와 자산을 로드하세요.

2025-06-10

앱은 디스플레이 배율, 테마, 고대비 및 기타 런타임 컨텍스트에 맞게 조정된 이미지 리소스 파일(또는 기타 자산 파일)을 로드할 수 있습니다. 이러한 이미지는 명령형 코드 또는 XAML 마크업에서 참조할 수 있습니다. 예를 들어, Image의 Source 속성으로 사용할 수 있습니다. 앱 패키지 매니페스트 원본 파일(예: Package.appxmanifest 파일)에 나타날 수 있으며, 예를 들어 Visual Studio 매니페스트 디자이너의 시각적 자산 탭에서 앱 아이콘 값으로 표시되거나 타일 및 알림 메시지에도 나타날 수 있습니다. 이미지의 파일 이름에 한정자를 사용하고 선택적으로 ResourceContext를 활용하여 동적으로 로드하면, 표시 배율, 테마, 고대비, 언어 및 기타 컨텍스트에 맞춰 사용자의 런타임 설정과 가장 잘 일치하는 적절한 이미지 파일이 로드될 수 있습니다.

이미지 리소스는 이미지 리소스 파일에 포함됩니다. 이미지를 자산으로 간주하고 이를 자산 파일로 포함하는 파일로 간주할 수도 있습니다. 프로젝트의 \Assets 폴더에서 이러한 종류의 리소스 파일을 찾을 수 있습니다. 이미지 리소스 파일의 이름에 한정자를 사용하는 방법에 대한 배경 정보는 언어, 크기 조정 및 기타 한정자에 맞게 리소스를 조정하는 방법을 확인하세요.

이미지의 일반적인 한정자는 비율, 테마, 대비및 대상 크기.

크기, 테마 및 대비에 따라 이미지 리소스를 평가하다.

scale 한정자의 기본값은 scale-100. 따라서 이 두 버전은 동등합니다(둘 다 배율 100 또는 배율 1로 이미지를 제공합니다).

\Assets\Images\logo.png
\Assets\Images\logo.scale-100.png

파일 이름 대신 폴더 이름에 한정자를 사용할 수 있습니다. 한정자당 여러 자산 파일이 있는 경우 더 나은 전략이 될 것입니다. 이러한 두 변형은 위의 두 변형과 동일합니다.

\Assets\Images\logo.png
\Assets\Images\scale-100\logo.png

다음은 표시 배율, 테마 및 고대비의 다양한 설정에 대해 이미지 /Assets/Images/logo.png리소스의 변형을 제공하는 방법의 예입니다. 이 예제에서는 폴더 이름을 사용합니다.

\Assets\Images\contrast-standard\theme-dark
	\scale-100\logo.png
	\scale-200\logo.png
\Assets\Images\contrast-standard\theme-light
	\scale-100\logo.png
	\scale-200\logo.png
\Assets\Images\contrast-high
	\scale-100\logo.png
	\scale-200\logo.png

XAML 태그 및 코드에서 이미지 또는 기타 자산 찾아보기

이미지 리소스의 이름 또는 식별자는 모든 한정자가 제거된 경로 및 파일 이름입니다. 이전 섹션의 예제와 같이 폴더 및/또는 파일의 이름을 지정하는 경우 단일 이미지 리소스가 있고 해당 이름(절대 경로)이 있습니다 /Assets/Images/logo.png. XAML 마크업에서 해당 이름을 사용하는 방법은 다음과 같습니다.

<Image x:Name="myXAMLImageElement" Source="ms-appx:///Assets/Images/logo.png"/>

참고하십시오. 앱 패키지에서 가져온 파일을 참조하므로 ms-appx URI 체계를 사용합니다. URI 체계를참조하세요. 명령적 코드에서 동일한 이미지 리소스를 참조하는 방법은 다음과 같습니다.

this.myXAMLImageElement.Source = new BitmapImage(new Uri("ms-appx:///Assets/Images/logo.png"));

앱 패키지에서 임의의 파일을 로드하는 데 사용할 ms-appx 수 있습니다.

var uri = new System.Uri("ms-appx:///Assets/anyAsset.ext");
var storagefile = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

ms-appx-web 스키마는 웹 구획에서 ms-appx과 동일한 파일에 접근합니다.

<WebView x:Name="myXAMLWebViewElement" Source="ms-appx-web:///Pages/default.html"/>

this.myXAMLWebViewElement.Source = new Uri("ms-appx-web:///Pages/default.html");

이러한 예제에 표시된 시나리오의 경우, UriKind를 유추하는 오버로드를 가진 Uri 생성자를 사용하세요. 스킴 및 권한을 포함하여 유효한 절대 URI를 지정하거나, 위의 예시처럼 권한을 앱의 패키지로 기본 설정되도록 두십시오.

이러한 예제 URI에서 스키마("ms-appx" 또는 "ms-appx-web") 다음에 "://"가 따르고 그 뒤에 절대 경로가 오는 방식을 살펴보세요. 절대 경로에서 맨 앞의 "/"는 경로가 패키지의 루트에서 시작되도록 해석하게 합니다.

비고

(ms-resource 경우) 및 (이미지 및 기타 자산의 경우) URI 스키마는 ms-appx(-web) 자동 한정자 일치를 수행하여 현재 컨텍스트에 가장 적합한 리소스를 찾습니다. ms-appdata 앱 데이터를 로드하는 데 사용되는 URI 체계는 이러한 자동 일치를 수행하지 않지만 ResourceContext.QualifierValues의 내용에 응답하고 URI의 전체 실제 파일 이름을 사용하여 앱 데이터에서 적절한 자산을 명시적으로 로드할 수 있습니다. 앱 데이터에 대한 정보는 설정 및 기타 앱 데이터를 저장 및 검색을 참조하세요. 웹 URI 스키마(예: http, https및 ftp)도 자동 일치를 수행하지 않습니다. 이 경우 수행할 작업에 대한 자세한 내용은 클라우드에서 이미지 호스팅 및 로딩를 참조하세요.

이미지 파일이 프로젝트 구조에 있는 위치에 남아 있는 경우 절대 경로는 좋은 선택입니다. 이미지 파일을 이동할 수 있지만 참조하는 XAML 태그 파일을 기준으로 동일한 위치에 유지되도록 주의하는 경우 절대 경로 대신 포함된 태그 파일을 기준으로 하는 경로를 사용할 수 있습니다. 이렇게 하면 URI 체계를 사용할 필요가 없습니다. 이 경우 XAML 마크업에서 상대 경로를 사용하기 때문에 자동 한정자 일치의 이점을 여전히 누릴 수 있습니다.

<Image Source="Assets/Images/logo.png"/>

또한 언어, 크기 조정 및 고대비에 대한 타일 및 토스트 지원을참조하세요.

목표 크기에 적합하도록 이미지 리소스를 설정하기

동일한 이미지 리소스의 서로 다른 변형에서는 scale 및 targetsize 한정자를 각각 사용할 수 있지만, 리소스의 단일 변형에서는 둘 다 사용할 수 없습니다. 또한 TargetSize 한정자 없이 하나 이상의 변형을 정의해야 합니다. 해당 변형은 scale의 값을 정의하거나 기본값을 scale-100으로 둡니다. 따라서 리소스의 이러한 두 가지 변형이 /Assets/Square44x44Logo.png 유효합니다.

\Assets\Square44x44Logo.scale-200.png
\Assets\Square44x44Logo.targetsize-24.png

그리고 이 두 가지 변형은 유효합니다.

\Assets\Square44x44Logo.png // defaults to scale-100
\Assets\Square44x44Logo.targetsize-24.png

그러나 이 변형은 유효하지 않습니다.

\Assets\Square44x44Logo.scale-200_targetsize-24.png

앱 패키지 매니페스트에서 이미지 파일을 참조하세요.

이전 섹션의 두 가지 유효한 예제 중 하나와 같이 폴더 및/또는 파일의 이름을 지정하는 경우 단일 앱 아이콘 이미지 리소스와 해당 이름(상대 경로)이 있습니다 Assets\Square44x44Logo.png. 앱 패키지 매니페스트에서 이름으로 리소스를 참조하기만 하면 됩니다. URI 체계를 사용할 필요가 없습니다.

이것만 하면 됩니다. 그러면 OS가 자동으로 한정자 일치를 수행하여 현재 컨텍스트에 가장 적합한 리소스를 찾습니다. 이러한 방식으로 지역화하거나 정규화할 수 있는 앱 패키지 매니페스트의 모든 항목 목록은 지역화 가능한 매니페스트 항목을 참조하세요.

레이아웃 방향에 맞춘 이미지 리소스 지정

미러링 이미지참조하세요.

특정 언어 또는 다른 컨텍스트에 대한 이미지 로드

앱 지역화의 가치 제안에 대한 자세한 내용은 세계화 및 지역화참조하세요.

기본 ResourceContext(ResourceContext.GetForCurrentView)에는 기본 런타임 컨텍스트(즉, 현재 사용자 및 머신에 대한 설정)를 나타내는 각 한정자 이름에 대한 한정자 값이 포함됩니다. 해당 런타임 컨텍스트의 한정자 값에 맞추어, 이미지 파일은 이름에 포함된 한정자를 기준으로 매칭됩니다.

그러나 앱이 시스템 설정을 재정의하고 일치하는 이미지를 로드할 때 사용할 언어, 크기 조정 또는 기타 한정자 값을 명시적으로 지정하려는 경우가 있을 수 있습니다. 예를 들어, 고대비 이미지를 언제, 어떤 것을 로드할지 정확히 제어하고 싶을 수 있습니다.

기본값을 사용하는 대신 새 ResourceContext 를 생성하고, 값을 재정의한 다음, 이미지 조회에서 해당 컨텍스트 개체를 사용하여 이 작업을 수행할 수 있습니다.

var resourceContext = new Windows.ApplicationModel.Resources.Core.ResourceContext(); // not using ResourceContext.GetForCurrentView 
resourceContext.QualifierValues["Contrast"] = "high";
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
var resourceCandidate = namedResource.Resolve(resourceContext);
var imageFileStream = resourceCandidate.GetValueAsStreamAsync().GetResults();
var bitmapImage = new Windows.UI.Xaml.Media.Imaging.BitmapImage();
bitmapImage.SetSourceAsync(imageFileStream);
this.myXAMLImageElement.Source = bitmapImage;

전역 수준에서 동일한 효과를 얻으려면 기본 ResourceContext의 한정자 값을 재정의할 수 있습니다. 대신 ResourceContext.SetGlobalQualifierValue를 호출하는 것이 좋습니다. 값을 한 번 설정하려면 SetGlobalQualifierValue을 호출하고 그러면 조회할 때마다 기본 ResourceContext에 해당 값이 적용됩니다. 기본적으로 ResourceManager 클래스는 기본 ResourceContext를 사용합니다.

Windows.ApplicationModel.Resources.Core.ResourceContext.SetGlobalQualifierValue("Contrast", "high");
var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
this.myXAMLImageElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);

한정 조건 값 변경 이벤트에 대한 응답으로 이미지 업데이트 중

실행 중인 앱은 기본 리소스 컨텍스트의 한정자 값에 영향을 주는 시스템 설정의 변경 내용에 응답할 수 있습니다. 이러한 시스템 설정은 MapChanged 이벤트를 ResourceContext.QualifierValues에서 호출합니다.

이 이벤트에 대한 응답으로 ResourceManager 기본적으로 사용하는 기본 ResourceContext사용하여 이미지를 다시 로드할 있습니다.

public MainPage()
{
    this.InitializeComponent();

    ...

    // Subscribe to the event that's raised when a qualifier value changes.
    var qualifierValues = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues;
    qualifierValues.MapChanged += new Windows.Foundation.Collections.MapChangedEventHandler<string, string>(QualifierValues_MapChanged);
}

private async void QualifierValues_MapChanged(IObservableMap<string, string> sender, IMapChangedEventArgs<string> @event)
{
    var dispatcher = this.myImageXAMLElement.Dispatcher;
    if (dispatcher.HasThreadAccess)
    {
        this.RefreshUIImages();
    }
    else
    {
        await dispatcher.RunAsync(Windows.UI.Core.CoreDispatcherPriority.Normal, () => this.RefreshUIImages());
    }
}

private void RefreshUIImages()
{
    var namedResource = Windows.ApplicationModel.Resources.Core.ResourceManager.Current.MainResourceMap[@"Files/Assets/Logo.png"];
    this.myImageXAMLElement.Source = new Windows.UI.Xaml.Media.Imaging.BitmapImage(namedResource.Uri);
}

중요 API

리소스 컨텍스트
ResourceContext.SetGlobalQualifierValue
MapChanged