Imágenes

¡Astro ofrece varias formas para que uses imágenes en tu sitio, ya sea que estén almacenadas localmente dentro de tu proyecto, enlazadas desde una URL externa o gestionadas en un CMS o CDN!

Astro proporciona componentes integrados <Image /> y <Picture />, procesamiento de la sintaxis de imágenes Markdown (![]()), Componentes SVG, y una función generadora de imágenes para optimizar y/o transformar tus imágenes. Además, puedes configurar redimensionamiento automático de imágenes responsivas de forma predeterminada, o establecer propiedades responsivas en componentes de imágenes e imágenes individuales.

Siempre puedes optar por utilizar imágenes y archivos SVG utilizando elementos HTML nativos en archivos .astro o Markdown, o la forma estándar para tu tipo de archivo (por ejemplo, <img /> en MDX y JSX). Sin embargo, Astro no realiza ningún procesamiento ni optimización de estas imágenes.

Astro tampoco ofrece compatibilidad nativa con vídeos, por lo que recomendamos elegir un servicio de alojamiento de vídeos para gestionar las necesidades de optimización y transmisión de contenido de vídeo.

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />.

Dónde guardar las imágenes

`src/` vs. `public/`

Recomendamos que las imágenes locales se mantengan en src/ cuando sea posible, para que Astro pueda transformar, optimizar y empaquetarlas. Los archivos en el directorio /public siempre se sirven o copian tal como están en la carpeta de construcción, sin ningún procesamiento.

Tus imágenes locales almacenadas en src/ pueden ser utilizadas por todos los archivos en tu proyecto: .astro, .md, .mdx, .mdoc y otros frameworks UI. Las imágenes pueden almacenarse en cualquier carpeta, incluida junto a tu contenido.

Almacena tus imágenes en la carpeta public/ si deseas evitar cualquier tipo de procesamiento o para tener un enlace público directo a ellas.

Imágenes remotas

También puedes optar por almacenar tus imágenes de forma remota, en un sistema de gestión de contenido (CMS) o en una plataforma de gestión de assets digitales (DAM). Astro puede obtener tus datos de forma remota utilizando APIs o mostrar imágenes desde su ruta completa de URL.

Para una protección adicional al tratar con fuentes externas, las imágenes remotas solo se procesarán desde fuentes de imágenes autorizadas especificadas en tu configuración. Sin embargo, cualquier imagen remota puede ser mostrada.

Imágenes en archivos `.astro`

Opciones: <Image />, <Picture />, <img>, <svg>, componentes SVG

El lenguaje de plantillas de Astro te permite renderizar imágenes optimizadas con el componente <Image /> y generar múltiples tamaños y formatos con el componente <Picture />. Ambos componentes también aceptan propiedades de imagen responsivas para redimensionarse según el tamaño del contenedor y responder al tamaño y la resolución de la pantalla del dispositivo.

Además, puedes importar y utilizar archivos SVG como componentes de Astro en componentes .astro.

Todas las etiquetas HTML nativas, incluidas <img> y <svg>, también están disponibles en componentes .astro. Las imágenes renderizadas con etiquetas HTML no serán procesadas (por ejemplo, optimizadas, transformadas) y se copiarán en tu carpeta de construcción tal cual.

Para todas las imágenes en archivos .astro, el valor del atributo src de la imagen se determina por la ubicación de tu archivo de imagen:

Una imagen local de la carpeta src/ de tu proyecto utiliza una importación desde la ruta relativa del archivo.

Los componentes de Image y Picture utilizan la importación nombrada directamente (por ejemplo, src={rocket}), mientras que la etiqueta <img> utiliza la propiedad del objeto src de la importación (por ejemplo, src={rocket.src}).
Las imágenes remotas y public/ utilizan una ruta URL.

Proporciona una URL completa para imágenes remotas (por ejemplo, src="https://www.example.com/images/my-remote-image.jpg"), o una ruta URL relativa en tu sitio que corresponda a la ubicación de tu archivo en la carpeta public/ (por ejemplo, src="/images/my-public-image.jpg" para una imagen ubicada en public/images/my-public-image.jpg).

