ImageBrush.ImageSource Propriedade
Definição
Importante
Algumas informações se referem a produtos de pré-lançamento que podem ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.
Obtém ou define a origem da imagem exibida por este ImageBrush. No código, você define isso com uma instância de subclasse ImageSource , em XAML, você define isso com um URI como um arquivo de origem da imagem.
public:
property ImageSource ^ ImageSource { ImageSource ^ get(); void set(ImageSource ^ value); };ImageSource ImageSource();
void ImageSource(ImageSource value);public ImageSource ImageSource { get; set; }var imageSource = imageBrush.imageSource;
imageBrush.imageSource = imageSource;Public Property ImageSource As ImageSource<ImageBrush ImageSource="imageUri"/>
Valor da propriedade
Um objeto que representa a origem da imagem, a ser exibido por este ImageBrush quando ele é aplicado ao conteúdo.
Comentários
Definir uma fonte de imagem de um arquivo ou fluxo de origem de imagem é inerentemente uma ação assíncrona. Definir a origem como um valor de URI (Uniform Resource Identifier) que não pode ser resolvido para um arquivo de origem de imagem válido não gerará um erro. Em vez disso, ele dispara um evento ImageFailed no ImageBrush. Se você quiser verificar se um arquivo de origem de imagem foi carregado corretamente, poderá manipular ImageOpened para verificação, além de ImageFailed como uma maneira de fornecer uma fonte de imagem de fallback ou recomposar sua interface do usuário.
Configurando ImageSource em XAML
Você pode definir essa propriedade em XAML, mas, nesse caso, você está definindo o valor do atributo ImageSource como uma cadeia de caracteres que representa um URI (Uniform Resource Identifier). Esse comportamento depende da conversão de tipo subjacente que processa a cadeia de caracteres como um URI (Uniform Resource Identifier) e chama o equivalente interno do construtor BitmapImage(Uri ).
O evento ImageFailed poderá ocorrer se o valor inicial do atributo ImageSource em XAML não especificar uma fonte válida. Você pode usar um caminho relativo para referenciar uma imagem que você empacota com o aplicativo ou um URI (Uniform Resource Identifier) absoluto para fazer referência a uma imagem de um servidor. Se você estiver usando uma fonte de imagem empacotada como parte do aplicativo, é comum usar os esquemas ms-appx ou ms-resource .
Configurando ImageSource no código
Se você definir um ImageBrush usando código, ImageBrush.ImageSource exigirá um BitmapImage (não um URI (Uniform Resource Identifier)) no código. Se a sua origem for um fluxo, use o método SetSourceAsync para iniciar o valor. Se sua origem for um URI (Uniform Resource Identifier) referenciando um arquivo, que inclui conteúdo em seu aplicativo que usa os esquemas ms-appx ou ms-resource , use o construtor BitmapImage que usa um URI (Uniform Resource Identifier). Você também pode considerar a manipulação do evento ImageOpened se houver algum problema de temporização com a recuperação ou decodificação da origem da imagem, em que você pode precisar de conteúdo alternativo para exibir até que a origem da imagem esteja disponível. Consulte Exemplo de imagens XAML , por exemplo, código.
Se você precisar compor um URI em relação a outro objeto na interface do usuário para ajudar a definir o escopo da solicitação de recurso, às vezes você poderá usar a propriedade FrameworkElement.BaseUri , como chamado em outro objeto na interface do usuário. Isso fornece um URI base que é de onde a página XAML vem dentro da estrutura de projeto do aplicativo.
Observação
Você pode usar o tratamento automático para acessar recursos não qualificados com qualificadores de escala e cultura atuais ou usar ResourceManager e ResourceMap com qualificadores para cultura e escala para obter os recursos diretamente. Para saber mais, veja Sistema de gerenciamento de recursos.
Origens de imagens e dimensionamento
Você deve criar suas fontes de imagem em vários tamanhos recomendados, para garantir que seu aplicativo fique ótimo quando Windows 8 dimensioná-lo. Ao especificar um ImageSource para um ImageBrush, você pode usar uma convenção de nomenclatura que referenciará automaticamente o recurso correto para o dimensionamento atual. Para saber mais sobre a convenção de nomenclatura, confira Início rápido: usando recursos de arquivo ou imagem.
Para obter mais informações sobre como projetar para dimensionamento, consulte Diretrizes de UX para layout e dimensionamento.
Para obter mais informações sobre recursos de aplicativo e como empacotar fontes de imagem em um aplicativo, consulte Definindo recursos do aplicativo.
Anotações para versões anteriores
Windows 8
Windows 8 teve um problema com a resolução ImageSource de um valor de URI de atributo XAML, se ImageBrush fizer parte de um estilo ou modelo XAML aplicado a um controle. Às vezes, o uso do controle usaria um URI base específico do componente em vez do URI base apropriado para o estilo ou modelo, que geralmente vem do aplicativo. O problema é corrigido começando com Windows 8.1; o URI base é determinado corretamente para recursos de aplicativo ou recursos de componente, dependendo do escopo que precisa do URI base. Os aplicativos compilados para Windows 8 podem ter usado soluções alternativas para esse comportamento, colocando seus arquivos de origem de imagem no lugar "errado", onde o URI XAML resolve e o aplicativo mostraria as imagens. Se você estiver migrando XAML de Windows 8 para Windows 8.1 deverá testar qualquer uso do ImageBrush em um estilo ou modelo do XAML e verificar se a resolução de imagem em seu aplicativo está funcionando com Windows 8.1. Se você tiver um problema, deverá mover os arquivos de origem da imagem dentro do pacote para que eles estejam no escopo de recurso correto para o novo comportamento.
Os aplicativos que foram compilados para Windows 8, mas estão sendo executados no Windows 8.1, continuam a adotar o comportamento do Windows 8.