Image.Source Propiedad

  • Referencia

Definición

Espacio de nombres:
Windows.UI.Xaml.Controls
Editar

Obtiene o establece el origen de la imagen.

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 de propiedad

ImageSource

Objeto que representa el archivo de origen de la imagen dibujada. Normalmente, se establece con un objeto BitmapImage , construido con el identificador uniforme de recursos (URI) que describe la ruta de acceso a un archivo de origen de imagen válido. O bien, puede inicializar un objeto BitmapSource con una secuencia, quizás una secuencia de un archivo de almacenamiento.

Comentarios

Establecer la propiedad Source es intrínsecamente una acción asincrónica. Dado que es una propiedad, no hay una sintaxis que se puede esperar, pero en la mayoría de los escenarios no es necesario interactuar con los aspectos asincrónicos de la carga de archivos de origen de imágenes. El marco esperará a que se devuelva el origen de la imagen y volverá a ejecutar el diseño cuando el archivo de origen de la imagen esté disponible.

Establecer el origen en un valor de identificador uniforme de recursos (URI) que no se puede resolver en un archivo de origen de imagen válido no produce una excepción. En su lugar, desencadena un evento ImageFailed . Los errores de descodificación también activan ImageFailed. Puede escribir un controlador ImageFailed y adjuntarlo al objeto Image para detectarlo y, posiblemente, usar errorMessage en datos de eventos para determinar la naturaleza del error. Además, si desea comprobar que un archivo de origen de imagen se cargó correctamente, puede controlar el evento ImageOpened en el elemento Image .

Establecer origen en XAML

Puedes establecer la propiedad Source como un atributo en XAML. En este caso, va a establecer el valor del atributo Source como una cadena de identificador uniforme de recursos (URI) que describe la ubicación del archivo de imagen de origen. Este comportamiento se basa en la conversión de tipos subyacente que procesa la cadena como identificador uniforme de recursos (URI) y llama al equivalente del constructor BitmapImage(Uri). Establecer la propiedad Source mediante una cadena de identificador uniforme de recursos (URI) es un acceso directo habilitado por XAML. Tenga en cuenta que el identificador uniforme de recursos (URI) aquí parece ser un identificador uniforme de recursos relativo (URI); la compatibilidad con el identificador uniforme de recursos (URI) parcial es otro acceso directo XAML.

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

El analizador XAML interpreta las cadenas que representan un identificador uniforme de recursos (URI) relativo mediante el identificador uniforme de recursos (URI) base de la página XAML que se analiza. Por ejemplo, si especificas un valor "Images/myImage.png" en XAML, esa cadena se interpreta como un sufijo de ruta de acceso relativo que se anexa a la ubicación base del identificador uniforme de recursos (URI) dentro del paquete de la aplicación donde existe la propia página XAML. Si el elemento Image anterior se agrega a una página que se encuentra en la raíz del paquete de la aplicación, el identificador uniforme de recursos (URI) se interpreta como ms-appx:///Images/myImage.png. Si la imagen se agrega a una página que se encuentra en una carpeta Pages de la aplicación, el identificador uniforme de recursos (URI) se interpreta como ms-appx:///Pages/Images/myImage.png.

Si la imagen de origen no forma parte del paquete de la aplicación, debes usar un identificador uniforme de recursos (URI) absoluto para establecer la propiedad Source en XAML. Para obtener más información, consulte Carga de recursos de archivos y ejemplos más adelante en este documento.

También es posible una sintaxis de elemento de propiedad en XAML, especificando un elemento de objeto BitmapImage con un origen válido como valor de propiedad.

Establecer el origen en el código

Para establecer la propiedad Image.Source en el código, se requiere una instancia de BitmapImage (o BitmapSource), que también debe construir. Si el origen de la imagen es una secuencia, use el método async SetSourceAsync de BitmapImage para definir la información de imagen de la secuencia.

