Introdução
Se já colocou a foto de um produto, definiu o logótipo da empresa ou adicionou a fotografia de um colaborador no Odoo, então já lidou com o campo Imagem. É o tipo de campo mais visível no modelo de dados do Odoo e aparece em mais lugares do que muitos utilizadores imaginam.
Para quem usa o sistema no dia a dia, o processo é simples: carrega-se um ficheiro e a imagem aparece. Por detrás dessa simplicidade há, contudo, um conjunto de comportamentos técnicos — desde a forma como os dados são guardados até ao redimensionamento automático — que consultores e programadores devem conhecer antes de adicionar campos visuais a modelos personalizados.
Este guia explica o que o campo Imagem guarda, como ele se integra no núcleo do Odoo, as formas de o adicionar (via Studio ou código Python) e exemplos práticos de utilização em processos reais de negócio.
O que é o campo de Imagem no Odoo
No Odoo, existe um tipo de campo específico para imagens — fields.Image — que passou a ser a forma recomendada a partir da versão 13. Antes disso, usavam-se campos Binary com um widget de imagem. Hoje, o fields.Image trata de todo o ciclo: valida, redimensiona e apresenta a imagem de forma consistente.
Tecnicamente, o conteúdo de uma imagem é guardado em binário codificado em base64. Em instalações modernas do Odoo estes binários ficam como anexos (ir.attachment) em vez de encherem as tabelas principais. Esse modelo de armazenamento torna a base de dados mais leve e permite servir imagens de forma eficiente através de URLs de anexo.
Aparência na interface
Num formulário, o campo Imagem surge como um espaço clicável para carregar ficheiros — às vezes aceita até uma URL colada — e mostra uma pré-visualização em miniatura diretamente no formulário, facilitando a identificação visual do registo.
Em listas, os thumbnails raramente aparecem porque podem degradar o desempenho; já em vistas kanban as imagens são muito úteis, pois os cartões pequenos beneficiam de uma referência visual, como a foto do produto ou o avatar de um contacto.
Imagem vs Binary no Odoo
É importante distinguir os dois: Binary serve para qualquer ficheiro (PDFs, folhas de cálculo, ZIPs). O campo Image é específico para imagens: aplica validações, redimensionamento automático e funciona naturalmente com o widget de imagem. Se o objectivo for guardar fotos ou logótipos, use Image; para outros ficheiros, use Binary.
Como o campo funciona
Quando um utilizador carrega uma imagem num campo Image, o Odoo processa o ficheiro antes de o guardar.
Redimensionamento automático
A declaração fields.Image aceita parâmetros como max_width e max_height. Se a imagem carregada exceder esses limites, o Odoo redimensiona-a mantendo a proporção. Esse ajuste é feito automaticamente no momento do ‘save’, pelo que o utilizador não precisa de se preocupar com dimensões.
Por defeito, o limite máximo de uma imagem padrão é 1920 pixels no lado mais longo — daí muitos modelos standard terem campos chamados image_1920 (por exemplo em product.template ou res.partner).
Variações de tamanho
Nos modelos integrados do Odoo é habitual encontrar uma família de campos relacionados: image_1920, image_1024, image_512, image_256, image_128. São campos Image relacionados entre si, cada um com limites diferentes de dimensão.
Esse padrão permite ao Odoo servir o tamanho adequado conforme o contexto: uma listagem usa um thumbnail pequeno para carregar mais depressa, enquanto a página de detalhe usa a imagem maior para melhor qualidade. Em modelos personalizados, decida se precisa desta estratégia de múltiplos tamanhos consoante onde a imagem será exibida.
Armazenamento como anexos
Por norma, os campos Image guardam o conteúdo como anexos em ir.attachment. Ou seja, o binário fica fora da tabela principal do registo e o registo mantém apenas a referência ao anexo.
Na prática, isto mantém as tabelas principais mais leves e cria URLs previsíveis para servir imagens, por exemplo /web/image/product.template/42/image_1920 — padrão usado em sites, templates de email e respostas de API.
Controlo de acesso
As imagens obedecem às mesmas regras de acesso do registo. Se um utilizador não tem permissão de leitura sobre um produto, também não consegue aceder à sua imagem. Esse controlo é gerido pela camada de segurança do Odoo, algo importante quando se criam portais de clientes ou páginas públicas no site.
Casos de uso para as empresas
O campo Imagem aparece em quase todos os módulos do Odoo. Eis os usos mais comuns nas empresas.
1. Catálogo de produtos (Vendas e Inventário)
As imagens de produto são provavelmente o uso mais visível. O product.template inclui normalmente um image_1920 e essas imagens aparecem na loja online, em PDFs de encomenda, nos ecrãs de POS e nas operações de picking em dispositivos móveis.
Empresas com catálogos extensos costumam fazer uploads massivos via API em vez de inserir imagens manualmente. O campo aceita dados binários em base64, tornando simples carregar imagens programaticamente por XML-RPC ou JSON-RPC.
2. Logótipos de clientes e fornecedores (CRM e Compras)
O res.partner tem um campo de Imagem para fotos de contacto e logótipos de empresas. Essas imagens aparecem no formulário do parceiro, no chatter e nos cartões kanban do CRM — muito útil para equipas comerciais que lidam com muitas contas e precisam de uma identificação rápida.
3. Fotos de colaboradores (RH)
O hr.employee guarda a fotografia do colaborador num campo Image. Essa imagem aparece no diretório de colaboradores, nalgumas configurações nas folhas de salário e no módulo Discuss ao lado das mensagens. Nos processos de onboarding, é comum importar essas fotos em lote.
4. Fotos de equipamentos e ativos (Manutenção)
No módulo de Manutenção, os técnicos podem ver a fotografia do equipamento diretamente na ordem de intervenção. Isso ajuda a confirmar rapidamente que estão a intervir na máquina correta antes de iniciar um reparo.
5. Formulários de inspeção ou qualidade personalizados
Muitos projetos criam modelos customizados para checklists, inspeções ou confirmações de entrega. Acrescentar um campo Image permite que a equipa de campo anexe provas fotográficas ao registo — prática comum tanto por Studio como por desenvolvimento Python.
Criar ou personalizar o campo
Existem duas formas principais de adicionar um campo Image: sem código, usando Odoo Studio, ou via desenvolvimento em Python quando é preciso maior controlo.
Usar o Odoo Studio
Odoo Studio é a ferramenta no-code integrada. Para adicionar uma imagem com Studio, abra a app, ative o Studio no menu superior e edite a vista de formulário onde quer inserir o campo.
Arraste um campo Image do painel de campos para o formulário. O Studio pede um rótulo e cria automaticamente o campo no modelo — é a forma mais prática para utilizadores de negócio e consultores funcionais que não querem envolver programadores.
Campos criados pelo Studio seguem a convenção x_studio_, por exemplo x_studio_site_photo, e comportam‑se como quaisquer campos Image nativos em termos de armazenamento e apresentação.
Usar Python (desenvolvimento Odoo)
Para personalizações técnicas define-se o campo directamente no ficheiro Python do modelo. Abaixo está um exemplo simples de como adicionar um campo Image a um modelo personalizado:
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',
)
Os parâmetros max_width e max_height limitam o tamanho guardado a 1920 pixels. O segundo campo (photo_128) é um campo relacionado que guarda uma versão reduzida para usar em vistas kanban ou listas — esse é o padrão de desenvolvimento recomendado no Odoo para gerir várias versões de uma mesma imagem.
Adicionar o campo à vista
Depois de criado no modelo, o campo deve ser incluído numa vista para aparecer na interface. Numa vista de formulário em XML usa-se o widget de imagem dessa forma:
<field name="photo" widget="image" class="oe_avatar"/>A classe oe_avatar posiciona a imagem como avatar circular no canto superior esquerdo do formulário, estilo padrão do Odoo. Pode também usar-se sem essa classe para inserir a imagem inline no layout do formulário.
Boas práticas
Recomendações práticas
Defina limites de tamanho realistas
O limite padrão de 1920px é adequado na maioria dos casos. Só aumente se tiver uma necessidade concreta (por exemplo fotografia de alta resolução para impressão). Imagens maiores traduzem-se em anexos maiores, mais espaço na base de dados e páginas mais lentas.
Crie um thumbnail para listas e kanban
Se for mostrar imagens em listas ou cartões kanban, defina um campo relacionado mais pequeno (128 ou 256px). Carregar thumbnails de 128px é muito mais rápido do que pedir a imagem completa para cada cartão visível.
Use a API para uploads em massa
Para carregar imagens em centenas ou milhares de registos, automatize via XML-RPC/JSON-RPC inserindo dados em base64. Esse método é muito mais eficiente do que fazer uploads manuais e pode ser integrado numa rotina ou script de migração.
Comprimir imagens antes de enviar
Embora o Odoo redimensione imagens, nem sempre as comprime ao máximo. Uma JPEG de 5 MB redimensionada pode continuar grande. Pré-comprimir antes do upload ajuda a controlar o tamanho dos anexos, sobretudo em catálogos extensos.
Evite campos Image em vistas de lista pesadas
Incluir uma imagem numa coluna de lista obriga o Odoo a buscar binários para cada linha, o que pode tornar a vista lenta. Use thumbnails quando for estritamente necessário e deixe a imagem em tamanho completo apenas para a vista de formulário.
Erros comuns a evitar
Erros comuns que encontramos com frequência
Confundir Binary com Image
Um campo Binary sem o widget adequado aparece como botão de download em vez de pré-visualização. Para exibir imagens correctamente precisa de um fields.Image ou de um fields.Binary com widget="image" na vista — um tropeço comum, sobretudo em versões antigas do Odoo.
Não planear variantes de tamanho desde o início
Criar apenas um campo grande é fácil, mas se mais tarde precisar de thumbnails para kanban ou website, adicionar esses campos em módulos custom implica migrações de dados. Planear as variantes desde o início evita trabalho extra.
Armazenar imagens directamente nas tabelas principais
Em versões muito antigas ou instalações mal configuradas, os binários podem ficar na coluna da tabela principal em vez de anexos. Isso infla as tabelas e reduz o desempenho. Garanta que a sua instância usa armazenamento de anexos (ficheiros locais ou S3) corretamente configurado.
Usar Image para gestão documental
Alguns tentam guardar documentos digitalizados em campos Image. Apesar de possível, não é a ferramenta ideal. Para documentos multipágina ou gestão documental use o módulo Documents do Odoo ou um campo Binary com widget de download. Image destina‑se a fotos e logótipos.
Esquecer regras de acesso em páginas públicas
Se publicar URLs de imagens num site público ou portal, verifique que o registo subjacente está acessível ao público. Caso contrário, o URL pode devolver 404. Sempre valide o acesso esperado quando constrói páginas web ou portais de clientes.
Conclusão
À primeira vista, o campo Imagem é simples de usar, mas tem nuances que podem complicar projetos quando não são planeadas. Compreender o redimensionamento, o armazenamento por anexos e o padrão de variantes de tamanho evita surpresas durante a implementação.
Para utilizadores de negócio, saber que as imagens ficam seguras no registo e disponíveis através de URLs previsíveis ajuda a construir páginas web e portais. Para desenvolvedores, familiarizar-se com fields.Image e com campos relacionados de thumbnails é um padrão essencial do Odoo.
Quer esteja a colocar uma foto num produto, a anexar uma imagem de inspeção a um modelo personalizado ou a construir um portal que exiba logótipos de clientes, o campo Imagem oferece uma forma integrada e limpa de gerir dados visuais dentro do modelo de dados do Odoo.
Precisa de ajuda com a sua implementação Odoo?
Na Dasolo ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os módulos e versões. Se precisa configurar campos em modelos standard, desenvolver módulos à medida ou migrar dados de sistemas legados, trabalhamos lado a lado com a sua equipa para pôr o Odoo a funcionar conforme os processos reais do seu negócio.
Se tem dúvidas sobre a sua configuração Odoo ou quer explorar possibilidades na plataforma, contacte‑nos— teremos todo o gosto em ajudar.