Introdução
Sempre que um usuário escolhe uma prioridade de lead, seleciona um método de pagamento ou marca um produto como ativo ou arquivado no Odoo, é muito provável que esteja interagindo com um campo de Seleção. É um dos tipos de campo mais práticos no framework Odoo e um dos mais importantes de entender se você deseja construir modelos de dados limpos e confiáveis.
Ao contrário de um campo de texto livre onde os usuários podem digitar qualquer coisa, o campo de Seleção restringe a entrada a uma lista pré-definida de opções. Essa restrição é o objetivo principal. Ela mantém seus dados consistentes, torna a filtragem e a geração de relatórios mais precisas e previne erros de digitação e variações que silenciosamente quebram agregações e painéis ao longo do tempo.
Este guia cobre tudo, desde o que o campo armazena e como ele aparece na interface, até a criação e personalização através do Odoo Studio, módulos Python ou a API XML-RPC. Você também encontrará exemplos práticos de fluxos de trabalho empresariais reais e uma lista de erros comuns a evitar.
O que é o Campo de Seleção no Odoo
No ORM do Odoo, o campo de Seleção armazena um valor de string escolhido a partir de uma lista fixa de opções. Cada opção é definida como um par chave-valor: a chave é o que é salvo no banco de dados, e o rótulo é o que o usuário vê na interface.
Por exemplo, um campo de prioridade pode ser definido com as seguintes opções:
priority = fields.Selection([
('0', 'Normal'),
('1', 'Baixo'),
('2', 'Alto'),
('3', 'Muito Alto'),
], string='Prioridade', default='0')Neste exemplo, '0', '1', '2' e '3' são as chaves armazenadas no banco de dados. Os rótulos Normal, Baixo, Alto e Muito Alto são o que os usuários veem na tela. Essa separação é muito importante quando se trata de mudar rótulos mais tarde sem quebrar registros existentes.
Na interface, um campo de Seleção aparece como uma lista suspensa nas visualizações de formulário. Nas visualizações de lista, ele mostra o rótulo legível por humanos. Ao usar o widget badge, cada opção é renderizada como uma etiqueta colorida, o que torna o valor imediatamente visível em visualizações de lista densas.
No Odoo Studio, esse tipo de campo é chamado de campo Seleção. Quando criado através do Studio, ele recebe um prefixo x_studio_. Quando criado via código ou pela API XML-RPC, você escolhe o nome técnico.
Como o Campo Funciona
No modelo de dados do Odoo, os campos de Seleção são armazenados no PostgreSQL como uma coluna VARCHAR. O banco de dados armazena apenas a chave, nunca o rótulo. Isso é importante ter em mente ao escrever filtros de domínio ou ações do servidor, já que você precisa usar a chave, não o valor legível por humanos.
Por exemplo, para buscar todos os leads com alta prioridade, seu domínio seria [('priority', '=', '2')], não [('priority', '=', 'Alto')].
Atributos do Campo Chave
Aqui estão as propriedades mais importantes de um campo de Seleção no framework Odoo:
- selection: A lista de tuplas
(chave, rótulo)definindo as opções disponíveis. Isso também pode ser um nome de método (string) que retorna uma lista dinamicamente. - default: A chave da opção a ser usada quando nenhum valor foi definido ainda. Se omitido, o campo começa vazio.
- required: Força o usuário a escolher uma opção antes de salvar. Combinado com um valor padrão, esse é um padrão comum para campos de status.
- selection_add: Usado na herança de módulos para adicionar novas opções a um campo de Seleção existente sem redefinir toda a lista. Esta é a abordagem correta ao estender um campo nativo.
- ondelete: Funciona em conjunto com
selection_addpara definir o que acontece com os registos que têm uma opção eliminada quando o módulo que a adicionou é desinstalado.
Listas de Seleção Estáticas vs Dinâmicas
Por padrão, a lista de opções é definida estaticamente na declaração do campo. Mas você também pode passar um nome de método como uma string para o parâmetro selection. Odoo chamará esse método em tempo de execução para construir a lista, o que permite mostrar opções diferentes dependendo do usuário atual, da empresa atual ou de qualquer outro contexto.
contract_type = fields.Selection(
selection='_get_contract_types',
string='Tipo de Contrato'
)
def _get_contract_types(self):
if self.env.user.has_group('hr.group_hr_manager'):
return [('permanent', 'Permanente'), ('fixed', 'Prazo Determinado'), ('interim', 'Interino')]
return [('permanent', 'Permanente'), ('fixed', 'Prazo Determinado')]Como Aparece nas Vistas
Em uma vista de formulário, um campo de Seleção é renderizado como um dropdown padrão. Você também pode usar o atributo widget="badge" para renderizá-lo como um rótulo colorido, que funciona bem em vistas de lista e kanban para campos de status. O atributo widget="radio" renderiza as opções como botões de rádio em linha, o que é adequado para campos com um pequeno número de escolhas onde você deseja que todas as opções estejam visíveis de uma vez.
Interação com o Odoo ORM
Ler e escrever campos de Seleção no Odoo ORM funciona de forma direta. Você atribui a chave diretamente, e o framework cuida do mapeamento de exibição automaticamente. Ao ler um registo através da API XML-RPC com fields_get, o atributo selection do campo inclui a lista completa de pares [key, label], que você pode usar para construir sua própria lógica de exibição em ferramentas externas.
Casos de Uso Empresarial
O campo de Seleção aparece em praticamente todos os módulos em uma implementação padrão do Odoo. Aqui estão cinco exemplos concretos de fluxos de trabalho empresariais comuns.
CRM: Prioridade de Lead e Tipo de Estágio do Pipeline
O campo de prioridade nos leads de CRM é um campo de Seleção nativo com quatro níveis: Normal, Baixo, Alto e Muito Alto. As equipes de vendas usam isso para concentrar sua atenção nas oportunidades mais promissoras. Ele alimenta diretamente a codificação de cores da vista Kanban e pode ser usado em ações automatizadas para acionar tarefas de acompanhamento quando um lead é escalado. Obter a distribuição de prioridades correta é uma das primeiras melhorias de qualidade de dados que a maioria das equipes de CRM faz após entrar em operação.
Vendas: Política de Prazo de Pagamento e Faturação
O campo invoice_policy nos produtos é um campo de Seleção que controla se a faturação é baseada nas quantidades encomendadas ou nas quantidades entregues. Este único campo determina todo o fluxo de faturação para um produto. Da mesma forma, o modo de faturação nos contratos de subscrição utiliza um campo de Seleção para distinguir entre ciclos de faturação pré-pagos e pós-pagos. Ambos são bons exemplos de campos de Seleção que têm consequências significativas nos fluxos de trabalho financeiros.
Inventário: Estados de Qualidade de Produto e Lote
Em fluxos de trabalho de fabricação e controle de qualidade, os campos de Seleção são usados para rastrear o estado de lotes, números de série e ordens de reparo. O campo de estado da ordem de reparo, por exemplo, passa por valores como rascunho, confirmado, em reparo, pronto e concluído. Cada transição pode acionar e-mails automatizados, movimentos de inventário ou lançamentos contábeis. O campo de Seleção atua como o ponto de controle em torno do qual todo o fluxo de trabalho é construído.
Contabilidade: Método de Pagamento e Tipo de Diário
O campo tipo de diário na Contabilidade Odoo é um campo de Seleção que distingue entre diários de vendas, diários de compras, diários de caixa e diários bancários. O Odoo usa este valor para aplicar a lógica de lançamento correta, determinar quais contas estão disponíveis e restringir certas operações aos tipos de diário corretos. Este é um bom exemplo de um campo de Seleção que controla regras de negócios em vez de apenas rotular um registro.
RH: Tipo de Emprego e Status do Contrato
As equipas de RH usam campos de Seleção para rastrear tipos de emprego, status de contrato e estados de pedidos de licença. O status do contrato, por exemplo, passa de novo para aberto, expirado ou cancelado. As automações podem notificar o gerente de RH um mês antes de um contrato expirar, acionar listas de verificação de integração quando um novo funcionário começa e atualizar regras de folha de pagamento com base no tipo de emprego. O campo de Seleção mantém o estado que impulsiona toda essa lógica.
Criando ou Personalizando o Campo de Seleção
Existem três maneiras principais de adicionar um campo de Seleção a um modelo Odoo, dependendo da sua configuração e se você precisa que a alteração seja controlada por versão ou aplicada programaticamente.
Usando Odoo Studio (Sem Código)
O Odoo Studio é a ferramenta interna de baixo código para adicionar campos sem escrever qualquer Python. Para adicionar um campo de Seleção através do Studio:
- Abra o Odoo Studio a partir do menu principal.
- Navegue até o formulário onde deseja o campo.
- Arraste um campo de Seleção da barra lateral para o formulário.
- Adicione suas opções no painel de propriedades do campo, inserindo um rótulo para cada escolha.
- Opcionalmente, defina um valor padrão e marque o campo como obrigatório.
- Salve e feche o Studio.
O Studio armazena cada opção com uma chave gerada automaticamente e o rótulo que você forneceu. O campo recebe um prefixo x_studio_ e é adicionado à visualização do formulário automaticamente. Esta é a abordagem mais rápida para adicionar um campo de Seleção durante uma sessão de análise de negócios com um cliente.
Usando Python em um Módulo Personalizado
Para desenvolvedores que estão construindo módulos Odoo, os campos de Seleção são definidos em arquivos de modelo Python. Esta é a abordagem recomendada para personalizações que precisam ser controladas por versão e implantadas em vários ambientes:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_delivery_slot = fields.Selection([
('morning', 'Manhã (8h - 12h)'),
('afternoon', 'Tarde (13h - 17h)'),
('evening', 'Noite (18h - 20h)'),
], string='Slot de Entrega', default='morning')Após definir o campo, você o adiciona ao arquivo XML da visualização relevante para que ele apareça na interface. O Odoo cuida da criação da coluna do banco de dados quando você instala ou atualiza o módulo.
Ao estender um campo nativo com novas opções, use selection_add em vez de redefinir o campo:
class SaleOrder(models.Model):
_inherit = 'sale.order'
state = fields.Selection(
selection_add=[('custom_approval', 'Aguardando Aprovação')],
ondelete={'custom_approval': 'set default'}
)Usando a API XML-RPC
Se você estiver gerenciando personalizações do Odoo programaticamente, por exemplo, como parte de um pipeline de implantação ou um caderno de configuração remota, pode criar campos de Seleção 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': 'Categoria do Contrato',
'model_id': model_id,
'ttype': 'selection',
'selection': "[('standard', 'Padrão'), ('premium', 'Premium'), ('custom', 'Personalizado')]",
'state': 'manual',
}]
)Note que ao criar um campo de Seleção através da API, o valor selection é passado como uma representação em string da lista Python. O valor state: manual informa ao Odoo que este campo foi criado manualmente, que é a configuração correta para campos criados através do Studio ou da API. É assim que a Dasolo lida com a criação remota de campos para clientes como parte de scripts de configuração automatizados.
Melhores Práticas
1. Use chaves significativas e estáveis
A chave é o que é armazenado no banco de dados e usado em filtros de domínio, ações automatizadas e lógica do lado do servidor. Escolha uma chave que descreva claramente a opção e que você não precisará mudar mais tarde. Strings curtas em minúsculas funcionam bem: 'draft', 'confirmed', 'cancelled'. Evite chaves numéricas, a menos que a sequência realmente importe, pois elas tornam seu código mais difícil de ler e entender meses depois.
2. Mantenha a lista curta e exaustiva
Um campo de Seleção com mais de oito ou dez opções geralmente é um sinal de que o campo está tentando fazer demais. Se a lista continuar crescendo, considere se uma relação Many2one com um modelo de configuração seria mais apropriada. Isso dá aos usuários a capacidade de gerenciar as opções por conta própria através da interface, sem exigir que um desenvolvedor atualize o código ou a definição do campo do banco de dados.
3. Sempre defina um padrão para campos obrigatórios
Se um campo de Seleção for obrigatório, também defina um valor padrão sensato. Isso evita erros de validação quando os registros são criados programaticamente, através de importações ou via API, onde o usuário não está presente para fazer uma seleção. O padrão deve representar o estado mais comum ou menos comprometido no fluxo de trabalho.
4. Use selection_add ao estender campos nativos
Se você precisar adicionar opções a um campo Odoo existente em um módulo personalizado, use selection_add em vez de redefinir o campo completo. Isso é mais seguro e mais compatível com outros módulos que também podem estender o mesmo campo. Sempre emparelhe com o parâmetro ondelete para lidar com o que acontece quando seu módulo é desinstalado.
5. Use o widget de badge para visibilidade em visualizações de lista
Em visualizações de lista e kanban, a renderização padrão de um campo de Seleção é apenas texto. Adicionar o widget="badge" no XML da visualização transforma cada valor em um rótulo colorido, tornando o campo muito mais fácil de escanear à primeira vista. Isso é especialmente útil para campos de status onde os usuários precisam identificar rapidamente registros que precisam de atenção.
Erros Comuns
Alterar uma chave quebra dados existentes
O rótulo de uma opção de Seleção pode ser alterado com segurança a qualquer momento, uma vez que apenas a chave é armazenada no banco de dados. No entanto, a chave nunca deve mudar uma vez que registros existam com esse valor. Se você renomear uma chave, todos os registros existentes com a chave antiga exibirão um valor vazio ou inválido na interface, e quaisquer filtros de domínio ou automações que utilizem a chave antiga deixarão de funcionar silenciosamente. Se uma chave realmente precisar ser alterada, você deve executar um script de migração de dados para atualizar todos os registros existentes primeiro.
Remover uma opção deixa registros órfãos
Se você remover uma opção da lista enquanto registros ainda mantêm essa chave, esses registros mostrarão um valor ausente ou quebrado. Antes de remover qualquer opção, procure registros que ainda a utilizem e atualize-os para um valor válido ou arquive-os. Este é um problema comum durante projetos de limpeza de dados quando a lista de opções foi projetada sem uma análise suficiente antecipadamente.
Usando o rótulo em vez da chave em filtros de domínio
Um erro muito comum, especialmente para usuários menos técnicos que escrevem regras de automação na interface do Odoo, é filtrar pelo rótulo legível por humanos em vez da chave armazenada. Isso produz um domínio que retorna zero resultados sem gerar um erro, o que pode ser difícil de diagnosticar. Sempre verifique a definição do campo para confirmar qual chave corresponde a qual rótulo antes de escrever um filtro.
Usando um campo de Seleção onde um Many2one é mais apropriado
Se a lista de opções muda com frequência, se os usuários precisam gerenciá-la sozinhos sem a intervenção de um desenvolvedor, ou se as opções possuem atributos adicionais como uma cor, uma sequência ou uma conta vinculada, então uma relação Many2one com um modelo de configuração é a melhor escolha. Campos de Seleção são ideais para listas estáveis, gerenciadas por desenvolvedores. Para qualquer coisa mais dinâmica, Many2one é mais sustentável a longo prazo.
Não lidar com o valor vazio na lógica do lado do servidor
Um campo de Seleção que não é obrigatório pode ter um valor False quando nenhuma opção foi selecionada. Se seu código Python ou ação automatizada comparar o valor do campo a uma string sem primeiro verificar se é False, você terá comportamentos inesperados ou erros. Sempre trate o caso vazio explicitamente em ações do servidor e campos computados que dependem de um campo de Seleção.
Conclusão
{'segment': 'O campo Selection é um daqueles tipos de campo que parece simples, mas tem uma verdadeira profundidade uma vez que você entende como funciona por trás dos panos. Conhecer a diferença entre uma chave e um rótulo, entender quando usar selection_add em vez de redefinir um campo, e reconhecer quando um Many2one seria mais adequado para você são as distinções que separam uma implementação Odoo bem projetada de uma que causa problemas um ano depois.'}
{'segment': 'Seja você adicionando um tipo de contrato através do Odoo Studio, definindo um campo de slot de entrega em um módulo Python personalizado, ou criando um campo de estado de qualidade através da API, os padrões descritos neste guia fornecem o que você precisa para tomar a decisão certa para o seu caso de uso.'}
{'segment': 'No modelo de dados do Odoo, o campo Selection é uma das principais ferramentas para garantir a qualidade dos dados na origem. Usado corretamente, mantém seus registros limpos, seus relatórios precisos e suas automações confiáveis.'}
{'segment': 'Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Seja você precisando de ajuda para projetar um modelo de dados limpo, adicionar campos personalizados aos seus fluxos de trabalho, ou construir um módulo Odoo completo do zero, nossa equipe está aqui para ajudar.'} {'segment': 'Entre em contato conosco'} {'segment': 'e vamos conversar sobre o seu projeto Odoo.'}