Si el origen de la imagen es un archivo al que hace referencia el identificador uniforme de recursos (URI), establezca la propiedad BitmapImage.UriSource o use el constructor BitmapImage que toma un parámetro de identificador uniforme de recursos (URI). El Windows Runtime exige que un identificador uniforme de recursos (URI) sea absoluto; no se puede usar el identificador uniforme de recursos (URI) relativo en Windows Runtime código. Si usa un valor System.Uri de .NET Framework y usa una firma que requiere un valor UriKind , asegúrese de especificar Absolute.

Al hacer referencia al contenido local, debe incluir el esquema ms-appx: en el identificador uniforme absoluto de recursos (URI) que se usa como BitmapImage.UriSource. En el código, no obtienes los accesos directos de procesamiento para combinar elementos relativos de identificador uniforme de recursos (URI) y el esquema ms-appx: que se produce automáticamente si especificas Source como atributo XAML. En su lugar, debe construir explícitamente un identificador uniforme de recursos (URI) absoluto con el esquema adecuado.

Aquí se muestra cómo establecer el origen en una imagen del paquete de la aplicación.

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

Si necesita asegurarse de que el control Image está listo antes de intentar usarlo en el código, controle el evento Loaded y establezca la propiedad Source en el controlador de eventos.

Nota

El evento FrameworkElement.Loaded se produce cuando el control Image se carga en la página XAML. El evento ImageOpened se produce cuando el archivo de imagen se abre en el control Image .

Este es un ejemplo de configuración de Image.Source en el controlador para el evento Loaded . En este ejemplo, el objeto Image se creó en XAML, pero no tiene un origen ni ningún otro valor de propiedad; en su lugar, estos valores se proporcionan en tiempo de ejecución cuando la imagen se carga desde 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;
 }
}

Puede controlar el evento ImageOpened si hay algún problema de tiempo con la recuperación o descodificación del origen de la imagen, donde es posible que necesite contenido alternativo para mostrarse hasta que el origen de la imagen esté disponible. Consulta ejemplo de imágenes XAML para obtener código de ejemplo.

Uso de un URI relativo en el código

Anteriormente vimos que el analizador XAML interpreta un identificador uniforme de recursos (URI) relativo mediante el identificador uniforme de recursos (URI) base de la página XAML que se analiza. Para lograr el mismo resultado en el código, puede construir un URI mediante uno de los constructores que crea un identificador uniforme de recursos (URI) combinando una base absoluta y, a continuación, una ruta de acceso relativa dentro de esa ubicación. Para el primer parámetro, llame a BaseUri en page donde se carga la imagen . (También puede llamar a BaseUri en la instancia de imagen donde se establece el origen u otro elemento de la página. Consulte la precaución a continuación). Esto crea un identificador uniforme de recursos (URI) con el esquema ms-appx: y agrega la ruta de acceso que forma parte de la ubicación de la página XAML. Para el segundo parámetro, pase la cadena relativa del identificador uniforme de recursos (URI) que describe la ubicación de la imagen de origen.

En C# o Microsoft Visual Basic, el tipo de URI se proyecta como System.Uri, por lo que use el constructor System.Uri(Uri,String) que toma una cadena como segundo parámetro. En las extensiones de componentes de 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 = winrt::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(winrt::Windows::Foundation::Uri(BaseUri().AbsoluteUri(), L"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;

Nota

Si crea una instancia de una nueva imagen en el código, la propiedad BaseUri es null hasta que se agrega la imagen al árbol visual de una página. Por ejemplo, el código siguiente produce una excepción ArgumentNull . Para evitar la excepción, agregue la imagen al árbol visual antes de establecer la propiedad Source.

En este ejemplo se produce una excepción porque llama a BaseUri en la imagen antes de agregar la imagen a la página. Se supone que "stackPanel1" es un elemento StackPanel declarado en 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);

Image img;
BitmapImage bitmapImage;

