Carregue imagens e recursos personalizados para escala, tema, alto contraste e muito mais.

2025-06-10

Seu aplicativo pode carregar arquivos de recurso de imagem (ou outros arquivos de ativo) personalizados para fator de escala de exibição, tema, alto contraste e outros contextos de runtime. Essas imagens podem ser referenciadas do código imperativo ou da marcação XAML, por exemplo, como a propriedade Source de um Image. Eles também podem aparecer no arquivo de origem do manifesto do pacote do aplicativo (o arquivo Package.appxmanifest)—por exemplo, como o valor para App Icon na guia Visual Assets do Visual Studio Manifest Designer—ou em seus tiles e toasts. Usando qualificadores nos nomes de arquivo de suas imagens e, opcionalmente, carregando-os dinamicamente com a ajuda de um ResourceContext, você pode fazer com que o arquivo de imagem mais apropriado seja carregado que melhor corresponda às configurações de runtime do usuário para escala de exibição, tema, alto contraste, idioma e outros contextos.

Um recurso de imagem está contido em um arquivo de recurso de imagem. Você também pode pensar na imagem como um ativo e no arquivo que a contém como um arquivo de ativo; e você pode encontrar esses tipos de arquivos de recurso na pasta \Assets do projeto. Para obter informações sobre como usar qualificadores nos nomes dos arquivos de recursos de imagem, consulte Personalizar seus recursos para idioma, escala e outros qualificadores.

Alguns qualificadores comuns para imagens são escala, tema, contrastee tamanho de destino.

Qualificar um recurso de imagem para escala, tema e contraste

O valor padrão do qualificador de scale é scale-100. Portanto, essas duas variantes são equivalentes (ambas fornecem uma imagem na escala 100 ou o fator de escala 1).

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

Você pode usar qualificadores em nomes de pasta em vez de nomes de arquivo. Essa seria uma estratégia melhor se você tivesse vários arquivos de ativos por qualificador. Para fins de ilustração, essas duas variantes são equivalentes às duas acima.

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

Em seguida, há um exemplo de como você pode fornecer variantes de um recurso de imagem, nomeado /Assets/Images/logo.png, para diferentes configurações de escala de exibição, tema e alto contraste. Este exemplo usa nomeação de pastas.

\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

Referenciar uma imagem ou outro recurso a partir da marcação XAML e do código

O nome — ou identificador — de um recurso de imagem é seu caminho e nome de arquivo com todo e qualquer qualificador removido. Se você nomear pastas e/ou arquivos como em qualquer um dos exemplos na seção anterior, você terá um único recurso de imagem e seu nome (como um caminho absoluto) será /Assets/Images/logo.png. Veja como usar esse nome na marcação XAML.

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

Observe que você usa o esquema de URI ms-appx porque está se referindo a um arquivo proveniente do pacote do aplicativo. Consulte esquemas de URI. E veja como você se refere ao mesmo recurso de imagem no código imperativo.

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

Você pode usar ms-appx para carregar qualquer arquivo arbitrário do pacote do aplicativo.

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

O esquema ms-appx-web acessa os mesmos arquivos que ms-appx, mas no compartimento da Web.

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

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

Para qualquer um dos cenários mostrados nesses exemplos, use a sobrecarga do construtor Uri que deduz o UriKind. Especifique um URI absoluto válido, incluindo o esquema e a autoridade, ou apenas deixe a autoridade padrão para o pacote do aplicativo como no exemplo acima.

Observe como nestes URIs de exemplo o esquema ("ms-appx" ou "ms-appx-web") é seguido por "://" que é seguido por um caminho absoluto. Em um caminho absoluto, o "/" inicial faz com que o caminho seja interpretado a partir da raiz do pacote.

Observação

Os esquemas URI ms-resource (para strings de recursos ) e ms-appx(-web) (para imagens e outros ativos) executam uma correspondência automática de qualificadores para encontrar o recurso mais apropriado para o contexto atual. O esquema de URI ms-appdata (que é usado para carregar dados do aplicativo) não executa essa correspondência automática, mas você pode responder ao conteúdo de ResourceContext.QualifierValues e carregar explicitamente os ativos apropriados dos dados do aplicativo usando o nome completo do arquivo físico no URI. Para obter informações sobre dados do aplicativo, consulte Store e recupere as configurações e outros dados do aplicativo. Os esquemas de URI da Web (por exemplo, http, httpse ftp) também não executam correspondência automática. Para obter informações sobre o que fazer nesse caso, consulte Hospedagem e carregamento de imagens na nuvem.

