Image Widget Crop
Proporciona una interfaz para usar la Crop API con campos de imagen, permitiendo a los usuarios definir múltiples zonas de recorte por imagen para diferentes tipos de recorte.
image_widget_crop
Install
composer require 'drupal/image_widget_crop:^3.0'
composer require 'drupal/image_widget_crop:8.x-2.4'
Overview
Image Widget Crop proporciona una experiencia de usuario para aplicar recortes a campos de imagen utilizando la Crop API. El módulo se integra con el sistema de imágenes de Drupal para permitir a los editores definir zonas de recorte óptimas para cada imagen según diferentes tipos de recorte (proporciones de aspecto).
El módulo es particularmente útil para sitios editoriales o sistemas de gestión de medios donde la misma imagen necesita mostrarse en diferentes contextos con diferentes proporciones de aspecto. Por ejemplo, un artículo podría necesitar una imagen hero panorámica, una miniatura cuadrada y una imagen vertical para la barra lateral, todo desde el mismo archivo fuente.
Las capacidades principales incluyen: soporte para múltiples tipos de recorte por imagen, interfaz de recorte visual en tiempo real usando la biblioteca Cropper.js, aplicación de proporciones de aspecto, validación de límites estrictos y flexibles, validación de tipos de recorte requeridos, e integración con File Entity, Entity Browser, IMCE y otros módulos de gestión de medios.
Features
- Múltiples tipos de recorte por imagen con soporte para diferentes proporciones de aspecto
- Interfaz de recorte visual usando la biblioteca Cropper.js con vista previa en tiempo real
- Aplicación automática de proporciones de aspecto basada en la configuración del tipo de recorte
- Validación de límites estrictos y flexibles para dimensiones mínimas de recorte
- Validación de tipos de recorte requeridos para asegurar que los editores definan los recortes necesarios
- Integración con File Entity para recortar imágenes directamente desde formularios de edición de archivos
- Soporte para los módulos Entity Browser, IMCE y FileField Sources
- Carga flexible de biblioteca: archivos locales, Libraries API o respaldo CDN
- Sistema de notificaciones para operaciones de aplicar y actualizar recortes
- Sistema de advertencias cuando las imágenes se usan en múltiples lugares
- Elemento de Form API (image_crop) para integración con formularios personalizados
- Interfaz de pestañas verticales para gestionar múltiples tipos de recorte
Use Cases
Sitio editorial con múltiples ubicaciones de imagen
Para un sitio de noticias donde los artículos aparecen en la página de inicio (banner panorámico), páginas de categoría (cuadrado mediano), barra lateral (vertical pequeño) y página del artículo (ancho completo). Crear tipos de recorte para cada proporción (16:9, 1:1, 3:4, etc.), configurar estilos de imagen con el efecto Manual crop, y los editores pueden definir zonas de recorte óptimas para cada ubicación al subir imágenes.
Imágenes de productos de comercio electrónico
Las imágenes de productos necesitan recorte consistente para grillas de catálogo, páginas de detalle de producto y vistas de zoom. Configurar tipos de recorte para cada contexto de visualización y requerir el tipo de recorte de catálogo para asegurar que todos los productos tengan miniaturas correctamente recortadas.
Biblioteca de medios con activos reutilizables
Usando el módulo Media con entidades de archivo, los editores pueden recortar imágenes una vez en la biblioteca de medios y reutilizarlas en todo el contenido. La opción warn_multiple_usages alerta a los editores cuando cambian recortes que afectan múltiples elementos de contenido.
Formulario personalizado con recorte
Agregar recorte a formularios personalizados usando el elemento image_crop de Form API. Cargar la entidad de archivo, configurar tipos de recorte y estilo de vista previa, y procesar recortes vía el servicio image_widget_crop.manager al enviar el formulario.
Imágenes responsive con dirección artística
Combinar con el módulo Responsive Image para imágenes responsive con dirección artística. Diferentes tipos de recorte permiten definir puntos focales óptimos para varios tamaños de viewport, asegurando que el contenido importante sea visible en todos los breakpoints.
Tips
- Usar estilos de imagen con Scale (no Scale and Crop) para la vista previa del recorte para mantener la proporción de aspecto y ver la imagen completa
- Establecer límites estrictos apropiados en los tipos de recorte para asegurar la calidad mínima de imagen para cada caso de uso
- Habilitar 'Advertir al usuario cuando un archivo tiene múltiples usos' para bibliotecas de medios donde los archivos pueden reutilizarse
- Usar el submódulo image_widget_crop_examples para probar la funcionalidad antes de configurar campos de producción
- El respaldo CDN funciona sin configuración adicional - no se requiere instalación de biblioteca para uso básico
- Configurar diferentes tipos de recorte por campo según dónde se mostrarán las imágenes de ese campo
Technical Details
Admin Pages 1
/admin/config/media/crop-widget
Configurar ajustes globales para el módulo Image Widget Crop incluyendo la fuente de la biblioteca Cropper, el estilo de vista previa de recorte predeterminado, los tipos de recorte disponibles y las preferencias de notificación.
Hooks 7
hook_entity_insert
Procesa automáticamente los datos de recorte cuando se crean entidades con campos de imagen
hook_entity_update
Procesa automáticamente los datos de recorte cuando se actualizan entidades con campos de imagen
hook_form_file_form_alter
Agrega el elemento image_crop a los formularios de edición de entidades de archivo para archivos de imagen
hook_library_info_alter
Configura dinámicamente la fuente de la biblioteca Cropper basándose en la configuración del módulo (URL personalizada, Libraries API o CDN)
hook_libraries_info
Define la biblioteca Cropper para la integración con el módulo Libraries API
hook_filefield_sources_widgets
Registra el widget image_widget_crop para compatibilidad con el módulo FileField Sources
hook_imce_supported_widgets_alter
Agrega image_widget_crop a la lista de widgets soportados por el módulo IMCE
Troubleshooting 5
Los tipos de recorte solo aparecen si al menos un Image Style los usa con el efecto 'Manual crop'. Ir a /admin/config/media/image-styles, editar o crear un estilo, y agregar el efecto 'Manual crop' seleccionando su tipo de recorte.
Verificar la configuración en /admin/config/media/crop-widget. Verificar que las URLs personalizadas sean accesibles, o asegurar que el módulo Libraries esté habilitado con cropper en /libraries/cropper/dist/. El módulo usa el respaldo CDN si no se encuentra una biblioteca local.
Asegurar que el widget del campo de imagen esté configurado como 'ImageWidget crop' en la configuración de visualización del formulario. Verificar que los tipos de recorte estén seleccionados en la configuración del widget. Verificar que la entidad tenga hook_entity_insert/update siendo ejecutado.
El área de recorte es menor que las dimensiones mínimas del límite estricto del tipo de recorte. Recortar un área más grande o reducir los valores del límite estricto en la configuración del tipo de recorte en /admin/config/media/crop.
Habilitar 'Advertir al usuario cuando un archivo tiene múltiples usos' en la configuración del widget. Cuando se usan entidades de medios, cada elemento de medios debería referenciar archivos únicos para evitar recortes compartidos.
Security Notes 3
- El módulo depende de los permisos existentes de Drupal - 'administer site configuration' para la página de configuración
- Los datos de recorte se almacenan por archivo, por lo que los usuarios con acceso a archivos pueden afectar recortes para contenido que no poseen si los archivos son compartidos
- Considerar la propiedad de archivos y patrones de acceso cuando se usan bibliotecas de medios compartidas