Ir al contenido

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.

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

El componente <Image /> optimiza y transforma imágenes.

src/components/MyComponent.astro
---
// 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 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>.

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 de src:

    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';
    ---
    <Image
    src="/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';
    ---
    <Image
    src="https://example.com/remote-image.jpg"
    alt="texto descriptivo"
    width="300"
    height="150"
    />

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.

Tipo: (number | `${number}x`)[] | undefined

Agregado en: 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.

src/components/MyComponent.astro
---
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

Agregado en: 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.

src/components/MyComponent.astro
---
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

Agregado en: 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.

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 0 al 100 (interpretado de manera diferente entre formatos).

Tipo: boolean
Por defecto: false

Agregado en: 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:

src/components/MyComponent.astro
---
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.

Tipo: boolean
Por defecto: false

Agregado en: 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).

src/components/MyComponent.astro
---
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'

Agregado en: 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).

MyComponent.astro
---
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á del width y height especificados, 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á un srcset para 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áticamente srcset ni sizes, 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:

src/components/MyComponent.astro
---
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:

Responsive Image Styles
: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'

Agregado en: 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.

Tipo: string
Por defecto: image.objectPosition | 'center'

Agregado en: 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.

Tipo: string | undefined

Agregado en: 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):

src/components/MyComponent.astro
---
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.

Agregado en: astro@3.3.0

El componente <Picture /> genera una imagen optimizada con múltiples formatos y/o tamaños.

src/pages/index.astro
---
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:

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'].

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.

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.

src/components/MyComponent.astro
---
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>

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.

src/components/Head.astro
---
import { Font } from "astro:assets";
---
<Font cssVariable="--font-roboto" />

El componente <Font /> acepta las siguientes propiedades:

Tipo: CssVariable
Tipo de ejemplo: "--font-roboto" | "--font-comic-sans" | ...

La cssVariable (EN) registrada en tu configuración de Astro:

src/components/Head.astro
---
import { Font } from "astro:assets";
---
<Font cssVariable="--font-roboto" />

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:

src/components/Head.astro
---
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:

src/components/Head.astro
---
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.

Tipo: (options: UnresolvedImageTransform) => Promise<GetImageResult>

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 />:

src/components/Background.astro
---
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>

Tipo: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Agregado en: 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");

Tipo: () => Promise<ImageService>

Agregado en: astro@2.1.3

Recupera el servicio de imágenes (EN) resuelto.

Tipo: AstroConfig["image"] (EN)

Agregado 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.

Tipo: Record<CssVariable, Array<FontData>>

Agregado en: 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"]

Tipo: (url: string, requestUrl?: URL) => Promise<string>

Agregado en: 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);
// ...
};

Los siguientes tipos se importan desde el módulo virtual de assets:

import type {
LocalImageProps,
RemoteImageProps,
FontData
} from "astro/assets";

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.

Aprende más sobre imágenes importadas en src/ con un ejemplo de uso.

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.

Tipo: { src: Array<{ url: string; format?: string; tech?: string }>; weight?: string; style?: string; subset?: string; }

Agregado en: astro@6.0.0

Describe los datos de la fuente asociados con una familia de fuentes determinada.

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.

Tipo: string

Especifica el peso de la fuente (por ejemplo, 400, 600).

Tipo: string

Especifica el estilo de la fuente (por ejemplo, normal, italic).

Tipo: string

Agregado en: astro@7.0.0

Especifica el subconjunto de la fuente (por ejemplo, latin, cyrillic).

Las siguientes funciones auxiliares se importan desde el módulo de assets regular:

import {
baseService,
getConfiguredImageService,
getImage,
isLocalService,
} from "astro/assets";

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:

src/image-service.ts
import { baseService } from "astro/assets";
const newImageService = {
getURL: baseService.getURL,
parseURL: baseService.parseURL,
getHTMLAttributes: baseService.getHTMLAttributes,
async transform(inputBuffer, transformOptions) {
/* ... */
},
};

Consulta getConfiguredImageService() desde astro:assets.

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).

Tipo: (service: ImageService | undefined) => boolean

Comprueba el tipo de un servicio de imágenes y devuelve true cuando se trata de un servicio local.

Los siguientes tipos se importan desde el módulo de assets regular:

import type {
LocalImageProps,
RemoteImageProps,
} from "astro/assets";

Consulta LocalImageProps desde astro:assets.

Consulta RemoteImageProps desde astro:assets.

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

Tipo: (src: string, { domains, remotePatterns }: { domains: string[], remotePatterns: RemotePattern[] }) => boolean

Agregado en: 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`

Tipo: (url: URL, hostname?: string, allowWildcard = false) => boolean

Agregado en: 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`

Tipo: (url: URL, pathname?: string, allowWildcard = false) => boolean

Agregado en: 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`

Tipo: (url: URL, remotePattern: RemotePattern) => boolean

Agregado en: 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`

Tipo: (url: URL, port?: string) => boolean
Por defecto: true

Agregado en: 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`

Tipo: (url: URL, protocol?: string) => boolean
Por defecto: true

Agregado en: 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`

