Añade una imagen en vivo de la biblioteca en Gutenberg

Usa el bloque Image de POM para mostrar una imagen de la biblioteca de medios con los diseños de imagen, superposiciones, imágenes al pasar el cursor y acciones de clic del tema. Esta guía es para editores de contenido que usan Gutenberg con POM activo.

Añadir una imagen

1. Abre Pages → All Pages o Posts → All Postsy, a continuación, edita tu contenido en Gutenberg.
2. Abre el insertador de bloques y elige el bloque Image de POM. Su descripción menciona imágenes en vivo de la biblioteca de medios y superposiciones del tema.
3. Elige o sube una imagen con el selector de medios.
4. En Image source, elige Image size, la alineación y dimensiones opcionales. También puedes usar la barra de herramientas flotante de alineación.
5. Guarda la página y usa la vista previa del frontend para revisar el resultado.

El bloque puede colocarse directamente en el documento o dentro de una sección o columna de POM. No requiere un contenedor de fila adicional.

Pegar una URL de imagen local

También puedes pegar una URL de imagen en Attachment ID or image URL, o usar la opción de URL del marcador de posición de imagen inicial. Cuando la URL coincide con una imagen de la biblioteca de medios del sitio actual, POM la sustituye por el ID del adjunto. Entonces quedan disponibles los controles de biblioteca. La misma comprobación se ejecuta al guardar, de modo que guardar inmediatamente después de pegar es compatible.

Se conserva una selección con nombre de Image size . Cuando el tamaño sigue siendo Full size (original ratio), una URL de miniatura reconocida selecciona ese tamaño de miniatura. Una URL a tamaño completo o de la subida original sigue el comportamiento existente de tamaño completo de la biblioteca, incluida la versión escalada que WordPress genera para una subida grande. Los tamaños presentes en los metadatos del adjunto pero ausentes del menú de tamaños actual aparecen como Saved image size.

Los ID numéricos existentes permanecen sin cambios, incluidos los ID de imágenes traducidas que comparten un archivo. El bloque almacena la referencia y el tamaño, no copias de los metadatos de la imagen. Las URL locales reconocidas se resuelven al editar o guardar, en lugar de consultarse desde su URL en cada renderizado del frontend sin caché.

Las URL externas siguen siendo URL y no se importan ni se descargan. Si una URL local no se puede hacer coincidir, también se mantiene sin cambios y el editor muestra una advertencia: usa Choose image o Replace image para seleccionar su entrada de la biblioteca. Los medios de otro sitio multisitio no se vinculan automáticamente a la biblioteca del sitio actual. Después de un error temporal de búsqueda, usa Refresh library preview para reintentar.

Los bloques de imagen basados en URL guardados previamente se comprueban al abrirlos o guardarlos. Esto no reescribe en bloque otras páginas ni shortcodes Legacy.

Mantener los metadatos actualizados

Las imágenes de la biblioteca usan su texto alternativo, título, leyenda, descripción, enlace de destino, fuentes responsivas y dimensiones actuales al renderizarse la página. El bloque no guarda copias independientes de estos valores.

Usa Edit image metadata in the library para actualizar el adjunto. Vuelve a Gutenberg y elige Refresh library preview en la barra de herramientas flotante. No necesitas guardar la página de nuevo solo para actualizar sus metadatos de imagen en el frontend.

Una página HTML en caché puede seguir mostrando metadatos anteriores hasta que la caché de página correspondiente se purgue o caduque. Cambiar los metadatos no purga automáticamente todas las cachés externas.

Escribe un texto alternativo que describa el propósito de la imagen. Un texto alternativo vacío marca una imagen ordinaria como decorativa. Como el texto alternativo de la biblioteca se comparte, cambiarlo afecta a cada imagen de POM que usa ese adjunto.

Un valor externo de Attachment ID or image URL usa el diseño de imagen legacy básico. Indica su Alternative text en el bloque. Las URL externas no proporcionan metadatos de biblioteca, fuentes responsivas ni los controles de superposición e interacción exclusivos de la biblioteca.

Diseño y superposición

