Carregar imagens e ativos personalizados para escala, tema, alto contraste e outrosLoad images and assets tailored for scale, theme, high contrast, and others

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.Your app can load image resource files (or other asset files) tailored for display scale factor, theme, high contrast, and other runtime contexts. Essas imagens podem ser referenciadas no código imperativo ou na marcação XAML, por exemplo, como a propriedade Source de uma Imagem .These images can be referenced from imperative code or from XAML markup, for example as the Source property of an Image . Elas também podem aparecer no arquivo de origem do manifesto do pacote de aplicativos (o arquivo Package.appxmanifest), por exemplo, como o valor do ícone de aplicativo na guia Ativos Visuais do Designer de Manifesto do Visual Studio, ou em seus blocos e notificações do sistema.They can also appear in your app package manifest source file (the Package.appxmanifest file)—for example, as the value for App Icon on the Visual Assets tab of the Visual Studio Manifest Designer—or on your tiles and toasts. 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.By using qualifiers in your images' file names, and optionally dynamically loading them with the help of a ResourceContext, you can cause the most appropriate image file to be loaded that best matches the user's runtime settings for display scale, theme, high contrast, language, and other contexts.

Um recurso de imagem está contido em um arquivo de recurso de imagem.An image resource is contained in an image resource file. 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.You can also think of the image as an asset, and the file that contains it as an asset file; and you can find these kinds of resource files in your project's \Assets folder. 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.For background on how to use qualifiers in the names of your image resource files, see Tailor your resources for language, scale, and other qualifiers.

Alguns qualificadores comuns para imagens são scale, theme, contrast e targetsize.Some common qualifiers for images are scale, theme, contrast, and targetsize.

Qualificar um recurso de imagem para escala, tema e contrasteQualify an image resource for scale, theme, and contrast