Tipo: (src: ImageMetadata | string) => boolean

Agregado en: 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`

Tipo: (src: ImageMetadata | string) => boolean

Agregado en: 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`

Tipo: (src: UnresolvedImageTransform[‘src’]) => Promise<string | ImageMetadata>

Agregado en: 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' }`

Tipo: (data: Uint8Array, src?: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Agregado en: 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
// }

Tipo: (id: string | undefined, fileEmitter?: Rollup.EmitFile) => Promise<(ImageMetadata & { contents?: Buffer }) | undefined>

Agregado en: 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([...])
// }

Tipo: (pluginContext: Rollup.PluginContext, options: Rollup.EmitFile) => string

Agregado en: 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()`
}
}
}

Tipo: (params: URLSearchParams) => Pick<ImageMetadata, ‘width’ | ‘height’ | ‘format’> | undefined

Agregado en: 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'
// }

Tipo: (url: string) => Promise<Omit<ImageMetadata, ‘src’ | ‘fsPath’>>

Agregado en: 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'
// }

Tipo: (filePath: string, transform: ImageTransform, hash: string) => string

Agregado en: 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 URI data:.
  • hash: Una cadena de hash única generada para distinguir el archivo transformado.
  • outputExtension: La extensión del archivo de salida deseada derivada de transform.format o 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'

Tipo: (transform: ImageTransform, imageService: string, propertiesToHash: string[]) => string

Agregado en: 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'
import type {
GetImageResult,
ImageTransform,
UnresolvedImageTransform,
ImageMetadata,
ImageInputFormat,
ImageOutputFormat,
ImageQuality,
ImageQualityPreset,
RemotePattern,
ImageService,
ExternalImageService,
LocalImageService,
ImageServiceConfig,
} from "astro";

Tipo: object

Agregado en: astro@2.2.0

Describe el resultado de la transformación tras la llamada a getImage().

Tipo: Record<string, any>

Define los atributos HTML adicionales necesarios para renderizar la imagen (por ejemplo, width, height, style).

Tipo: ImageTransform

Describe los ajustes de transformación tras la validación.

Tipo: ImageTransform

Describe los ajustes de transformación originales.

Tipo: string

La ruta a la imagen generada.

Tipo: { values: { transform: ImageTransform; descriptor?: string; attributes?: Record<string, any>; url: string; }[]; attribute: string; }

Agregado en: astro@3.3.0

Un objeto que describe cómo renderizar el atributo srcset.

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.

Tipo: string

Un valor listo para usar en el atributo srcset.

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.

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.

Tipo: number | undefined

El ancho de la imagen.

Tipo: number | undefined

La altura de la imagen.

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.

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.

Tipo: boolean

Determina si el ancho y la altura de la imagen deben inferirse.

Consulta también el atributo inferSize disponible en <Image />.

Tipo: { src: string; width: number; height: number; format: ImageInputFormat; orientation?: number; }

Agregado en: astro@2.1.3

Describe los datos recopilados durante la importación de imágenes. Contiene las siguientes propiedades:

Tipo: string

La ruta absoluta de la imagen en el sistema de archivos.

Tipo: number

El ancho de la imagen.

Tipo: number

La altura de la imagen.

Tipo: ImageInputFormat

El formato de la imagen.

Tipo: number

Agregado en: astro@2.8.3

La orientación de la imagen cuando sus metadatos contienen esta información.

Tipo: "jpeg" | "jpg" | "png" | "tiff" | "webp" | "gif" | "svg" | "avif"

Agregado en: astro@2.2.0

Describe una unión de formatos compatibles para imágenes importadas.

Tipo: string | "jpeg" | "jpg" | "png" | "webp" | "svg" | "avif"

Agregado en: astro@2.2.0

Especifica el formato para las imágenes de salida. Puede ser un literal predefinido o cualquier cadena.

Tipo: ImageQualityPreset | number

Agregado en: 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.

Tipo: string | "low" | "mid" | "high" | "max"

Agregado en: astro@2.2.0

Define los ajustes preestablecidos disponibles para controlar la calidad de la imagen, ampliable con cualquier cadena.

Tipo: { hostname?: string; pathname?: string; protocol?: string; port?: string; }

Agregado en: astro@5.14.2

Describe un host remoto mediante cuatro propiedades opcionales: hostname, pathname, protocol y port.

Tipo: ExternalImageService | LocalImageService

Define los hooks que debe proporcionar un servicio de imágenes local o externo.

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).

Aprende cómo construir servicios externos (EN) en la referencia de la API del Servicio de Imágenes con ejemplos de uso.

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).

Aprende cómo construir servicios locales (EN) en la referencia de la API del Servicio de Imágenes con ejemplos de uso.

Tipo: { entrypoint: 'astro/assets/services/sharp' | string; config?: T; }

Agregado en: astro@2.3.3

Describe el objeto de configuración para un servicio de imágenes. Contiene las siguientes propiedades:

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.

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.

Contribuir Comunidad Patrocinador