Imágenes y pinceles de imagen

  • Artículo

Para mostrar una imagen, puedes usar los objetos Image o ImageBrush. Un objeto Image representa una imagen y un objeto ImageBrush pinta otro objeto con una imagen.

¿Son estos los elementos adecuados?

Usa un elemento Image para mostrar una imagen independiente en la aplicación.

Usa un elemento ImageBrush para aplicar una imagen a otro objeto. Entre los usos de ImageBrush, se incluyen efectos decorativos para el texto o fondos para los controles o los contenedores de diseño.

UWP y WinUI 2

Importante

La información y los ejemplos de este artículo están optimizados para aplicaciones que usan el SDK de Aplicaciones para Windows y WinUI 3, pero generalmente son aplicables a las aplicaciones para UWP que usan WinUI 2. Consulte el material de referencia de las API de UWP para obtener información y ejemplos específicos de la plataforma.

Esta sección contiene información que necesita para usar el control en una aplicación para UWP o WinUI 2.

Las API de este control existen en los espacios de nombres Windows.UI.Xaml.Controls y Windows.UI.Xaml.Media .

Se recomienda usar la versión más reciente de WinUI 2 para obtener los estilos y plantillas más actuales para todos los controles.

A partir de Windows 10, versión 1607, el elemento Image admite imágenes GIF animadas. Si usas un elemento BitmapImage como propiedad Source de la imagen, puedes acceder a las API de BitmapImage para controlar la reproducción de la imagen GIF animada. Para más información, consulta los comentarios de la página de la clase BitmapImage.

Nota

La compatibilidad con GIF animados está disponible cuando la aplicación se compila para Windows 10, versión 1607 y se ejecuta en la versión 1607 (o posterior). Si tu aplicación está compilada para versiones anteriores o se ejecuta en versiones anteriores, el primer fotograma del GIF se muestra, pero no animado.

Crear una imagen

Abra la aplicación Galería de WinUI 3 y vea ImageBrushes en acción.

La aplicación WinUI 3 Gallery incluye ejemplos interactivos de la mayoría de los controles, las características y la funcionalidad de WinUI 3. Obtenga la aplicación en Microsoft Store o el código fuente en GitHub.

Imagen

En este ejemplo se muestra cómo crear una imagen mediante el objeto Image.

<Image Width="200" Source="sunset.jpg" />

Este es el objeto Image representado.

Ejemplo de un elemento de imagen

En este ejemplo, la propiedad Source especifica la ubicación de la imagen que quieres mostrar. Puede establecer el origen especificando una dirección URL absoluta (por ejemplo, http://contoso.com/myPicture.jpg) o especificando una dirección URL relativa a la estructura de empaquetado de la aplicación. En nuestro ejemplo, colocamos el archivo de imagen "sunset.jpg" en la carpeta raíz del proyecto y declaramos la configuración del proyecto que incluye el archivo de imagen como contenido.

ImageBrush

Con el objeto ImageBrushpuedes utilizar una imagen para pintar un área que admita un objeto Brush. Por ejemplo, puedes usar un objeto ImageBrush para el valor de la propiedad Fill de una Elipse o la propiedad Backgroundde unLienzo.

En el siguiente ejemplo se muestra cómo usar ImageBrush para pintar un elemento Ellipse.

<Ellipse Height="200" Width="300">
   <Ellipse.Fill>
     <ImageBrush ImageSource="sunset.jpg" />
   </Ellipse.Fill>
</Ellipse>

Este es el elemento Ellipse que ha pintado ImageBrush.

Un elemento Ellipse que ha pintado ImageBrush.

Ajustar una imagen

Si no establece los valores de Width o Height de un objeto Image, este se muestra con las dimensiones de la imagen que especificó Source. Cuando se establecen los valores Width y Height, se crea un área rectangular contenedora donde se muestra la imagen. Mediante la propiedad Stretch se puede especificar la forma en que la imagen rellena esta área contenedora. La propiedad Stretch acepta estos valores, que define la enumeración Stretch:

  • None: la imagen no se ajusta para rellenar las dimensiones de salida. Ten cuidado con el valor de Stretch: si la imagen de origen es mayor que el área contenedora, se recortará, lo que no es deseable, ya que no tendrás control sobre la ventanilla, algo que tendrías con un elemento Clip intencionado.
  • Uniform: la imagen se escala para ajustarse a las dimensiones de salida. aunque la relación de aspecto del contenido se mantiene. Este es el valor predeterminado.
  • UniformToFill: la imagen se escala de forma que rellenar completamente el área de salida, pero mantiene su relación de aspecto original.
  • Fill: la imagen se escala para ajustarse a las dimensiones de salida. Como el alto y el ancho del contenido se escalan de forma independiente, la relación de aspecto original de la imagen quizás no se mantenga. En otras palabras, la imagen podría distorsionarse para rellenar completamente el área de salida.

Ejemplo de las configuraciones de Stretch.

Recortar una imagen

Puedes usar la propiedad Clip para recortar un área de la salida de la imagen. Establece la propiedad Clip en un valor Geometry. Actualmente, no se admiten los recortes no rectangulares.

En el siguiente ejemplo se muestra cómo usar un objeto RectangleGeometrycomo la región de recorte de una imagen. En este ejemplo, se define un objeto Image con un valor de alto de 200. Un elemento RectangleGeometry define un rectángulo para el área de la imagen que se mostrará. La propiedad Rectestá establecida en "25,25,100,150", que define un rectángulo que comienza en la posición "25,25" con un ancho de 100 y un alto de 150. Solo se muestra la parte de la imagen que está dentro del área del rectángulo.

<Image Source="sunset.jpg" Height="200">
    <Image.Clip>
        <RectangleGeometry Rect="25,25,100,150" />
    </Image.Clip>
</Image>

Esta es la imagen recortada sobre un fondo negro.

Un objeto Image recortado por RectangleGeometry.

Aplicar una opacidad

Puedes aplicar una propiedad Opacity a una imagen para que se represente como semitranslúcida. Los valores de opacidad van de 0,0 a 1,0; donde 1,0 es totalmente opaco y 0,0 es totalmente transparente. En este ejemplo se muestra cómo aplicar una opacidad de 0,5 a un elemento Image.

<Image Height="200" Source="sunset.jpg" Opacity="0.5" />

Esta es la imagen representada con una opacidad de 0,5 y un fondo negro que se ve a través de la opacidad parcial.

Un objeto Image con una opacidad de 0,5.

Formatos de archivos de imagen

Image e ImageBrush pueden mostrar los siguientes 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)