---
import { Image } from 'astro:assets';
import localBirdImage from '../../images/subfolder/localBirdImage.png';
---
<Image src={localBirdImage} alt="Un pájaro sentado sobre un nido de huevos."/>
<Image src="/images/bird-in-public-folder.jpg" alt="Un pájaro." width="50" height="50" />
<Image src="https://example.com/remote-bird.jpg" alt="Un pájaro." width="50" height="50" />

<img src={localBirdImage.src} alt="Un pájaro sentado sobre un nido de huevos.">
<img src="/images/bird-in-public-folder.jpg" alt="Un pájaro.">
<img src="https://example.com/remote-bird.jpg" alt="Un pájaro.">

Consulta la referencia completa de la API para los componentes <Image /> y <Picture /> incluidas las propiedades obligatorias y opcionales.

Receta relacionada: Importa imágenes dinámicamente

Imágenes en archivos Markdown

Opciones: ![](), <img> (con imágenes públicas o remotas)

Utiliza la sintaxis estándar de Markdown ![alt](src) en tus archivos .md. Tus imágenes locales almacenadas en src/ y las imágenes remotas serán procesadas y optimizadas. Cuando configures imágenes responsivas globalmente, estas imágenes también serán responsivas.

Las imágenes almacenadas en la carpeta public/ nunca se optimizan.

# Mi página Markdown

<!-- Imagen local almacenada en src/assets/ -->
<!-- Usa una ruta de archivo relativa o un alias de importación -->
![Un cielo estrellado.](../assets/stars.png)

<!-- Imagen almacenada en public/images/ -->
<!-- Usa la ruta de archivo relativa a public/ -->
![Un cielo estrellado.](/images/stars.png)