• Fit image to parent width usa el ayudante de ajuste existente del tema. Deja vacíos Custom width (px) y Custom height (px) para el tamaño de imagen seleccionado. Indicar solo uno conserva la proporción de la imagen.
• Overlay → Display overlay ofrece None, On hover, Hide on hover y Always.
• Elige un fondo sólido o con degradado inferior, un color numérico de la paleta del tema y opacidad en pasos del 10%. El color del texto usa las clases de paleta existentes del tema.
• Establece la alineación de la superposición, un marco con sangría, el zoom al pasar el cursor y una entrada opcional según la dirección del puntero.
• Selecciona título, leyenda, descripción, icono de lightbox, título enlazado, icono de enlace, botón y un icono de biblioteca opcional. Los títulos, leyendas y descripciones proceden del adjunto.
• Preview overlay y Preview hover image cambian solo la vista previa del editor, no el comportamiento guardado.

El editor usa los componentes de imagen del tema sin cargar la hoja de estilos completa del frontend. Las acciones de clic y la reproducción de GIF se revisan en la vista previa del frontend; los enlaces de la vista previa del editor están inactivos a propósito para no interrumpir la edición.

Usa Replace image en la barra de herramientas flotante del bloque para una selección rápida de medios. El editor resuelve las fuentes de imagen diferidas sin ejecutar los scripts de interacción del frontend. Usa Refresh library preview después de editar los metadatos del adjunto.

Acciones de clic

Click actions → Whole image action puede no hacer nada, ampliar la imagen en un lightbox, abrir un modal existente, usar el enlace de destino del adjunto o controlar un slider existente.

El título de la superposición, el icono de enlace y el botón tienen su propio ajuste de acción, que se muestra solo cuando una superposición habilitada contiene un elemento accionable. Link the title está disponible cuando el título está habilitado. Deshabilitar la superposición conserva sus opciones, pero no carga un modal solo por su acción anterior. El icono de lightbox siempre amplía la imagen. Los destinos de enlace y las preferencias de nueva pestaña proceden de los metadatos de la biblioteca de medios.

Para un modal, indica su Modal box IDexistente, sin #. Para un slider, elige su ID y la acción de diapositiva siguiente, anterior o personalizada. La imagen no crea estos destinos. El carrusel de destino posee sus propios recursos de slider.

Puedes crear el diálogo con un Modal block y copiar su Modal ID en la acción de la imagen.

Las dimensiones del lightbox normalmente proceden de la imagen original; usa las anulaciones de ancho y alto solo cuando sea necesario. Show description in lightbox incluye la descripción del adjunto.

Hover, GIF y SVG

Hover image te permite elegir una segunda imagen de la biblioteca. Su texto alternativo también se lee de la biblioteca.

Para los GIF, GIF playback → Playback ofrece salida sin modificar, reproducción automática, al pasar el cursor, al hacer clic y al entrar en el área de visualización. Elige una Static GIF thumbnail para los modos que necesitan detener la animación. Un GIF sin fotograma estático no puede volver visualmente a una imagen no animada.

Render SVG inline se aplica solo a adjuntos SVG locales. POM sanea el SVG antes de incrustarlo. Los demás tipos de imagen siguen siendo elementos de imagen ordinarios.

Rendimiento y visibilidad

Performance expone el comportamiento de carga y la prioridad de obtención. La prioridad alta fuerza la carga ansiosa; resérvala para una imagen importante sobre el pliegue. La carga diferida sigue el ajuste de carga diferida del tema.

Visibility controla escritorio, tableta en horizontal, tableta en vertical y móvil de forma independiente, usando los límites de 992/768/576px del tema. Los bloques ocultos siguen siendo seleccionables en el editor.

CSS classes → Additional CSS classes acepta ayudantes existentes en el contenedor de la imagen, incluidos los de imágenes externas. Advanced → HTML anchor establece un identificador explícito. Ninguno crea CSS de frontend arbitrario; los fondos de superposición usan el CSS generado de la página.

Verificar y solucionar problemas

1. Guarda, recarga el editor y confirma que la imagen y los ajustes elegidos se mantienen.
2. Revisa la alineación y el ancho en los cuatro tamaños de dispositivo.
3. Abre la vista previa del frontend y prueba el comportamiento del lightbox, modal, slider o GIF según corresponda.
4. Si los metadatos de la biblioteca parecen antiguos, actualiza la vista previa del editor y limpia la caché del frontend correspondiente.
5. Si la imagen no está disponible, selecciona un adjunto de imagen público existente. Si una interacción no hace nada, comprueba su ID de destino y que el destino exista en la página.

Relacionado: botones de Gutenberg, visibilidad por dispositivoy el shortcode Image legacy.