Caminhos absolutos são uma boa opção se os arquivos de imagem permanecerem onde estão na estrutura do projeto. Se você quiser poder mover um arquivo de imagem, mas tiver cuidado para que ele permaneça no mesmo local em relação ao arquivo de marcação XAML de referência, em vez de um caminho absoluto, talvez você queira usar um caminho relativo ao arquivo de marcação que contém. Se você fizer isso, não será necessário usar um esquema de URI. Você ainda se beneficiará da correspondência automática de qualificadores neste caso, mas isso ocorre apenas porque você está usando o caminho relativo na marcação XAML.

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

Consulte também suporte a blocos e notificações para linguagem, escala e alto contraste.

Qualificar um recurso de imagem para o tamanho-alvo

Você pode usar os qualificadores scale e targetsize em variantes diferentes do mesmo recurso de imagem; mas você não pode usá-los em uma única variante de um recurso. Além disso, você precisa definir pelo menos uma variante sem um qualificador de TargetSize. Essa variante deve definir um valor para scaleou deixar como padrão scale-100. Portanto, essas duas variantes do recurso /Assets/Square44x44Logo.png são válidas.

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

E essas duas variantes são válidas.

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

Mas essa variante não é válida.

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

Faça referência a um arquivo de imagem do manifesto do pacote do aplicativo

Se você nomear pastas e/ou arquivos como em qualquer um dos dois exemplos válidos na seção anterior, você terá um único recurso de imagem de ícone de aplicativo e seu nome (como um caminho relativo) será Assets\Square44x44Logo.png. No manifesto do pacote do aplicativo, basta consultar o recurso pelo nome. Não é necessário usar nenhum esquema de URI.

Isso é tudo o que você precisa fazer, e o sistema operacional executará a combinação automática de qualificadores para encontrar o recurso mais apropriado para o contexto atual. Para obter uma lista de todos os itens no manifesto do pacote do aplicativo que você pode localizar ou qualificar dessa maneira, consulte Itens de manifesto localizáveis.

Qualificar um recurso de imagem para direção de layout

Veja imagens refletidas.

Carregar uma imagem para um idioma específico ou outro contexto

Para obter mais informações sobre a proposta de valor de adaptar seu aplicativo para diferentes mercados, consulte Globalização e localização.

O ResourceContext padrão (obtido de ResourceContext.GetForCurrentView) contém um valor qualificador para cada nome qualificador, representando o contexto de tempo de execução padrão (em outras palavras, as configurações atuais do usuário e do computador). Os arquivos de imagem são comparados, com base nos qualificadores em seus nomes, com os valores do qualificador nesse contexto de execução.

Mas pode haver momentos em que você deseja que seu aplicativo substitua as configurações do sistema e seja explícito sobre o idioma, a escala ou outro valor qualificador a ser usado ao procurar uma imagem correspondente para carregar. Por exemplo, talvez você queira controlar exatamente quando e quais imagens de alto contraste são carregadas.

Você pode fazer isso construindo um novo ResourceContext (em vez de usar o padrão), substituindo seus valores e, em seguida, usando esse objeto de contexto em suas pesquisas de imagem.

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;

Para obter o mesmo efeito em um nível global, você pode substituir os valores dos qualificadores no ResourceContext padrão. Mas, em vez disso, aconselhamos que você chame ResourceContext.SetGlobalQualifierValue. Você define valores uma vez ao chamar SetGlobalQualifierValue, e, em seguida, esses valores estão em vigor no contexto padrão de ResourceContext sempre que você o utiliza para consultas. Por padrão, a classe ResourceManager usa o ResourceContextpadrão.

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);

Atualizando imagens em resposta a eventos de alteração de valor qualificador

Seu aplicativo em execução pode responder a alterações nas configurações do sistema que afetam os valores do qualificador no contexto de recurso padrão. Qualquer uma dessas configurações do sistema invoca o evento MapChanged em ResourceContext.QualifierValues.

Em resposta a esse evento, você pode recarregar suas imagens com a ajuda do ResourceContext padrão, que o ResourceManager usa por padrão.

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);
}

APIs importantes

Contexto de Recursos
ResourceContext.SetGlobalQualifierValue
MapaAlterado