<!-- Imagen remota en otro servidor -->
<!-- Usa la URL completa de la imagen -->
![Astro](https://example.com/images/remote-image.png)

La etiqueta HTML <img> también se puede utilizar para mostrar imágenes almacenadas en public/ o imágenes remotas sin necesidad de optimizar ni procesar las imágenes. Sin embargo, <img> no es compatible con las imágenes locales en src.

Los componentes <Image /> y <Picture /> no están disponibles en archivos .md. Si necesitas más control sobre los atributos de tus imágenes, te recomendamos usar la integración MDX de Astro para agregar soporte para el formato de archivo .mdx. MDX permite opciones adicionales de imagen disponibles en MDX, incluyendo la combinación de componentes con la sintaxis Markdown.

Imágenes en archivos MDX

Opciones: <Image />, <Picture />, <img>, ![](), componentes SVG

Puedes utilizar los componentes <Image /> y <Picture /> de Astro en tus archivos .mdx importando tanto el componente como tu imagen. Úsalos tal y como se utilizan en los archivos .astro. La etiqueta JSX <img /> también es compatible con imágenes sin procesar y utiliza la misma importación de imágenes que la etiqueta HTML <img>.

Además, se admite la sintaxis estándar de Markdown ![alt](src) sin necesidad de importarla.

---
title: Mi título de página
---
import { Image } from 'astro:assets';
import rocket from '../assets/rocket.png';

# Mi página MDX

// Imagen local guardada en la misma carpeta
![Houston en estado salvaje](houston.png)

// Imagen local almacenada en src/assets/
<Image src={rocket} alt="Un cohete en el espacio." />
<img src={rocket.src} alt="Un cohete en el espacio." />
![Un cohete en el espacio](../assets/rocket.png)

// Imagen almacenada en public/images/
<Image src="/images/stars.png" alt="Un cielo estrellado." />
<img src="/images/stars.png" alt="Un cielo estrellado." />
![Un cielo estrellado.](/images/stars.png)

// Imagen remota en otro servidor
<Image src="https://example.com/images/remote-image.png" />
<img src="https://example.com/images/remote-image.png" />
![Astro](https://example.com/images/remote-image.png)

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />.

Imágenes en componentes UI de frameworks

Opciones de imagen: la sintaxis de imagen propia del framework (por ejemplo, <img /> en JSX, <img> en Svelte)

Las imágenes locales deben importarse primero para acceder a sus propiedades de imagen, como src. Luego, se pueden renderizar como lo harías normalmente en la sintaxis de imagen de ese framework:

import stars from "../assets/stars.png";

export default function ReactImage() {
  return (
    <img src={stars.src} alt="Un cielo estrellado." />
  )
}

<script>
  import stars from '../assets/stars.png';
</script>

<img src={stars.src} alt="Un cielo estrellado." />

Los componentes de Astro (por ejemplo, <Image />, <Picture />, componentes SVG) no están disponibles dentro de los componentes de framework UI porque una isla de cliente debe contener solo código válido para su propio framework.

Pero, puedes pasar el contenido estático generado por estos componentes a un componente de framework dentro de un archivo .astro como hijos o utilizando un <slot/> nombrado:

---
import ReactComponent from './ReactComponent.jsx';
import { Image } from 'astro:assets';
import stars from '~/stars/docline.png';
---

<ReactComponent>
  <Image src={stars} alt="Un cielo estrellado." />
</ReactComponent>

Componentes Astro para imágenes

Astro proporciona dos componentes integrados para imágenes (<Image /> y <Picture />) y también te permite importar archivos SVG y usarlos como componentes Astro. Estos componentes se pueden usar en cualquier archivo que pueda importar y renderizar componentes .astro.

`<Image />`

Utiliza el componente integrado <Image /> para mostrar versiones optimizadas de:

tus imágenes locales ubicadas dentro de la carpeta src/
imágenes remotas configuradas de fuentes autorizadas

<Image /> puede transformar las dimensiones, el tipo de archivo y la calidad de una imagen local o remota autorizada para controlar la imagen que se muestra. Esta transformación se produce en el momento de la compilación de las páginas prerenderizadas. Cuando tu página se renderiza bajo demanda, esta transformación se produce sobre la marcha cuando se visualiza la página. La etiqueta <img> resultante incluye los atributos alt, loading y decoding, e infiere las dimensiones de la imagen para evitar el desplazamiento acumulativo del diseño (CLS).

---
// Importa el componente Image y la imagen
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png'; // La imagen es 1600x900
---

<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="Una descripción de mi imagen." />

<!-- Salida prerenderizada -->
<!-- La imagen está optimizada, se aplican los atributos adecuados -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  alt="Una descripción de mi imagen."
/>

<!-- Salida renderizada bajo demanda-->
<!-- src utilizará un endpoint generado bajo demanda-->
<img
  src="/_image?href=%2F_astro%2Fmy_image.hash.webp&amp;w=1600&amp;h=900&amp;f=webp"
  <!-- ... -->
/>

El componente <Image /> acepta varias propiedades de componente así como cualquier atributo aceptado por la etiqueta HTML <img>.

El siguiente ejemplo proporciona una clase al componente de imagen que se aplicará al elemento <img> final.

---
import { Image } from 'astro:assets';
import myImage from '../assets/my_image.png';
---

<!-- `alt` es obligatorio en el componente Imagen -->
<Image src={myImage} alt="" class="mi-clase" />

<!-- Salida prerenderizada -->
<img
  src="/_astro/my_image.hash.webp"
  width="1600"
  height="900"
  decoding="async"
  loading="lazy"
  class="mi-clase"
  alt=""
/>

`<Picture />`

Agregado en: astro@3.3.0

Usa el componente integrado <Picture /> para generar una etiqueta <picture> con múltiples formatos y/o tamaños de tu imagen. Esto te permite especificar formatos de archivo preferidos para mostrar y, al mismo tiempo, proporcionar un formato de respaldo. Al igual que el componente <Image />, las imágenes se procesarán en el momento de la construcción para las páginas prerenderizadas. Cuando tu página se renderiza bajo demanda, el procesamiento ocurrirá sobre la marcha cuando se visualice la página.

El siguiente ejemplo utiliza el componente <Picture /> para transformar un archivo .png local en un formato avif y webp compatible con la web, así como en el <img> .png que se puede mostrar como respaldo cuando sea necesario:

---
import { Picture } from 'astro:assets';
import myImage from '../assets/my_image.png'; // La imagen es de 1600x900
---

<!-- `alt` es obligatorio en el componente Picture -->
<Picture src={myImage} formats={['avif', 'webp']} alt="Una descripción de mi imagen." />

<!-- Salida prerenderizada -->
<picture>
  <source srcset="/_astro/my_image.hash.avif" type="image/avif" />
  <source srcset="/_astro/my_image.hash.webp" type="image/webp" />
  <img
    src="/_astro/my_image.hash.png"
    width="1600"
    height="900"
    decoding="async"
    loading="lazy"
    alt="Una descripción de mi imagen."
  />
</picture>

Consulta los detalles de las propiedades del componente <Picture /> en la referecia astro:assets

Imagenes responsivas

Agregado en: astro@5.10.0

Las imágenes responsivas son imágenes que se ajustan para mejorar el rendimiento en diferentes dispositivos. Estas imágenes pueden cambiar de tamaño para adaptarse a su contenedor y pueden servirse en diferentes tamaños según el tamaño y la resolución de la pantalla de tu visitante.

Con propiedades de imagen responsivas aplicadas a los componentes <Image /> o <Picture />, Astro generará automáticamente los valores srcset y sizes requeridos para tus imágenes y aplicará los estilos necesarios para garantizar que se redimensionen correctamente.

Cuando este comportamiento responsivo se configura globalmente, se aplicará a todos los componentes de imagen y también a cualquier imagen local y remota que utilice la sintaxis Markdown ![]().

Las imágenes en tu carpeta public/ nunca se optimizan, y las imágenes responsivas no son compatibles.

Consulta los detalles de las imágenes responsivas en la documentación de MDN.

Salida HTML generada para imágenes responsivas

Cuando un diseño está configurado, ya sea por defecto o en un componente individual, las imágenes tienen atributos srcset y sizes generados automáticamente en función de las dimensiones de la imagen y el tipo de diseño. Las imágenes con diseños constrained y full-width tendrán estilos aplicados para garantizar que se redimensionen de acuerdo con su contenedor.

---
import { Picture } from "astro:assets";
import myImage from "../my_image.png";
---
<Image src={myImage} alt="Una descripción de mi imagen." layout='constrained' width={800} height={600} />

Este componente <Image /> generará la siguiente salida HTML en una página prerenderizada:

<img
  src="/_astro/my_image.hash3.webp"
  srcset="/_astro/my_image.hash1.webp 640w,
      /_astro/my_image.hash2.webp 750w,
      /_astro/my_image.hash3.webp 800w,
      /_astro/my_image.hash4.webp 828w,
      /_astro/my_image.hash5.webp 1080w,
      /_astro/my_image.hash6.webp 1280w,
      /_astro/my_image.hash7.webp 1600w"
  alt="Una descripción de mi imagen."
  sizes="(min-width: 800px) 800px, 100vw"
  loading="lazy"
  decoding="async"
  fetchpriority="auto"
  width="800"
  height="600"
  style="--fit: cover; --pos: center;"
  data-astro-image="constrained"
>

Estilos para imágenes responsivas

Configurar image.responsiveStyles: true aplica un pequeño número de estilos globales para garantizar que tus imágenes se redimensionen correctamente. En la mayoría de los casos, querrás habilitar esto como valor predeterminado; tus imágenes no serán responsivas sin estilos adicionales.

Sin embargo, si prefieres manejar el estilo de las imágenes responsivas tú mismo, o necesitas sobrescribir estos valores predeterminados al usar Tailwind 4, deja configurado el valor predeterminado false.

Los estilos globales aplicados por Astro dependerán del tipo de diseño y están diseñados para producir el mejor resultado para los atributos srcset y sizes generados. Estos son los estilos predeterminados:

:where([data-astro-image]) {
  object-fit: var(--fit);
  object-position: var(--pos);
}
:where([data-astro-image='full-width']) {
  width: 100%;
}
:where([data-astro-image='constrained']) {
  max-width: 100%;
}

Los estilos utilizan la pseudo-clase :where(), que tiene una especificidad de 0, lo que significa que es fácil de sobrescribir con tus propios estilos. Cualquier selector CSS tendrá una especificidad más alta que :where(), por lo que puedes sobrescribir fácilmente los estilos agregando tus propios estilos para dirigirte a la imagen.

Puedes sobrescribir los estilos object-fit y object-position en una base por imagen configurando las propiedades fit y position en el componente <Image /> o <Picture />.

Imágenes responsivas con Tailwind 4

Tailwind 4 es compatible con los estilos responsivos predeterminados de Astro. Sin embargo, Tailwind utiliza capas de cascada, lo que significa que sus reglas siempre tienen una especificidad más baja que las reglas que no utilizan capas, incluidos los estilos responsivos de Astro. Por lo tanto, el estilo de Astro tendrá prioridad sobre el estilo de Tailwind. Para utilizar las reglas de Tailwind en lugar del estilo predeterminado de Astro, no habilites los estilos responsivos predeterminados de Astro.

Componentes SVG

Agregado en: astro@5.7.0

Astro te permite importar archivos SVG y utilizarlos como componentes de Astro. Astro integrará el contenido SVG en tu salida HTML.

Referencia la importación predeterminada de cualquier archivo .svg local. Dado que esta importación se trata como un componente de Astro, debes usar las mismas convenciones (por ejemplo, capitalización) que al usar etiquetas dinámicas.

---
import Logo from './path/to/svg/file.svg';
---

<Logo />

Tu componente SVG, como <Image /> o cualquier otro componente de Astro, no está disponible dentro de los componentes de UI framework, pero puede ser pasado a un componente de framework dentro de un componente .astro.

Atributos del componente SVG

Puedes pasar propiedades como width, height, fill, stroke, y cualquier otro atributo aceptado por el elemento <svg> nativo. Estos atributos se aplicarán automáticamente al elemento <svg> subyacente. Si una propiedad está presente en el archivo .svg original y se pasa al componente, el valor pasado al componente sobrescribirá el valor original.

---
import Logo from '../assets/logo.svg';
---

<Logo width={64} height={64} fill="currentColor" />

Tipo `SvgComponent`

Agregado en: astro@5.14.0 Nuevo

Puedes hacer cumplir la seguridad de tipos para tus activos .svg utilizando el tipo SvgComponent:

---
import type { SvgComponent } from "astro/types";
import HomeIcon from './Home.svg'

interface Link {
  url: string
  text: string
  icon: SvgComponent
}

const links: Link[] = [
  {
    url: '/',
    text: 'Home',
    icon: HomeIcon
  }
]
---

Creando componentes de imagen personalizados

Puedes crear un componente de imagen reutilizable y personalizado envolviendo el componente <Image /> o <Picture /> en otro componente de Astro. Esto te permite establecer atributos y estilos predeterminados solo una vez.

Por ejemplo, podrías crear un componente para las imágenes de tus publicaciones de blog que reciba atributos como props y aplique estilos consistentes a cada imagen:

---
import { Image } from 'astro:assets';

const { src, ...attrs } = Astro.props;
---
<Image src={src} {...attrs} />

<style>
  img {
    margin-block: 2.5rem;
    border-radius: 0.75rem;
  }
</style>

Mostrar imágenes sin procesar con la etiqueta HTML `<img>`

La sintaxis de plantilla de Astro también admite escribir una etiqueta <img> directamente, con control total sobre su salida final. Estas imágenes no serán procesadas ni optimizadas. Acepta todas las propiedades de la etiqueta HTML <img>, y la única propiedad requerida es src. Sin embargo, se recomienda encarecidamente incluir la propiedad alt para accesibilidad.

imágenes en `src/`

Las imágenes locales deben importarse desde la ruta relativa del archivo .astro existente, o puedes configurar y usar un alias de importación. Luego, puedes acceder a las propiedades src y otras de la imagen para usarlas en la etiqueta <img>.

Los activos de imagen importados coinciden con la siguiente firma:

interface ImageMetadata {
  src: string;
  width: number;
  height: number;
  format: string;
}

El siguiente ejemplo utiliza las propias propiedades height y width de la imagen para evitar el cambio de diseño acumulativo (CLS) y mejorar los Core Web Vitals:

---
// importa imágenes locales
import myDog from '../../images/pets/local-dog.jpg';
---
// accede a las propiedades de la imagen
<img src={myDog.src} width={myDog.width} height={myDog.height} alt="Un perro ladrando." />

Imágenes en `public/`

Para las imágenes ubicadas dentro de public/, utiliza la ruta del archivo de la imagen relativa a la carpeta pública como el valor de src:

<img src="/images/public-cat.jpg" alt="Un gato durmiendo." >

Imágenes remotas

Para las imágenes remotas, utiliza la URL completa de la imagen como el valor de src:

<img src="https://example.com/remote-cat.jpg" alt="Un gato durmiendo." >

Elegir `<Image />` vs `<img>`

El componente <Image /> optimiza tu imagen e infiere el ancho y la altura (para las imágenes que puede procesar) en función de la relación de aspecto original para evitar CLS. Es la forma preferida de usar imágenes en archivos .astro siempre que sea posible.

Utiliza el elemento HTML <img> cuando no puedas usar el componente <Image />, por ejemplo:

para formatos de imagen no compatibles
cuando no quieras que tu imagen sea optimizada por Astro
para acceder y cambiar el atributo src dinámicamente del lado del cliente

Usando imágenes de un CMS o CDN

Los CDNs de imágenes funcionan con todas las opciones de imagen de Astro. Utiliza la URL completa de una imagen como el atributo src en el componente <Image />, una etiqueta <img> o en notación Markdown. Para la optimización de imágenes con imágenes remotas, también configura tus dominios autorizados o patrones de URL.

Alternativamente, el CDN puede proporcionar sus propios SDK para integrarse más fácilmente en un proyecto Astro. Por ejemplo, Cloudinary admite un SDK de Astro que te permite agregar imágenes fácilmente con su componente CldImage o un SDK de Node.js que puede generar URL para usar con una etiqueta <img> en un entorno de Node.js.

Consulta la referencia completa de la API para los componentes <Image /> y <Picture />.

Autorizando imágenes remotas

Puedes configurar listas de dominios y patrones de URL de origen de imágenes autorizados para la optimización de imágenes utilizando image.domains y image.remotePatterns. Esta configuración es una capa adicional de seguridad para proteger tu sitio al mostrar imágenes de una fuente externa.

Las imágenes remotas de otras fuentes no serán optimizadas, pero usar el componente <Image /> para estas imágenes evitará el cambio de diseño acumulativo (CLS).

Por ejemplo, la siguiente configuración solo permitirá que las imágenes remotas de astro.build sean optimizadas:

export default defineConfig({
  image: {
    domains: ["astro.build"],
  }
});

La siguiente configuración solo permitirá que las imágenes remotas de hosts HTTPS sean optimizadas:

export default defineConfig({
  image: {
    remotePatterns: [{ protocol: "https" }],
  }
});

Imágenes en colecciones de contenido

Puedes declarar una imagen asociada para una entrada de colecciones de contenido, como la imagen de portada de una publicación de blog, en tu frontmatter utilizando su ruta relativa a la carpeta actual:

---
title: "Mi primer post de blog"
cover: "./firstpostcover.jpeg" # va a resolver a "src/content/blog/firstpostcover.jpeg"
coverAlt: "Una fotografía de un atardecer detrás de una cordillera."
---

Contenido del post de blog.

El helper image para el esquema de colecciones de contenido te permite validar e importar la imagen.

import { defineCollection, z } from "astro:content";

const blogCollection = defineCollection({
  schema: ({ image }) => z.object({
    title: z.string(),
    cover: image(),
    coverAlt: z.string(),
  }),
});

export const collections = {
  blog: blogCollection,
};

La imagen será importada y transformada en metadatos, lo que te permitirá pasarla como src a <Image/>, <img>, o getImage() en un componente Astro.

El siguiente ejemplo muestra una página de índice de blog que renderiza la foto de portada y el título de cada publicación de blog a partir del esquema anterior:

---
import { Image } from "astro:assets";
import { getCollection } from "astro:content";
const allBlogPosts = await getCollection("blog");
---

{
  allBlogPosts.map((post) => (
    <div>
      <Image src={post.data.cover} alt={post.data.coverAlt} />
      <h2>
        <a href={"/blog/" + post.slug}>{post.data.title}</a>
      </h2>
    </div>
  ))
}

Generando imágenes con `getImage()`

La función getImage() está destinada a generar imágenes que se utilizarán en otros lugares que no sean directamente en HTML, por ejemplo, en una Ruta API. Cuando necesites opciones que los componentes <Picture> y <Image> no admiten actualmente, puedes usar la función getImage() para crear tu propio componente <Image /> personalizado.

Consulta más en la referencia de getImage().

Receta relacionada: Construye un componente de imagen personalizado

Texto Alternativo

No todos los usuarios pueden ver las imágenes de la misma manera, por lo que la accesibilidad es una preocupación especialmente importante al usar imágenes. Usa el atributo alt para proporcionar texto alternativo descriptivo para las imágenes.

Este atributo es obligatorio tanto para los componentes <Image /> como para los <Picture />. Si no se proporciona texto alternativo, se mostrará un mensaje de error útil recordándote que incluyas el atributo alt.

Si la imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece alt="" para que los lectores de pantalla sepan que ignoren la imagen.

Servicio de imagen predeterminado

Sharp es el servicio de imagen predeterminado utilizado para astro:assets. Puedes configurar aún más el servicio de imagen utilizando la opción image.service.

Configurar un servicio de paso a través no-op

Si tu adaptador no es compatible con la optimización de imágenes Sharp integrada de Astro (por ejemplo, Deno, Cloudflare), puedes configurar un servicio de imagen no-op para permitirte usar los componentes <Image /> y <Picture />. Ten en cuenta que Astro no realiza ninguna transformación y procesamiento de imágenes en estos entornos. Sin embargo, aún puedes disfrutar de los otros beneficios de usar astro:assets, incluido el desplazamiento acumulativo de diseño (CLS) nulo, el atributo alt impuesto y una experiencia de autoría coherente.

Configura el passthroughImageService() para evitar el procesamiento de imágenes de Sharp:

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService()
  }
});

