Campos de Contexto no Odoo: Um Guia Prático

Se você passou algum tempo trabalhando com o ORM do Odoo ou personalizando visualizações, você quase certamente viu a palavra contexto aparecer. Ela aparece nas definições de campos, nos atributos de visualização XML e em todo o código Python do Odoo. No entanto, para muitos desenvolvedores e consultores, continua sendo uma daquelas coisas que simplesmente funcionam até que não funcionam mais.

Entender os campos de contexto no Odoo não é apenas um exercício acadêmico. Isso afeta diretamente como seu modelo de dados se comporta, como os formulários preenchem valores, como os registros são filtrados e como os campos computados decidem o que retornar. Seja você um simples customizador do odoo ou esteja construindo um módulo completo, acertar o contexto economiza muito tempo de depuração.

Este guia detalha o que é contexto, como ele flui através do framework Odoo e como usá-lo com confiança em projetos reais.

O que é Contexto no Odoo

O contexto no Odoo é um dicionário Python que viaja junto com cada solicitação, cada chamada de método e cada operação de registro. Não é um tipo de campo no sentido tradicional. Você não encontrará fields.Context() no ORM do Odoo. Em vez disso, o contexto é um mecanismo que modifica o comportamento dos campos.

Pense nisso como um conjunto de instruções invisíveis passadas junto com seus dados. Essas instruções dizem ao Odoo coisas como: preencha este campo com um valor padrão, mostre registros arquivados também, compute este campo usando um idioma diferente ou aplique este domínio ao mostrar o seletor de registros relacionados.

Onde o Contexto Aparece

Você encontrará contexto em três lugares principais no modelo de dados Odoo:

• Nas definições de campo em Python: O parâmetro context em campos relacionais como Many2one, One2many e Many2many.
• Nos atributos de visualização XML: O atributo context nas tags <field> em visualizações de formulário, lista e kanban.
• No ambiente ORM: Acessível via self.env.context no código Python, e modificável com self.with_context(key=value).

Em todos os três casos, o contexto está fazendo a mesma coisa fundamental: ele carrega informações extras que moldam como um campo ou um registro se comporta em tempo de execução.

Como o Contexto Funciona no Modelo de Dados do Odoo

O contexto flui através do ciclo de vida da solicitação Odoo desde o momento em que um usuário abre um formulário até o momento em que um registro é salvo. Aqui está como os mecanismos principais funcionam na prática.

Valores Padrão com default_*

Um dos padrões de contexto mais comumente usados é default_field_name. Quando você passa uma chave que começa com default_, o Odoo a utiliza para preencher um campo automaticamente quando um novo registro é criado.

Por exemplo, se um botão abre um novo formulário de pedido de venda e passa {"default_partner_id": 42} no contexto, o campo do cliente já estará definido para o parceiro com ID 42. O usuário vê um formulário pré-preenchido sem necessidade de lógica Python adicional.

Esse padrão é amplamente utilizado no desenvolvimento Odoo para criar fluxos de navegação inteligentes entre registros.

O Atributo de Contexto em Campos Relacionais

Quando você define um campo Many2one, One2many ou Many2many em Python, pode passar um parâmetro context. Este contexto é aplicado sempre que o campo relacional carrega ou cria registros através do seu popup ou dropdown.

Um exemplo prático: um Many2one apontando para res.partner com context={"default_is_company": True} significa que, se o usuário criar um novo parceiro diretamente a partir desse campo, a caixa de seleção É uma Empresa será pré-selecionada. Você está direcionando o usuário para os dados corretos sem impor isso.

Contexto em Visualizações XML

Na XML de visualização, o atributo context em uma tag de campo funciona da mesma forma, mas pode ser dinâmico. Você pode referenciar outros valores de campo usando a sintaxe de avaliação do Odoo:

Isso permite que você construa formulários inteligentes onde o contexto de um campo depende do valor de outro. É uma técnica fundamental na personalização do odoo para criar comportamentos relacionais inteligentes sem escrever código Python extra.

Lendo e Modificando o Contexto em Python

Dentro de qualquer método de modelo, você pode ler o contexto atual usando self.env.context. Isso lhe dá o dicionário completo como estava quando o método foi chamado.

Para executar código com um contexto modificado, você usa self.with_context(key=value). Isso retorna um novo conjunto de registros que carrega o contexto atualizado sem alterar o original. É um padrão limpo e não destrutivo que se encaixa bem com o estilo de programação funcional do Odoo.

Chaves de Contexto Comuns Incorporadas

O próprio Odoo usa várias chaves de contexto reservadas que acionam comportamentos específicos em todo o framework Odoo:

• lang: Altera o idioma usado para valores de campo traduzidos.
• active_test: Definido como False para incluir registros arquivados nos resultados da pesquisa.
• no_recompute: Impede que campos computados armazenados sejam recalculados.
• mail_notrack: Desativa o rastreamento de conversas para uma operação de escrita.
• allowed_company_ids: Controla a visibilidade de registros em múltiplas empresas.
• bin_size: Retorna tamanhos de arquivo em vez de conteúdo binário para campos Binários.

