Introdução
Os campos binários não são glamourosos, mas estão em toda parte em uma implementação real do Odoo. Sempre que um usuário faz o upload de um contrato assinado, anexa uma ficha técnica de produto ou armazena um logotipo da empresa em um registro, há um campo Binário funcionando nos bastidores. Compreender como ele armazena dados, onde esses dados acabam e quando usar um tipo de campo diferente faz uma grande diferença ao construir formulários personalizados ou estender modelos do Odoo.
Este guia cobre o que o campo Binário armazena, como o modo de anexo afeta o armazenamento e o desempenho, como criá-lo e personalizá-lo usando o Odoo Studio ou Python, e casos de uso práticos em CRM, RH, Inventário e mais.
O que é o Campo Binário no Odoo
No ORM do Odoo, o campo Binário (fields.Binary) armazena dados binários brutos: arquivos, documentos, imagens ou qualquer conteúdo que um usuário faça upload para um registro. Do ponto de vista do usuário, ele aparece como um botão de upload de arquivo nas visualizações de formulário. Uma vez que um arquivo é anexado, o mesmo botão permite que os usuários o baixem com um único clique.
O detalhe técnico mais importante é onde esses dados realmente acabam. Por padrão, nas versões modernas do Odoo, os campos Binários usam o modo de anexo. Isso significa que o conteúdo do arquivo é armazenado na tabela ir.attachment e no armazenamento de arquivos do servidor, não diretamente dentro da coluna do modelo. A coluna do modelo mantém apenas um ID de referência apontando para o registro de anexo. Essa abordagem mantém suas tabelas principais do banco de dados enxutas e permite que o Odoo gerencie arquivos de forma eficiente.
No Odoo Studio, o campo Binário é rotulado como Arquivo no seletor de campos. Ele é renderizado como um simples controle de upload e download nas visualizações de formulário. Para conteúdo de imagem especificamente, o Odoo também fornece um tipo dedicado fields.Image que adiciona redimensionamento automático e visualização em miniatura. Abordaremos isso nas seções relevantes abaixo.
Aqui está como um campo Binário aparece em uma definição de modelo Python:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Contrato Assinado',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Nome do Arquivo do Contrato Assinado',
)Note o campo Char acompanhante x_signed_contract_filename. Emparelhar um campo Binário com um campo Char para o nome do arquivo é um padrão de desenvolvimento padrão do Odoo. O Odoo usa o campo _filename para lembrar e exibir o nome original do arquivo na interface. Sem ele, os arquivos baixados podem receber um nome genérico.
Como o Campo Funciona
Quando você define um campo Binário no modelo de dados do Odoo, o framework cuida da criação da coluna automaticamente na instalação ou atualização do módulo. Nenhum SQL manual é necessário da sua parte.
Modos de Armazenamento
O parâmetro attachment em um campo Binário controla onde os bytes do arquivo são realmente armazenados:
- attachment=True (recomendado): O conteúdo do arquivo é armazenado em
ir.attachment, vinculado ao registro pelo nome do modelo e ID do registro. A coluna do modelo mantém apenas um ID de referência. Isso mantém as tabelas do modelo pequenas e aproveita o sistema de filestore do Odoo. - attachment=False: Os dados brutos codificados em base64 são armazenados diretamente dentro da coluna do banco de dados do modelo. Isso faz com que as tabelas cresçam muito, desacelerando as consultas em todo o modelo. Evite este modo para qualquer coisa maior do que uma pequena miniatura de imagem.
Formato de Dados
Os campos Binários armazenam e retornam dados como bytes codificados em base64. Quando você lê um campo Binário via ORM do Odoo ou a API XML-RPC, você recebe uma string em base64. Quando você escreve nele, você também deve fornecer uma string codificada em base64.
Na prática, isso significa codificar antes de escrever e decodificar após ler:
import base64
# Escrevendo um arquivo em um campo Binário
with open('document.pdf', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Lendo um arquivo de um campo Binário
raw_bytes = base64.b64decode(record.x_signed_contract)Atributos do Campo Chave
Estes são os atributos mais importantes que você pode configurar em um campo Binário no framework Odoo:
- attachment: Booleano. Se deve armazenar em
ir.attachment(Verdadeiro) ou diretamente na coluna (Falso). Padrão: Verdadeiro nas versões recentes do Odoo. - string: Rótulo de exibição mostrado na interface.
- required: Torna o campo obrigatório antes de salvar o registro.
- compute: Liga um método Python para calcular o valor do campo dinamicamente, por exemplo, gerando um PDF sob demanda como um campo computado do Odoo.
- store: Quando usado com
compute, salva o valor calculado no banco de dados. - groups: Restringe o acesso ao campo a grupos de usuários específicos do Odoo. Importante para documentos sensíveis.
- copy: Controla se o valor é duplicado quando um registro é copiado. Os padrões variam dependendo do modo de anexo e da versão do Odoo.
A Subclasse fields.Image
fields.Image é uma subclasse especializada de fields.Binary introduzida no Odoo 13. Ela adiciona redimensionamento automático de imagem para uma dimensão máxima configurável, um tamanho de visualização opcional para miniaturas e renderiza uma pré-visualização adequada da imagem nas visualizações de formulário. Para armazenar imagens de produtos, fotos de parceiros, logotipos de empresas ou qualquer conteúdo visual, use fields.Image em vez de um campo Binário simples. Isso previne uploads excessivamente grandes e proporciona uma experiência de usuário muito melhor para dados de imagem.
Como Aparece nas Vistas
Nas vistas de formulário, o widget padrão para um campo Binário é um botão de upload e download. Para conteúdo de imagem, aplique o widget image para obter uma pré-visualização em miniatura. Nas vistas de lista, os campos Binários geralmente não são mostrados diretamente porque carregar o conteúdo completo do arquivo para cada linha visível cria uma transferência de dados desnecessária. A abordagem padrão é mostrar um indicador booleano ou um ícone nas vistas de lista para sinalizar se um arquivo está anexado.
Casos de Uso Empresarial
O campo Binário aparece em muitos módulos do Odoo em implementações reais. Aqui estão cinco exemplos práticos de fluxos de trabalho empresariais comuns.
CRM: Armazenamento de NDAs ou Contratos Assinados nos Registros de Clientes
Muitas empresas precisam anexar um documento assinado diretamente a um registro de cliente ou lead no Odoo CRM. Um campo Binário em res.partner ou crm.lead dá às equipes de vendas acesso com um clique ao contrato relevante sem sair da interface do Odoo. Isso elimina a necessidade de uma ferramenta de gestão de documentos separada para armazenamento básico de arquivos e mantém a informação exatamente onde a equipe espera encontrá-la durante o processo de vendas.
RH: Armazenamento de Documentos de Funcionários
Os departamentos de RH precisam regularmente armazenar cópias de documentos de identificação de funcionários, permissões de trabalho, contratos de trabalho assinados ou certificados de formação. Um campo Binário em hr.employee armazena esses arquivos de forma segura dentro do sistema de controle de acesso do Odoo. Usando o atributo groups, você pode restringir a visibilidade para que apenas os gerentes de RH possam visualizar documentos sensíveis, enquanto outros gerentes veem o formulário sem acessar os arquivos reais. Este é um pedido comum de personalização do Odoo em empresas com requisitos rigorosos de privacidade de dados.
Inventário: Fichas de Especificação de Produto e Dados de Segurança
Produtos técnicos frequentemente vêm com fichas de especificação em PDF, fichas de dados de segurança ou certificados de qualidade do fabricante. Um campo Binário em product.template permite que as equipes de compras e o pessoal do armazém acessem a documentação correta diretamente do registro do produto no Odoo. Esta é uma das adições de personalização do Odoo mais frequentemente solicitadas em empresas de manufatura e distribuição, e é fácil de implementar com o Odoo Studio ou um módulo Python personalizado.
Vendas: Imagem do Carimbo da Empresa ou Assinatura Autorizada
Alguns contextos empresariais exigem um carimbo da empresa ou uma assinatura autorizada em cotações impressas ou confirmações de pedido. Um campo fields.Image em res.company armazena este ativo visual, que pode ser referenciado em um modelo de relatório QWeb. Isso permite que documentos impressos incluam o carimbo automaticamente, sem qualquer manuseio manual por documento, economizando tempo em operações de vendas de alto volume e reduzindo o risco de enviar cotações não assinadas por acidente.
Contabilidade: Anexar Recibo Escaneado em Registros de Despesas
Os fluxos de trabalho de gestão de despesas normalmente requerem a anexação de um recibo ou fatura digitalizada a cada registo de despesa como prova para reembolso. Para despesas padrão do Odoo, o sistema de anexos lida com isso de forma nativa. Mas em modelos de despesas personalizados, fluxos de trabalho de faturas de fornecedores ou integrações de terceiros, um campo Binário fornece uma maneira limpa de armazenar a imagem ou PDF do recibo diretamente no registo e incluí-lo na lógica de roteamento de aprovações sem depender do painel de anexos genérico.
Criando ou Personalizando o Campo Binário
Existem três maneiras principais de adicionar um campo Binário a um modelo Odoo, dependendo do seu contexto técnico e de quanto controle você precisa.
Usando Odoo Studio (Sem Código)
O Odoo Studio é a ferramenta de personalização de baixo código integrada. Para adicionar um campo Binário sem escrever código:
- Abra o Odoo Studio a partir do menu principal.
- Navegue até o formulário onde você deseja o campo.
- Arraste um campo Arquivo do seletor de campos para o formulário.
- Defina o rótulo e quaisquer condições de visibilidade opcionais no painel de propriedades.
- Salve e feche o Studio.
O Studio cria o campo com um prefixo x_studio_ e usa automaticamente o modo de anexo. Nenhuma configuração de banco de dados é necessária do seu lado. Este é um dos campos mais acessíveis do Odoo Studio para usuários de negócios que precisam de capacidade de upload de arquivos em seus formulários sem envolvimento de desenvolvedores.
Usando Python em um Módulo Personalizado
Para desenvolvimento Odoo que precisa ser controlado por versão e implantado em múltiplos ambientes, a abordagem padrão é definir campos Binários diretamente em Python. Esta é a abordagem recomendada em qualquer guia de desenvolvedor Odoo para trabalhos sérios de personalização do Odoo:
from odoo import fields, models
class HrEmployee(models.Model):
_inherit = 'hr.employee'
x_id_document = fields.Binary(
string='ID Document',
attachment=True,
groups='hr.group_hr_user',
)
x_id_document_filename = fields.Char(
string='ID Document Filename',
)Após adicionar o campo ao modelo, inclua-o na visualização do formulário XML com o widget binary e o atributo filename apontando para o campo Char acompanhante. O Odoo gerencia automaticamente a coluna do banco de dados na instalação ou atualização do módulo. Esta abordagem funciona de forma limpa em todos os tipos de implantação do Odoo, incluindo Odoo.sh e instalações locais.
Usando a API XML-RPC
Se você estiver gerenciando a criação de campos do Odoo programaticamente, por exemplo, através de um script de configuração remota ou um caderno de implantação, você pode criar campos Binary via a API XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_document',
'field_description': 'Custom Document',
'model_id': model_id,
'ttype': 'binary',
'state': 'manual',
}]
)O valor state: manual informa ao Odoo que este campo foi criado manualmente em vez de instalado por um módulo. Campos criados via API usam o modo de anexo por padrão nas versões atuais do Odoo. Esta é a abordagem usada em scripts de configuração automatizados do Odoo e fluxos de trabalho de implantação remota.
Melhores Práticas
1. Sempre use attachment=True
A menos que você tenha uma razão técnica muito específica para armazenar o conteúdo do arquivo diretamente na coluna do banco de dados, use o modo de anexo. Isso mantém as tabelas do modelo pequenas, previne consultas lentas e permite que o Odoo gerencie arquivos através de seu filestore embutido. Este também é o comportamento padrão nas versões recentes, portanto, simplesmente omitir o parâmetro attachment é suficiente na maioria dos casos. Para qualquer arquivo maior que um pequeno miniatura, o modo de anexo não é opcional.
2. Emparelhe campos Binary com um campo Char de nome de arquivo
Sempre adicione um campo Char acompanhante _filename ao lado de qualquer campo Binary usado em uma visualização de formulário. Sem ele, o widget de upload de arquivo não pode exibir ou restaurar o nome original do arquivo, e os usuários que baixam o arquivo acabam com um nome genérico como download. Esta pequena adição leva uma linha de código e faz uma diferença notável na experiência do usuário do formulário.
3. Use fields.Image para conteúdo visual
Se você estiver armazenando fotos de produtos, retratos de parceiros, logotipos de empresas ou quaisquer outras imagens, use fields.Image em vez de um campo Binary simples. Ele limita automaticamente o tamanho do upload às dimensões máximas configuradas, renderiza uma miniatura na interface e inclui um campo separado para a imagem de visualização redimensionada. Usar o tipo de campo certo para o conteúdo certo é um princípio fundamental no design limpo do modelo de dados do Odoo.
4. Restringir o acesso com o parâmetro groups
Campos binários que armazenam documentos sensíveis, como arquivos de funcionários, contratos assinados ou registros financeiros, devem definir restrições de acesso usando o parâmetro groups. Isso limita quem pode ler ou escrever no campo, o que é importante tanto para a privacidade dos dados quanto para os requisitos de trilha de auditoria em ambientes regulamentados.
5. Lidar com a codificação base64 com cuidado no código
Ao ler ou escrever campos binários programaticamente, sempre lide com a codificação base64 de forma explícita. Use base64.b64encode(file_bytes).decode('utf-8') para converter bytes antes de escrever e base64.b64decode(field_value) para converter de volta para bytes após a leitura. Não assuma que os dados já estão no formato que você precisa. Esta é uma fonte comum de bugs em integrações do Odoo ORM que só aparecem quando arquivos reais são processados.
Armadilhas Comuns
Definindo attachment=False para arquivos grandes
Armazenar o conteúdo de arquivos diretamente em uma coluna de banco de dados pode aumentar significativamente o tamanho das suas tabelas PostgreSQL. Algumas dezenas de documentos PDF armazenados com attachment=False podem adicionar centenas de megabytes a uma única tabela de modelo, desacelerando cada consulta nesse modelo. Este é um dos erros de configuração mais impactantes na gestão de banco de dados do Odoo. Uma vez que os dados são armazenados dessa forma e a tabela cresce, migrar para o modo de anexo requer um script personalizado e planejamento cuidadoso.
Esquecendo o campo acompanhante do nome do arquivo
Sem um campo Char pareado para o nome do arquivo, os usuários que baixam um arquivo de um campo Binário frequentemente recebem um nome de arquivo genérico. Este é um problema pequeno, mas persistente, que faz a implementação parecer inacabada. Adicionar o campo acompanhante leva menos de um minuto e deve ser parte de qualquer definição de campo Binário que apareça em uma visualização de formulário voltada para o usuário.
Confundindo campos Binários e de Imagem
Usar um campo Binário simples para conteúdo de imagem perde o redimensionamento automático e a renderização de miniaturas que fields.Image fornece. Os usuários podem fazer upload de arquivos de imagem muito grandes que desaceleram o carregamento de formulários e consomem espaço de armazenamento desnecessário. Por outro lado, usar fields.Image para arquivos não-imagem, como PDFs, causa erros porque o Odoo tenta processar o conteúdo como uma imagem. A regra é simples: combine o tipo de campo com o tipo de conteúdo esperado.
Incluindo campos Binários diretamente nas visualizações de lista
Adicionar um campo Binário a uma visualização de lista faz com que o Odoo carregue o conteúdo completo do arquivo para cada linha visível. Para uma lista com cinquenta registros, isso pode significar transferir megabytes de dados apenas para renderizar a página. Se você precisar indicar a presença de arquivos em uma visualização de lista, use um campo booleano computado ou um botão de ícone em vez do campo Binário diretamente. Este é um problema comum de desempenho em implementações do Odoo que só se torna visível em volumes reais de dados.
Não verificar se é False antes de processar no código
Um campo Binário sem valor retorna False em Python, não uma string vazia e não bytes vazios. Se você tentar decodificar um valor de campo Binário sem verificar se é False primeiro, você receberá um TypeError que interrompe o método. Sempre proteja com: if record.x_document: data = base64.b64decode(record.x_document). Isso é importante em métodos de cálculo, ações do servidor e qualquer código que processe valores Binários condicionalmente.
Conclusão
O campo Binário é uma parte simples, mas importante do modelo de dados do Odoo. Ele lida com o armazenamento de arquivos e documentos de uma maneira que se integra naturalmente com a interface do Odoo, seu sistema de anexos e seu framework de controle de acesso.
Os principais hábitos a desenvolver: sempre usar o modo de anexo, emparelhar campos Binários com um campo Char de nome de arquivo, escolher fields.Image para conteúdo visual, restringir o acesso a documentos sensíveis e lidar com a codificação base64 com cuidado em código personalizado. Essas práticas evitam os problemas mais comuns antes que tenham a chance de surgir em produção.
Seja você adicionando um campo de upload de arquivo através do Odoo Studio, construindo um módulo Python personalizado ou gerenciando a criação de campos via Odoo ORM ou API XML-RPC, acertar os campos Binários desde o início leva a uma implementação do Odoo mais limpa e confiável no geral.
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Se você precisa de ajuda para projetar um modelo de dados com os tipos de campo certos, construir fluxos de trabalho personalizados de gerenciamento de arquivos ou desenvolver um módulo Odoo completo, nossa equipe está aqui para apoiar você. Entre em contato conosco e vamos conversar sobre o seu projeto Odoo.