Carregar imagens e ativos personalizados para escala, tema, alto contraste e outros

  • Artigo

O app 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 tempo de execução. Essas imagens podem ser referenciadas no código imperativo ou na marcação XAML, por exemplo, como a propriedade Source de uma Imagem. Eles também podem aparecer no arquivo de origem do manifesto do pacote do aplicativo (o Package.appxmanifest arquivo), por exemplo, como o valor de Ícone do Aplicativo na guia Ativos Visuais do manifesto do Visual Studio Designer ou em blocos e notificações do sistema. Usando qualificadores nos nomes de arquivo das imagens e, opcionalmente, carregando-os dinamicamente com a ajuda de um ResourceContext, você pode fazer com que o arquivo de imagem que melhor corresponde às configurações de tempo de execução do usuário para escala de exibição, tema, alto contraste, idiomas e outros contextos seja carregado.

Um recurso de imagem está contido em um arquivo de recurso de imagem. Você também pode considerar a imagem como um ativo e o arquivo que o contém como um arquivo de ativo; esses tipos de arquivos de recurso podem ser encontrados na pasta \Assets do projeto. Para informações sobre como usar os qualificadores nos nomes de seus arquivos de recurso de imagem, consulte Ajustar seus recursos para idioma, escala e outros qualificadores.

Alguns qualificadores comuns para imagens são:

Qualificar um recurso de imagem para escala, tema e contraste

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

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

Você pode usar qualificadores nos nomes de pasta, e não nos nomes de arquivo. Essa é uma estratégia melhor quando você tem 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

O exemplo a seguir mostra como você pode fornecer variantes de um recurso de imagem, chamado /Assets/Images/logo.png, para diferentes configurações de escala de exibição, tema e alto contraste. Este exemplo usa a pasta de nomenclatura.

\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

Fazer referência a uma imagem ou outro ativo no código e na marcação XAML

O nome ou identificador de um recurso de imagem é seu caminho e nome de arquivo com todos os qualificadores removidos. Se você nomear pastas e/ou arquivos como qualquer um dos exemplos na seção anterior, terá um recurso de imagem único 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á fazendo referência a um arquivo que vem do pacote do app. Confira Esquemas de URI na documentação da UWP. É assim que 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 app.

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 nestes exemplos, use a sobrecarga do construtor Uri que infere o UriKind. Especifique um URI absoluto válido, incluindo o esquema e a autoridade, ou deixe a autoridade assumir o conjunto de aplicativo como valor padrão no exemplo acima.

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

Observação

Os ms-resource esquemas de URI (para recursos de cadeia de caracteres) e ms-appx(-web) (para imagens e outros ativos) executam a correspondência automática do qualificador para localizar o recurso mais apropriado para o contexto atual. O esquema URI ms-appdata (que é usado para carregar dados de app) não executa nenhuma correspondência automática, mas você pode responder ao conteúdo de ResourceContext.QualifierValues e carregar explicitamente os ativos apropriados a partir dos dados de app usando seu nome de arquivo físico completo no URI. Para obter mais informações sobre dados de aplicativo, consulte Armazenar e recuperar configurações e outros dados de app. Esquemas URI da Web (por exemplo, http, https e ftp) não executam quaisquer correspondências automáticas. Para obter informações sobre o que fazer nesse caso, consulte Hospedando e carregando imagens na nuvem.

Os caminhos absolutos serão uma boa opção se os arquivos de imagem permanecerem onde estão na estrutura do projeto. Se você deseja mover um arquivo de imagem, mas deseja mantê-lo no mesmo local em relação ao seu arquivo de marcação XAML de referência, use um caminho relativo ao arquivo de marcação que o contêm, em vez de usar um caminho absoluto. Se você fizer isso, não precisará usar um esquema de URI. Você ainda tirará proveito da correspondência automática de qualificador nesse caso, mas apenas porque está usando o caminho relativo na marcação XAML.

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

Consulte também Suporte a bloco e notificações do sistema para idioma, escala e alto contraste.

Qualifica um recurso de imagem para targetsize

Você pode usar os qualificadores scale e targetsize em variantes diferentes do mesmo recurso de imagem, mas não poderá usar os dois em uma única variante de um recurso. Além disso, você precisa definir pelo menos uma variante sem um qualificador targetsize. Essa variante deve definir um valor para scale ou deixá-la assumir scale-100 como valor padrão. Portanto, estas 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

Consulte um arquivo de imagem do manifesto do conjunto de aplicativo

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

adicionar recursos, inglês

Isso é tudo o que você precisa fazer; o sistema operacional fará a correspondência automática de qualificador para localizar o recurso mais apropriado para o contexto atual. Para obter uma lista de todos os itens no manifesto do conjunto de aplicativo que você pode localizar ou se qualificar dessa maneira, consulte Itens de manifesto localizáveis.

Qualifica um recurso de imagem para layoutdirection

Consulte Espelhando imagens.

Carregar uma imagem para um idioma ou outro contexto

Para obter mais informações sobre a proposta de valor de localização do aplicativo, consulte Globalização e localização.

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

Mas, pode haver momentos em que seu app deverá substituir as configurações do sistema e ser explícito sobre o idioma, a escala ou outro valor de qualificador a ser usado durante a procura de uma imagem correspondente a ser carregada. Por exemplo, convém controlar exatamente quando as imagens de alto contraste serão carregadas e quais serã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 ResourceMap com GetValue ou TryGetValue.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Contrast"] = "high";
var resourceMap = resourceManager.MainResourceMap;
var namedResource = resourceMap.TryGetValue(@"Files/Assets/Logo.png", resourceContext);
var imageFileBytes = namedResource.ValueAsBytes;

using (var ms = new InMemoryRandomAccessStream())
{
    using (var writer = new DataWriter(ms.GetOutputStreamAt(0)))
    {
        writer.WriteBytes(imageFileBytes);
        writer.StoreAsync().GetResults();
    }
    var image = new BitmapImage();
    image.SetSource(ms);
    this.myXAMLImageElement.Source = image;
}

Por padrão, a classe ResourceManager usa o ResourceContext padrão.

APIs importantes

Confira também