Conhecer essas chaves internas é parte de qualquer guia de desenvolvedor odoo sólido, pois permite controlar o comportamento sem escrever código personalizado.

Casos de Uso Empresarial

Os campos de contexto não são apenas uma ferramenta para desenvolvedores. Eles resolvem problemas reais de fluxo de trabalho em diferentes áreas de negócios. Aqui estão cinco exemplos de implementações comuns do Odoo.

1. CRM: Pré-preenchendo a Equipe de Vendas em Novos Leads

Um gerente de vendas tem uma visão kanban filtrada para sua equipe. Quando ela clica em "Novo", espera que o lead seja automaticamente atribuído à sua equipe. Ao passar default_team_id no contexto da ação, o campo da equipe é pré-preenchido no momento em que o formulário é aberto. Nenhuma seleção manual necessária, nenhuma atribuição errada de equipe.

2. Vendas: Definindo a Lista de Preços com Base no Segmento do Cliente

Quando um vendedor cria um orçamento a partir de uma visualização de categoria de cliente específica, o campo da lista de preços pode ser pré-definido usando o contexto. O contexto carrega default_pricelist_id com base na categoria, guiando o vendedor para a precificação correta sem restringir suas escolhas.

3. Inventário: Filtrando Localizações em Formulários de Transferência

Em operações de armazém, o campo de localização de origem de um formulário de transferência pode usar o contexto para restringir o dropdown apenas a localizações pertencentes a um armazém específico. Isso é feito passando um domínio via contexto no campo Many2one, mantendo a interface limpa e reduzindo erros em configurações de múltiplos armazéns.

4. Contabilidade: Linhas de Fatura em Várias Línguas

Ao gerar faturas para clientes internacionais, a chave de contexto lang força as descrições traduzidas a aparecer na língua do cliente. Uma fatura enviada a um cliente francês mostrará os nomes e descrições dos produtos em francês, mesmo que a base de dados interna armazene tudo em inglês.

5. Modelos Personalizados: Mostrando Produtos Arquivados em uma Visualização Especial

Uma equipe de operações precisa revisar produtos descontinuados ao lado dos ativos. Uma visualização de lista personalizada passa active_test: False em seu contexto de ação. Sem mudar nenhum código Python, todos os produtos, incluindo os arquivados, aparecem nessa visualização específica, enquanto o restante da interface permanece inalterado.

Criando e Personalizando Contexto em Campos

Existem dois caminhos para adicionar ou modificar contexto em campos no Odoo: usando o Odoo Studio para ajustes sem código, ou escrevendo Python e XML para controle técnico total. Esta é uma parte chave de qualquer tutorial técnico do odoo sobre o comportamento de campos.

Usando o Odoo Studio

O Odoo Studio permite modificar certas propriedades de campo sem escrever código. Para campos relacionais, o Studio expõe uma opção de configuração de contexto onde você pode definir valores padrão que serão aplicados quando um novo registro for criado a partir desse campo.

Isto é útil para casos simples: pré-preencher uma empresa, uma equipe, uma categoria ou um usuário responsável. A limitação é que o suporte a contexto do Studio é intencionalmente simplificado. Para um contexto dinâmico que referencia outros valores de campo, você precisará seguir o caminho técnico.

Ao usar campos do odoo studio, tenha em mente que o contexto que você define é armazenado diretamente na visualização. Se você criar uma personalização técnica na mesma visualização mais tarde, precisará considerar o contexto definido pelo Studio existente para evitar conflitos.

Definindo Contexto em Campos em Python

Em um módulo personalizado, o contexto é adicionado diretamente à definição do campo. Para um campo Many2one, o parâmetro context aceita um dicionário estático:

Este contexto estático é aplicado toda vez que o campo carrega ou cria registros relacionados. Ele não muda com base em outros valores de campo. Para um contexto que reage ao estado do registro atual, você move a lógica para o nível da visualização.

Definindo Contexto em Visualizações XML

Na XML de visualização, o atributo de contexto aceita uma string que o Odoo avalia em tempo de execução. Você pode referenciar valores de campo, o ID do usuário atual (uid), o ID do registro ativo (active_id) e outras variáveis:

Isso torna o contexto a nível de visualização muito mais flexível do que o contexto a nível de campo. É a abordagem padrão no framework odoo para construir formulários onde o comportamento de um campo depende de outro. É também assim que você cria comportamentos de campos odoo que parecem nativos e intuitivos para os usuários finais.

Passando Contexto via Ações de Janela

O contexto também pode ser definido em registros de ir.actions.act_window. É assim que menus e botões passam contexto para as visualizações que abrem. O campo context de uma ação contém o dicionário que é mesclado no contexto da sessão quando a visualização é carregada.

Esta é a maneira mais limpa de lidar com casos de uso como o exemplo da equipe de vendas do CRM acima. O contexto vive na ação, não na definição do campo, o que significa que você pode ter diferentes padrões em diferentes contextos de navegação sem tocar no código do modelo.

Melhores Práticas

