BitmapImage Clase

Definición

Espacio de nombres:

Windows.UI.Xaml.Media.Imaging

Proporciona el tipo práctico de origen del objeto para las propiedades Image.Source e ImageBrush.ImageSource . Puede definir un objeto BitmapImage mediante un identificador uniforme de recursos (URI) que haga referencia a un archivo de origen de imagen, o llamando a SetSourceAsync y proporcionando una secuencia.

public ref class BitmapImage sealed : BitmapSource

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
/// [Windows.Foundation.Metadata.Activatable(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory, 65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
class BitmapImage final : BitmapSource

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.UI.Xaml.Media.Imaging.IBitmapImageFactory), 65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
public sealed class BitmapImage : BitmapSource

Public NotInheritable Class BitmapImage
Inherits BitmapSource

<BitmapImage .../>

Herencia

Object Platform::Object IInspectable DependencyObject ImageSource BitmapSource BitmapImage

Atributos

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Requisitos de Windows

Familia de dispositivos	Windows 10 (se introdujo en la versión 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (se introdujo en la versión v1.0)

Ejemplos

Este es un ejemplo del uso de un objeto BitmapImage para establecer Image.Source en C#. 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; 
    BitmapImage bitmapImage = new BitmapImage();
    img.Width = bitmapImage.DecodePixelWidth = 80; 
    // Natural px width of image source.
    // You don't need to set Height; the system maintains aspect ratio, and calculates the other
    // dimension, as long as one dimension measurement is provided.
    bitmapImage.UriSource = new Uri(img.BaseUri,"Assets/StoreLogo.png");
    img.Source = bitmapImage;
}

Comentarios

BitmapImage se puede obtener a partir de estos formatos de archivo de imagen:

• Formato JPEG (Joint Photographic Experts Group)
• Formato PNG (Portable Network Graphics)
• Mapa de bits (BMP)
• Formato de intercambio de gráficos (GIF)
• Tagged Image File Format (TIFF)
• JPEG XR
• iconos (ICO)

Si el origen de la imagen es una secuencia, se espera que esa secuencia contenga un archivo de imagen en uno de estos formatos.

La clase BitmapImage representa una abstracción para que un origen de imagen se pueda establecer de forma asincrónica, pero seguir siendo al que se hace referencia en el marcado XAML como un valor de propiedad, o en el código como un objeto que no usa la sintaxis que se puede esperar. Al crear un objeto BitmapImage en el código, inicialmente no tiene ningún origen válido. A continuación, debe establecer su origen mediante una de estas técnicas:

• Use el constructor BitmapImage(Uri) en lugar del constructor predeterminado. Aunque es un constructor que puede considerar que tiene un comportamiento asincrónico implícito: BitmapImage no estará listo para su uso hasta que genere un evento ImageOpened que indique una operación correcta del conjunto de origen asincrónico.
• Establezca la propiedad UriSource . Al igual que con el uso del constructor URI , esta acción es implícitamente asincrónica y BitmapImage no estará lista para su uso hasta que genere un evento ImageOpened .
• Use SetSourceAsync. Este método es explícitamente asincrónico. Las propiedades en las que puede usar bitmapImage, como Image.Source, están diseñadas para este comportamiento asincrónico y no producirán excepciones si se establecen mediante un bitmapImage que aún no tiene un origen completo. En lugar de controlar las excepciones, debe controlar los eventos ImageOpened o ImageFailed directamente en bitmapImage o en el control que usa el origen (si esos eventos están disponibles en la clase de control).

ImageFailed e ImageOpened son mutuamente excluyentes. Siempre se generará un evento u otro siempre que un objeto BitmapImage tenga su valor de origen establecido o restablecido.

BitmapImage y codificación

La API del componente de creación de imágenes (WIC) de Windows proporciona la compatibilidad subyacente con el códec para los archivos de imagen en Windows. Para obtener más información sobre formatos de imagen específicos como se documenta para los códecs, consulta Códecs WIC nativos. Para obtener más información sobre los formatos y cómo usar el identificador uniforme de recursos (URI) para acceder a los archivos de origen de imagen que proceden de recursos de la aplicación, consulta Image e ImageBrush.

