Referencia de la API de Imágenes y Recursos
Agregado en:
astro@3.0.0
Astro proporciona componentes integrados y funciones auxiliares para optimizar y mostrar tus imágenes. Para conocer las funciones y ver ejemplos de uso, consulta nuestra guía de imágenes.
Importaciones desde astro:assets
Sección titulada «Importaciones desde astro:assets»Las siguientes funciones auxiliares se importan desde el módulo virtual de recursos:
import { Image, Picture, Font, getImage, inferRemoteSize, getConfiguredImageService, imageConfig, fontData, experimental_getFontFileURL,} from 'astro:assets';<Image />
Sección titulada «<Image />»El componente <Image /> optimiza y transforma imágenes.
---// importa el componente Image y la imagenimport { Image } from 'astro:assets';import myImage from "../assets/my_image.png"; // La imagen es 1600x900---
<!-- `alt` es obligatorio en el componente Image --><Image src={myImage} alt="Una descripción de mi imagen." /><!-- Salida --><!-- La imagen está optimizada y se aplican los atributos correctos --><img src="/_astro/my_image.hash.webp" width="1600" height="900" decoding="async" loading="lazy" alt="Una descripción de mi imagen."/>El componente <Image /> acepta las siguientes propiedades listadas, además de todas las propiedades que acepta la etiqueta HTML <img>.
src (required)
Sección titulada «src (required)»Tipo: ImageMetadata | string | Promise<{ default: ImageMetadata }>
El formato del valor src de tu archivo de imagen depende de dónde se encuentre tu archivo de imagen:
-
Imágenes locales en
src/: debes importar también la imagen usando una ruta relativa del archivo o configurar y usar un alias de importación (EN). Luego, utiliza el nombre del import como valor desrc:src/pages/index.astro ---import { Image } from 'astro:assets';import myImportedImage from '../assets/my-local-image.png';---<Image src={myImportedImage} alt="texto descriptivo" /> -
Imágenes en la carpeta
public/: utiliza la ruta del archivo relativa a la carpeta public:src/pages/index.astro ---import { Image } from 'astro:assets';---<Imagesrc="/my-public-image.png"alt="texto descriptivo"width="300"height="150"/> -
Imágenes remotas: utiliza la URL completa de la imagen como valor de la propiedad:
src/pages/index.astro ---import { Image } from 'astro:assets';---<Imagesrc="https://example.com/remote-image.jpg"alt="texto descriptivo"width="300"height="150"/>
alt (required)
Sección titulada «alt (required)»Tipo: string
Usa el atributo obligatorio alt para proporcionar un texto alternativo descriptivo para las imágenes.
Si una imagen es meramente decorativa (es decir, no contribuye a la comprensión de la página), establece alt="" para que los lectores de pantalla y otras tecnologías de asistencia sepan que deben ignorar la imagen.
width and height (required for images in public/)
Sección titulada «width and height (required for images in public/)»Tipo: number | `${number}` | undefined
Estas propiedades definen las dimensiones que se usarán para la imagen.
Cuando se establece un tipo de layout, estas se generan automáticamente en función de las dimensiones de la imagen y, en la mayoría de los casos, no deberían establecerse manualmente.
Al usar imágenes con su relación de aspecto original, width y height son opcionales. Estas dimensiones se pueden inferir automáticamente a partir de archivos de imagen ubicados en src/. Para imágenes remotas, agrega el atributo inferSize establecido en true en el componente <Image /> o <Picture /> o usa la función inferRemoteSize().
Sin embargo, ambas propiedades son obligatorias para las imágenes almacenadas en tu carpeta public/, ya que Astro no puede analizar estos archivos.
densities
Sección titulada «densities»Tipo: (number | `${number}x`)[] | undefined
astro@3.3.0
Una lista de densidades de píxeles para generar la imagen.
El atributo densities no es compatible con tener la propiedad layout o la configuración image.layout establecida, y será ignorado si se establece.
Si se proporciona, este valor se usará para generar un atributo srcset en la etiqueta <img>. No proporciones un valor para widths cuando uses este valor.
Las densidades que sean iguales o mayores que los anchos superiores a la imagen original serán ignoradas para evitar escalar la imagen hacia arriba.
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} width={myImage.width / 2} densities={[1.5, 2]} alt="Una descripción de mi imagen."/><!-- Salida --><img src="/_astro/my_image.hash.webp" srcset=" /_astro/my_image.hash.webp 1.5x, /_astro/my_image.hash.webp 2x " alt="Una descripción de mi imagen." width="800" height="450" loading="lazy" decoding="async"/>Tipo: number[] | undefined
astro@3.3.0
Una lista de anchos para generar la imagen.
Si se proporciona, este valor se usará para generar un atributo srcset en la etiqueta <img>. También se debe proporcionar una propiedad sizes.
Los atributos widths y sizes se generarán automáticamente para imágenes utilizando una propiedad layout. Generalmente no es necesario proporcionar estos valores, pero se pueden utilizar para anular cualquier valor generado automáticamente.
No proporciones un valor para densities cuando uses este valor. Solo uno de estos dos valores puede usarse para generar un srcset.
Los anchos que sean mayores que la imagen original serán ignorados para evitar escalar la imagen hacia arriba.
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png'; // La imagen es de 1600x900---<Image src={myImage} widths={[240, 540, 720, myImage.width]} sizes={`(max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, ${myImage.width}px`} alt="Una descripción de mi imagen."/><!-- Salida --><img src="/_astro/my_image.hash.webp" srcset=" /_astro/my_image.hash.webp 240w, /_astro/my_image.hash.webp 540w, /_astro/my_image.hash.webp 720w, /_astro/my_image.hash.webp 1600w " sizes=" (max-width: 360px) 240px, (max-width: 720px) 540px, (max-width: 1600px) 720px, 1600px " alt="Una descripción de mi imagen." width="1600" height="900" loading="lazy" decoding="async"/>Tipo: string | undefined
astro@3.3.0
Especifica el ancho de visualización de la imagen para cada una de las distintas condiciones de pantalla. Debe proporcionarse al especificar widths.
Los atributos widths y sizes se generarán automáticamente para imágenes utilizando una propiedad layout. Generalmente no es necesario proporcionar estos valores, pero se pueden utilizar para anular cualquier valor generado automáticamente.
El atributo sizes generado para imágenes con constrained y full-width se basa en la suposición de que la imagen se muestra cerca del ancho completo de la pantalla cuando el viewport es más pequeño que el ancho de la imagen. Si es significativamente diferente (por ejemplo, si está en un diseño de varias columnas en pantallas pequeñas), es posible que debas ajustar el atributo sizes manualmente para obtener mejores resultados.
Tipo: ImageOutputFormat | undefined
Opcionalmente, puedes indicar la salida del tipo de archivo de imagen que se utilizará.
Por defecto, el componente <Image /> producirá un archivo .webp.
quality
Sección titulada «quality»Tipo: ImageQuality | undefined
quality es una propiedad opcional que puede ser:
- un ajuste preestablecido (
low,mid,high,max) que se normaliza automáticamente entre formatos. - un número del
0al100(interpretado de manera diferente entre formatos).
inferSize
Sección titulada «inferSize»Tipo: boolean
Por defecto: false
astro@4.4.0
Te permite establecer automáticamente el width y height originales de una imagen remota.
De forma predeterminada, este valor está establecido en false y debes especificar manualmente ambas dimensiones para tu imagen remota.
Agrega inferSize al componente <Image /> (o inferSize: true a getImage()) para inferir estos valores a partir del contenido de la imagen cuando se obtiene. Esto es útil si no conoces las dimensiones de la imagen remota o si estas podrían cambiar:
---import { Image } from 'astro:assets';---<Image src="https://example.com/cat.png" inferSize alt="Un gato durmiendo al sol." />A partir de Astro 5.17.3, inferSize solo obtiene dimensiones para dominios de imágenes remotas autorizados. Las imágenes remotas fuera de la lista de permitidos no se obtienen.
priority
Sección titulada «priority»Tipo: boolean
Por defecto: false
astro@5.10.0
Te permite configurar automáticamente los atributos loading, decoding y fetchpriority en sus valores óptimos para imágenes en la mitad superior de la página (above-the-fold).
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} priority alt="Una descripción de mi imagen" />Cuando se añade priority="true" (o la sintaxis abreviada priority) al componente <Image /> o <Picture />, añadirá los siguientes atributos para indicarle al navegador que cargue la imagen inmediatamente:
loading="eager"decoding="sync"fetchpriority="high"Estos atributos individuales aún se pueden configurar manualmente si necesitas personalizarlos más.
Tipo: 'constrained' | 'full-width' | 'fixed' | 'none'
Por defecto: image.layout | 'none'
astro@5.10.0
Determina cómo debe cambiar el tamaño de la imagen cuando cambia el tamaño de su contenedor. Se puede usar para sobrescribir el valor configurado por defecto para image.layout (EN).
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} alt="Una descripción de mi imagen." layout='constrained' width={800} height={600} />Cuando se establece un layout, los atributos srcset y sizes se generan automáticamente en función de las dimensiones de la imagen y el tipo de layout. El componente <Image /> anterior generará la siguiente salida HTML:
<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">layout admite los siguientes valores:
-
constrained- La imagen se reducirá para ajustarse al contenedor, manteniendo su relación de aspecto, pero no aumentará más allá delwidthyheightespecificados, o de las dimensiones originales de la imagen.Úsalo si quieres que la imagen se muestre al tamaño solicitado cuando sea posible, pero que se reduzca para ajustarse a pantallas más pequeñas. Esto coincide con el comportamiento predeterminado para imágenes al usar Tailwind. Si no estás seguro, probablemente este sea el layout que debas elegir.
-
full-width- La imagen se escalará para ajustarse al ancho del contenedor, manteniendo su relación de aspecto.Úsalo para imágenes principales (hero) u otras imágenes que deban ocupar todo el ancho de la página.
-
fixed- La imagen mantendrá las dimensiones solicitadas y no cambiará de tamaño. Generará unsrcsetpara pantallas de alta densidad, pero no para diferentes tamaños de pantalla.Úsalo si la imagen no cambiará de tamaño, por ejemplo, íconos o logotipos más pequeños que cualquier ancho de pantalla, u otras imágenes en un contenedor de ancho fijo.
-
none- La imagen no será responsiva. No se generarán automáticamentesrcsetnisizes, y no se aplicarán estilos.Esto es útil si tienes habilitado un diseño por defecto, pero quieres desactivarlo para una imagen específica.
Por ejemplo, con constrained establecido como el diseño predeterminado, puedes sobrescribir la propiedad layout de cualquier imagen individual:
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---<Image src={myImage} alt="Esto usará el layout constrained" width={800} height={600} /><Image src={myImage} alt="Esto usará el diseño full-width" layout="full-width" /><Image src={myImage} alt="Esto deshabilitará las imágenes responsivas" layout="none" />El valor de layout también define los estilos predeterminados aplicados a la etiqueta <img> para determinar cómo debe cambiar el tamaño de la imagen según su contenedor:
: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%;}Tipo: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'
Por defecto: image.objectFit | 'cover'
astro@5.10.0
Define cómo debe recortarse una imagen si se cambia su relación de aspecto.
Los valores coinciden con los de object-fit en CSS. Por defecto es cover, o el valor de image.objectFit (EN) si está configurado. Se puede usar para sobrescribir los estilos object-fit predeterminados.
position
Sección titulada «position»Tipo: string
Por defecto: image.objectPosition | 'center'
astro@5.10.0
Define la posición del recorte de la imagen para una imagen si se cambia su relación de aspecto.
Los valores coinciden con los de object-position en CSS. Por defecto es center, o el valor de image.objectPosition (EN) si está configurado. Se puede usar para sobrescribir los estilos object-position predeterminados.
background
Sección titulada «background»Tipo: string | undefined
astro@5.17.0
El color de fondo que se utilizará al aplanar una imagen para transformarla al format de salida solicitado.
Por defecto, Sharp utiliza un fondo negro al aplanar una imagen. Especificar un color de fondo diferente es especialmente útil al transformar imágenes con fondos transparentes a un formato que no admite transparencia (por ejemplo, .jpeg):
---import { Image } from 'astro:assets';import myImage from '../assets/my_image.png';---
<Image src={myImage} alt="Una descripción de mi imagen" format="jpeg" background="#ffffff"/>Los valores se pasan directamente al servicio de imágenes. Sharp acepta cualquier valor que el paquete color-string pueda analizar.
<Picture />
Sección titulada «<Picture />»
Agregado en:
astro@3.3.0
El componente <Picture /> genera una imagen optimizada con múltiples formatos y/o tamaños.
---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 --><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><Picture /> acepta todas las propiedades de el componente <Image /> además de las siguientes:
formats
Sección titulada «formats»Tipo: ImageOutputFormat[]
Un array de formatos de imagen para usar en las etiquetas <source>. Las entradas se añadirán como elementos <source> en el orden en que se listan, y este orden determina qué formato se muestra. Para el mejor rendimiento, lista primero el formato más moderno (por ejemplo, webp o avif). Por defecto, está establecido en ['webp'].
fallbackFormat
Sección titulada «fallbackFormat»Tipo: ImageOutputFormat
Formato a usar como valor alternativo para la etiqueta <img>. Por defecto es .png para imágenes estáticas (o .jpg si la imagen es un JPG), .gif para imágenes animadas y .svg para archivos SVG.
pictureAttributes
Sección titulada «pictureAttributes»Tipo: HTMLAttributes<'picture'>
Un objeto de atributos que se añadirán a la etiqueta <picture>.
Usa esta propiedad para aplicar atributos al propio elemento exterior <picture>. Los atributos aplicados al componente <Picture /> directamente se aplicarán al elemento interior <img>, excepto aquellos utilizados para la transformación de imágenes.
---import { Picture } from 'astro:assets';import myImage from '../assets/my_image.png'; // La imagen es de 1600x900---
<Picture src={myImage} alt="Una descripción de mi imagen." pictureAttributes={{ style: "background-color: red;" }}/><!-- Salida --><picture style="background-color: red;"> <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><Font />
Sección titulada «<Font />»
Agregado en:
astro@6.0.0
El componente <Font /> genera etiquetas de estilo y opcionalmente puede generar enlaces de precarga para una familia de fuentes determinada.
Debe importarse y añadirse a la etiqueta <head> de tu página. Comúnmente esto se hace en un componente como Head.astro que se utiliza en una plantilla común del sitio para uso global, pero puede añadirse a páginas individuales según sea necesario.
Con este componente, tienes control sobre qué familia de fuentes se utiliza en qué página y qué fuentes se precargan.
---import { Font } from "astro:assets";---
<Font cssVariable="--font-roboto" />El componente <Font /> acepta las siguientes propiedades:
cssVariable (required)
Sección titulada «cssVariable (required)»Tipo: CssVariable
Tipo de ejemplo: "--font-roboto" | "--font-comic-sans" | ...
La cssVariable (EN) registrada en tu configuración de Astro:
---import { Font } from "astro:assets";---
<Font cssVariable="--font-roboto" />preload
Sección titulada «preload»Tipo: boolean | { weight?: string | number; style?: string; subset?: string }[]
Por defecto: false
Indica si se deben generar enlaces de precarga o no. Con la directiva preload, el navegador comenzará a descargar inmediatamente todos los enlaces de fuentes posibles durante la carga de la página:
---import { Font } from "astro:assets";---
<Font cssVariable="--font-roboto" preload />Selecciona cuidadosamente las fuentes que precargas. Precargar demasiadas fuentes puede afectar el rendimiento, ya que esto puede bloquear la carga de otros recursos importantes o descargar fuentes que no son necesarias para la página actual.
Para controlar selectivamente qué archivos de fuentes se precargan, puedes proporcionar un array de objetos que describan cualquier combinación de weight, style o subset de la fuente a precargar:
---import { Font } from "astro:assets";---
<Font cssVariable="--font-roboto" preload={[ { subset: "latin", style: "normal" }, { weight: "400" }, ]}/>Los archivos de fuentes de peso variable se precargarán si se solicita cualquier peso dentro de su rango. Por ejemplo, un archivo de fuente para el peso de fuente 100 900 se incluirá cuando se especifique 400 en un objeto preload.
getImage()
Sección titulada «getImage()»Tipo: (options: UnresolvedImageTransform) => Promise<GetImageResult>
getImage() depende de APIs exclusivas del servidor y lanzará un error en el cliente.
Si necesitas la URL resultante de la imagen en el lado del cliente, puedes pasar el src desde una llamada a getImage() renderizada en el servidor al cliente.
La función getImage() está pensada para generar imágenes destinadas a ser usadas en otro lugar que no sea directamente en HTML, por ejemplo, en una ruta de API (EN). También te permite crear tu propio componente <Image />.
Esta función toma un objeto de opciones con las mismas propiedades que el componente Image (excepto alt y sizes) y devuelve un objeto GetImageResult.
El siguiente ejemplo genera una background-image en AVIF para un <div />:
---import { getImage } from "astro:assets";import myBackground from "../background.png"
const optimizedBackground = await getImage({src: myBackground, format: 'avif'})---
<div style={`background-image: url(${optimizedBackground.src});`}><slot /></div>inferRemoteSize()
Sección titulada «inferRemoteSize()»Tipo: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>
astro@4.12.0
Una función para establecer el width y height original de una imagen remota automáticamente. Esto se puede usar como una alternativa a pasar la propiedad inferSize .
import { inferRemoteSize } from 'astro:assets';const { width, height } = await inferRemoteSize("https://example.com/cat.png");getConfiguredImageService()
Sección titulada «getConfiguredImageService()»Tipo: () => Promise<ImageService>
astro@2.1.3
Recupera el servicio de imágenes (EN) resuelto.
imageConfig
Sección titulada «imageConfig»Tipo: AstroConfig["image"] (EN)
astro@3.0.9
Las opciones de configuración para imágenes (EN) establecidas por el usuario y fusionadas con todos los valores por defecto.
fontData
Sección titulada «fontData»Tipo: Record<CssVariable, Array<FontData>>
astro@6.0.0
Un objeto donde cada clave es una cssVariable (EN) y el valor es un array que describe las fuentes asociadas. Cada fuente es un objeto que contiene un array de src disponible para esa fuente y las siguientes propiedades opcionales: weight y style:
import { fontData } from "astro:assets"
const data = fontData["--font-roboto"]experimental_getFontFileURL()
Sección titulada «experimental_getFontFileURL()»Tipo: (url: string, requestUrl?: URL) => Promise<string>
astro@6.2.0
Resuelve la URL de un archivo de fuente obtenido desde fontData:
import { fontData, experimental_getFontFileURL } from "astro:assets";
const fontPath = fontData["--font-roboto"][0]?.src[0]?.url;
if (fontPath === undefined) { throw new Error("Cannot find the font path.");}
const url = experimental_getFontFileURL(fontPath);const buffer = await fetch(url).then((res) => res.arrayBuffer());Cuando se llama en una ruta renderizada bajo demanda, se debe proporcionar la URL de la solicitud:
import type { APIRoute } from "astro";import { fontData, experimental_getFontFileURL } from "astro:assets";
export const prerender = false; // No se necesita en modo 'server'
export const GET: APIRoute = async (context) => { // ... const fontPath = fontData["--font-roboto"][0]?.src[0]?.url; const url = experimental_getFontFileURL(fontPath, context.url); // ...};Tipos de astro:assets
Sección titulada «Tipos de astro:assets»Los siguientes tipos se importan desde el módulo virtual de assets:
import type { LocalImageProps, RemoteImageProps, FontData} from "astro/assets";LocalImageProps
Sección titulada «LocalImageProps»Tipo: ImageSharedProps<T> & { src: ImageMetadata | Promise<{ default: ImageMetadata; }> }
Describe las propiedades de una imagen local. Esto asegura que src coincida con la forma de una imagen importada.
src/ con un ejemplo de uso.
RemoteImageProps
Sección titulada «RemoteImageProps»Tipos:
ImageSharedProps<T> & { src: string; inferSize: true; }ImageSharedProps<T> & { src: string; inferSize?: false | undefined; }
Describe las propiedades de una imagen remota. Esto asegura que cuando inferSize no se proporcione o esté establecido en false, tanto width como height sean obligatorios.
FontData
Sección titulada «FontData»Tipo: { src: Array<{ url: string; format?: string; tech?: string }>; weight?: string; style?: string; subset?: string; }
astro@6.0.0
Describe los datos de la fuente asociados con una familia de fuentes determinada.
FontData.src
Sección titulada «FontData.src»Tipo: Array<{ url: string; format?: string; tech?: string }>
Un array de objetos que describen los archivos de fuentes disponibles para una familia de fuentes determinada. Cada objeto contiene una url y, opcionalmente, el format y la tech asociados.
FontData.weight
Sección titulada «FontData.weight»Tipo: string
Especifica el peso de la fuente (por ejemplo, 400, 600).
FontData.style
Sección titulada «FontData.style»Tipo: string
Especifica el estilo de la fuente (por ejemplo, normal, italic).
FontData.subset
Sección titulada «FontData.subset»Tipo: string
astro@7.0.0
Especifica el subconjunto de la fuente (por ejemplo, latin, cyrillic).
Importaciones desde astro/assets
Sección titulada «Importaciones desde astro/assets»Las siguientes funciones auxiliares se importan desde el módulo de assets regular:
import { baseService, getConfiguredImageService, getImage, isLocalService,} from "astro/assets";baseService
Sección titulada «baseService»Tipo: Omit<LocalImageService, ‘transform’>
El servicio de imágenes local integrado que se puede extender para crear un servicio de imágenes personalizado (EN).
El siguiente ejemplo reutiliza baseService para crear un nuevo servicio de imágenes:
import { baseService } from "astro/assets";
const newImageService = { getURL: baseService.getURL, parseURL: baseService.parseURL, getHTMLAttributes: baseService.getHTMLAttributes, async transform(inputBuffer, transformOptions) { /* ... */ },};getConfiguredImageService()
Sección titulada «getConfiguredImageService()»Consulta getConfiguredImageService() desde astro:assets.
getImage()
Sección titulada «getImage()»Tipo: (options: UnresolvedImageTransform, imageConfig: AstroConfig[‘image’]) => Promise<GetImageResult>
Una función similar a getImage() desde astro:assets con dos argumentos obligatorios: un objeto options con las mismas propiedades que el componente Image y un segundo objeto para la configuración de la imagen (EN).
isLocalService()
Sección titulada «isLocalService()»Tipo: (service: ImageService | undefined) => boolean
Comprueba el tipo de un servicio de imágenes y devuelve true cuando se trata de un servicio local.
Tipos de astro/assets
Sección titulada «Tipos de astro/assets»Los siguientes tipos se importan desde el módulo de assets regular:
import type { LocalImageProps, RemoteImageProps,} from "astro/assets";LocalImageProps
Sección titulada «LocalImageProps»Consulta LocalImageProps desde astro:assets.
RemoteImageProps
Sección titulada «RemoteImageProps»Consulta RemoteImageProps desde astro:assets.
Importaciones desde astro/assets/utils
Sección titulada «Importaciones desde astro/assets/utils»Las siguientes funciones auxiliares se importan desde el directorio utils en el módulo de assets regular y se pueden usar para construir un servicio de imágenes (EN):
import { isRemoteAllowed, matchHostname, matchPathname, matchPattern, matchPort, matchProtocol, isESMImportedImage, isRemoteImage, resolveSrc, imageMetadata, emitImageMetadata, emitClientAsset, getOrigQueryParams, inferRemoteSize, propsToFilename, hashTransform,} from "astro/assets/utils";isRemoteAllowed()
Sección titulada «isRemoteAllowed()»Tipo: (src: string, { domains, remotePatterns }: { domains: string[], remotePatterns: RemotePattern[] }) => boolean
astro@4.0.0
Determina si un recurso remoto determinado, identificado por su URL de origen, está permitido según los dominios y los patrones remotos especificados.
import { isRemoteAllowed } from 'astro/assets/utils';
const url = new URL('https://example.com/images/test.jpg');const domains = ['example.com', 'anotherdomain.com'];const remotePatterns = [ { protocol: 'https', hostname: 'images.example.com', pathname: '/**', // Permite cualquier ruta bajo este hostname }];
isRemoteAllowed(url.href, { domains, remotePatterns }); // Output: `true`matchHostname()
Sección titulada «matchHostname()»Tipo: (url: URL, hostname?: string, allowWildcard = false) => boolean
astro@4.0.0
Compara el hostname de una URL dada con un hostname especificado, con soporte opcional para patrones comodín.
import { matchHostname } from 'astro/assets/utils';
const url = new URL('https://sub.example.com/path/to/resource');
matchHostname(url, 'example.com'); // Output: `false`matchHostname(url, 'example.com', true); // Output: `true`matchPathname()
Sección titulada «matchPathname()»Tipo: (url: URL, pathname?: string, allowWildcard = false) => boolean
astro@4.0.0
Compara la ruta de una URL dada con un patrón especificado, con soporte opcional para comodines.
import { matchPathname } from 'astro/assets/utils';
const testURL = new URL('https://example.com/images/photo.jpg');
matchPathname(testURL, '/images/photo.jpg'); // Output: `true`matchPathname(testURL, '/images/'); // Output: `false`matchPathname(testURL, '/images/*', true); // Output: `true`matchPattern()
Sección titulada «matchPattern()»Tipo: (url: URL, remotePattern: RemotePattern) => boolean
astro@4.0.0
Evalúa si una URL dada coincide con el patrón remoto especificado en función del protocolo, el hostname, el puerto y la ruta.
import { matchPattern } from 'astro/assets/utils';
const url = new URL('https://images.example.com/photos/test.jpg');const remotePattern = { protocol: 'https', hostname: 'images.example.com', pathname: '/photos/**', // Permite todos los archivos bajo /photos/};
matchPattern(url, remotePattern); // Output: `true`matchPort()
Sección titulada «matchPort()»Tipo: (url: URL, port?: string) => boolean
Por defecto: true
astro@4.0.0
Comprueba si el puerto de la URL dada coincide con el puerto especificado. Si no se proporciona ningún puerto, devuelve true.
import { matchPort } from 'astro/assets/utils';
const urlWithPort = new URL('https://example.com:8080/resource');const urlWithoutPort = new URL('https://example.com/resource');
matchPort(urlWithPort, '8080'); // Output: `true`matchPort(urlWithoutPort, '8080'); // Output: `false`matchProtocol()
Sección titulada «matchProtocol()»Tipo: (url: URL, protocol?: string) => boolean
Por defecto: true
astro@4.0.0
Compara el protocolo de la URL proporcionada con un protocolo especificado. Esto devuelve true si el protocolo coincide o si no se proporciona ningún protocolo.
import { matchProtocol } from 'astro/assets/utils';
const secureUrl = new URL('https://example.com/resource');const regularUrl = new URL('http://example.com/resource');
matchProtocol(secureUrl, 'https'); // Output: `true`matchProtocol(regularUrl, 'https'); // Output: `false`isESMImportedImage()
Sección titulada «isESMImportedImage()»Tipo: (src: ImageMetadata | string) => boolean
astro@4.0.0
Determina si la fuente dada es una imagen importada como Módulo ECMAScript (ESM).
import { isESMImportedImage } from 'astro/assets/utils';
const imageMetadata = { src: '/images/photo.jpg', width: 800, height: 600, format: 'jpg',};const filePath = '/images/photo.jpg';
isESMImportedImage(imageMetadata); // Output: `true`isESMImportedImage(filePath); // Output: `false`isRemoteImage()
Sección titulada «isRemoteImage()»Tipo: (src: ImageMetadata | string) => boolean
astro@4.0.0
Determina si la fuente proporcionada es una URL de imagen remota en forma de cadena.
import { isRemoteImage } from 'astro/assets/utils';
const imageUrl = 'https://example.com/images/photo.jpg';const localImage = { src: '/images/photo.jpg', width: 800, height: 600, format: 'jpg',};
isRemoteImage(imageUrl); // Output: `true`isRemoteImage(localImage); // Output: `false`resolveSrc()
Sección titulada «resolveSrc()»Tipo: (src: UnresolvedImageTransform[‘src’]) => Promise<string | ImageMetadata>
astro@4.0.0
Devuelve la fuente de la imagen. Esta función garantiza que si src es una Promise (por ejemplo, un import() dinámico), se espere y se extraiga el src correcto. Si src ya es un valor resuelto, se devuelve tal cual.
import { resolveSrc } from 'astro/assets/utils';import localImage from "./images/photo.jpg";
const resolvedLocal = await resolveSrc(localImage);// Valor de ejemplo: `{ src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg', width: 800, height: 600, format: 'jpg' }`
const resolvedRemote = await resolveSrc("https://example.com/remote-img.jpg");// Value: `"https://example.com/remote-img.jpg"`
const resolvedDynamic = await resolveSrc(import("./images/dynamic-image.jpg"))// Valor de ejemplo: `{ src: '/@fs/home/username/dev/astro-project/src/images/dynamic-image.jpg', width: 800, height: 600, format: 'jpg' }`imageMetadata()
Sección titulada «imageMetadata()»Tipo: (data: Uint8Array, src?: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>
astro@4.0.0
Extrae los metadatos de la imagen, como las dimensiones, el formato y la orientación, a partir de los datos de imagen proporcionados.
import { imageMetadata } from 'astro/assets/utils';
const binaryImage = new Uint8Array([/* ...binary image data... */]);const sourcePath = '/images/photo.jpg';
const metadata = await imageMetadata(binaryImage, sourcePath);// Valor de ejemplo:// {// width: 800,// height: 600,// format: 'jpg',// orientation: undefined// }emitImageMetadata()
Sección titulada «emitImageMetadata()»Tipo: (id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise<(ImageMetadata & { contents?: Buffer }) | undefined>
astro@5.7.0
Procesa un archivo de imagen y emite sus metadatos y opcionalmente su contenido. En modo de compilación, la función utiliza fileEmitter para generar una referencia de recurso. En modo de desarrollo, se resuelve en una URL de archivo local con parámetros de consulta para los metadatos.
import { emitImageMetadata } from 'astro/assets/utils';
const imageId = '/images/photo.jpg';const metadata = await emitImageMetadata(imageId);// Valor de ejemplo:// {// src: '/@fs/home/username/dev/astro-project/src/images/photo.jpg?origWidth=800&origHeight=600&origFormat=jpg',// width: 800,// height: 600,// format: 'jpg',// contents: Uint8Array([...])// }emitClientAsset()
Sección titulada «emitClientAsset()»Tipo: (pluginContext: Rollup.PluginContext, options: Rollup.EmitFile) => string
astro@6.0.0
Emite un recurso de cliente que se moverá al directorio de cliente para recursos (por ejemplo, dist/client/_astro/) durante las compilaciones SSR. Esta función está destinada a autores de integraciones que necesitan emitir recursos (como imágenes) desde contenido renderizado en el servidor que debería estar disponible en el cliente.
Usa esto en lugar de pluginContext.emitFile() de Rollup directamente cuando trabajes en el contexto de un plugin de Vite y necesites que el recurso emitido se mueva al directorio de salida del cliente.
import { emitClientAsset } from 'astro/assets/utils';
function myVitePlugin() { return { name: 'my-plugin', transform(code, id) { const handle = emitClientAsset(this, { type: 'asset', name: 'my-image.png', source: imageBuffer, }); // Returns the asset handle similar to `emitFile()` } }}getOrigQueryParams()
Sección titulada «getOrigQueryParams()»Tipo: (params: URLSearchParams) => Pick<ImageMetadata, ‘width’ | ‘height’ | ‘format’> | undefined
astro@4.0.0
Recupera el width, height y format de una imagen a partir de un objeto URLSearchParams. Si alguno de estos parámetros falta o no es válido, la función devuelve undefined.
import { getOrigQueryParams } from 'astro/assets/utils';
const url = new URL('https://example.com/image.jpg?width=800&height=600&format=jpg');const origParams = getOrigQueryParams(url.searchParams);// Valor de ejemplo:// {// width: 800,// height: 600,// format: 'jpg'// }inferRemoteSize()
Sección titulada «inferRemoteSize()»Tipo: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>
astro@4.0.0
Infiere las dimensiones de una imagen remota transmitiendo sus datos y analizándola progresivamente hasta que haya suficientes metadatos disponibles.
import { inferRemoteSize } from 'astro/assets/utils';
const remoteImageUrl = 'https://example.com/image.jpg';const imageSize = await inferRemoteSize(remoteImageUrl);// Valor de ejemplo:// {// width: 1920,// height: 1080,// format: 'jpg'// }propsToFilename()
Sección titulada «propsToFilename()»Tipo: (filePath: string, transform: ImageTransform, hash: string) => string
astro@4.0.0
Genera un nombre de archivo formateado para una imagen en función de su ruta de origen, propiedades de transformación y un hash único.
El nombre de archivo formateado sigue esta estructura:
<prefixDirname>/<baseFilename>_<hash><outputExtension>
prefixDirname: Si la imagen es una imagen importada por ESM, este es el nombre del directorio de la ruta del archivo original; de lo contrario, será una cadena vacía.baseFilename: El nombre base del archivo o un nombre corto con hash si el archivo es un URIdata:.hash: Una cadena de hash única generada para distinguir el archivo transformado.outputExtension: La extensión del archivo de salida deseada derivada detransform.formato la extensión del archivo original.
import { propsToFilename } from 'astro/assets/utils';
const filePath = '/images/photo.jpg';const transform = { format: 'png', src: filePath };const hash = 'abcd1234';
const filename = propsToFilename(filePath, transform, hash);// Valor de ejemplo: '/images/photo_abcd1234.png'hashTransform()
Sección titulada «hashTransform()»Tipo: (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string
astro@4.0.0
Transforma el objeto transform proporcionado en una cadena de hash basada en las propiedades seleccionadas y el imageService especificado.
import { hashTransform } from 'astro/assets/utils';
const transform = { src: '/images/photo.jpg', width: 800, height: 600, format: 'jpg',};const imageService = 'astro/assets/services/sharp';const propertiesToHash = ['width', 'height', 'format'];
const hash = hashTransform(transform, imageService, propertiesToHash);// Valor de ejemplo: 'd41d8cd98f00b204e9800998ecf8427e'Tipos de astro
Sección titulada «Tipos de astro»import type { GetImageResult, ImageTransform, UnresolvedImageTransform, ImageMetadata, ImageInputFormat, ImageOutputFormat, ImageQuality, ImageQualityPreset, RemotePattern, ImageService, ExternalImageService, LocalImageService, ImageServiceConfig,} from "astro";GetImageResult
Sección titulada «GetImageResult»Tipo: object
astro@2.2.0
Describe el resultado de la transformación tras la llamada a getImage().
GetImageResult.attributes
Sección titulada «GetImageResult.attributes»Tipo: Record<string, any>
Define los atributos HTML adicionales necesarios para renderizar la imagen (por ejemplo, width, height, style).
GetImageResult.options
Sección titulada «GetImageResult.options»Tipo: ImageTransform
Describe los ajustes de transformación tras la validación.
GetImageResult.rawOptions
Sección titulada «GetImageResult.rawOptions»Tipo: ImageTransform
Describe los ajustes de transformación originales.
GetImageResult.src
Sección titulada «GetImageResult.src»Tipo: string
La ruta a la imagen generada.
GetImageResult.srcSet
Sección titulada «GetImageResult.srcSet»Tipo: { values: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]; attribute: string; }
astro@3.3.0
Un objeto que describe cómo renderizar el atributo srcset.
GetImageResult.srcSet.values
Sección titulada «GetImageResult.srcSet.values»Tipo: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]
Un array de valores generados donde cada entrada incluye una URL y un descriptor de tamaño. Esto se puede usar para generar manualmente el valor del atributo srcset.
GetImageResult.srcSet.attribute
Sección titulada «GetImageResult.srcSet.attribute»Tipo: string
Un valor listo para usar en el atributo srcset.
ImageTransform
Sección titulada «ImageTransform»Tipo: object
Define las opciones aceptadas por el servicio de transformación de imágenes. Contiene una propiedad src obligatoria, propiedades predefinidas opcionales y cualquier propiedad adicional requerida por el servicio de imágenes.
Las propiedades predefinidas coinciden con las aceptadas por el componente <Image />, excepto alt y sizes. Las siguientes propiedades utilizan tipos diferentes.
ImageTransform.src
Sección titulada «ImageTransform.src»Tipo: ImageMetadata | string
Define la ruta a una imagen local en el directorio public, la URL de una imagen remota o los datos de una imagen importada.
ImageTransform.width
Sección titulada «ImageTransform.width»Tipo: number | undefined
El ancho de la imagen.
ImageTransform.height
Sección titulada «ImageTransform.height»Tipo: number | undefined
La altura de la imagen.
UnresolvedImageTransform
Sección titulada «UnresolvedImageTransform»Tipo: Omit<ImageTransform, “src”> & { src: ImageMetadata | string | Promise<{ default: ImageMetadata }>; inferSize?: boolean; }
Representa una imagen con opciones de transformación. Contiene las mismas propiedades que el tipo ImageTransform con un tipo src diferente y una propiedad inferSize adicional.
UnresolvedImageTransform.src
Sección titulada «UnresolvedImageTransform.src»Tipo: ImageMetadata | string | Promise<{ default: ImageMetadata }>
La ruta a una imagen importada o ubicada en el directorio public, o la URL de una imagen remota.
UnresolvedImageTransform.inferSize
Sección titulada «UnresolvedImageTransform.inferSize»Tipo: boolean
Determina si el ancho y la altura de la imagen deben inferirse.
inferSize disponible en <Image />.
ImageMetadata
Sección titulada «ImageMetadata»Tipo: { src: string; width: number; height: number; format: ImageInputFormat; orientation?: number; }
astro@2.1.3
Describe los datos recopilados durante la importación de imágenes. Contiene las siguientes propiedades:
ImageMetadata.src
Sección titulada «ImageMetadata.src»Tipo: string
La ruta absoluta de la imagen en el sistema de archivos.
ImageMetadata.width
Sección titulada «ImageMetadata.width»Tipo: number
El ancho de la imagen.
ImageMetadata.height
Sección titulada «ImageMetadata.height»Tipo: number
La altura de la imagen.
ImageMetadata.format
Sección titulada «ImageMetadata.format»Tipo: ImageInputFormat
El formato de la imagen.
ImageMetadata.orientation
Sección titulada «ImageMetadata.orientation»Tipo: number
astro@2.8.3
La orientación de la imagen cuando sus metadatos contienen esta información.
ImageInputFormat
Sección titulada «ImageInputFormat»Tipo: "jpeg" | "jpg" | "png" | "tiff" | "webp" | "gif" | "svg" | "avif"
astro@2.2.0
Describe una unión de formatos compatibles para imágenes importadas.
ImageOutputFormat
Sección titulada «ImageOutputFormat»Tipo: string | "jpeg" | "jpg" | "png" | "webp" | "svg" | "avif"
astro@2.2.0
Especifica el formato para las imágenes de salida. Puede ser un literal predefinido o cualquier cadena.
ImageQuality
Sección titulada «ImageQuality»Tipo: ImageQualityPreset | number
astro@2.2.0
Representa la calidad perceptual de la imagen de salida como una unión de literales predefinidos, una cadena o un número.
ImageQualityPreset
Sección titulada «ImageQualityPreset»Tipo: string | "low" | "mid" | "high" | "max"
astro@2.2.0
Define los ajustes preestablecidos disponibles para controlar la calidad de la imagen, ampliable con cualquier cadena.
RemotePattern
Sección titulada «RemotePattern»Tipo: { hostname?: string; pathname?: string; protocol?: string; port?: string; }
astro@5.14.2
Describe un host remoto mediante cuatro propiedades opcionales: hostname, pathname, protocol y port.
ImageService
Sección titulada «ImageService»Tipo: ExternalImageService | LocalImageService
Define los hooks que debe proporcionar un servicio de imágenes local o externo.
ExternalImageService
Sección titulada «ExternalImageService»Tipo: object
Define los hooks que debe proporcionar un servicio de transformación de imágenes externo. Requiere un hook getUrl() (EN) y admite tres hooks adicionales (EN).
LocalImageService
Sección titulada «LocalImageService»Tipo: object
Define los hooks que debe proporcionar un servicio de transformación de imágenes local. Requiere los hooks getUrl() (EN), parseUrl() (EN) y transform() (EN), y admite hooks adicionales (EN).
ImageServiceConfig
Sección titulada «ImageServiceConfig»Tipo: { entrypoint: 'astro/assets/services/sharp' | string; config?: T; }
astro@2.3.3
Describe el objeto de configuración para un servicio de imágenes. Contiene las siguientes propiedades:
ImageServiceConfig.entrypoint
Sección titulada «ImageServiceConfig.entrypoint»Tipo: 'astro/assets/services/sharp' | string
Un paquete o ruta al módulo del servicio de imágenes. Puede ser el servicio Sharp integrado de Astro o un servicio de terceros.
ImageServiceConfig.config
Sección titulada «ImageServiceConfig.config»Tipo: Record<string, any>
Un objeto de configuración pasado al servicio de imágenes. La forma depende del servicio específico que se esté utilizando.
Reference