O valor padrão do qualificador scale é scale-100.The default value for the scale qualifier is scale-100. Portanto, essas duas variantes são equivalentes (elas fornecem uma imagem em escala 100 ou fator de escala 1).So, these two variants are equivalent (they both provide an image at scale 100, or scale factor 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.You can use qualifiers in folder names instead of file names. Essa será uma estratégia melhor se você tiver vários arquivos de ativo por qualificador.That would be a better strategy if you have several asset files per qualifier. Para fins de ilustração, essas duas variantes são equivalentes às duas acima.For purposes of illustration, these two variants are equivalent to the two above.

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

Veja a seguir um exemplo de como você pode fornecer variantes de um recurso de imagem, —denominado /Assets/Images/logo.png—, para as diferentes configurações de escala de exibição, tema e alto contraste.Next is an example of how you can provide variants of an image resource—named /Assets/Images/logo.png—for different settings of display scale, theme, and high contrast. Este exemplo usa a pasta de nomenclatura.This example uses folder naming.

\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 XAMLReference an image or other asset from XAML markup and code

O nome —ou identificador— de um recurso de imagem é seu caminho e nome de arquivo com todos os qualificadores removidos.The name—or identifier—of an image resource is its path and file name with any and all qualifiers removed. 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.If you name folders and/or files as in any of the examples in the previous section, then you have a single image resource and its name (as an absolute path) is /Assets/Images/logo.png. Veja como usar esse nome na marcação XAML.Here’s how you use that name in XAML markup.

<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.Notice that you use the ms-appx URI scheme because you're referring to a file that comes from your app's package. Consulte Esquemas de URI.See URI schemes. Veja também como fazer referência ao mesmo recurso de imagem no código imperativo.And here’s how you refer to the same image resource in imperative code.

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.You can use ms-appx to load any arbitrary file from your app package.

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.The ms-appx-web scheme accesses the same files as ms-appx, but in the web compartment.

<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.For any of the scenarios shown in these examples, use the Uri constructor overload that infers the 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.Specify a valid absolute URI including the scheme and authority, or just let the authority default to the app's package as in the example above.

Observe como, nestes URIs de exemplo, o esquema ("ms-appx" ou "ms-appx-web") é seguido por "://", que é acompanhado por um caminho absoluto.Notice how in these example URIs the scheme ("ms-appx" or "ms-appx-web") is followed by "://" which is followed by an absolute path. Em um caminho absoluto, o símbolo "/" à esquerda faz com que o caminho seja interpretado da raiz do pacote.In an absolute path, the leading "/" causes the path to be interpreted from the root of the package.

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 de qualificador automática para localizar o recurso mais apropriado para o contexto atual.The ms-resource (for string resources) and ms-appx(-web) (for images and other assets) URI schemes perform automatic qualifier matching to find the resource that's most appropriate for the current context. 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.The ms-appdata URI scheme (which is used to load app data) does not perform any such automatic matching, but you can respond to the contents of ResourceContext.QualifierValues and explicitly load the appropriate assets from app data using their full physical file name in the URI. Para obter mais informações sobre dados de aplicativo, consulte Armazenar e recuperar configurações e outros dados de app.For info about app data, see Store and retrieve settings and other app data. Esquemas URI da Web (por exemplo, http, https e ftp) não executam quaisquer correspondências automáticas.Web URI schemes (for example, http, https, and ftp) do not perform automatic matching, either. Para obter informações sobre o que fazer nesse caso, consulte Hospedando e carregando imagens na nuvem.For info about what to do in that case, see Hosting and loading images in the cloud.

Os caminhos absolutos serão uma boa opção se os arquivos de imagem permanecerem onde estão na estrutura do projeto.Absolute paths are a good choice if your image files remain where they are in the project structure. 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.If you want to be able to move an image file, but you're careful that it remains in the same location relative to its referencing XAML markup file, then instead of an absolute path you might want to use a path that's relative to the containing markup file. Se você fizer isso, não precisará usar um esquema de URI.If you do that, then you needn't use a URI scheme. 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.You will still benefit from automatic qualifier matching in this case, but only because you are using the relative path in XAML markup.

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

Consulte também Suporte a bloco e notificações do sistema para idioma, escala e alto contraste.Also see Tile and toast support for language, scale, and high contrast.

Qualifica um recurso de imagem para targetsizeQualify an image resource for 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.You can use the scale and targetsize qualifiers on different variants of the same image resource; but you can't use them both on a single variant of a resource. Além disso, você precisa definir pelo menos uma variante sem um qualificador TargetSize.Also, you need to define at least one variant without a TargetSize qualifier. Essa variante deve definir um valor para scale ou deixá-la assumir scale-100 como valor padrão.That variant must either define a value for scale, or let it default to scale-100. Portanto, estas duas variantes do recurso /Assets/Square44x44Logo.png são válidas.So, these two variants of the /Assets/Square44x44Logo.png resource are valid.

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

E essas duas variantes são válidas.And these two variants are valid.

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

Mas essa variante não é válida.But this variant is not valid.

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

Consulte um arquivo de imagem do manifesto do conjunto de aplicativoRefer to an image file from your app package manifest

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.If you name folders and/or files as in either of the two valid examples in the previous section, then you have a single app icon image resource and its name (as a relative path) is Assets\Square44x44Logo.png. No manifesto do conjunto de aplicativo, basta fazer referência ao recurso pelo nome.In your app package manifest, simply refer to the resource by name. Não é necessário para usar qualquer esquema de URI.There's no need to use any URI scheme.

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.That's all you need to do, and the OS will perform automatic qualifier matching to find the resource that's most appropriate for the current context. 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.For a list of all items in the app package manifest that you can localize or otherwise qualify in this way, see Localizable manifest items.

Qualifica um recurso de imagem para layoutdirectionQualify an image resource for layoutdirection

Consulte Espelhando imagens.See Mirroring images.

Carregar uma imagem para um idioma ou outro contextoLoad an image for a specific language or other context

Para obter mais informações sobre a proposta de valor de localização do aplicativo, consulte Globalização e localização.For more info about the value proposition of localizing your app, see Globalization and localization.

O ResourceContext padrão (obtido em ResourceContext.GetForCurrentView) contém um valor de qualificador para cada nome de qualificador, representando o contexto de tempo de execução padrão (em outras palavras, as configurações do usuário atual e da máquina).The default ResourceContext (obtained from ResourceContext.GetForCurrentView) contains a qualifier value for each qualifier name, representing the default runtime context (in other words, the settings for the current user and machine). Os arquivos de imagem são comparados—, com base nos qualificadores contidos em seus nomes—, com os valores de qualificador nesse contexto de tempo de execução.Image files are matched—based on the qualifiers in their names—against the qualifier values in that runtime context.

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.But there might be times when you want your app to override the system settings and be explicit about the language, scale, or other qualifier value to use when looking for a matching image to load. Por exemplo, convém controlar exatamente quando as imagens de alto contraste serão carregadas e quais serão carregadas.For example, you might want to control exactly when and which high contrast images are loaded.

Você pode fazer isso criando um novo ResourceContext , em vez de usar o padrão, substituindo seus valores e, em seguida, usando esse objeto de contexto em pesquisas de imagem.You can do that by constructing a new ResourceContext (instead of using the default one), overriding its values, and then using that context object in your image lookups.

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 de qualificador no ResourceContext padrão.For the same effect at a global level, you can override the qualifier values in the default ResourceContext . Mas, em vez disso, recomendamos que você chame ResourceContext.SetGlobalQualifierValue.But instead we advise you to call ResourceContext.SetGlobalQualifierValue. Você define valores de uma só vez com uma chamada para SetGlobalQualifierValue , e esses valores estarão em vigor no ResourceContext padrão cada vez que você usá-lo nas pesquisas.You set values one time with a call to SetGlobalQualifierValue and then those values are in effect on the default ResourceContext each time you use it for lookups. Por padrão, a classe ResourceManager usa o ResourceContext padrão.By default, the ResourceManager class uses the default 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);

Atualizando imagens em resposta aos eventos de alteração de valor de qualificadorUpdating images in response to qualifier value change events

O app em execução pode responder às alterações feitas nas configurações do sistema que afetam os valores de qualificador no contexto de recurso padrão.Your running app can respond to changes in system settings that affect the qualifier values in the default resource context. Qualquer uma dessas configurações de sistema invoca o evento MapChanged em ResourceContext.QualifierValues.Any of these system settings invokes the MapChanged event on 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.In response to this event, you can reload your images with the help of the default ResourceContext , which ResourceManager uses by default.

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 importantesImportant APIs