Se já trabalhou com o ORM do Odoo ou mexeu em vistas, é provável que tenha topado com o termo contexto. Surge em definições de campos, atributos XML de vistas e no código Python do Odoo. Para muitos consultores e programadores é algo que funciona silenciosamente até que, num dado momento, causa comportamentos inesperados.
Compreender os campos de contexto no Odoo não é teoria: tem impacto direto no comportamento do seu modelo de dados, em como formulários chegam pré-preenchidos, em que registos aparecem nas pesquisas e em como campos calculados determinam o seu valor. Desde uma pequena customização Odoo até ao desenvolvimento de um módulo completo, dominar o contexto poupa imenso tempo de depuração.
Este guia explica o que é o contexto, como ele percorre o framework Odoo e como aplicá-lo com segurança em projetos reais.
O que significa Contexto no Odoo
No Odoo, o contexto é basicamente um dicionário Python que acompanha cada pedido, chamada de método e operação sobre registos. Não é um tipo de campo convencional — não existe fields.Context() no ORM do Odoo. Em vez disso, é um mecanismo que altera o comportamento dos campos e operações.
Pense nele como um conjunto de instruções invisíveis que seguem com os dados: instruções para pré-preencher valores, incluir registos arquivados, usar outra língua para traduções, ou aplicar um domínio específico ao selecionar registos relacionados.
Onde o Contexto Surge
Encontrará contexto sobretudo em três pontos do modelo de dados do Odoo:
- Nas definições de campo em Python: o parâmetro
contextem campos relacionais como Many2one, One2many e Many2many. - Em atributos de vista XML: o atributo
contextnas etiquetas<field>em formulários, listas e kanban. - No ambiente do ORM: acedido através de
self.env.contextem Python e alterável comself.with_context(key=value).
Em todos estes locais, o propósito é o mesmo: transportar informação adicional que define como um campo ou registo se comporta em tempo de execução.
Como o Contexto Funciona no Modelo de Dados do Odoo
O contexto acompanha o ciclo de vida de uma interação — desde abrir um formulário até gravar um registo. A seguir ficam os mecanismos principais em ação.
Valores Padrão com default_*
Um padrão de contexto muito usado é a chave que começa por default_. Sempre que esse par é passado, o Odoo utiliza-o para pré-preencher um campo ao criar um registo novo.
Por exemplo, se um botão abre um formulário de encomenda e passa {"default_partner_id": 42} no contexto, o campo cliente aparece já preenchido com o parceiro cujo ID é 42. O utilizador vê o formulário pronto para avançar, sem código Python extra.
Este padrão é amplamente aproveitado no desenvolvimento Odoo para criar fluxos de navegação mais ágeis entre registos.
O Atributo context em Campos Relacionais
Ao declarar um Many2one, One2many ou Many2many em Python, pode fornecer um parâmetro context. Esse contexto aplica-se sempre que o campo relaciona-se com registos via pop-up ou dropdown.
Exemplo prático: um Many2one para res.partner com context={"default_is_company": True} fará com que, ao criar um parceiro a partir desse campo, a opção "É uma empresa" venha marcada por defeito. É uma forma de orientar o utilizador sem impor regras rígidas.
Contexto em Vistas XML
No XML de vistas, o atributo context numa tag de campo funciona de forma semelhante, mas pode ser dinâmico. É possível referenciar valores de outros campos usando a sintaxe de avaliação do Odoo:
Isso permite criar formulários inteligentes onde o contexto de um campo depende de outro. É uma técnica central nas customizações Odoo para comportamentos relacionais sem recorrer a código Python adicional.
Ler e Modificar o Contexto em Python
Em qualquer método de modelo, pode aceder ao contexto atual com self.env.context. Recebe o dicionário tal como estava quando o método foi chamado.
Para executar código com contexto alterado, utilize self.with_context(key=value). Isso devolve um novo recordset que traz o contexto atualizado, sem modificar o original — um padrão não-destrutivo que encaixa bem no estilo funcional do Odoo.
Chaves de Contexto Integradas
O próprio Odoo usa várias chaves de contexto reservadas que desencadeiam comportamentos específicos no framework:
lang: altera a língua usada para campos traduzidos.active_test: defina comoFalsepara incluir registos arquivados nas pesquisas.no_recompute: evita que campos calculados armazenados sejam recalculados.mail_notrack: desliga o tracking do chatter numa operação de escrita.allowed_company_ids: controla a visibilidade em ambientes multiempresa.bin_size: devolve tamanhos de ficheiro em vez do conteúdo binário para campos Binary.
Conhecer estas chaves nativas faz parte de qualquer bom guia para desenvolvedores Odoo, pois permite controlar comportamentos sem código extra.
Cenários de Negócio
Os campos de contexto resolvem problemas reais de fluxo de trabalho em várias áreas. A seguir apresentam-se cinco exemplos típicos em implementações Odoo.
1. CRM: Pré-preencher a Equipa de Vendas em Novas Leads
Quando um gestor de vendas trabalha numa vista kanban filtrada pela sua equipa e cria uma nova lead, espera que esta já venha atribuída à equipa. Ao passar default_team_id no contexto da ação, o campo da equipa aparece preenchido ao abrir o formulário, evitando atribuições incorretas.
2. Vendas: Definir a Tabela de Preços segundo o Segmento do Cliente
Ao criar um orçamento a partir de uma vista filtrada por categoria de clientes, pode passar default_pricelist_id no contexto. Assim, o representante vê a tabela de preços apropriada sem ser impedido de alterá-la.
3. Inventário: Filtrar Localizações em Formulários de Transferência
Nas operações de armazém, o campo de localização de origem num formulário de transferência pode usar contexto para limitar o dropdown às localizações de um armazém específico. Faz-se passar um domínio via contexto no campo Many2one, simplificando a interface e reduzindo erros em setups multi-armazém.
4. Contabilidade: Linhas de Fatura em Vários Idiomas
Para clientes internacionais, a chave lang no contexto força as descrições traduzidas a aparecerem na língua do cliente. Uma fatura enviada para França mostrará nomes e descrições em francês, mesmo que o repositório tenha os dados originais noutra língua.
5. Modelos Personalizados: Mostrar Produtos Arquivados numa Vista Especial
Uma equipa de operações pode precisar rever produtos descontinuados ao lado dos ativos. Uma vista de lista personalizada passa active_test: False na ação, mostrando todos os produtos nessa vista concreta, sem alterar o comportamento global da aplicação.
Criar e Personalizar Contexto em Campos
Existem duas formas de adicionar ou alterar contexto em campos: usar o Odoo Studio para ajustes sem código ou recorrer a Python e XML para controlo total. Isto é um ponto essencial em qualquer tutorial técnico Odoo sobre comportamento de campos.
Usar o Odoo Studio
O Odoo Studio deixa alterar algumas propriedades de campo sem programar. Para campos relacionais, o Studio expõe uma opção de configuração de contexto onde pode definir valores por defeito aplicáveis quando um registo é criado a partir desse campo.
Isto é ideal para casos simples: pré-preencher empresa, equipa, categoria ou um utilizador responsável. A limitação é que o suporte do Studio ao contexto é intencionalmente simplificado; para contexto dinâmico que referencia outros campos, é preciso ir pela via técnica.
Ao usar campos do Odoo Studio, lembre-se que o contexto definido fica gravado na vista. Se depois criar uma customização técnica na mesma vista, tenha em atenção o contexto definido pelo Studio para evitar conflitos.
Definir Contexto em Campos via Python
Num módulo personalizado, adiciona-se contexto diretamente na definição do campo. Para um Many2one, o parâmetro context aceita um dicionário estático:
Esse contexto estático aplica-se sempre que o campo carrega ou cria os registos relacionados. Não muda com base nos valores do registo atual — para comportamento reativo use a vista.
Definir Contexto em Vistas XML
No XML de vistas, o atributo context aceita uma string que o Odoo avalia em runtime. Pode referenciar valores de campos, o ID do utilizador atual (uid), o ID do registo ativo (active_id) e outras variáveis:
Isto torna o contexto ao nível da vista muito mais flexível do que o contexto declarado no campo. É a abordagem padrão no framework Odoo para formularios onde um campo depende de outro, e é a forma de criar comportamentos de campos no Odoo que parecem naturais para o utilizador final.
Passar Contexto através de Ações de Janela
O contexto também pode ser definido em registos ir.actions.act_window. É assim que menus e botões passam contexto para as vistas que abrem: o campo context da ação é o dicionário que se funde com o contexto de sessão quando a vista carrega.
Esta é a forma mais limpa de tratar casos como o exemplo da equipa de CRM: o contexto vive na ação, não na definição do campo, permitindo ter defaults diferentes según o percurso de navegação sem tocar no código do modelo.
Boas Práticas
Trabalhar com contexto torna-se mais previsível se adotar alguns hábitos consistentes, válidos quer para um módulo quer para uma rápida customização Odoo.
- Use contexto para sugerir, não para impor. Defaults via contexto orientam os utilizadores sem os bloquear. Se precisa de uma restrição rígida, use um domínio ou um método onchange.
- Coloque contexto dinâmico nas vistas, não nas definições de campo. O contexto em campo é estático; quando precisa de reagir ao estado do registo, a vista XML é o local adequado.
- Prefira with_context() em vez de mutar env.context diretamente. O ambiente do Odoo é pensado como imutável durante a chamada. Crie sempre um novo ambiente com
with_context()em vez de tentar alterar o contexto existente. - Seja intencional sobre o que passa no contexto. As chaves de contexto acumulam-se ao longo da cadeia de chamadas. Incluir elementos desnecessários pode provocar comportamentos inesperados noutros métodos que verificam essas chaves.
- Use contexto para sinalizadores de lógica condicional. Um padrão comum é passar uma flag booleana como
from_wizard: Trueno contexto e testá-la em computes ou onchanges para aplicar comportamentos distintos — assim evita encher o modelo com campos de estado temporários. - Documente chaves de contexto personalizadas no seu módulo. As chaves são invisíveis na interface; acrescente comentários ou docstrings a explicar quaisquer chaves customizadas que o seu módulo leia ou defina. Isso facilita a manutenção futura.
Erros Comuns
Bugs relacionados com contexto podem ser difíceis de encontrar porque o contexto é invisível na UI. Estes são os erros que aparecem com mais frequência em projetos reais.
Tratar default_* como Valores Obrigatórios
Um default definido via contexto aplica-se apenas quando o registo é criado através de um formulário. Se criar registos programaticamente sem passar o contexto apropriado, o default não será aplicado. Alguns desenvolvedores confundem isto com o parâmetro Python default do campo; não é o mesmo. Ao criar registos em código, passe explicitamente o contexto se os defaults forem importantes.
Mutar o Dicionário de Contexto Diretamente
O dicionário de contexto circula por toda a pilha de chamadas. Se modificar self.env.context diretamente, poderá influenciar código que corre na mesma transação de forma inesperada. O padrão correto é usar sempre self.with_context(new_key=value), que cria uma cópia do contexto com as alterações.
Passar Demasiada Informação no Contexto
Cada chave que adicionar via contexto segue pela cadeia inteira de chamadas. Alguns métodos do Odoo verificam por chaves específicas e alteram o seu comportamento. Inserir chaves inesperadas pode ativar essas ramificações sem querer. Mantenha o contexto enxuto e específico.
Esquecer active_test ao Pesquisar Registos Arquivados
Por omissão, os métodos search() e search_read() filtram registos arquivados (onde active = False). Se o seu código precisa de incluir arquivados, tem de passar explicitamente active_test: False no contexto. Esquecer isto é uma causa frequente de erros em customizações de inventário e produtos.
Conflitos de Contexto entre Studio e Código Personalizado
Se o Odoo Studio definiu contexto numa vista e mais tarde adicionar uma extensão técnica à mesma vista, ambos os contextos podem conflitar ou um pode sobrescrever o outro dependendo da ordem de merge do XML. Revise sempre o contexto existente antes de adicionar o seu via herança de vista — isto é especialmente comum quando se mistura campos do Odoo Studio com customizações em módulo.
Resumo
O contexto é um desses mecanismos do Odoo que trabalha nos bastidores. Compreendendo como ele percorre definições de campo, atributos de vista e o ambiente do ORM, ganha-se um controlo muito mais refinado sobre o comportamento do modelo de dados.
As conclusões principais são diretas: use chaves default_* para orientar os utilizadores sem os obrigar; coloque contexto dinâmico nas vistas, não nos campos; utilize sempre with_context() em vez de alterar o contexto in-place; e mantenha o contexto enxuto para evitar interferências indesejadas.
Quer esteja a seguir um tutorial sobre campos no Odoo, a desenvolver um módulo personalizado ou a investigar um campo que se comporta de forma estranha, entender o contexto fará sempre parte da solução.
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo para os fluxos de trabalho reais. Se está a trabalhar numa customização que envolve contexto e tem dúvidas, ou simplesmente quer discutir a sua implementação Odoo, podemos ajudar.
Contacte a nossa equipa através da página de contacto e conte-nos o que pretende construir. Trabalhamos com empresas de várias dimensões para que o Odoo funcione como deve ser.