Caché de imágenes

Astro almacena los activos de imagen procesados en un directorio de caché durante las compilaciones del sitio, tanto para imágenes locales como para imágenes remotas de fuentes autorizadas. Al preservar el directorio de caché entre compilaciones, los activos procesados se reutilizan, mejorando el tiempo de compilación y el uso del ancho de banda.

El directorio de caché predeterminado es ./node_modules/.astro, sin embargo, esto se puede cambiar utilizando la configuración cacheDir.

Imágenes remotas

Las imágenes remotas en la caché de activos se gestionan en función de HTTP Caching y respetan el Cache-Control header devuelto por el servidor remoto. Las imágenes se almacenan en caché si el encabezado Cache-Control lo permite y se utilizarán hasta que ya no estén frescas.

Revalidación

Agregado en: astro@5.1.0

La Revalidación reduce el uso de ancho de banda y el tiempo de compilación al verificar con el servidor remoto si una imagen en caché caducada sigue estando actualizada. Si el servidor indica que la imagen sigue siendo fresca, se reutiliza la versión en caché; de lo contrario, se vuelve a descargar la imagen.

La revalidación requiere que el servidor remoto envíe los encabezados Last-Modified y/o Etag (etiqueta de entidad) con sus respuestas. Esta función está disponible para servidores remotos que admiten los encabezados If-Modified-Since y If-None-Match.

