Introduzione
Se hai caricato la foto di un prodotto, impostato il logo aziendale o aggiunto l'immagine profilo di un dipendente su Odoo, hai già usato il campo Immagine. È il tipo di campo più visibile nel modello dati e compare in molte schermate dell’applicazione, spesso senza che l’utente se ne renda conto.
Per l’utente finale tutto sembra semplice: clic, selezioni un file e l’immagine appare. Per chi configura Odoo invece c’è più complessità: il campo Immagine ha un suo modo di memorizzare i dati, ridimensiona automaticamente i file e presenta alcune sottigliezze da conoscere prima di aggiungerlo a modelli personalizzati.
Questa guida spiega cosa viene memorizzato dal campo Immagine, come si comporta nell’architettura di Odoo, come aggiungerlo tramite Odoo Studio o scrivendo codice Python e mostra esempi pratici tratti da flussi di lavoro reali.
Cos'è il campo Immagine in Odoo
Il campo Immagine è un tipo dedicato nell’ORM di Odoo, introdotto come fields.Image a partire dalla versione 13. Prima si utilizzava fields.Binary con il widget image per ottenere un risultato simile. Oggi fields.Image gestisce in autonomia l’intero ciclo di vita delle immagini, incluso il ridimensionamento automatico.
Dietro le quinte l’immagine viene salvata come dati binari in base64. Nelle installazioni moderne i contenuti vengono spesso mantenuti come allegati (ir.attachment) anziché incastonati nelle tabelle principali, così il database resta più leggero e Odoo può servire le immagini tramite URL dedicati in modo efficiente.
Come si presenta nell’interfaccia
Nel form il campo Immagine appare come un riquadro cliccabile con anteprima: l’utente può caricare un file dal computer e, in certi casi, incollare un’immagine da URL. La miniatura mostrata direttamente sul form rende immediata l’identificazione dell’elemento.
Nelle viste elenco le immagini si usano di rado perché le anteprime possono rallentare il caricamento. Invece nelle viste kanban le immagini sono molto utili: le card compatte traggono vantaggio da foto prodotto o avatar che facilitano la lettura visiva.
Tipi di campo in Odoo: Image vs Binary
È importante non confonderli. Il campo Binary accetta qualsiasi tipo di file (PDF, zip, ecc.). Il campo Image è pensato per immagini: applica convalide specifiche, ridimensiona automaticamente e si integra con il widget immagine. Per documenti usa Binary; per foto e loghi usa Image.
Come funziona il campo
Quando un utente carica un’immagine in un campo Image, Odoo non si limita a conservare il file grezzo: lo elabora prima di salvarlo.
Ridimensionamento automatico
La dichiarazione fields.Image accetta parametri come max_width e max_height. Se il file superasse queste dimensioni, Odoo lo ridimensiona mantenendo le proporzioni, in modo trasparente al salvataggio, senza che l’utente debba intervenire.
Il limite predefinito più comune è 1920 pixel sul lato più lungo: per questo sui modelli standard il campo spesso si chiama image_1920 (es. product.template o res.partner).
Varianti di dimensione dell’immagine
Nei modelli di base Odoo si trova spesso una serie di campi legati all’immagine principale: image_1920, image_1024, image_512, image_256, image_128. Si tratta di campi fields.Image correlati tra loro e con limiti diversi.
Così Odoo può servire la taglia giusta a seconda del contesto: la lista prodotti prende una miniatura (image_128) per essere veloce, la scheda dettaglio prende image_1920 per mostrare più dettaglio. Per modelli personalizzati valuta se ti servono più versioni o se basta il campo principale.
Memorizzazione come allegati
Per impostazione predefinita i campi Image memorizzano i dati come allegati (ir.attachment). Il contenuto binario risiede quindi nel modello allegati anziché nella tabella del record; il record mantiene un riferimento.
Questo mantiene leggere le tabelle principali e permette di accedere alle immagini tramite URL prevedibili (es. /web/image/product.template/42/image_1920), utili per sito web, template email e API.
Controllo degli accessi
Gli stessi permessi che regolano la lettura del record valgono anche per le immagini. Se un utente non può leggere un prodotto, non potrà recuperarne l’immagine: lo gestisce automaticamente il layer di sicurezza di Odoo, elemento cruciale quando si costruiscono portali o pagine pubbliche.
Casi d'uso aziendali
Il campo Immagine è usato in moltissimi moduli Odoo. Di seguito i casi più diffusi in azienda.
1. Catalogo prodotti (Vendite e Magazzino)
Le immagini prodotto sono probabilmente l’uso più visibile di questo campo: ogni product.template ha image_1920 e queste immagini compaiono nel negozio online, nei PDF d’ordine, nei POS e nelle app di magazzino.
Chi gestisce cataloghi ampi spesso carica le immagini tramite API anziché manualmente. Il campo accetta dati binari in base64, quindi è semplice automatizzare upload di massa via XML-RPC o JSON-RPC.
2. Loghi di clienti e fornitori (CRM e Acquisti)
Il modello res.partner contiene un campo Immagine per foto di contatto e loghi aziendali. L’immagine compare nella scheda partner, nella chatter e nelle card kanban, e aiuta i team commerciali a riconoscere visivamente i contatti.
3. Foto dei dipendenti (HR)
Il modello hr.employee memorizza la foto del dipendente: appare nella directory, in alcuni casi sulle buste paga e in Discuss accanto ai messaggi. In azienda si caricano spesso foto in batch durante l’onboarding attraverso import o API.
4. Foto di macchinari e beni (Manutenzione)
In Manutenzione è utile allegare foto alle schede degli impianti: i tecnici in campo possono verificare rapidamente che stanno intervenendo sull’apparecchiatura corretta prima di iniziare la riparazione.
5. Moduli di controllo o ispezione personalizzati
Molte aziende creano modelli personalizzati per verifiche qualità, sopralluoghi o conferme di consegna: aggiungere un campo Immagine permette agli operatori di allegare prove fotografiche direttamente sul record, sia via Studio che con codice.
Creare o personalizzare il campo
Ci sono due strade principali per aggiungere un campo Immagine: usare Odoo Studio senza codice o definire il campo in Python per controlli avanzati.
Utilizzare Odoo Studio
Odoo Studio è lo strumento no-code integrato. Per aggiungere un campo Immagine apri l’app interessata, attiva Studio dalla barra in alto e modifica la vista form dove vuoi inserire il campo.
Dalla palette dei campi trascina un campo Immagine sul form. Studio chiederà l’etichetta e creerà automaticamente il campo nel modello: è la strada consigliata per consulenti funzionali e utenti di business che non vogliono coinvolgere sviluppatori.
I campi creati con Studio usano il prefisso x_studio_ (es. x_studio_site_photo) e funzionano come i campi Image nativi riguardo memorizzazione e visualizzazione.
Sviluppo in Python (personalizzazione tecnica)
Per esigenze tecniche definisci il campo direttamente in un modulo Python. Questa strada offre pieno controllo su parametri, related fields e comportamento.
Esempio minimale di dichiarazione in Python:
from odoo import models, fields
class SiteInspection(models.Model):
_name = 'site.inspection'
_description = 'Site Inspection'
name = fields.Char(string='Reference', required=True)
photo = fields.Image(
string='Site Photo',
max_width=1920,
max_height=1920,
)
photo_128 = fields.Image(
related='photo',
max_width=128,
max_height=128,
store=True,
string='Thumbnail',
)
I parametri max_width e max_height limitano la dimensione massima (qui 1920 px). photo_128 è un campo related che conserva una versione ridotta utile per kanban o liste: è il pattern tipico per gestire più taglie su uno stesso record.
Aggiungere il campo alla vista
Dopo aver creato il campo va inserito nella vista per renderlo visibile. In un form XML si usa l’attributo widget="image":
<field name="photo" widget="image" class="oe_avatar"/>La classe oe_avatar posiziona l’immagine come avatar circolare in alto a sinistra del form, stile standard Odoo; puoi anche rimuoverla per inserirla inline nel layout.
Buone pratiche
Raccomandazioni pratiche per l’uso del campo Immagine in Odoo.
Imposta limiti di dimensione realistici
Il limite di 1920 px va bene nella maggior parte dei casi. Non aumentarlo senza motivo (ad es. per fotografia destinata alla stampa), perché immagini più grandi aumentano la dimensione degli allegati e rallentano le pagine.
Crea una miniatura per liste e kanban
Se prevedi di mostrare immagini in liste o kanban definisci un campo correlato di piccole dimensioni (128 o 256 px). Caricare una miniatura da 128 px è molto più efficiente che scaricare la versione completa per ogni card.
Usa l’API per caricamenti massivi
Per centinaia o migliaia di immagini evita l’upload manuale: automatizza tramite XML-RPC/JSON-RPC inviando dati in base64. È molto più veloce e ripetibile rispetto all’interfaccia.
Comprimi le immagini prima di caricarle
Odoo ridimensiona ma non sempre comprime al massimo: una JPEG da 5 MB ridimensionata a 1920 px può restare pesante. Comprimi le immagini prima dell’upload per mantenere gli allegati snelli, specialmente con grandi cataloghi.
Evita campi Immagine in viste elenco frequentemente interrogate
Inserire immagini in colonne delle liste costringe Odoo a scaricare dati binari per ogni riga visibile e può rallentare molto. Usa una miniatura se serve una visuale in lista e conserva la versione full-size solo nei form.
Errori comuni
Gli errori più frequenti quando si comincia a usare i campi Immagine in Odoo.
Confondere Binary e Image
Un campo Binary senza widget image compare come pulsante di download, non come anteprima. Per visualizzare l’immagine servono fields.Image o fields.Binary con widget="image" impostato nella vista: è una fonte comune di confusione, specie con versioni più vecchie.
Non prevedere le varianti di dimensione abbastanza presto
Aggiungere solo un campo grande è semplice, ma se poi servono versioni ridotte per kanban o sito, crearle successivamente può richiedere migrazioni. Pianifica le varianti dimensione all’inizio per risparmiare lavoro dopo.
Memorizzare le immagini direttamente invece di usare gli allegati
In installazioni molto datate o mal configurate i binari possono finire nelle colonne delle tabelle principali, gonfiandole e rallentando query non correlate. Assicurati che l’istanza usi la memorizzazione come allegati o storage S3-like.
Usare i campi Immagine come archivio documentale
Alcuni cercano di memorizzare documenti scansionati o screenshot in campi Immagine: tecnicamente possibile, ma non è lo strumento giusto. Per documenti multi-pagina usa il modulo Documents o un campo Binary con widget di download.
Dimenticare le regole di accesso su pagine pubbliche
Se mostri URL di immagini su un sito pubblico ma il record non è accessibile agli anonimi, l’immagine restituisce 404. Quando costruisci pagine web o portali verifica sempre i permessi degli elementi mostrati.
Conclusione
Il campo Immagine è semplice da usare in superficie, ma può creare problemi se non si pianifica. Conoscere come Odoo ridimensiona, conserva come allegati e gestisce le varianti di dimensione evita sorprese durante lo sviluppo e la gestione.
Per l’utente business sapere che le immagini sono archiviate in modo sicuro e raggiungibili tramite URL prevedibili aiuta nella creazione di pagine web o portali. Per gli sviluppatori il pattern fields.Image più campi thumbnail correlati è lo standard da padroneggiare fin da subito.
Che tu debba aggiungere la foto di un prodotto, allegare la fotografia di un sopralluogo a un modello personalizzato o costruire un portale che mostri i loghi dei clienti, il campo Immagine offre un modo integrato e pulito per gestire dati visivi all’interno del modello Odoo.
Serve supporto per la tua implementazione Odoo?
Noi di Dasolo supportiamo le aziende nell’implementazione, personalizzazione e ottimizzazione di Odoo su tutti i moduli e versioni. Se serve configurare campi su modelli standard, sviluppare moduli custom o migrare dati da sistemi legacy, lavoriamo a fianco del tuo team per far funzionare Odoo come richiede il tuo business.
Se hai dubbi sulla tua installazione Odoo o vuoi esplorare le possibilità della piattaforma, contattaci— saremo felici di aiutarti.