Partilhar via

Image.Source Propriedade

  • Referência

Definição

Namespace:
Microsoft.UI.Xaml.Controls
Editar

Obtém ou define a origem da imagem.

public:
 property ImageSource ^ Source { ImageSource ^ get(); void set(ImageSource ^ value); };
ImageSource Source();

void Source(ImageSource value);
public ImageSource Source { get; set; }
var imageSource = image.source;
image.source = imageSource;
Public Property Source As ImageSource
<Image Source="uri"/>

Valor da propriedade

ImageSource

Um objeto que representa o arquivo de origem da imagem desenhada. Normalmente, você define isso com um objeto BitmapImage , construído com o URI (Uniform Resource Identifier) que descreve o caminho para um arquivo de origem de imagem válido. Ou você pode inicializar um BitmapSource com um fluxo, talvez um fluxo de um arquivo de armazenamento.

Comentários

Definir a propriedade Source é inerentemente uma ação assíncrona. Como é uma propriedade, não há uma sintaxe aguardável, mas, para a maioria dos cenários, você não precisa interagir com os aspectos assíncronos do carregamento do arquivo de origem da imagem. A estrutura aguardará o retorno da origem da imagem e executará o layout novamente quando o arquivo de origem da imagem ficar disponível.

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 gera uma exceção. Em vez disso, ele dispara um evento ImageFailed . Falhas de decodificação também disparam ImageFailed. Você pode escrever um manipulador ImageFailed e anexá-lo ao objeto Image para detectar isso e, possivelmente, usar ErrorMessage nos dados do evento para determinar a natureza da falha. Além disso, se você quiser verificar se um arquivo de origem de imagem foi carregado corretamente, poderá manipular o evento ImageOpened no elemento Image .

Definindo a origem em XAML

Você pode definir a propriedade Source como um atributo em XAML. Nesse caso, você está definindo o valor do atributo Source como uma cadeia de caracteres URI (Uniform Resource Identifier) que descreve o local do arquivo de imagem de origem. 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 do construtor BitmapImage(Uri ). Definir a propriedade Source usando uma cadeia de caracteres URI (Uniform Resource Identifier) é um atalho habilitado pelo XAML. Observe que o URI (Uniform Resource Identifier) aqui parece ser um URI (Uniform Resource Identifier) relativo; o suporte ao URI (Uniform Resource Identifier) parcial é outro atalho XAML.

<Image Width="200" Source="Images/myImage.png"/>

O analisador XAML interpreta todas as cadeias de caracteres que representam um URI (Uniform Resource Identifier) relativo usando o URI (Uniform Resource Identifier) base da página XAML que está sendo analisada. Por exemplo, se você especificar um valor "Imagens/myImage.png" em XAML, essa cadeia de caracteres será interpretada como um sufixo de caminho relativo que é acrescentado ao local base do URI (Uniform Resource Identifier) dentro do pacote do aplicativo em que a própria página XAML existe. Se o elemento Image anterior for adicionado a uma página que está na raiz do pacote do aplicativo, o URI (Uniform Resource Identifier) será interpretado como ms-appx:///Images/myImage.png. Se a Imagem for adicionada a uma página que está em uma pasta Pages no aplicativo, o URI (Uniform Resource Identifier) será interpretado como ms-appx:///Pages/Images/myImage.png.

Se a imagem de origem não fizer parte do pacote do aplicativo, você deverá usar um URI (Uniform Resource Identifier) absoluto para definir a propriedade Source em XAML. Para obter mais informações, consulte Como carregar recursos de arquivo e exemplos posteriormente neste documento.

Uma sintaxe de elemento de propriedade em XAML também é possível, especificando um elemento de objeto BitmapImage com origem válida como o valor da propriedade.

Definindo a origem no código

Para definir a propriedade Image.Source no código, é necessária uma instância de BitmapImage (ou BitmapSource), que você também deve construir. Se a origem da imagem for um fluxo, use o método assíncrono SetSourceAsync de BitmapImage para definir as informações de imagem do fluxo.

Se a origem da imagem for um arquivo referenciado pelo URI (Uniform Resource Identifier), defina a propriedade BitmapImage.UriSource ou use o construtor BitmapImage que usa um parâmetro URI (Uniform Resource Identifier). O Windows Runtime impõe que um URI (Uniform Resource Identifier) deve ser absoluto; você não pode usar o URI (Uniform Resource Identifier) relativo em Windows Runtime código. Se você estiver usando um valor .NET Framework System.Uri e usar uma assinatura que exija um valor UriKind, especifique Absolute.

Ao fazer referência ao conteúdo local, você deve incluir o esquema ms-appx: no URI (Uniform Resource Identifier) absoluto que você usa como o BitmapImage.UriSource. No código, você não obtém os atalhos de processamento para combinar partes relativas do URI (Uniform Resource Identifier) e o esquema ms-appx: que acontece automaticamente se você especificar Source como um atributo XAML. Em vez disso, você deve construir explicitamente um URI (Uniform Resource Identifier) absoluto com o esquema apropriado.