Integraciones de la comunidad

Hay varias integraciones de imágenes de la comunidad de terceros para optimizar y trabajar con imágenes en tu proyecto Astro.

Contribuir Comunidad Patrocinador

Imágenes

Dónde guardar las imágenes

src/ vs. public/

Imágenes remotas

Imágenes en archivos .astro

Imágenes en archivos Markdown

Imágenes en archivos MDX

Imágenes en componentes UI de frameworks

Componentes Astro para imágenes

<Image />

<Picture />

Imagenes responsivas

Salida HTML generada para imágenes responsivas

Estilos para imágenes responsivas

Imágenes responsivas con Tailwind 4

Componentes SVG

Atributos del componente SVG

Tipo SvgComponent

Creando componentes de imagen personalizados

Mostrar imágenes sin procesar con la etiqueta HTML <img>

imágenes en src/

Imágenes en public/

Imágenes remotas

Elegir <Image /> vs <img>

Usando imágenes de un CMS o CDN

Autorizando imágenes remotas

Imágenes en colecciones de contenido

Generando imágenes con getImage()

Texto Alternativo

Servicio de imagen predeterminado

Configurar un servicio de paso a través no-op

Caché de imágenes

Imágenes remotas

Revalidación

Integraciones de la comunidad

`src/` vs. `public/`

Imágenes en archivos `.astro`

`<Image />`

`<Picture />`

Tipo `SvgComponent`

Mostrar imágenes sin procesar con la etiqueta HTML `<img>`

imágenes en `src/`

Imágenes en `public/`

Elegir `<Image />` vs `<img>`

Generando imágenes con `getImage()`