La API para Image, BitmapImage y BitmapSource no incluye ningún método dedicado para codificar y descodificar formatos multimedia. Todas las operaciones de codificación y descodificación están integradas y, como mucho, mostrarán aspectos de la codificación o descodificación como parte de los datos de evento para los eventos de carga. Si quieres realizar cualquier trabajo especial con codificación o descodificación de imagen, que puedes usar si la aplicación realiza conversiones de imágenes o manipulación, debes usar la API que está disponible en el espacio de nombres Windows.Graphics.Imaging . Esta API de creación de imágenes se puede usar mediante una aplicación para UWP mediante C++, C# o Visual Basic o una aplicación de Windows mediante JavaScript. Estas API también son compatibles con el componente Componente de creación de imágenes de Windows (WIC) de Windows 8.

Imágenes animadas

A partir de Windows 10, versión 1607, el elemento Imagen XAML admite imágenes GIF animadas. Al usar bitmapImage como origen de la imagen, puede acceder a BitmapImage API para controlar la reproducción de la imagen GIF animada.

• Utilice la propiedad Reproducción automática, que tiene como valor predeterminado true, para especificar si un mapa de bits animado se reproduce en cuanto se carga.
• Utilice la propiedad IsAnimatedBitmap para comprobar si se anima un mapa de bits.
• Utilice la propiedad IsPlaying junto con los métodos Play y Stop para controlar la reproducción de un mapa de bits animado.

Nota

Para la mayoría de las aplicaciones, se recomienda establecer Reproducción automática en false si UISettings.AnimationsEnabled es false, para admitir las necesidades de accesibilidad de los usuarios. No hagas esto si el contenido del GIF animado es importante para la facilidad de uso de la aplicación.

Si la aplicación se ejecuta en versiones de Windows 10 anteriores a la versión 1607, debes usar la clase ApiInformation para comprobar la presencia de estos miembros antes de usarlas. Para obtener más información, consulta Código adaptable de versión: Usar nuevas API al tiempo que mantiene la compatibilidad con versiones anteriores.

En este ejemplo se muestra cómo usar un GIF animado. Un botón permite al usuario iniciar o detener la animación. En este ejemplo se usa código adaptable de versión para que pueda ejecutarse en todas las versiones de Windows 10. En las versiones anteriores a la versión 1607, se muestra el primer fotograma del GIF, pero no se anima.

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    <Image Loaded="Image_Loaded">
        <Image.Source>
            <BitmapImage x:Name="imageSource"
                         UriSource="Assets/example.gif"
                         ImageOpened="imageSource_ImageOpened"/>
        </Image.Source>
    </Image>

    <AppBarButton x:Name="playButton"
              Icon="Play"
              Visibility="Collapsed"
              Click="playButton_Click"/>
</Grid>

// Set the AutoPlay property.
private void Image_Loaded(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "AutoPlay") == true)
    {
        imageSource.AutoPlay = false;
    }
}

// Show the play/stop button if the image is animated.
private void imageSource_ImageOpened(object sender, RoutedEventArgs e)
{
    var bitmapImage = (BitmapImage)sender;
    // At this point you can query whether the image is animated or not.
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsAnimatedBitmap") 
        && bitmapImage.IsAnimatedBitmap == true)
    {
        // Enable the play button
        playButton.Visibility = Visibility.Visible;
    }
}

// Play or stop the animated bitmap.
void playButton_Click(object sender, RoutedEventArgs e)
{
    if (ApiInformation.IsPropertyPresent("Windows.UI.Xaml.Media.Imaging.BitmapImage", "IsPlaying"))
    {
        // You can call the Play and Stop methods safely because is the IsPlaying property is
        // present, these methods are also present.
        if (imageSource.IsPlaying == true)
        {
            playButton.Icon = new SymbolIcon(Symbol.Play);
            imageSource.Stop();
        }
        else
        {
            playButton.Icon = new SymbolIcon(Symbol.Stop);
            imageSource.Play();
        }
    }
}

Para obtener más ejemplos, consulta el ejemplo de reproducción gif animada.

Historial de versiones

Versión de Windows	Versión del SDK	Valor agregado
1607	14393	Reproducción automática
1607	14393	IsAnimatedBitmap
1607	14393	IsPlaying
1607	14393	Reproducir
1607	14393	Stop

Constructores

BitmapImage()	Inicializa una nueva instancia de la clase BitmapImage .
BitmapImage(Uri)	Inicializa una nueva instancia de la clase BitmapImage mediante el identificador uniforme de recursos (URI) proporcionado.

Propiedades

