Introdução
O campo Char é um dos tipos de campo mais fundamentais no modelo de dados do Odoo. Se você já olhou para um nome de contato, uma referência de produto ou uma nota de pedido de venda, você interagiu com um campo Char sem necessariamente saber disso.
Entender como este tipo de campo funciona é importante, seja você um usuário de negócios configurando formulários no Odoo Studio, um desenvolvedor escrevendo módulos personalizados, ou um consultor ajudando um cliente a projetar seu ambiente Odoo.
Parece simples à primeira vista, mas existem várias propriedades e comportamentos que vale a pena conhecer para usá-lo bem e evitar erros comuns. Este guia abrange tudo, desde o que o campo armazena e como se comporta na interface, até a criação e personalização, juntamente com casos de uso empresarial reais.
O que é o campo Char no Odoo
No Odoo ORM, o campo Char é projetado para armazenar cadeias de texto curtas. Ele mapeia para uma coluna VARCHAR ou TEXT no PostgreSQL, dependendo se você define um limite de tamanho.
Do ponto de vista do usuário, um campo Char aparece como um campo de entrada de texto de uma linha em formulários e como uma coluna de texto simples em visualizações de lista. É a escolha padrão para armazenar nomes, códigos, referências, identificadores e qualquer outro pedaço curto de texto que caiba em uma linha.
Aqui está como ele aparece em uma definição de modelo Python:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
customer_po_reference = fields.Char(
string='Customer PO Reference',
size=64,
index=True,
)O parâmetro string define o rótulo exibido na interface. O parâmetro size, que é opcional, limita o número de caracteres. O parâmetro index cria um índice de banco de dados para buscas mais rápidas.
No Odoo Studio, esse mesmo campo é chamado de campo Texto (linha única). Quando criado através do Studio, ele recebe automaticamente um prefixo x_studio_. Quando criado via código ou pela API XML-RPC, você escolhe o nome técnico você mesmo.
Como o campo funciona
Quando você define um campo Char no Odoo, o framework cuida da criação da coluna no banco de dados automaticamente durante a instalação ou atualização do módulo. Não há necessidade de escrever migrações SQL manualmente.
No banco de dados, campos Char sem um limite de tamanho são armazenados como TEXT. Aqueles com um parâmetro size usam VARCHAR(n). O PostgreSQL trata ambos os tipos de forma eficiente, então a diferença é principalmente sobre a imposição de uma restrição de comprimento em vez de uma distinção de desempenho significativa.
Atributos Chave do Campo
Aqui estão as propriedades mais importantes de um campo Char no framework Odoo:
- size: Número máximo de caracteres. Omitir isso e não há limite de comprimento no nível do banco de dados.
- translate: Quando definido como
True, o valor do campo pode ser traduzido por idioma. Útil em implantações multilíngues. - obrigatório: Torna o campo obrigatório na interface e a nível de modelo.
- padrão: Define um valor padrão automático quando novos registos são criados.
- índice: Cria um índice de base de dados para filtragem e pesquisa mais rápidas nesse campo.
- cálculo: Liga um método Python que calcula o valor do campo dinamicamente, útil para valores derivados ou concatenados.
- armazenar: Quando combinado com
cálculo, controla se o valor calculado é persistido na base de dados. - copiar: Controla se o valor do campo é copiado ao duplicar um registo. Por padrão, é
True.
Como Aparece nas Vistas
Em vistas de formulário, um campo Char é renderizado como um elemento padrão <input type="text">. Em vistas de lista, é exibido como texto simples. Em vistas de pesquisa, suporta filtros usando operadores de contém, igual a e começa com, por padrão.
Você também pode combinar um campo Char com widgets na vista para alterar a sua aparência. Por exemplo, o widget email transforma um campo Char em um link de email clicável, e o widget url faz com que ele abra em uma nova aba do navegador.
Interação com o Odoo ORM
Do ponto de vista do desenvolvedor, ler e escrever campos Char funciona como qualquer outro campo no Odoo ORM. Você acessa o valor diretamente no objeto do registo, e o framework cuida da sanitização e validação com base na definição do campo. Não há transformações complexas envolvidas, o que é parte do que torna o campo Char tão prático para uso diário no desenvolvimento Odoo.
Casos de uso empresarial
O campo Char aparece em quase todos os cantos de uma implementação Odoo. Aqui estão cinco exemplos do mundo real de fluxos de trabalho empresariais comuns.
CRM: Números de Referência de Clientes
Muitas empresas atribuem números de referência internos aos seus clientes. Um campo Char no modelo res.partner pode armazenar este código, tornando-o pesquisável a partir da lista de clientes e visível em pedidos de venda e faturas. As equipas de vendas podem rapidamente acessar a conta correta sem confusão quando múltiplos clientes partilham nomes semelhantes.
Vendas: Referências de Pedidos de Compra
Quando os clientes enviam pedidos de compra, eles incluem um número de PO que precisa aparecer nas faturas e documentos de entrega. O campo nativo client_order_ref no sale.order é um campo Char. Ele flui automaticamente para a fatura, reduzindo a troca de mensagens com o cliente sobre referências em falta.
Inventário: Referências Internas de Produtos
O campo default_code no product.template é um campo Char nativo no Odoo. Ele armazena a referência interna utilizada em armazéns, leitores de código de barras e pedidos de compra. Manter este campo limpo e consistente é uma das prioridades mais comuns de qualidade de dados em implementações de inventário.
Contabilidade: Números de Imposto e Registro
Números de IVA, IDs fiscais e números de registro de empresas são armazenados como campos Char nos registos de parceiros. Esses valores aparecem automaticamente nas faturas de clientes e nas faturas de fornecedores quando configurados corretamente. Para empresas que operam em vários países, ter esses dados armazenados de forma confiável em um só lugar economiza muito trabalho manual de correção.
RH: Identificadores de Funcionários e Códigos de Cracha
As equipas de RH frequentemente precisam armazenar números de identificação de funcionários, códigos de crachá ou identificadores de sistemas externos de folha de pagamento ou controle de acesso. Um campo Char no modelo de funcionário facilita a ligação dos registos do Odoo com outras ferramentas de negócios sem necessidade de uma integração completa desde o primeiro dia.
Criando ou personalizando o campo Char
Existem três maneiras principais de adicionar um campo Char a um modelo Odoo, dependendo da sua configuração técnica e abordagem de implementação.
Usando o Odoo Studio (Sem Código)
Odoo Studio é a ferramenta de personalização de baixo código integrada. Para adicionar um campo Char sem escrever código:
- Abra o Odoo Studio a partir do menu principal.
- Navegue até o formulário onde deseja o campo.
- Arraste um campo Texto (linha única) da barra lateral para o formulário.
- Defina o rótulo, o status de obrigatoriedade e, opcionalmente, um limite de tamanho no painel de propriedades do campo.
- Salve e feche o Studio.
O Studio cria automaticamente o campo com um prefixo x_studio_ e o adiciona à visualização do formulário. Nenhuma migração de banco de dados é necessária da sua parte.
Usando Python em um Módulo Personalizado
Para desenvolvedores que constroem módulos Odoo, os campos Char são definidos em arquivos de modelo Python. Esta é a abordagem recomendada para qualquer personalização que precise ser controlada por versão e implantada em vários ambientes:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_erp_customer_id = fields.Char(
string='ERP Customer ID',
size=32,
index=True,
copy=False,
)Após adicionar o campo ao modelo, você também precisa adicioná-lo ao arquivo XML da visualização relevante para que apareça na interface. O Odoo gerencia a criação da coluna do banco de dados quando você instala ou atualiza o módulo.
Usando a API XML-RPC
Se você está gerenciando personalizações do Odoo programaticamente, por exemplo, como parte de um pipeline de implantação ou um caderno de configuração remota, você pode criar campos Char via a API XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_reference',
'field_description': 'Referência Personalizada',
'model_id': model_id,
'ttype': 'char',
'size': 64,
'state': 'manual',
}]
)O valor state: manual informa ao Odoo que este campo foi criado manualmente (não por um módulo), que é a configuração correta para campos criados através do Studio ou da API. É assim que a Dasolo gerencia a criação remota de campos para clientes como parte de scripts de configuração automatizados.
Melhores práticas
1. Defina um tamanho quando souber o comprimento máximo
Se o campo armazena códigos de países ISO, números de telefone ou identificadores de comprimento fixo, defina um size. Isso comunica a intenção a qualquer um que leia o modelo e previne erros acidentais de entrada de dados. Um campo destinado a armazenar um código de país de duas letras não deve aceitar silenciosamente uma string de 500 caracteres.
2. Adicione um índice para campos que você pesquisa com frequência
Se os usuários filtram ou pesquisam registros regularmente por um campo Char, como um código de cliente ou referência de pedido, defina index=True. Em tabelas com dezenas de milhares de registros, isso pode fazer a diferença entre uma pesquisa de um segundo e uma espera de dez segundos.
3. Use translate=True para conteúdo multilíngue
Se sua instância do Odoo atende usuários em vários idiomas e um campo contém texto que varia por idioma, habilite a tradução. Isso é importante para nomes de produtos, cargos ou qualquer campo cujo valor os usuários em diferentes regiões esperariam ver em seu próprio idioma.
4. Dê nomes técnicos claros e consistentes aos campos
Em módulos personalizados, nomeie os campos de forma descritiva. Um campo chamado x_customer_erp_id é muito mais fácil de manter do que x_field1. Se estiver usando o Studio, renomeie o campo no painel de propriedades antes de implantá-lo. Nomes técnicos não podem ser facilmente alterados depois que os dados são armazenados.
5. Use compute para referências derivadas
Os campos Char podem ser calculados dinamicamente. Por exemplo, uma referência que combina um ano e um número de sequência pode ser construída como um campo Char calculado. Com store=True, o valor é salvo no banco de dados e pode ser usado em filtros de pesquisa e relatórios, enquanto a lógica de cálculo permanece centralizada em um método.
Erros comuns
A ausência de limite de tamanho abre a porta para dados ruins
Sem uma restrição de tamanho, os usuários podem colar parágrafos inteiros em um campo de referência. Este é um problema real quando o valor aparece posteriormente em documentos impressos ou é enviado para sistemas externos com limites de caracteres rigorosos. Sempre defina um tamanho razoável para campos onde o comprimento importa.
Faltando índices em campos frequentemente pesquisados
Sem um índice, filtrar por um campo Char em uma tabela grande é uma varredura completa da tabela. Muitas equipes só descobrem esse problema depois que seu banco de dados cresce para um tamanho significativo. Se um campo é usado regularmente em filtros de visualização de lista ou barras de pesquisa, adicione o índice desde o início.
Confundindo Char com campo de Texto
O campo Char é para texto curto em uma única linha. O campo Texto é para conteúdo mais longo em várias linhas. Usar um campo Char para endereços, notas ou descrições leva a uma experiência de usuário ruim, uma vez que a entrada não será quebrada ou permitirá quebras de linha. Se o conteúdo puder realisticamente abranger várias frases, use um campo Texto em vez disso.
Esquecendo traduzir em campos multilíngues
Em empresas que operam em vários países, não usar a opção translate=True em um campo voltado para o usuário significa que todos os usuários de diferentes idiomas veem o mesmo valor. Isso pode causar confusão em documentos voltados para o cliente, onde o conteúdo do campo deve se adaptar ao idioma do documento.
Usando Char para dados que deveriam ser uma Seleção ou relação
Se um campo sempre contém um dos um conjunto limitado de valores, como uma categoria, um status ou um país, ele deve ser um campo de Seleção ou uma relação Many2one, não um campo Char. Usar Char para isso cria valores inconsistentes entre os registros e torna a filtragem e a elaboração de relatórios não confiáveis. Campos de texto livre convidam erros de digitação e variações que quebram agrupamentos e análises.
Perguntas frequentes
Qual é a diferença entre um campo Char e um campo Texto no Odoo?
Um campo Char armazena texto curto em uma única linha e é renderizado como um campo de texto em formulários. Um campo Text armazena conteúdo mais longo em várias linhas e é renderizado como uma área de texto redimensionável. Use Char para nomes, códigos e referências. Use Text para descrições, notas e qualquer coisa que os usuários possam escrever em várias frases.
Posso limitar o número de caracteres armazenados em um campo Char?
Sim. Use o parâmetro size ao definir o campo em Python, por exemplo fields.Char(size=64). No Odoo Studio, você pode definir esse limite no painel de propriedades do campo. Se nenhum tamanho for definido, o campo não tem limite de comprimento imposto no nível do banco de dados.
Como faço para que um campo Char apareça na barra de pesquisa?
Adicione o campo à visualização de pesquisa do modelo. No Studio, ative a opção de pesquisa nas propriedades do campo. No código, adicione <field name="your_char_field"/> dentro da definição da visualização <search> no seu XML. Uma vez adicionado, os usuários podem filtrar registros por esse campo diretamente da barra de pesquisa.
Posso armazenar números em um campo Char?
Tecnicamente sim, mas não é recomendado para valores que precisam de cálculo ou comparação numérica. Use campos Integer ou Float para quantidades e valores. Char é apropriado para strings que contêm dígitos, como códigos postais, números de telefone, números IBAN ou números de série, onde o valor é tratado como texto em vez de um número.
Como faço para criar um campo Char computado que também armazena seu valor?
Defina o campo com compute='_compute_my_field' e store=True. Escreva o método de computação usando @api.depends() para declarar quais outros campos acionam a recomputação. Com store=True, o Odoo salva o valor computado no banco de dados, tornando-o disponível em pesquisas, filtros e exportações sem recalcular a cada leitura.
Conclusão
O campo Char é enganosamente simples. A maioria das pessoas interage com dezenas deles todos os dias no Odoo sem pensar nisso. Mas quando você está construindo ou personalizando um sistema Odoo, entender suas propriedades, seu comportamento no banco de dados e quando usá-lo em vez de outros tipos de campo faz uma diferença real na qualidade do seu modelo de dados.
Seja adicionando uma referência de cliente através do Odoo Studio, definindo um campo em um módulo Python personalizado ou criando campos programaticamente via API, os padrões descritos neste guia ajudarão você a acertar da primeira vez.
Um modelo de dados bem projetado, construído com os tipos de campo certos, é uma das fundações mais importantes de uma implementação bem-sucedida do Odoo. O campo Char é uma pequena parte desse quebra-cabeça, mas é uma que vale a pena entender corretamente.
Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Quer precise de ajuda para desenhar um modelo de dados limpo, adicionar campos personalizados aos seus fluxos de trabalho ou construir um módulo Odoo completo do zero, a nossa equipa está aqui para ajudar. Entre em contacto connosco e vamos conversar sobre o seu projeto Odoo.