// AN EXCEPTION IS THROWN BECAUSE img.BaseUri IS NULL AT THIS POINT.
Uri uri(img.BaseUri(), L"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 este error, puede llamar a BaseUri en la propia página , como se ha mostrado anteriormente, o agregar la imagen a la página antes de llamar a BaseUri, como se muestra aquí.

En este ejemplo, la imagen se agrega a la página antes de la llamada a BaseUri, por lo que BaseUri no es null. Se supone que "stackPanel1" es un elemento StackPanel declarado en 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;

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

BitmapImage bitmapImage;
// img.BaseUri in not null because img has been added to the page.
Uri uri(img.BaseUri(), L"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;

Uso de archivos de una red

Para usar un archivo desde una ubicación de red como origen de imagen, use los esquemas http: o https: , como se muestra aquí. Especifique el identificador uniforme de recursos (URI) absoluto. Para obtener más información, consulta Carga de recursos de archivos.

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

Image img;
img.Source(BitmapImage(Uri(L"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"));

Uso de archivos del almacenamiento local

Para usar archivos que se colocan en el almacenamiento local de la aplicación como origen de imagen, use el esquema ms-appdata: , como se muestra aquí. Especifique el identificador uniforme de recursos (URI) absoluto. Para obtener más información, consulta Carga de recursos de archivos.

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

Uso de un origen de secuencia para mostrar imágenes de la biblioteca imágenes

Un uso típico de los elementos Image de una aplicación es mostrar imágenes de la biblioteca imágenes del usuario. Es posible que se acceda a estas imágenes mediante programación o a través de un FileOpenPicker. En cualquier caso, el objeto StorageFile que se obtiene se puede abrir como una secuencia, pero no proporciona una referencia de identificador uniforme de recursos (URI) al archivo de imagen. Para usar una secuencia como origen de imagen, debe escribir código que establezca la instancia de Image para usar la secuencia. Esto no se puede hacer solo en XAML.

Para mostrar una imagen individual, use los objetos StorageFile para enumerar la biblioteca y llamar a OpenAsync para obtener una secuencia. Use esta secuencia para establecer el origen de la imagen, mediante la creación de un objeto BitmapImage y, a continuación, llamar a SetSourceAsync y pasar la secuencia para usarla como parámetro streamSource .

En este ejemplo se muestra cómo usar un FileOpenPicker para tener acceso a un archivo de imagen desde la biblioteca Imágenes y establecerlo como origen de un control Image . El código ya es awaitable porque está esperando que el usuario elija un archivo y solo se ejecute después de eso. La secuencia que se va a usar procede de StorageFile.OpenAsync después de que se devuelva una instancia de StorageFile de las acciones del selector asincrónico. Para obtener más información sobre el uso de selectores de archivos, consulta Abrir archivos y carpetas con un selector.

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

En este ejemplo se muestra cómo obtener acceso mediante programación a un archivo de imagen desde la biblioteca Imágenes y establecerlo como origen de un control Image . Para acceder al contenido de la biblioteca imágenes mediante programación, llame a StorageFolder.GetFilesAsync. Recuerde que debe especificar una funcionalidad para acceder a la biblioteca de imágenes mediante programación.

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

Orígenes y escala de las imágenes

Si estás haciendo referencia a imágenes empaquetadas en la aplicación, debes crear los orígenes de imágenes en varios tamaños recomendados, para asegurarte de que la aplicación tenga un aspecto excelente cuando la Windows Runtime la escala. Al especificar un origen para una imagen como identificador uniforme de recursos (URI), puede usar una convención de nomenclatura que hará referencia automáticamente al recurso de imagen correcto para el escalado actual tal como lo detectó el sistema en tiempo de ejecución. Para ver información más específica acerca de la convención de nomenclatura y otros temas, consulta Inicio rápido: usar recursos de archivo o imagen.

Para obtener más información sobre cómo diseñar el escalado, consulta Tamaños de pantalla y puntos de interrupción o Comentarios en imagen.

Orígenes de imágenes y calificadores de recursos

Puede usar el control automático para acceder a recursos no calificados con calificadores de escala y referencia cultural actuales, o puede usar ResourceManager y ResourceMap con calificadores para la referencia cultural y la escala para obtener los recursos directamente. Para obtener más información, consulta Sistema de administración de recursos o Comentarios en Imagen. Para obtener más información sobre los recursos de la aplicación y cómo empaquetar orígenes de imágenes en una aplicación, consulta Definición de recursos de aplicación.

Se aplica a

Consulte también