Introdução
Sempre que alguém define a prioridade de um lead, escolhe um método de pagamento ou alterna o estado de um produto entre ativo e arquivado no Odoo, há grandes hipóteses de estar a interagir com um campo do tipo Selection. Trata‑se de um dos tipos de campo mais utilizados porque permite controlar escolhas e manter a coerência dos dados desde o início.
Ao contrário de um campo de texto livre, onde cada pessoa pode escrever algo diferente, o campo Selection limita as respostas a um conjunto pré‑definido de opções. Essa restrição evita discrepâncias, facilita filtros e relatórios e reduz os erros silenciosos — como variações ortográficas — que estragam análises e painéis com o tempo.
Este guia explica o que o campo guarda e como aparece na interface, e mostra como criá‑lo e adaptá‑lo com Odoo Studio, módulos Python ou via API XML‑RPC. Inclui também exemplos práticos extraídos de fluxos de trabalho reais e uma lista de armadilhas comuns a evitar.
O que é o campo Selection no Odoo
No ORM do Odoo, um campo Selection guarda uma cadeia de texto que corresponde a uma opção fixa. Cada opção é definida por uma dupla (chave, rótulo): a chave é o valor que vai para a base de dados e o rótulo é o texto exibido ao utilizador.
Por exemplo, um campo de prioridade pode ter várias opções predefinidas para representar níveis distintos de atenção.
priority = fields.Selection([
('0', 'Normal'),
('1', 'Low'),
('2', 'High'),
('3', 'Very High'),
], string='Priority', default='0')Neste exemplo, as entradas '0', '1', '2' e '3' são as chaves que ficam guardadas na base de dados. Os rótulos Normal, Low, High e Very High são o que o utilizador vê. Essa distinção é crucial: permite alterar a apresentação sem corromper os dados existentes.
Na interface, um campo Selection aparece como uma lista pendente (dropdown) nos formulários; nas vistas de lista mostra o rótulo legível. Se aplicar o widget badge, cada opção surge como uma etiqueta colorida — muito útil para identificar rapidamente estados em listas densas.
No Odoo Studio, este tipo de campo chama‑se Selection. Os campos criados por Studio recebem automaticamente o prefixo x_studio_. Se o campo for adicionado por código ou via API, escolha você o nome técnico.
Como funciona este campo
No modelo de dados do Odoo, Selection são colunas PostgreSQL do tipo VARCHAR. O que é guardado na base de dados é só a chave, nunca o rótulo. Por isso, quando faz filtros (domains) ou ações no servidor, tem de usar a chave e não o texto visível.
Por exemplo, para procurar todos os leads de alta prioridade o domain correto seria [('priority', '=', '2')], não [('priority', '=', 'High')].
Atributos principais do campo
A seguir estão as propriedades mais relevantes de um campo Selection no Odoo:
- selection: A lista de tuplos
(chave, rótulo)que define as opções disponíveis. Pode também ser uma string com o nome de um método que retorna a lista dinamicamente. - default: A chave que será atribuída quando nenhum valor tiver sido definido. Se não houver default, o campo começa vazio.
- required: Obriga o utilizador a escolher uma opção antes de gravar. Em conjunto com um default, é um padrão comum para campos de estado.
- selection_add: Usado ao herdar um módulo para acrescentar opções a um campo Selection existente sem reescrever toda a lista. É a forma correta de estender um campo nativo.
- ondelete: Trabalha em conjunto com
selection_addpara definir o que acontece às linhas que usam uma opção quando o módulo que a adicionou é desinstalado.
Listas estáticas vs dinâmicas
Normalmente as opções são declaradas estaticamente, mas pode indicar o nome de um método na propriedade selection. O Odoo chama esse método em tempo de execução e constrói a lista, permitindo variar as opções consoante o utilizador, a empresa ou qualquer contexto.
contract_type = fields.Selection(
selection='_get_contract_types',
string='Contract Type'
)
def _get_contract_types(self):
if self.env.user.has_group('hr.group_hr_manager'):
return [('permanent', 'Permanent'), ('fixed', 'Fixed Term'), ('interim', 'Interim')]
return [('permanent', 'Permanent'), ('fixed', 'Fixed Term')]Como aparece nas vistas
Num formulário, o Selection mostra‑se como um dropdown tradicional. Pode também usar widget="badge" para apresentar um rótulo colorido em listas e kanban; ou widget="radio" para opções apresentadas como botões rádio inline, adequado quando há poucas escolhas e quer‑se visibilidade imediata.
Interação com o ORM do Odoo
Ler e escrever valores é simples: grava‑se a chave e o Odoo trata da exibição. Ao ler um registo via API XML‑RPC com fields_get, o atributo selection contém a lista completa de pares [key, label], útil para apresentar opções em ferramentas externas.
Casos práticos nas empresas
O campo Selection está presente na maior parte dos módulos padrão do Odoo. Abaixo seguem cinco exemplos práticos retirados de fluxos empresariais comuns.
CRM: prioridade do lead e tipo de fase no pipeline
No CRM, a prioridade do lead é um Selection com níveis que ajudam a equipa de vendas a focar esforços. Esse campo alimenta a coloração dos cartões no Kanban e pode activar ações automáticas quando um lead é escalado. Ajustar a distribuição de prioridades é muitas vezes uma das primeiras melhorias de qualidade de dados depois do arranque do projecto.
Vendas: condição de pagamento e política de faturação
O campo invoice_policy nos produtos determina se a faturação se baseia em quantidades encomendadas ou entregues — uma decisão que altera todo o fluxo de cobrança do produto. Do mesmo modo, contratos de subscrição usam Selection para definir ciclos pré‑pago ou pós‑pago, mostrando como este tipo de campo pode ter impacto directo em processos financeiros.
Inventário: estados de qualidade de produto e lote
Em produção e controlo de qualidade, Selections são usados para acompanhar estados de lotes, números de série ou ordens de reparação. Um campo de estado de reparação, por exemplo, pode evoluir por draft, confirmed, under repair, ready e done — e cada transição pode disparar emails, movimentos de stock ou lançamentos contabilísticos.
Contabilidade: método de pagamento e tipo de diário
O tipo de diário na contabilidade é um Selection que diferencia diários de vendas, compras, caixa e banco. Esse valor define regras de lançamento, contas disponíveis e restrições operacionais — um exemplo claro de Selection que governa lógica de negócio, não só a rotulagem.
Recursos Humanos: tipo de contrato e estado do contrato
Equipas de RH usam Selection para registar tipos de emprego, estados de contrato e estágios de pedidos de ausência. O estado do contrato, por exemplo, pode mover‑se de novo para aberto, expirado ou cancelado, e essas mudanças podem activar notificações, checklists de onboarding ou ajustes nas regras de folha.
Criar ou personalizar um campo Selection
Existem três formas principais de acrescentar um campo Selection a um modelo Odoo, consoante precise de controlo de versão ou automatização.
Usar Odoo Studio (sem código)
O Odoo Studio é a ferramenta low‑code integrada para adicionar campos sem escrever Python. Para criar um Selection em Studio:
- Abra o Odoo Studio a partir do menu principal.
- Navegue até ao formulário onde pretende inserir o campo.
- Arraste um campo Selection da barra lateral para o formulário.
- Adicione as opções no painel de propriedades, indicando um rótulo por escolha.
- Opcionalmente defina um valor por omissão e marque como obrigatório.
- Grave e feche o Studio.
O Studio gera chaves automaticamente e guarda os rótulos que inseriu. O campo recebe o prefixo x_studio_ e é acrescentado à vista. É a forma mais rápida de prototipar um campo durante uma sessão com um cliente.
Usar Python num módulo personalizado
Para quem desenvolve módulos Odoo, Selections são definidos em ficheiros Python — o método recomendado para personalizações que devem ser versionadas e implantadas em vários ambientes:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_delivery_slot = fields.Selection([
('morning', 'Morning (8h - 12h)'),
('afternoon', 'Afternoon (13h - 17h)'),
('evening', 'Evening (18h - 20h)'),
], string='Delivery Slot', default='morning')Depois de definir o campo em Python, acrescente‑o ao ficheiro XML da vista correspondente para que fique visível na interface. O Odoo cria a coluna na base de dados ao instalar ou atualizar o módulo.
Quando estende um campo nativo para adicionar opções, utilize selection_add em vez de reescrever o campo inteiro:
class SaleOrder(models.Model):
_inherit = 'sale.order'
state = fields.Selection(
selection_add=[('custom_approval', 'Pending Approval')],
ondelete={'custom_approval': 'set default'}
)Usar a API XML‑RPC
Se gere personalizações de forma programática — por exemplo num pipeline de deploy ou num script remoto — pode criar Selections através da API XML‑RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_contract_category',
'field_description': 'Contract Category',
'model_id': model_id,
'ttype': 'selection',
'selection': "[('standard', 'Standard'), ('premium', 'Premium'), ('custom', 'Custom')]",
'state': 'manual',
}]
)Ao criar um Selection pela API, o parâmetro selection é passado como a representação textual da lista Python. O atributo state: manual indica que o campo foi criado manualmente — adequado para campos gerados por Studio ou por scripts remotos.
Boas práticas
1. Use chaves significativas e estáveis
A chave é o que fica na base de dados e é usada em filtros, automações e lógica server‑side. Opte por chaves descritivas e estáveis que não precise de alterar: strings curtas em minúsculas funcionam bem, como 'draft', 'confirmed' ou 'cancelled'. Evite números salvo quando a ordem tiver significado, porque chaves numéricas tornam o código mais difícil de ler no futuro.
2. Mantenha a lista curta e completa
Se um Selection ultrapassa oito a dez opções, é sinal de que está a tentar representar algo demasiado variável. Nesse caso, considere uma relação Many2one para um modelo de configuração: isso permite aos utilizadores gerir as opções através da interface sem envolver um programador.
3. Sempre defina um default para campos obrigatórios
Se o campo é obrigatório, escolha um valor por omissão sensato. Isso evita erros de validação quando registos são criados programaticamente, por importações ou pela API, onde não há um utilizador a escolher o valor. O default deve refletir o estado mais comum ou menos comprometedor.
4. Use selection_add ao estender campos nativos
Para acrescentar opções a um campo Odoo existente, prefira selection_add em vez de reescrever a definição inteira. É mais seguro e compatível com outros módulos que também possam estender o mesmo campo. Combine sempre com ondelete para gerir a remoção do módulo.
5. Utilize o widget badge para visibilidade em listas
Nas vistas de lista e kanban, o Selection aparece por defeito como texto. Adicionar widget="badge" transforma os valores em etiquetas coloridas, tornando a leitura muito mais rápida — especialmente útil para campos de estado que exigem atenção imediata.
Erros frequentes
Mudar a chave quebra os dados existentes
O rótulo de uma opção pode ser alterado sem problemas, pois apenas a chave é guardada. Já a chave nunca deve ser alterada depois de haver registos que a utilizam: isso fará com que esses registos apresentem um valor inválido e que filtros e automações deixem de funcionar. Se for imprescindível mudar a chave, execute antes um script de migração para atualizar todos os registos.
Remover uma opção deixa registos órfãos
Eliminar uma opção enquanto existirem registos com essa chave faz com que esses registos passem a mostrar um valor em falta. Antes de remover qualquer opção, pesquise os registos afetados e atualize‑os para um valor válido ou archive‑os — é um problema comum em projetos de limpeza de dados.
Usar o rótulo em vez da chave nos filtros
Um erro frequente, sobretudo de utilizadores menos técnicos a criar regras de automação na interface, é filtrar pelo rótulo visível em vez da chave guardada. Isso gera domains que devolvem zero resultados sem erro explícito, tornando o problema difícil de identificar. Confirme sempre a definição do campo para saber qual chave corresponde a cada rótulo antes de escrever filtros.
Usar Selection quando um Many2one é mais adequado
Se as opções mudam com frequência, se os utilizadores precisam de gerir a lista sem um programador, ou se cada opção tem atributos adicionais (cor, sequência, conta associada), então um Many2one para um modelo de configuração é mais apropriado. Selections são ideais para listas estáveis, geridas por desenvolvimento; para cenários dinâmicos, prefira Many2one.
Não tratar o valor vazio na lógica server‑side
Um Selection não obrigatório pode ter o valor False quando nenhuma opção foi escolhida. Se o seu código Python ou ação automatizada compara directamente com uma string sem verificar False, pode ter comportamentos inesperados ou erros. Trate sempre explicitamente o caso vazio em ações server e campos computados dependentes de um Selection.
Conclusão
O campo Selection é um exemplo de elemento aparentemente simples, mas com impacto real quando se conhece o funcionamento interno. Saber distinguir chave e rótulo, quando usar selection_add e quando optar por um Many2one são decisões que definem se a implementação Odoo se mantém saudável ou se cria problemas com o passar do tempo.
Quer esteja a acrescentar um tipo de contrato pelo Studio, a definir um campo de intervalo de entrega num módulo Python, ou a criar um estado de qualidade pela API, os padrões descritos aqui ajudam‑no a escolher a solução correta para cada caso.
No modelo de dados do Odoo, o campo Selection é uma ferramenta central para garantir qualidade desde a origem. Usado corretamente, mantém os registos organizados, os relatórios fiáveis e as automações previsíveis.
Na Dasolo apoiamos empresas na implementação, personalização e otimização do Odoo em todas as áreas. Se precisa de ajuda a desenhar um modelo de dados limpo, a adicionar campos personalizados ou a desenvolver um módulo completo, temos uma equipa pronta a colaborar. Contacte‑nos e falemos sobre o seu projecto Odoo.