Introdução
Se você já carregou uma foto de produto, definiu um logotipo de empresa ou anexou uma foto de perfil a um registro de funcionário no Odoo, você já interagiu com um campo de Imagem. É um dos tipos de campo mais visuais no modelo de dados do Odoo e aparece em mais lugares do que a maioria dos usuários percebe.
Para os usuários empresariais, ele geralmente funciona sem problemas. Você clica em um botão, carrega um arquivo e a imagem aparece no registro. Mas para consultores e desenvolvedores que configuram o Odoo, há bastante coisa acontecendo por trás. O campo de Imagem tem seu próprio mecanismo de armazenamento, comportamento de redimensionamento automático e algumas nuances que vale a pena entender antes de começar a adicionar campos de imagem a modelos personalizados.
Este guia cobre o que o campo de Imagem armazena, como ele se comporta na estrutura do Odoo, como adicioná-lo usando o Odoo Studio ou Python, e exemplos práticos de fluxos de trabalho empresariais reais.
O que é o Campo de Imagem no Odoo
O campo de Imagem é um tipo de campo dedicado no Odoo ORM, introduzido como fields.Image no Odoo 13. Antes dessa versão, os desenvolvedores usavam um campo fields.Binary combinado com o widget image para alcançar o mesmo resultado. Hoje, o tipo de campo Imagem gerencia todo o ciclo de vida do armazenamento de imagens, incluindo redimensionamento automático, por conta própria.
Nos bastidores, o campo de Imagem armazena dados binários codificados em base64. No banco de dados PostgreSQL, esses dados são salvos como uma coluna bytea ou, mais comumente nas versões modernas do Odoo, como um anexo de arquivo vinculado ao registro. Esse armazenamento baseado em anexos mantém as principais tabelas do banco de dados mais leves e permite que o Odoo sirva imagens de forma eficiente através do seu sistema de URLs de anexos.
Como aparece na interface
Em uma visualização de formulário, um campo de Imagem é renderizado como um espaço reservado de imagem clicável. Os usuários podem fazer upload de um arquivo diretamente de seu computador e, em alguns casos, também podem colar uma URL. O campo mostra uma prévia em miniatura diretamente no formulário, o que facilita a identificação à primeira vista.
Em visualizações de lista, os campos de Imagem raramente são exibidos porque miniaturas em listas podem desacelerar o carregamento. No entanto, eles podem ser exibidos em visualizações kanban, onde layouts pequenos baseados em cartões se beneficiam de indicadores visuais, como fotos de produtos ou avatares de contatos.
Tipos de campo do Odoo: Imagem vs Binário
Vale a pena conhecer a distinção entre os dois. Um campo Binário armazena qualquer tipo de arquivo: PDFs, planilhas, arquivos zip, e assim por diante. O campo de Imagem é especificamente projetado para arquivos de imagem. Ele aplica redimensionamento automático ao salvar, impõe validação específica para imagens e renderiza corretamente com o widget de imagem por padrão. Se você estiver armazenando arquivos que não são imagens, use Binário. Se você estiver armazenando fotos ou logotipos, use Imagem.
Como o Campo Funciona
Quando um usuário faz upload de uma imagem para um campo de Imagem, o Odoo não simplesmente armazena o arquivo bruto como está. Ele processa a imagem primeiro.
Redimensionamento automático
A declaração fields.Image aceita os parâmetros max_width e max_height. Se a imagem carregada exceder essas dimensões, o Odoo a redimensiona automaticamente enquanto preserva a proporção. Isso acontece de forma transparente ao salvar, então os usuários nunca precisam pensar sobre isso.
O tamanho máximo padrão para um campo de Imagem padrão é 1920 pixels no lado mais longo. É por isso que o campo é frequentemente nomeado image_1920 em modelos padrão do Odoo, como product.template ou res.partner.
Variantes de tamanho de imagem
Nos modelos integrados do Odoo, você frequentemente verá um padrão de campos de imagem relacionados ao lado do principal: image_1920, image_1024, image_512, image_256 e image_128. Estes são campos separados fields.Image definidos como campos relacionados que apontam de volta para a imagem principal, cada um com diferentes limites de tamanho.
Essa abordagem permite que o Odoo sirva o tamanho de imagem correto dependendo do contexto. Uma página de listagem de produtos busca o pequeno thumbnail image_128 para manter os carregamentos de página rápidos. Uma página de detalhes do produto busca a imagem completa image_1920 para uma exibição mais nítida. Para modelos personalizados, pode ser que você precise ou não desse padrão de múltiplos tamanhos, dependendo de como e onde a imagem será exibida.
Armazenamento como anexos
Por padrão, os campos de Imagem armazenam seus dados como anexos de arquivo do Odoo. Isso significa que o conteúdo binário vive no modelo ir.attachment em vez de diretamente na tabela de registros. O registro mantém uma referência ao anexo.
Na prática, isso mantém as principais tabelas do banco de dados enxutas. Também significa que as imagens são acessíveis através de URLs previsíveis como /web/image/product.template/42/image_1920, que é o padrão usado em páginas da web, modelos de e-mail e respostas de API.
Controle de acesso
Os campos de Imagem respeitam as mesmas regras de acesso que o restante do registro. Se um usuário não tiver acesso de leitura a um produto, ele não poderá recuperar sua imagem também. Isso é tratado automaticamente pela camada de segurança do Odoo, que é algo que vale a pena saber ao construir portais voltados para o cliente ou páginas de sites públicos.
Casos de Uso Empresarial
O campo Imagem aparece em quase todos os módulos do Odoo. Aqui estão algumas das aplicações mais comuns no mundo real.
1. Catálogo de produtos (Vendas e Inventário)
As imagens dos produtos são provavelmente o uso mais visível dos campos de Imagem no Odoo. Cada modelo de produto tem um campo image_1920, e essas imagens aparecem na loja virtual, em PDFs de pedidos de venda, nas telas de ponto de venda e em operações de separação em dispositivos móveis.
Empresas com catálogos grandes costumam usar a API para fazer upload em massa de imagens de produtos em vez de adicioná-las uma a uma através da interface. O campo Imagem aceita dados binários codificados em base64, portanto, é simples fazer upload de imagens programaticamente via XML-RPC ou JSON-RPC.
2. Logotipos de clientes e fornecedores (CRM e Compras)
O modelo res.partner tem um campo de Imagem usado para fotos de contato e logótipos de empresas. Esta imagem aparece no formulário do parceiro, na área de chatter e nos cartões kanban do CRM. Para as equipas de vendas que trabalham com muitas contas, ter logótipos nos registos de contacto facilita a navegação visual pela lista de clientes.
3. Fotos de funcionários (RH)
O modelo hr.employee armazena uma foto de funcionário em um campo de Imagem. Esta foto aparece no diretório de funcionários, nos recibos de pagamento em algumas configurações e no módulo Odoo Discuss ao lado das mensagens. As equipas de RH costumam carregar essas fotos ao integrar um grande lote de novos funcionários, novamente utilizando importação em massa ou a API.
4. Fotos de equipamentos e ativos (Manutenção)
O módulo de Manutenção permite anexar uma imagem aos registos de equipamentos. Os técnicos de campo acham útil ter uma foto da máquina diretamente na ordem de manutenção, para que possam confirmar rapidamente que estão a trabalhar na peça de equipamento certa antes de iniciar um reparo.
5. Formulários de inspeção ou qualidade personalizados
Algumas empresas criam modelos personalizados no Odoo para verificações de qualidade, inspeções de locais ou confirmações de entrega. Adicionar um campo de Imagem a esses modelos permite que a equipa de campo anexe uma foto como evidência diretamente no registo. Este é um padrão comum de personalização do Odoo e funciona bem quer o campo seja adicionado através do Odoo Studio ou diretamente no código Python.
Criando ou Personalizando o Campo
Existem duas maneiras principais de adicionar um campo de Imagem a um modelo Odoo: através do Odoo Studio sem escrever código, ou através do desenvolvimento em Python para mais controle.
Usando o Odoo Studio
O Odoo Studio é a ferramenta de personalização sem código integrada. Para adicionar um campo de Imagem usando o Studio, abra o aplicativo relevante, ative o Studio no menu superior e navegue até a vista do formulário onde deseja que o campo apareça.
No painel de campos à esquerda, arraste um campo de Imagem para o formulário. O Studio solicitará que você dê um rótulo e criará automaticamente o campo subjacente no modelo. Esta é a abordagem recomendada para utilizadores de negócios e consultores funcionais que desejam criar campos no Odoo sem envolver um desenvolvedor.
Os campos criados através do Studio são prefixados com x_studio_ por convenção, por exemplo x_studio_site_photo. Eles se comportam exatamente como campos de Imagem nativos em termos de armazenamento e exibição.
Usando Python (desenvolvimento Odoo)
Para personalizações técnicas, você define campos de Imagem diretamente em um arquivo de modelo Python. Aqui está um exemplo básico de como um desenvolvedor adicionaria um campo de Imagem a um modelo personalizado:
from odoo import models, fields
class SiteInspection(models.Model):
_name = 'site.inspection'
_description = 'Inspeção de Site'
name = fields.Char(string='Referência', required=True)
photo = fields.Image(
string='Foto do Site',
max_width=1920,
max_height=1920,
)
photo_128 = fields.Image(
related='photo',
max_width=128,
max_height=128,
store=True,
string='Miniatura',
)Os parâmetros max_width e max_height informam ao Odoo para limitar o tamanho armazenado a 1920 pixels. O segundo campo, photo_128, é um campo relacionado que armazena uma versão menor para uso em cartões kanban ou visualizações de lista. Este é o padrão de desenvolvimento do Odoo para lidar com múltiplos tamanhos de imagem em um único registro.
Adicionando o campo a uma visualização
Uma vez que o campo existe no modelo, ele precisa ser adicionado a uma visualização para ser visível na interface. Em uma visualização de formulário XML, você exibe um campo de Imagem usando o atributo widget="image":
<field name="photo" widget="image" class="oe_avatar"/>A classe oe_avatar o posiciona como um avatar circular no canto superior esquerdo do formulário, que é o estilo padrão do Odoo. Você também pode usá-lo sem a classe para colocá-lo em linha dentro de um layout de formulário.
Melhores Práticas
Aqui estão as recomendações que damos aos clientes ao trabalhar com campos de Imagem no Odoo.
Defina limites de tamanho realistas
O limite padrão de 1920 pixels é apropriado para a maioria dos casos de uso. Evite aumentá-lo a menos que você tenha um motivo forte, como fotografia de produto em alta resolução para impressão. Imagens maiores significam anexos maiores, o que afeta o tamanho do banco de dados e o desempenho de carregamento da página.
Crie uma variante de miniatura para listas e kanban
Se você estiver exibindo a imagem em visualizações de lista ou cartões kanban, defina um campo relacionado de tamanho pequeno separado, limitado a 128 ou 256 pixels. Buscar uma miniatura de 128 pixels é muito mais rápido do que carregar a imagem completa de 1920 pixels para cada cartão na tela.
Use a API para uploads em massa de imagens
Quando você precisa carregar imagens para centenas ou milhares de registros, não faça isso manualmente através da interface. Use a API Odoo XML-RPC ou JSON-RPC para gravar dados de imagem codificados em base64 diretamente no campo. Isso é muito mais rápido e pode ser automatizado em um script. O guia do desenvolvedor Odoo cobre bem esse padrão.
Comprimir imagens antes de fazer o upload
Embora o Odoo redimensione imagens automaticamente, ele nem sempre as comprime de forma agressiva. Um JPEG de 5 MB redimensionado para 1920 pixels ainda pode ter várias centenas de kilobytes. Pré-comprimir imagens antes de fazer o upload mantém os tamanhos dos anexos gerenciáveis, especialmente ao lidar com grandes catálogos de produtos.
Evite campos de imagem em visualizações de lista frequentemente consultadas
Incluir um campo de Imagem em uma coluna de visualização de lista força o Odoo a buscar dados binários para cada linha visível. Isso pode tornar as visualizações de lista visivelmente mais lentas. Use uma miniatura pequena se você realmente precisar de um visual em uma lista e mantenha a imagem em tamanho real apenas para a visualização do formulário.
Erros Comuns
Esses são os erros que vemos com mais frequência quando as equipes começam a trabalhar com campos de Imagem no Odoo.
Confundindo campos Binários e de Imagem
Um campo Binário sem o widget de imagem será renderizado como um botão de download, e não como uma pré-visualização da imagem. Se você quiser uma exibição de imagem adequada, precisa de um tipo de campo fields.Image ou de um fields.Binary com widget="image" explicitamente definido na visualização. Esquecer isso é uma fonte comum de confusão, especialmente ao trabalhar em versões mais antigas do Odoo.
Não pensar sobre variantes de tamanho de imagem cedo o suficiente
Adicionar um único campo de Imagem grande é fácil, mas se você perceber mais tarde que precisa de versões menores para uma visualização kanban ou uma listagem de site, adicionar esses campos relacionados requer uma migração de banco de dados se você estiver em um módulo personalizado. Planejar as variantes de tamanho antecipadamente evita dores de cabeça mais tarde.
Armazenando imagens diretamente em vez de usar anexos
Em versões muito antigas do Odoo ou em instâncias mal configuradas, dados binários poderiam ser armazenados diretamente na coluna do banco de dados em vez de como anexos. Isso aumenta significativamente o tamanho das tabelas principais e desacelera consultas não relacionadas. Certifique-se de que sua instância do Odoo está configurada para usar armazenamento de arquivos ou armazenamento compatível com S3 para anexos.
Usando campos de Imagem como armazenamento de documentos
Alguns usuários tentam armazenar documentos digitalizados ou capturas de tela em campos de Imagem. Embora tecnicamente possível, não é a ferramenta certa. Para gerenciamento de documentos, use o módulo Odoo Documents ou um campo Binário com um widget de download de arquivos. Campos de Imagem são projetados para fotos e logotipos, não para armazenar documentos de várias páginas.
Esquecendo regras de acesso em páginas públicas
Se você exibir URLs de imagens em um site público ou em um portal e o registro subjacente não for acessível a usuários públicos, a imagem retornará um erro 404. Ao construir páginas de site ou portais de clientes, sempre verifique se a URL da imagem é acessível ao público esperado.
Conclusão
O campo de Imagem é um dos tipos de campo mais simples de usar à primeira vista, mas tem profundidade suficiente para confundir equipes que não planejam com antecedência. Compreender como o Odoo lida com redimensionamento, armazenamento como anexos e o padrão de variantes de múltiplos tamanhos economizará seu tempo ao construir ou configurar modelos que precisam de dados visuais.
Para usuários de negócios, saber que as imagens estão armazenadas com segurança no registro e acessíveis através de URLs previsíveis ajuda ao configurar páginas de site ou visualizações de portal. Para desenvolvedores, a combinação de fields.Image com campos de miniatura relacionados é o padrão Odoo, e vale a pena se familiarizar com isso desde cedo.
Seja adicionando uma foto de produto ao seu catálogo, anexando uma foto de inspeção de site a um modelo personalizado ou construindo um portal de clientes que exibe logotipos de contato, o campo de Imagem oferece uma maneira limpa e integrada de lidar com dados visuais dentro do modelo de dados do Odoo.
Precisa de Ajuda com a Sua Implementação do Odoo?
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os módulos e versões. Se você precisa configurar campos em modelos padrão, construir módulos personalizados do zero ou migrar dados de um sistema legado, trabalhamos diretamente com sua equipe para fazer o Odoo funcionar da maneira como seu negócio realmente opera.
Se você tiver perguntas sobre sua configuração do Odoo ou quiser explorar o que é possível com a plataforma, entre em contato conosco. Estamos felizes em ajudar.