Introducción
Si alguna vez ha subido una foto de producto, ha establecido un logotipo de empresa o ha adjuntado una foto de perfil a un registro de empleado en Odoo, ya ha interactuado con un campo de imagen. Es uno de los tipos de campo más visuales en el modelo de datos de Odoo, y aparece en más lugares de los que la mayoría de los usuarios se da cuenta.
Para los usuarios empresariales, simplemente funciona. Haces clic en un botón, subes un archivo y la imagen aparece en el registro. Pero para los consultores y desarrolladores que configuran Odoo, hay bastante sucediendo por debajo. El campo de imagen tiene su propio mecanismo de almacenamiento, comportamiento de redimensionamiento automático y algunas sutilezas que vale la pena entender antes de comenzar a agregar campos de imagen a modelos personalizados.
Esta guía cubre lo que almacena el campo de imagen, cómo se comporta en el marco de Odoo, cómo agregarlo utilizando Odoo Studio o Python, y ejemplos prácticos de flujos de trabajo empresariales reales.
¿Qué es el campo de imagen en Odoo?
El campo de imagen es un tipo de campo dedicado en el ORM de Odoo, introducido como fields.Image en Odoo 13. Antes de esa versión, los desarrolladores utilizaban un campo fields.Binary combinado con el widget image para lograr el mismo resultado. Hoy en día, el tipo de campo de imagen maneja todo el ciclo de vida del almacenamiento de imágenes, incluyendo el redimensionamiento automático, por sí mismo.
Bajo el capó, el campo de imagen almacena datos binarios codificados en base64. En la base de datos PostgreSQL, estos datos se guardan como una columna bytea o, más comúnmente en las versiones modernas de Odoo, como un archivo adjunto vinculado al registro. Este almacenamiento basado en archivos adjuntos mantiene las tablas principales de la base de datos más ligeras y permite a Odoo servir imágenes de manera eficiente a través de su sistema de URL de adjuntos.
Cómo se ve en la interfaz
En una vista de formulario, un campo de imagen se representa como un marcador de posición de imagen clicable. Los usuarios pueden subir un archivo directamente desde su computadora, y en algunos casos también pueden pegar una URL. El campo muestra una vista previa en miniatura directamente en el formulario, lo que facilita su identificación de un vistazo.
En las vistas de lista, los campos de imagen rara vez se muestran porque las miniaturas en las listas pueden ralentizar la carga. Sin embargo, pueden mostrarse en vistas kanban, donde los diseños basados en tarjetas pequeñas se benefician de indicadores visuales como fotos de productos o avatares de contactos.
Tipos de campos de Odoo: Imagen vs Binario
Vale la pena conocer la distinción entre los dos. Un campo Binario almacena cualquier tipo de archivo: PDFs, hojas de cálculo, archivos zip, y así sucesivamente. El campo de Imagen está diseñado específicamente para archivos de imagen. Aplica redimensionamiento automático al guardar, impone validación específica para imágenes y se representa correctamente con el widget de imagen por defecto. Si estás almacenando archivos que no son imágenes, utiliza Binario. Si estás almacenando fotos o logotipos, utiliza Imagen.
Cómo funciona el campo
Cuando un usuario sube una imagen a un campo de imagen, Odoo no simplemente almacena el archivo bruto tal como está. Primero procesa la imagen.
Redimensionamiento automático
La declaración fields.Image acepta parámetros max_width y max_height. Si la imagen subida excede esas dimensiones, Odoo la redimensiona automáticamente mientras preserva la relación de aspecto. Esto sucede de manera transparente al guardar, por lo que los usuarios nunca necesitan pensar en ello.
El tamaño máximo predeterminado para un campo de imagen estándar es de 1920 píxeles en el lado más largo. Por eso, el campo a menudo se llama image_1920 en modelos estándar de Odoo como product.template o res.partner.
Variantes de tamaño de imagen
En los modelos integrados de Odoo, a menudo verás un patrón de campos de imagen relacionados junto al principal: image_1920, image_1024, image_512, image_256 y image_128. Estos son campos separados de fields.Image definidos como campos relacionados que apuntan de vuelta a la imagen principal, cada uno con diferentes límites de tamaño.
Este enfoque permite a Odoo servir el tamaño de imagen correcto dependiendo del contexto. Una página de listado de productos obtiene la miniatura pequeña image_128 para mantener las cargas de página rápidas. Una página de detalles del producto obtiene la image_1920 completa para una visualización más nítida. Para modelos personalizados, es posible que necesites o no este patrón de múltiples tamaños dependiendo de cómo y dónde se mostrará la imagen.
Almacenamiento como adjuntos
Por defecto, los campos de imagen almacenan sus datos como adjuntos de archivo de Odoo. Esto significa que el contenido binario vive en el modelo ir.attachment en lugar de directamente en la tabla de registros. El registro mantiene una referencia al adjunto.
Prácticamente, esto mantiene las tablas principales de la base de datos delgadas. También significa que las imágenes son accesibles a través de URLs predecibles como /web/image/product.template/42/image_1920, que es el patrón utilizado en páginas web, plantillas de correo electrónico y respuestas de API.
Control de acceso
Los campos de imagen respetan las mismas reglas de acceso que el resto del registro. Si un usuario no tiene acceso de lectura a un producto, tampoco puede recuperar su imagen. Esto se maneja automáticamente por la capa de seguridad de Odoo, lo cual es algo que vale la pena saber al construir portales orientados al cliente o páginas web públicas.
Casos de uso empresarial
El campo de imagen aparece en casi todos los módulos de Odoo. Aquí hay algunas de las aplicaciones del mundo real más comunes.
1. Catálogo de productos (Ventas e Inventario)
Las imágenes de productos son probablemente el uso más visible de los campos de imagen en Odoo. Cada plantilla de producto tiene un campo image_1920, y esas imágenes aparecen en la tienda en línea, en los PDFs de órdenes de venta, en las pantallas de punto de venta y en las operaciones de picking en dispositivos móviles.
Las empresas con catálogos grandes a menudo utilizan la API para cargar imágenes de productos en masa en lugar de agregarlas una por una a través de la interfaz. El campo de imagen acepta datos binarios codificados en base64, por lo que es sencillo cargar imágenes programáticamente a través de XML-RPC o JSON-RPC.
2. Logotipos de clientes y proveedores (CRM y Compras)
El modelo res.partner tiene un campo de Imagen utilizado para fotos de contacto y logotipos de empresas. Esta imagen aparece en el formulario del socio, en el área de chat y en las tarjetas kanban de CRM. Para los equipos de ventas que trabajan con muchas cuentas, tener logotipos en los registros de contacto facilita la navegación visual a través de la lista de clientes.
3. Fotos de empleados (RRHH)
El modelo hr.employee almacena una foto de empleado en un campo de Imagen. Esta foto aparece en el directorio de empleados, en las nóminas en algunas configuraciones y en el módulo Odoo Discuss junto a los mensajes. Los equipos de RRHH a menudo cargan estas fotos al incorporar un gran lote de nuevos empleados, utilizando nuevamente la importación masiva o la API.
4. Fotos de equipos y activos (Mantenimiento)
El módulo de Mantenimiento permite adjuntar una imagen a los registros de equipos. A los técnicos de campo les resulta útil tener una foto de la máquina directamente en la orden de mantenimiento, para que puedan confirmar rápidamente que están trabajando en la pieza de equipo correcta antes de comenzar una reparación.
5. Formularios de inspección o calidad personalizados
Algunas empresas construyen modelos personalizados en Odoo para controles de calidad, inspecciones de sitios o confirmaciones de entrega. Agregar un campo de Imagen a estos modelos permite al personal de campo adjuntar una foto como evidencia directamente en el registro. Este es un patrón común de personalización en Odoo y funciona bien ya sea que el campo se agregue a través de Odoo Studio o directamente en código Python.
Creando o personalizando el campo
Hay dos formas principales de agregar un campo de Imagen a un modelo de Odoo: a través de Odoo Studio sin escribir código, o mediante desarrollo en Python para tener más control.
Usando Odoo Studio
Odoo Studio es la herramienta de personalización sin código integrada. Para agregar un campo de Imagen usando Studio, abre la aplicación relevante, activa Studio desde el menú superior y navega a la vista de formulario donde deseas que aparezca el campo.
En el panel de campos a la izquierda, arrastra un campo de Imagen al formulario. Studio te pedirá que le des una etiqueta y creará automáticamente el campo subyacente en el modelo. Este es el enfoque recomendado para usuarios de negocios y consultores funcionales que desean crear campos en Odoo sin involucrar a un desarrollador.
Los campos creados a través de Studio se prefijan con x_studio_ por convención, por ejemplo x_studio_site_photo. Se comportan exactamente como los campos de Imagen nativos en términos de almacenamiento y visualización.
Usando Python (desarrollo de Odoo)
Para personalizaciones técnicas, defines campos de imagen directamente en un archivo de modelo de Python. Aquí hay un ejemplo básico de cómo un desarrollador añadiría un campo de imagen a un modelo personalizado:
from odoo import models, fields
class SiteInspection(models.Model):
_name = 'site.inspection'
_description = 'Inspección del Sitio'
name = fields.Char(string='Referencia', required=True)
photo = fields.Image(
string='Foto del Sitio',
max_width=1920,
max_height=1920,
)
photo_128 = fields.Image(
related='photo',
max_width=128,
max_height=128,
store=True,
string='Miniatura',
)Los parámetros max_width y max_height indican a Odoo que limite el tamaño almacenado a 1920 píxeles. El segundo campo, photo_128, es un campo relacionado que almacena una versión más pequeña para su uso en tarjetas kanban o vistas de lista. Este es el patrón estándar de desarrollo de Odoo para manejar múltiples tamaños de imagen en un solo registro.
Añadiendo el campo a una vista
Una vez que el campo existe en el modelo, necesita ser añadido a una vista para ser visible en la interfaz. En un XML de vista de formulario, muestras un campo de imagen usando el atributo widget="image":
<field name="photo" widget="image" class="oe_avatar"/>La clase oe_avatar lo posiciona como un avatar circular en la esquina superior izquierda del formulario, que es el estilo estándar de Odoo. También puedes usarlo sin la clase para colocarlo en línea dentro de un diseño de formulario.
Mejores prácticas
Aquí están las recomendaciones que damos a los clientes al trabajar con campos de imagen en Odoo.
Establecer límites de tamaño realistas
El límite predeterminado de 1920 píxeles es apropiado para la mayoría de los casos de uso. Evita aumentarlo a menos que tengas una razón de peso, como fotografía de productos de muy alta resolución para impresión. Las imágenes más grandes significan archivos adjuntos más grandes, lo que afecta el tamaño de la base de datos y el rendimiento de carga de la página.
Crea una variante de miniatura para listas y kanban
Si estás mostrando la imagen en vistas de lista o tarjetas kanban, define un campo relacionado de tamaño pequeño separado limitado a 128 o 256 píxeles. Obtener una miniatura de 128 píxeles es mucho más rápido que cargar la imagen completa de 1920 píxeles para cada tarjeta en pantalla.
Utiliza la API para cargas masivas de imágenes
Cuando necesites cargar imágenes para cientos o miles de registros, no lo hagas manualmente a través de la interfaz. Utiliza la API XML-RPC o JSON-RPC de Odoo para escribir datos de imagen codificados en base64 directamente en el campo. Esto es mucho más rápido y se puede automatizar en un script. La guía del desarrollador de Odoo cubre bien este patrón.
Comprime las imágenes antes de subirlas
Aunque Odoo redimensiona las imágenes automáticamente, no siempre las comprime de manera agresiva. Un JPEG de 5 MB redimensionado a 1920 píxeles puede seguir siendo de varios cientos de kilobytes. Pre-comprimir las imágenes antes de subirlas mantiene los tamaños de los archivos adjuntos manejables, especialmente al tratar con catálogos de productos grandes.
Evita los campos de imagen en vistas de lista consultadas con frecuencia
Incluir un campo de imagen en una columna de vista de lista obliga a Odoo a obtener datos binarios para cada fila visible. Esto puede hacer que las vistas de lista sean notablemente más lentas. Utiliza una miniatura pequeña si realmente necesitas un visual en una lista, y guarda la imagen de tamaño completo solo para la vista de formulario.
Errores comunes
Estos son los errores que vemos con más frecuencia cuando los equipos comienzan a trabajar con campos de imagen en Odoo.
Confundir campos binarios y de imagen
Un campo binario sin el widget de imagen se mostrará como un botón de descarga, no como una vista previa de imagen. Si deseas una visualización adecuada de la imagen, necesitas un tipo de campo fields.Image o un fields.Binary con widget="image" explícitamente configurado en la vista. Olvidar esto es una fuente común de confusión, especialmente al trabajar en versiones más antiguas de Odoo.
No pensar en las variantes de tamaño de imagen lo suficientemente pronto
Agregar un solo campo de imagen grande es fácil, pero si luego te das cuenta de que necesitas versiones más pequeñas para una vista kanban o un listado en un sitio web, agregar esos campos relacionados requiere una migración de base de datos si estás en un módulo personalizado. Planificar las variantes de tamaño por adelantado ahorra dolores de cabeza más tarde.
Almacenar imágenes directamente en lugar de usar adjuntos
En versiones muy antiguas de Odoo o en instancias mal configuradas, los datos binarios podían almacenarse directamente en la columna de la base de datos en lugar de como adjuntos. Esto inflará significativamente el tamaño de las tablas principales y ralentizará las consultas no relacionadas. Asegúrate de que tu instancia de Odoo esté configurada para usar almacenamiento de archivos o almacenamiento compatible con S3 para los adjuntos.
Usar campos de imagen como almacenamiento de documentos
Algunos usuarios intentan almacenar documentos escaneados o capturas de pantalla en campos de imagen. Si bien es técnicamente posible, no es la herramienta adecuada. Para la gestión de documentos, utiliza el módulo de Documentos de Odoo o un campo Binario con un widget de descarga de archivos. Los campos de imagen están diseñados para fotos y logotipos, no para almacenar documentos de varias páginas.
Olvidar las reglas de acceso en páginas públicas
Si muestras URLs de imágenes en un sitio web público o en un portal y el registro subyacente no es accesible para los usuarios públicos, la imagen devolverá un error 404. Al construir páginas web o portales de clientes, siempre verifica que la URL de la imagen sea accesible para la audiencia esperada.
Conclusión
El campo de imagen es uno de los tipos de campo más simples de usar en la superficie, pero tiene suficiente profundidad para tropezar a equipos que no planifican con anticipación. Comprender cómo Odoo maneja el redimensionamiento, el almacenamiento como adjuntos y el patrón de variantes de múltiples tamaños te ahorrará tiempo al construir o configurar modelos que necesitan datos visuales.
Para los usuarios empresariales, saber que las imágenes se almacenan de forma segura en el registro y son accesibles a través de URLs predecibles ayuda al configurar páginas web o vistas de portales. Para los desarrolladores, la combinación de fields.Image con campos de miniatura relacionados es el patrón estándar de Odoo, y vale la pena familiarizarse con él desde el principio.
Ya sea que estés agregando una foto de producto a tu catálogo, adjuntando una foto de inspección del sitio a un modelo personalizado, o construyendo un portal de clientes que muestre logotipos de contacto, el campo de imagen te ofrece una forma limpia e integrada de manejar datos visuales dentro del modelo de datos de Odoo.
¿Necesita ayuda con su implementación de Odoo?
En Dasolo, ayudamos a las empresas a implementar, personalizar y optimizar Odoo en todos los módulos y versiones. Ya sea que necesites configurar campos en modelos estándar, construir módulos personalizados desde cero, o migrar datos de un sistema legado, trabajamos mano a mano con tu equipo para hacer que Odoo funcione de la manera en que realmente opera tu negocio.
Si tienes preguntas sobre tu configuración de Odoo o quieres explorar lo que es posible con la plataforma, contáctanos. Estamos felices de ayudar.