Las API para Image, BitmapImage y BitmapSource no incluyen 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 algún trabajo especial con la codificación o descodificación de imágenes, que puedes usar si la aplicación realiza manipulaciones o conversiones de imágenes, deberías usar las API que están disponibles en el espacio de nombres Windows.Graphics.Imaging. Estas API también son compatibles con Windows Imaging Component (WIC) en Windows.

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 Carga de imágenes y recursos adaptados a escala, tema, contraste alto y otros.

WriteableBitmap

WriteableBitmap proporciona un objeto BitmapSource que se puede modificar y que no usa la descodificación basada en archivo básica del WIC. Puedes modificar imágenes de forma dinámica y volver a representar la imagen actualizada. Para definir el contenido del búfer de WriteableBitmap, usa la propiedad PixelBuffer para acceder al búfer y utiliza una secuencia o un tipo de búfer específico del lenguaje para rellenarlo. Para ver el código de ejemplo, consulta WriteableBitmap.

RenderTargetBitmap

La clase RenderTargetBitmap puede capturar el árbol de la interfaz de usuario de XAML de una aplicación en funcionamiento y después muestra un origen de imagen de mapa de bits. Tras la captura, dicho origen de imagen se puede aplicar a otras partes de la aplicación, guardar como un recurso o dato de la aplicación o emplear en otros escenarios. Un escenario especialmente útil es crear una miniatura en tiempo de ejecución de una página XAML para un esquema de navegación. RenderTargetBitmap presenta algunas limitaciones en cuanto al contenido que va a aparecer en la imagen capturada. Para más información, consulta el tema de referencia de la API para RenderTargetBitmap.

Orígenes y escala de las imágenes

Deberías crear los orígenes de imágenes con varios tamaños recomendados para garantizar que la aplicación tenga una apariencia excelente cuando Windows cambie su escala. Cuando se especifica una propiedad Source para un elemento Image, puedes usar una convención de nomenclatura que haga referencia automáticamente al recurso correcto para la escala actual. 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 más información sobre cómo diseñar teniendo en cuenta la escala, consulta Directrices sobre la experiencia del usuario para diseño y escalado.

Image e ImageBrush en código

Es habitual especificar elementos Image e ImageBrush con XAML en lugar de código. Esto es así porque estos elementos suelen ser el resultado de herramientas de diseño como parte de una definición de interfaz de usuario de XAML.

Si defines un elemento Image o ImageBrush mediante código, usa los constructores predeterminados y establece la propiedad de origen relevante (Image.Source o ImageBrush.ImageSource). Las propiedades de origen requieren un elemento BitmapImage (no un identificador URI) cuando se establecen mediante código. Si el origen es una secuencia, usa el método SetSourceAsync para inicializar el valor. Si el origen es un identificador URI, que incluye contenido en la aplicación que usa los esquemas ms-appx o ms-resource, utiliza el constructor BitmapImage que toma un URI. También puedes considerar la posibilidad de controlar el evento ImageOpened si hay problemas de temporización al recuperar o descodificar el origen de la imagen, ya que es posible que necesites que aparezca otro contenido hasta que el origen de la imagen esté disponible. Para obtener código de ejemplo, consulte el ejemplo de la Galería de WinUI.

Nota

Si estableces imágenes mediante código, puedes usar el control automático para obtener acceso a los recursos sin calificar con calificadores de referencia cultural y de escala actuales, o bien puedes usar ResourceManager y ResourceMap con calificadores de escala y referencia cultural para obtener los recursos directamente. Para obtener más información, consulta Sistema de administración de recursos.

Obtención del código de ejemplo