AutoPlay	Obtiene o establece un valor que indica si una imagen animada debe reproducirse tan pronto como se cargue.
AutoPlayProperty	Identifica la propiedad de dependencia Reproducción automática.
CreateOptions	Obtiene o establece el objeto BitmapCreateOptions para bitmapImage.
CreateOptionsProperty	Identifica la propiedad de dependencia CreateOptions .
DecodePixelHeight	Obtiene o establece el alto que se va a usar para las operaciones de descodificación de imágenes.
DecodePixelHeightProperty	Identifica la propiedad de dependencia DecodePixelHeight .
DecodePixelType	Obtiene o establece un valor que determina cómo se interpretan los valores DecodePixelWidth y DecodePixelHeight para las operaciones de descodificación.
DecodePixelTypeProperty	Identifica la propiedad de dependencia DecodePixelType .
DecodePixelWidth	Obtiene o establece el ancho que se va a usar para las operaciones de descodificación de imágenes.
DecodePixelWidthProperty	Identifica la propiedad de dependencia DecodePixelWidth .
Dispatcher	Obtiene el CoreDispatcher al que está asociado este objeto. CoreDispatcher representa una instalación que puede tener acceso a DependencyObject en el subproceso de interfaz de usuario incluso si un subproceso que no es de interfaz de usuario inicia el código. (Heredado de DependencyObject)
IsAnimatedBitmap	Obtiene un valor que indica si se anima una imagen.
IsAnimatedBitmapProperty	Identifica la propiedad de dependencia IsAnimatedBitmap .
IsPlaying	Obtiene un valor que indica si se está reproduciendo una imagen animada.
IsPlayingProperty	Identifica la propiedad de dependencia IsPlaying .
PixelHeight	Obtiene el alto del mapa de bits en píxeles. (Heredado de BitmapSource)
PixelWidth	Obtiene el ancho del mapa de bits en píxeles. (Heredado de BitmapSource)
UriSource	Obtiene o establece el identificador uniforme de recursos (URI) del archivo de origen de gráficos que generó este bitmapImage.
UriSourceProperty	Identifica la propiedad de dependencia UriSource .

Métodos

ClearValue(DependencyProperty)	Borra el valor local de una propiedad de dependencia. (Heredado de DependencyObject)
GetAnimationBaseValue(DependencyProperty)	Devuelve cualquier valor base establecido para una propiedad de dependencia, que se aplicaría en los casos en los que una animación no está activa. (Heredado de DependencyObject)
GetValue(DependencyProperty)	Devuelve el valor efectivo actual de una propiedad de dependencia de dependencyObject. (Heredado de DependencyObject)
Play()	Inicia la animación de una imagen animada.
ReadLocalValue(DependencyProperty)	Devuelve el valor local de una propiedad de dependencia, si se establece un valor local. (Heredado de DependencyObject)
RegisterPropertyChangedCallback(DependencyProperty, DependencyPropertyChangedCallback)	Registra una función de notificación para escuchar los cambios en una dependencyProperty específica en esta instancia de DependencyObject . (Heredado de DependencyObject)
SetSource(IRandomAccessStream)	Establece la imagen de origen de un objeto BitmapSource mediante el acceso a una secuencia. La mayoría de los autores de llamadas deben usar SetSourceAsync en su lugar. (Heredado de BitmapSource)
SetSourceAsync(IRandomAccessStream)	Establece la imagen de origen de un objeto BitmapSource accediendo a una secuencia y procesando el resultado de forma asincrónica. (Heredado de BitmapSource)
SetValue(DependencyProperty, Object)	Establece el valor local de una propiedad de dependencia en dependencyObject. (Heredado de DependencyObject)
Stop()	Finaliza la animación de una imagen animada.
UnregisterPropertyChangedCallback(DependencyProperty, Int64)	Cancela una notificación de cambio registrada anteriormente llamando a RegisterPropertyChangedCallback. (Heredado de DependencyObject)

Eventos

DownloadProgress	Se produce cuando se ha producido un cambio significativo en el progreso de descarga del contenido bitmapImage .
ImageFailed	Se produce cuando se produce un error asociado a la recuperación o formato de la imagen.
ImageOpened	Se produce cuando el origen de la imagen se descarga y descodifica sin errores. Puede usar este evento para determinar el tamaño de una imagen antes de representarla.

Consulte también

• Image
• BitmapSource
• Source
• ImageSource
• Image e ImageBrush
• Ejemplo de reproducción gif animada (XAML)