Trabalhar com contexto no Odoo se torna muito mais suave uma vez que você siga alguns hábitos consistentes. Estes se aplicam quer você esteja construindo um módulo ou fazendo uma rápida personalização do odoo.

• Use contexto para sugestões, não para imposições. Padrões orientados por contexto guiam os usuários sem bloqueá-los. Se você precisar de uma restrição rígida, use um domínio ou um método onchange em vez disso.
• Coloque contexto dinâmico em visualizações, não em definições de campo. O contexto a nível de campo é estático. Se o contexto precisa refletir o estado do registro atual, a XML da visualização é o lugar certo para isso.
• Use with_context() em vez de modificar env.context diretamente. O ambiente do Odoo é projetado para ser imutável dentro de uma chamada. Sempre crie um novo ambiente com with_context() em vez de tentar modificar o existente.
• Seja intencional sobre o que você passa no contexto. As chaves de contexto se acumulam à medida que viajam pela pilha de chamadas. Passar chaves desnecessárias pode levar a comportamentos inesperados em métodos que verificam essas chaves.
• Use contexto para passar flags para lógica condicional. Um padrão comum é passar uma flag booleana como from_wizard: True no contexto, e depois verificá-la em um método compute ou onchange para aplicar um comportamento diferente. Isso evita poluir os campos do modelo com o estado do fluxo de trabalho.
• Documente chaves de contexto personalizadas no seu módulo. As chaves de contexto são invisíveis a menos que você saiba onde procurar. Adicione um comentário ou docstring explicando quaisquer chaves de contexto personalizadas que seu módulo lê ou define. Isso vale a pena quando você ou um colega retorna ao código mais tarde.

Armadilhas Comuns

Bugs relacionados ao contexto podem ser difíceis de diagnosticar porque o contexto é invisível na interface do usuário. Esses são os erros que aparecem com mais frequência em projetos reais.

Tratar default_* como Valores Obrigatórios

Um valor padrão definido via contexto é aplicado apenas quando um registro é criado através de um formulário. Se você criar registros programaticamente via ORM sem passar o contexto relevante, o padrão não será aplicado. Os desenvolvedores às vezes esperam que os padrões de contexto se comportem como parâmetros default em nível Python nos campos. Eles não se comportam assim. Sempre passe o contexto explicitamente ao criar registros em código se esses padrões forem importantes.

Mutando o Dicionário de Contexto Diretamente

O dicionário de contexto é compartilhado em toda a pilha de chamadas. Se você modificar self.env.context diretamente, pode afetar outro código em execução na mesma transação de maneiras inesperadas. O padrão correto é sempre self.with_context(new_key=value), que cria um novo ambiente com uma cópia do contexto mais suas alterações.

Passando Demais no Contexto

Cada chave que você adiciona ao contexto viaja por toda a cadeia de chamadas. Alguns métodos do Odoo verificam chaves de contexto específicas e alteram seu comportamento de acordo. Passar chaves inesperadas pode acionar esses ramos acidentalmente. Mantenha o contexto enxuto e específico para o que a operação imediata precisa.

Esquecendo active_test Ao Pesquisar Registros Arquivados

Por padrão, os métodos search() e search_read() do Odoo filtram registros arquivados (onde active = False). Se seu código precisa trabalhar com registros arquivados, você deve passar explicitamente active_test: False no contexto. Esquecer isso é um erro muito comum em personalizações de gerenciamento de inventário e produtos.

Conflitos de Contexto Entre o Studio e Código Personalizado

Se o Odoo Studio definiu contexto em um campo em uma visualização, e você posteriormente adiciona uma extensão técnica de visualização direcionada ao mesmo campo, ambos os contextos podem entrar em conflito ou um pode substituir o outro dependendo da ordem de mesclagem do XML. Sempre inspecione o contexto existente em um campo antes de adicionar o seu via herança de visualização. Este é um problema particularmente comum ao misturar campos do odoo studio com personalizações baseadas em módulos.

Conclusão

O contexto é um desses mecanismos no Odoo que silenciosamente faz muito trabalho. Uma vez que você entende como ele flui através das definições de campo, atributos de visualização e o ambiente ORM, você ganha um nível muito mais refinado de controle sobre como seu modelo de dados se comporta.

As principais conclusões são diretas. Use as chaves default_* para guiar os usuários em direção a dados corretos sem forçá-los. Coloque o contexto dinâmico nas visualizações em vez de nas definições de campo. Sempre use with_context() em vez de modificar o contexto no local. E mantenha seu contexto enxuto para que não interfira inesperadamente em outras partes do sistema.

Seja você um tutorial de campo do odoo, construindo um módulo personalizado ou solucionando um campo que está se comportando de maneira estranha, entender o contexto sempre fará parte da resposta.

Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo para se adequar aos seus reais fluxos de trabalho. Se você está trabalhando em uma personalização onde o contexto está envolvido e não tem certeza se está certo, ou se apenas quer discutir sua implementação do Odoo, estamos felizes em ajudar.

Entre em contato com nossa equipe através da página de contato e nos informe o que você está construindo. Trabalhamos com empresas de todos os tamanhos para fazer o Odoo funcionar da maneira que deveria.