Crop API
Proporciona almacenamiento y API para recortes de imágenes. Este módulo define la estructura de entidad subyacente y la API que los módulos de interfaz de usuario pueden utilizar para proporcionar funcionalidad de recorte de imágenes.
crop
Install
composer require 'drupal/crop:8.x-2.5'
composer require 'drupal/crop:8.x-2.2'
Overview
El módulo Crop API proporciona una API fundamental para el recorte de imágenes en Drupal. Establece un tipo de entidad de contenido llamado "Crop" que almacena información de recorte (posición, tamaño, coordenadas de anclaje) para imágenes, junto con un tipo de entidad de configuración llamado "Crop Type" que define diferentes tipos de recortes con restricciones opcionales de relación de aspecto y límites de tamaño.
Este módulo está diseñado como una capa API y no proporciona una interfaz de recorte orientada al usuario por sí solo. En su lugar, proporciona el almacenamiento de datos, servicios y hooks que módulos de interfaz de usuario como Image Widget Crop o Focal Point pueden utilizar para ofrecer soluciones completas de recorte.
El módulo incluye un efecto de imagen "Manual crop" que se puede agregar a los estilos de imagen para aplicar datos de recorte almacenados al generar derivados de imagen. También proporciona un sistema de plugins extensible para proveedores de entidades, permitiendo la integración con diferentes tipos de entidades (File, Media) que contienen imágenes.
Las características arquitectónicas clave incluyen el vaciado automático de derivados de imagen cuando los datos de recorte cambian, invalidación de caché basada en URL mediante parámetros hash, soporte para proveedores de recorte automático a través de un sistema de eventos e integración con el exportador de contenido predeterminado de Drupal para escenarios de preparación de contenido.
Features
- Define un tipo de entidad de contenido 'Crop' para almacenar datos de recorte de imagen con posición (coordenadas centrales x, y), tamaño (ancho, alto), anclaje (esquina superior izquierda) y referencia a la entidad de origen
- Define una entidad de configuración 'CropType' para crear diferentes tipos de recorte con relación de aspecto opcional (por ejemplo, 16:9), límites suaves (advertencia si el recorte es más pequeño) y límites duros (tamaño mínimo de recorte)
- Proporciona el plugin de efecto de imagen 'Manual crop' para usar en estilos de imagen que aplica datos de recorte almacenados a las imágenes
- Sistema de proveedores de entidades basado en plugins que soporta entidades File y Media de forma nativa, extensible para tipos de entidades personalizadas
- Sistema de eventos para proveedores de recorte automático que permite a otros módulos proporcionar recorte de respaldo cuando no existen recortes manuales
- Vaciado automático de derivados de estilos de imagen afectados cuando se guardan entidades de recorte (configurable mediante ajustes)
- Adición de parámetro hash en URL para invalidación de caché cuando los recortes cambian, permitiendo la invalidación de caché de CDN/proxy
- Integración con la configuración de tipos de Media para especificar qué campo de imagen debe usarse para el recorte
- Integración con el exportador de contenido predeterminado del núcleo de Drupal (Drupal 11+) para importación/exportación adecuada de entidades de recorte
- Soporte de revisiones para entidades de recorte con seguimiento completo del historial de revisiones
- Soporte de traducción para entidades de recorte permitiendo diferentes recortes por idioma
- Optimización de índices de base de datos en campos uri y type para búsquedas eficientes de recortes
Use Cases
Recorte de imágenes responsivas
Cree diferentes tipos de recorte para varias relaciones de aspecto necesarias en su sitio (por ejemplo, 16:9 para imágenes hero, 1:1 para miniaturas, 4:3 para imágenes de artículos). Configure estilos de imagen con el efecto Manual crop para cada tipo de recorte. Use un módulo de interfaz de usuario para permitir que los editores de contenido establezcan recortes para cada imagen. La misma imagen de origen puede tener diferentes recortes para diferentes contextos de visualización.
Biblioteca de medios con recorte
Configure sus tipos de Media para especificar qué campo de imagen debe usarse para el recorte. Cuando los editores agregan o editan elementos de Media, pueden definir recortes que se aplicarán consistentemente dondequiera que se muestre ese elemento de Media. Esto asegura la consistencia de marca en todo el sitio.
Arquitectura desacoplada/headless
Para sitios que usan almacenamiento en la nube (como S3) con entrega por CDN, deshabilite el vaciado automático de derivados estableciendo flush_derivative_images en false. Genere derivados de imagen a través de un proceso de construcción separado y súbalos a su almacenamiento en la nube. Crop API aún añadirá parámetros hash a las URLs para invalidación de caché.
Recorte de respaldo automático
Suscríbase al evento crop.automatic_crop para proporcionar recorte automático cuando los editores no han establecido un recorte manual. Por ejemplo, use detección de rostros para centrar automáticamente los recortes en caras, o use datos de punto focal para crear recortes inteligentes que preserven las partes importantes de las imágenes.
Preparación de contenido con recortes
Al usar el exportador de contenido predeterminado de Drupal 11, las entidades de recorte se manejan automáticamente durante la exportación/importación. Los recortes se exportan con referencias UUID a sus entidades de origen y se vuelven a vincular correctamente durante la importación, haciendo que los flujos de trabajo de preparación de contenido sean fluidos.
Recorte de imágenes multi-idioma
Dado que las entidades de recorte son traducibles, se pueden definir diferentes recortes para diferentes idiomas. Esto es útil cuando las imágenes necesitan diferentes recortes para diferentes versiones de idioma (por ejemplo, imágenes que contienen texto que varía según el idioma).
Tips
- Siempre instale un módulo de interfaz de usuario (como Image Widget Crop o Focal Point) junto con Crop API - el módulo API solo no proporciona interfaz de recorte
- Use límites suaves para guiar a los editores hacia recortes de calidad mínima mientras permite recortes más pequeños cuando sea necesario
- Use límites duros cuando tenga requisitos estrictos de tamaño mínimo que deban cumplirse
- La configuración de relación de aspecto es opcional - déjela vacía para recorte de forma libre donde cualquier proporción sea aceptable
- Al depurar problemas de recorte, verifique la tabla de base de datos crop_field_data para verificar que las entidades de recorte se estén creando con valores correctos
- Use la operación 'Vaciar' con cuidado - elimina permanentemente todos los datos de recorte para un tipo de recorte
- Para mejor rendimiento con muchos recortes, el módulo crea un índice de base de datos en las columnas (uri, type)
Technical Details
Admin Pages 5
/admin/config/media/crop
Lista todos los tipos de recorte configurados en el sistema. Muestra el nombre, descripción, relación de aspecto y qué estilos de imagen usan cada tipo de recorte. Proporciona operaciones para editar, eliminar o vaciar recortes para cada tipo.
/admin/config/media/crop/add
Formulario para crear un nuevo tipo de recorte con nombre configurable, nombre de máquina, descripción, relación de aspecto y límites de tamaño.
/admin/config/media/crop/manage/{crop_type}
Formulario para modificar la configuración de un tipo de recorte existente. El nombre de máquina no se puede cambiar después de la creación.
/admin/config/media/crop/manage/{crop_type}/delete
Formulario de confirmación para eliminar un tipo de recorte. El tipo de recorte solo se puede eliminar si no hay entidades de recorte que lo usen.
/admin/config/media/crop/manage/{crop_type}/flush
Formulario de confirmación para eliminar todas las entidades de recorte de un tipo de recorte específico. Esto es útil cuando desea eliminar todos los datos de recorte para un tipo particular sin eliminar la definición del tipo en sí.
Permissions 2
Hooks 1
hook_crop_entity_provider_info_alter
Permite a los módulos alterar la información proporcionada por los plugins CropEntityProvider. Se puede usar para modificar etiquetas, descripciones u otras propiedades de los plugins de proveedores de entidades.
Troubleshooting 5
Asegúrese de que flush_derivative_images esté establecido en true en crop.settings. Limpie todas las cachés y verifique que la entidad de recorte se esté guardando correctamente. Para configuraciones de almacenamiento en la nube, puede que necesite regenerar los derivados manualmente.
Verifique que: 1) El estilo de imagen tenga el efecto 'Manual crop' con el tipo de recorte correcto seleccionado, 2) Exista una entidad de recorte para la URI de la imagen y el tipo de recorte, 3) La entidad de recorte tenga valores válidos de posición y tamaño.
Primero agregue un campo de archivo o imagen a su tipo de Media. El fieldset de configuración de recorte solo aparece cuando hay campos de archivo/imagen válidos en el bundle.
Primero debe eliminar o vaciar todas las entidades de recorte de ese tipo. Use la operación 'Vaciar' para eliminar todos los recortes, luego elimine el tipo.
Asegúrese de que la relación de aspecto esté en formato W:H solo con enteros positivos (por ejemplo, 16:9, 4:3, 1:1). No incluya decimales, porcentajes u otros formatos.
Security Notes 3
- El módulo usa verificaciones de acceso al consultar entidades de recorte
- Los plugins de proveedores de entidades deben validar tipos de entidades y valores de campos antes de devolver URIs
- Los datos de recorte se almacenan por URI y potencialmente podrían exponer la estructura del sistema de archivos a través del campo uri