Veja como definir a origem para uma imagem do pacote do aplicativo.

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();
Uri uri = new Uri("ms-appx:///Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

// OR

Image img = new Image();
img.Source = new BitmapImage(new Uri("ms-appx:///Assets/Logo.png"));

Windows::UI::Xaml::Controls::Image img;
Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
Windows::Foundation::Uri uri{ L"ms-appx:///Assets/LockScreenLogo.png" };
bitmapImage.UriSource(uri);
img.Source(bitmapImage);

// OR

Windows::UI::Xaml::Controls::Image img;
img.Source(Windows::UI::Xaml::Media::Imaging::BitmapImage{ Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" } });

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
auto uri = ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

// OR

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("ms-appx:///Assets/Logo.png"));

Se você precisar garantir que o controle Imagem esteja pronto antes de tentar usá-lo no código, manipule o evento Loaded e defina a propriedade Source no manipulador de eventos.

Observação

O evento FrameworkElement.Loaded ocorre quando o controle Image é carregado na página XAML. O evento ImageOpened ocorre quando o arquivo de imagem é aberto no controle Image .

Aqui está um exemplo de como definir Image.Source no manipulador para o evento Loaded . Neste exemplo, o objeto Image foi criado em XAML, mas não tem uma origem ou outros valores de propriedade; Em vez disso, esses valores são fornecidos em tempo de execução quando a imagem é carregada de XAML.

<Image Loaded="Image_Loaded"/>

void Image_Loaded(object sender, RoutedEventArgs e)
{
    Image img = sender as Image;
    if (img != null)
    {
        BitmapImage bitmapImage = new BitmapImage();
        img.Width = bitmapImage.DecodePixelWidth = 280;
        bitmapImage.UriSource = new Uri("ms-appx:///Assets/Logo.png");
        img.Source = bitmapImage;
    }
}

void MainPage::Image_Loaded(winrt::Windows::Foundation::IInspectable const& sender, winrt::Windows::UI::Xaml::RoutedEventArgs const& /* e */)
{
    auto img{ sender.as<Windows::UI::Xaml::Controls::Image>() }; // throws if QI fails, so no need for null-check afterwards.
    Windows::UI::Xaml::Media::Imaging::BitmapImage bitmapImage;
    img.Width(280);
    bitmapImage.DecodePixelWidth(280);
    bitmapImage.UriSource(Windows::Foundation::Uri{ L"ms-appx:///Assets/LockScreenLogo.png" });
    img.Source(bitmapImage);
}

void App1::MainPage::Image_Loaded(Platform::Object^ sender, Windows::UI::Xaml::RoutedEventArgs^ e)
{
 auto img = dynamic_cast<Image^>(sender);
 if (img != nullptr)
 {
  auto bitmapImage = ref new BitmapImage();
  img->Width = 280; bitmapImage->DecodePixelWidth = 280;
  bitmapImage->UriSource = ref new Uri("ms-appx:///Assets/Logo.png");
  img->Source = bitmapImage;
 }
}

Você poderá manipular o evento ImageOpened se houver problemas de tempo com a recuperação ou decodificação da origem da imagem, em que talvez seja necessário exibir conteúdo alternativo até que a origem da imagem esteja disponível. Confira Exemplo de imagens XAML para obter um código de exemplo.

Usando um URI relativo no código

Vimos anteriormente que o analisador XAML interpreta um URI (Uniform Resource Identifier) relativo usando o URI (Uniform Resource Identifier) base da página XAML que está sendo analisada. Para obter o mesmo resultado no código, você pode construir um Uri usando um dos construtores que cria um URI (Uniform Resource Identifier) combinando uma base absoluta e, em seguida, um caminho relativo dentro desse local. Para o primeiro parâmetro, chame BaseUri na Página em que a Imagem é carregada. (Você também pode chamar BaseUri na instância image em que você está definindo a origem ou outro elemento na página. Confira o Aviso abaixo.) Isso cria um URI (Uniform Resource Identifier) com o esquema ms-appx: e adiciona o caminho que faz parte do local da página XAML. Para o segundo parâmetro, passe a cadeia de caracteres URI (Uniform Resource Identifier) relativa que descreve o local da imagem de origem.

No C# ou no Microsoft Visual Basic, o tipo Uri é projetado como System.Uri, portanto, use o construtor System.Uri(Uri, String) que usa uma cadeia de caracteres como o segundo parâmetro. Em Extensões de componente do Visual C++ (C++/CX), use Uri(String,String).

<Image x:Name="capturedPhoto"/>

BitmapImage bitmapImage = new BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage.UriSource = new Uri(this.BaseUri, "Assets/placeholder.png");
capturedPhoto.Source = bitmapImage;

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// Call BaseUri on the root Page element and combine it with a relative path
// to consruct an absolute URI.
bitmapImage->UriSource = ref new Windows::Foundation::Uri(BaseUri->AbsoluteUri, "Assets/placeholder.png");
capturedPhoto->Source = bitmapImage;

Observação

Se você instanciar uma nova Imagem no código, a propriedade BaseUri será nula até que a Imagem seja adicionada à árvore visual de uma página. Por exemplo, o código a seguir gera uma exceção ArgumentNull . Para evitar a exceção, adicione a Imagem à árvore visual antes de definir a propriedade Source.

Este exemplo gera uma exceção porque chama BaseUri na Imagem antes que a Imagem seja adicionada à página. Supõe-se que 'stackPanel1' seja um elemento StackPanel declarado em XAML.

Image img = new Image();
BitmapImage bitmapImage = new BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");

bitmapImage.UriSource = uri;
img.Source = bitmapImage;
stackPanel1.Children.Add(img);

auto img = ref new Image();
auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();

// AN EXCEPTION IS THROWN BECAUSE img->BaseUri IS NULL AT THIS POINT.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");

bitmapImage->UriSource = uri;
img->Source = bitmapImage;
stackPanel1->Children->Append(img);

Para evitar esse erro, você pode chamar BaseUri na própria Página , conforme mostrado anteriormente, ou adicionar a Imagem à página antes de chamar BaseUri, conforme mostrado aqui.

Neste exemplo, a Imagem é adicionada à página antes da chamada para BaseUri, portanto , BaseUri não é nulo. Supõe-se que 'stackPanel1' seja um elemento StackPanel declarado em XAML.

Image img = new Image();
// Add the image to the page.
stackPanel1.Children.Add(img);

BitmapImage bitmapImage = new BitmapImage();
// img.BaseUri in not null because img has been added to the page.
Uri uri = new Uri(img.BaseUri, "Assets/Logo.png");
bitmapImage.UriSource = uri;
img.Source = bitmapImage;

auto img = ref new Image();
// Add the image to the page.
stackPanel1->Children->Append(img);

auto bitmapImage = ref new Windows::UI::Xaml::Media::Imaging::BitmapImage();
// img->BaseUri in not null because img has been added to the page.
auto uri = ref new Windows::Foundation::Uri(img->BaseUri->AbsoluteUri, "Assets/Logo.png");
bitmapImage->UriSource = uri;
img->Source = bitmapImage;

Usando arquivos de uma rede

Para usar um arquivo de um local de rede como fonte de imagem, use os esquemas http: ou https: conforme mostrado aqui. Especifique o URI (Uniform Resource Identifier) absoluto. Para obter mais informações, consulte Como carregar recursos de arquivo.

<Image Source="http://www.contoso.com/images/logo.png"/>

Image img = new Image();
img.Source = new BitmapImage(new Uri("http://www.contoso.com/images/logo.png"));

auto img = ref new Image();
img->Source = ref new BitmapImage(ref new Windows::Foundation::Uri("http://www.contoso.com/images/logo.png"));

Usando arquivos do armazenamento local

Para usar arquivos que são colocados no armazenamento local do aplicativo como uma fonte de imagem, use o esquema ms-appdata: , conforme mostrado aqui. Especifique o URI (Uniform Resource Identifier) absoluto. Para obter mais informações, consulte Como carregar recursos de arquivo.

<!-- Access an image file stored in the local folder -->
<Image Source="ms-appdata:///local/images/logo.png"/>

<!-- Access an image file stored in the roaming folder -->
<Image Source="ms-appdata:///roaming/images/logo.png"/>

<!-- Access an image file stored in the temp folder -->
<Image Source="ms-appdata:///temp/images/logo.png"/>

var uri = new System.Uri("ms-appdata:///local/images/logo.png");
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(uri);

Image img = new Image();
img.Source = file;

Usando uma fonte de fluxo para mostrar imagens da biblioteca Imagens

Um uso típico de elementos Image em um aplicativo é mostrar imagens da biblioteca Imagens do usuário. Essas imagens podem ser acessadas programaticamente ou por meio de um FileOpenPicker. Em ambos os casos, o objeto StorageFile obtido pode ser aberto como um fluxo, mas não fornece uma referência de URI (Uniform Resource Identifier) ao arquivo de imagem. Para usar um fluxo como fonte de imagem, você deve escrever um código que define sua instância de Imagem para usar o fluxo. Isso não pode ser feito apenas em XAML.

Para exibir uma imagem individual, use os objetos StorageFile da enumeração da biblioteca e chame OpenAsync para obter um fluxo. Use esse fluxo para definir a origem da imagem, criando um novo BitmapImage, chamando SetSourceAsync e passando o fluxo para usar como o parâmetro streamSource .

Este exemplo mostra como usar um FileOpenPicker para acessar um arquivo de imagem da biblioteca Imagens e defini-lo como a Origem de um controle Image . O código já é aguardado porque está aguardando o usuário escolher um arquivo e só será executado depois que isso acontecer. O fluxo a ser usado vem de StorageFile.OpenAsync depois que uma instância storageFile é retornada das ações do seletor assíncrono. Para obter mais informações sobre como usar seletores de arquivos, consulte Abrir arquivos e pastas com um seletor.

<Button Content="Get photo" Click="GetPhotoButton_Click"/>

<Image x:Name="image1" Width="300"/>

private async void GetPhotoButton_Click(object sender, RoutedEventArgs e)
{
    // Set up the file picker.
    Windows.Storage.Pickers.FileOpenPicker openPicker = 
        new Windows.Storage.Pickers.FileOpenPicker();
    openPicker.SuggestedStartLocation = 
        Windows.Storage.Pickers.PickerLocationId.PicturesLibrary;
    openPicker.ViewMode = 
        Windows.Storage.Pickers.PickerViewMode.Thumbnail;

    // Filter to include a sample subset of file types.
    openPicker.FileTypeFilter.Clear();
    openPicker.FileTypeFilter.Add(".bmp");
    openPicker.FileTypeFilter.Add(".png");
    openPicker.FileTypeFilter.Add(".jpeg");
    openPicker.FileTypeFilter.Add(".jpg");

    // Open the file picker.
    Windows.Storage.StorageFile file = 
        await openPicker.PickSingleFileAsync();

    // 'file' is null if user cancels the file picker.
    if (file != null)
    {
        // Open a stream for the selected file.
        // The 'using' block ensures the stream is disposed
        // after the image is loaded.
        using (Windows.Storage.Streams.IRandomAccessStream fileStream =
            await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
        {
            // Set the image source to the selected bitmap.
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            bitmapImage.SetSource(fileStream);
            image1.Source = bitmapImage;
        }
    }
}

Este exemplo mostra como acessar programaticamente um arquivo de imagem da biblioteca Imagens e defini-lo como a Origem de um controle Image . Para acessar o conteúdo da biblioteca Imagens programaticamente, chame StorageFolder.GetFilesAsync. Lembre-se de que você precisa especificar um recurso para acessar a biblioteca Imagens programaticamente.

protected async override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get the Pictures library
    Windows.Storage.StorageFolder picturesFolder = 
        Windows.Storage.KnownFolders.PicturesLibrary;
    IReadOnlyList<StorageFolder> folders = 
        await picturesFolder.GetFoldersAsync();

    // Process file folders
    foreach (StorageFolder folder in folders)
    {
        // Get and process files in folder
        IReadOnlyList<StorageFile> fileList = await folder.GetFilesAsync();
        foreach (StorageFile file in fileList)
        {
            Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage = 
                new Windows.UI.Xaml.Media.Imaging.BitmapImage();

            // Open a stream for the selected file.
            // The 'using' block ensures the stream is disposed
            // after the image is loaded.
            using (Windows.Storage.Streams.IRandomAccessStream fileStream = 
                await file.OpenAsync(Windows.Storage.FileAccessMode.Read))
            {
                // Set the image source to the selected bitmap.
                Windows.UI.Xaml.Media.Imaging.BitmapImage bitmapImage =
                    new Windows.UI.Xaml.Media.Imaging.BitmapImage();
                bitmapImage.SetSource(fileStream);

                // Create an Image control.  
                Image img = new Image();
                img.Height = 50;
                img.Source = bitmapImage;

                // Add the Image control to the UI. 'imageGrid' is a
                // VariableSizedWrapGrid declared in the XAML page.
                imageGrid.Children.Add(img);
            }
        }
    }
}

Origens de imagens e dimensionamento

Se você estiver fazendo referência a imagens empacotadas em seu aplicativo, deverá criar suas fontes de imagem em vários tamanhos recomendados, para garantir que seu aplicativo fique ótimo quando o Windows Runtime dimensioná-lo. Ao especificar uma Origem para uma Imagem como um URI (Uniform Resource Identifier), você pode usar uma convenção de nomenclatura que referenciará automaticamente o recurso de imagem correto para o dimensionamento atual, conforme detectado pelo sistema em tempo de execução. 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 Design responsivo 101 para ou Comentários na Imagem.

Fontes de imagem e qualificadores de recursos

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 obter mais informações, consulte Sistema de gerenciamento de recursos ou Comentários na Imagem. Para obter mais informações sobre recursos de aplicativo e como empacotar fontes de imagem em um aplicativo, consulte Definindo recursos de aplicativo.

Aplica-se a

Confira também