Introdução
O campo Char é um dos tipos de dado mais presentes no Odoo. Sempre que vê um nome de contacto, um código de produto ou uma referência num pedido de venda, provavelmente está a interagir com um Char sem se aperceber.
Saber como este campo se comporta é útil tanto para quem configura formulários no Odoo Studio, como para programadores a criar módulos ou consultores a desenhar a solução para um cliente.
Apesar da aparente simplicidade, o Char tem atributos e comportamentos que influenciam a qualidade dos dados e a experiência do utilizador. Este guia explica o que armazena, como aparece na interface, como o criar e personalizar, e apresenta exemplos práticos do mundo real.
O que é o campo Char no Odoo
No ORM do Odoo, o Char serve para guardar pequenas cadeias de texto. Em PostgreSQL, isso traduz-se numa coluna do tipo VARCHAR ou TEXT, consoante se define ou não um limite de tamanho.
Para o utilizador, o Char surge como um campo de texto de uma linha em formulários e como uma coluna de texto simples nas listas. É a escolha habitual para nomes, códigos, referências e identificadores curtos.
Exemplo prático na definição de um 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 a etiqueta visível na interface; size limita o número de caracteres se for usado; index cria um índice na base de dados para pesquisas mais rápidas.
No Odoo Studio, o campo equivalente aparece como um campo de Texto (linha única) e recebe automaticamente um prefixo x_studio_. Em código ou via API escolhe-se o nome técnico.
Como funciona este campo
Quando adiciona um Char num módulo, o Odoo cria a coluna na base de dados durante a instalação ou actualização do módulo — não é necessário escrever migrations SQL manualmente.
Sem size definido, o campo fica como TEXT; com size, usa VARCHAR(n). No PostgreSQL isso é mais uma questão de validação de tamanho do que de desempenho absoluto.
Atributos principais do campo
Abaixo estão os atributos mais relevantes do Char no framework Odoo:
- size: Número máximo de caracteres; se omitido não existe limite a nível de base de dados.
- translate: Se True, o valor pode ser traduzido por idioma — útil em implementações multinacionais.
- required: Torna o campo obrigatório na interface e a nível do modelo.
- default: Valor predefinido atribuído quando se cria um registo novo.
- index: Cria um índice na base de dados para acelerar filtros e pesquisas.
- compute: Liga o campo a um método Python que calcula o seu valor dinamicamente.
- store: Usado com compute para decidir se o valor calculado é gravado na base de dados.
- copy: Define se o valor é copiado ao duplicar um registo; por defeito é True.
Como aparece nas vistas
Em formulários, o Char rende um elemento <input type="text">. Em listas aparece como texto simples. Nas pesquisas, suporta operadores do tipo contém, igual e começa por.
É possível aplicar widgets para alterar a apresentação: um widget email transforma o Char numa ligação clicável; um widget url abre o link numa nova aba, por exemplo.
Interacção com o ORM do Odoo
Para o programador, ler e escrever num Char é directo: acede-se ao atributo no objecto record, e o framework trata da validação conforme a definição do campo — não há transformações complexas por trás.
Casos de uso na empresa
O Char aparece em quase todos os processos do Odoo. Seguem cinco exemplos do dia a dia empresarial.
CRM: códigos de cliente
Muitas empresas guardam um identificador interno para cada cliente. Um Char em res.partner permite procurar contas rapidamente e exibir esse código em pedidos e facturas, evitando confusões quando existem nomes semelhantes.
Vendas: referências de encomenda do cliente
As ordens de compra dos clientes trazem um número de referência que deve constar nas facturas e documentos de entrega. O campo client_order_ref em sale.order é um Char que facilita o fluxo dessa informação sem necessidade de comunicações adicionais.
Inventário: referências internas de produto
O campo default_code em product.template é um Char que guarda o código de referência interno usado em armazéns, leitores de código de barras e pedidos de compra. Manter este campo consistente é crítico para a qualidade dos dados no inventário.
Contabilidade: números fiscais e de registo
Números de IVA, identificadores fiscais e números de registo empresarial são normalmente Char em res.partner. Quando bem configurados, aparecem automaticamente em facturas e faturas de fornecedor, poupando muito trabalho manual, sobretudo em operações internacionais.
RH: identificadores e códigos de cartão
Departamentos de RH usam Char para números de empregado, códigos de crachá ou IDs provenientes de sistemas externos de folha de pagamento ou controlo de acessos, facilitando a ligação entre Odoo e outras ferramentas sem integração completa imediata.
Criar ou personalizar um campo Char
Formas de adicionar um campo Char
Existem três vias principais, conforme o ambiente técnico e o método de implementação.
Com Odoo Studio (sem código)
- Odoo Studio permite criar campos sem programação. Passos básicos:
- Abra o Odoo Studio a partir do menu principal.
- Vá ao formulário onde pretende o campo.
- Arraste um campo Texto (linha única) do painel lateral para o formulário.
- Configure a etiqueta, se é obrigatório e, opcionalmente, limite de tamanho nas propriedades do campo.
Guarde e saia do Studio.
O Studio cria o campo com prefixo x_studio_ e actualiza a vista automaticamente, sem necessidade de migrations manuais.
Com Python num módulo personalizado
Para customizações controladas por código (ideais para deploys em vários ambientes), define-se o campo em ficheiros Python do módulo:
Depois de declarar o campo no modelo, deve também ser adicionado à vista XML relevante para aparecer na interface; o Odoo cria a coluna quando o módulo é instalado ou actualizado.
Pela API XML-RPC
Se automatiza configurações ou faz deploys programáticos, pode criar campos via XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_reference',
'field_description': 'Custom Reference',
'model_id': model_id,
'ttype': 'char',
'size': 64,
'state': 'manual',
}]
)
Definir state como manual indica que o campo foi criado fora de um módulo, o que é apropriado para campos gerados por Studio ou por scripts de configuração remota.
Boas práticas
1. Defina size quando existir um comprimento conhecido
Se o campo guarda códigos ISO, números de telefone ou identificadores de comprimento fixo, defina size. Isso evita que alguém coloque strings demasiado longas e documenta a intenção no modelo.
2. Crie índice para campos pesquisados com frequência
Se os utilizadores filtram regularmente por esse campo (ex.: código do cliente), ative index=True. Em tabelas grandes, um índice pode reduzir pesquisas de dez segundos para um segundo.
3. Use translate=True para conteúdo multilíngue
Quando utilizadores em várias línguas devem ver valores diferentes (nomes de produto, cargos), ative a tradução para que cada idioma apresente o texto adequado.
4. Dê nomes técnicos claros e consistentes
Nomes como x_customer_erp_id são muito mais fáceis de manter do que x_field1. No Studio, renomeie o campo antes de o usar em produção, porque mudar o nome técnico depois é complicado.
5. Use compute para referências derivadas
Char pode ser calculado — por exemplo, concatenar ano e sequência. Com store=True grava-se esse valor na base de dados, permitindo pesquisar e gerar relatórios sem recalcular a cada leitura.
Erros comuns
Perigo de não definir um limite de tamanho
Sem size, utilizadores podem colar parágrafos inteiros num campo de referência — um problema quando esse valor é exibido em documentos impressos ou enviado para sistemas externos com limites rígidos.
Falta de índices em campos muito pesquisados
Sem índice, filtros em tabelas grandes provocam varreduras completas. Muitas equipas só notam o problema quando a base de dados cresce. Se o campo é usado em filtros, acrescente o índice desde o início.
Confundir Char com Text
Char serve para texto curto de uma linha; Text para conteúdo longo e multilinha. Usar Char para endereços ou descrições resulta numa experiência pobre, porque não permite quebras de linha nem formatação adequada.
Esquecer translate em campos multilingues
Em empresas multinacionais, não activar translate em campos visíveis aos clientes faz com que todos vejam o mesmo texto, o que pode causar erros em documentos enviados em diferentes idiomas.
Usar Char quando devia ser Selection ou relação
Se o campo só pode assumir valores de um conjunto fixo (categorias, estados, país), use Selection ou Many2one. Campos de texto livres fomentam erros tipográficos e dados inconsistentes que dificultam relatórios e agrupamentos.
Perguntas frequentes
Qual a diferença entre Char e Text no Odoo?
Char guarda texto curto em linha única e rendereiza como input; Text guarda texto longo e aparece como textarea redimensionável. Use Char para nomes e códigos; Text para descrições e notas.
Posso limitar o número de caracteres num Char?
Sim — defina size ao declarar o campo (por exemplo fields.Char(size=64)). No Studio, configure essa opção nas propriedades. Se não for definido, não existe limite imposto pela base de dados.
Como faço para o Char aparecer na barra de pesquisa?
Adicione-o à vista <search> do modelo. No Studio, ative a opção de pesquisa nas propriedades do campo. Em XML, inclua <field name="your_char_field"/> dentro da vista de pesquisa para permitir filtros directos.
Posso guardar números num Char?
Tecnicamente sim, mas não é recomendado para cálculos ou comparações numéricas. Use Integer ou Float para quantidades. Char é adequado para valores que são códigos numéricos tratados como texto — códigos postais, telemóveis, IBAN, números de série.
Como criar um Char calculado e armazená-lo?
Declare o campo com compute='_compute_my_field' e store=True. Implemente o método de cálculo com @api.depends() para indicar os gatilhos da recomputação. Com store=True, o valor é guardado e pode ser usado em pesquisas e relatórios.
Conclusão
O Char é simples na aparência, mas omnipresente. Entender as suas características e quando optar por outros tipos de campo melhora muito a robustez do modelo de dados.
Quer esteja a adicionar um campo pelo Studio, a definir um campo num módulo Python ou a criar campos via API, as pautas deste guia ajudam a acertar desde a primeira implementação.
Um modelo de dados bem pensado, com tipos de campo adequados, é uma base essencial para um projecto Odoo bem-sucedido. O Char é uma peça pequena desse puzzle, mas merece atenção.
Na Dasolo apoiamos empresas a implementar, personalizar e optimizar o Odoo em todos os departamentos. Se precisa de ajuda para desenhar um modelo limpo, adicionar campos às suas rotinas ou desenvolver um módulo completo, estamos disponíveis. Contacte-nos e converse connosco sobre o seu projecto Odoo.