Campo de Texto no Odoo: Guia Completo

Introdução

O campo de Texto é um dos tipos de campo mais práticos no Odoo. Sempre que um usuário preenche uma área de notas, escreve uma descrição de produto ou adiciona um comentário interno em um pedido de venda, há uma boa chance de que esteja digitando em um campo de Texto.

Parece uma área de texto simples na interface, mas entender suas propriedades e como se encaixa no modelo de dados do Odoo e no ORM faz uma grande diferença ao projetar formulários, construir módulos personalizados ou configurar campos do Odoo Studio para sua equipe.

Este guia cobre tudo, desde o que o campo de Texto armazena e como se comporta, até casos de uso empresarial reais, personalização técnica, melhores práticas e os erros que a maioria das pessoas comete ao optar por este tipo de campo.

O que é o Campo de Texto no Odoo

No ORM do Odoo, fields.Text é o tipo de campo para armazenar texto simples em várias linhas. Ele mapeia para uma coluna TEXT no PostgreSQL, sem restrição de comprimento. Os usuários podem escrever uma única frase ou vários parágrafos, e o campo lida com isso igualmente bem.

Em formulários, é renderizado como um elemento <textarea> redimensionável. Em visualizações de lista, aparece como texto simples truncado. Em visualizações de pesquisa, suporta filtragem baseada em texto, assim como o campo Char.

Aqui está como uma definição básica de campo Text se parece em um módulo Python:

from odoo import fields, models

class SaleOrder(models.Model):
    _inherit = 'sale.order'

    internal_notes = fields.Text(
        string='Notas Internas',
        translate=False,
    )

No Odoo Studio, este campo é chamado de Texto de Múltiplas Linhas. Quando criado através do Studio, o Odoo atribui automaticamente um prefixo x_studio_. Quando você o cria através de código ou da API XML-RPC, você define o nome técnico você mesmo.

Como Difere de Char e Html

Três tipos de campos no Odoo podem armazenar conteúdo de texto, e saber quando usar qual é um ponto comum de confusão:

• Campo Char: Entrada de texto de uma linha. Melhor para valores curtos como nomes, códigos e referências. Suporta um limite de tamanho opcional.
• Campo Text: Área de texto de múltiplas linhas. Melhor para notas, descrições e comentários em formato livre. Armazena texto simples sem formatação.
• Campo Html: Editor de texto rico de múltiplas linhas. Melhor para conteúdo onde a formatação é importante, como modelos de e-mail, descrições de produtos na web ou páginas de sites. Armazena marcação HTML.

O campo Text fica entre os dois. Ele oferece aos usuários mais espaço do que um campo Char, mas sem a complexidade da marcação HTML. Para a maioria das notas internas e descrições simples, é a escolha certa no modelo de dados do Odoo.

Como o Campo Funciona

Quando você adiciona um campo Text a um modelo Odoo, o framework cria automaticamente a coluna correspondente TEXT no PostgreSQL durante a instalação ou atualização do módulo. Não há migrações SQL manuais envolvidas.

Ao contrário do campo Char, não há parâmetro size disponível nos campos Text. A coluna do banco de dados não impõe limite de caracteres. Isso é intencional: os campos Text são destinados a conteúdo aberto, onde limitar o comprimento antecipadamente não faria sentido.

Atributos Chave do Campo

As propriedades mais importantes de um campo de Texto no framework Odoo:

• traduzir: Quando definido como True, o valor do campo pode ser traduzido por idioma. Útil para instâncias Odoo multilíngues onde o texto muda dependendo do idioma do usuário.
• obrigatório: Torna o campo obrigatório na interface e no nível ORM. Os usuários não podem salvar um registro sem preenchê-lo.
• padrão: Define um valor padrão automático quando novos registros são criados. Pode ser uma string estática ou um método chamável.
• calcular: Liga um método Python que gera o valor do campo dinamicamente. Útil para resumos gerados automaticamente ou conteúdo derivado.
• armazenar: Quando combinado com calcular, controla se o valor calculado é salvo no banco de dados. Com armazenar=True, o valor é pesquisável e disponível em relatórios.
• copiar: Controla se o valor do campo é incluído ao duplicar um registro. O padrão é True. Defina como False para notas que não devem ser transferidas para duplicatas.
• índice: Não é comumente usado em campos de Texto, uma vez que a indexação de texto completo funciona de forma diferente do índice B-tree simples usado para campos Char. Para conteúdo pesquisável, a pesquisa de texto completo do PostgreSQL ou o filtro embutido do Odoo geralmente são suficientes.

Como Aparece nas Vistas

Nas vistas de formulário, o campo de Texto é renderizado como um <textarea> que os usuários podem redimensionar verticalmente. Nas vistas de lista, o conteúdo é truncado para caber na largura da coluna. Nas vistas de pesquisa, suporta filtros de pesquisa baseados em texto por padrão, uma vez que você o adiciona à definição da vista de pesquisa.

Ao contrário dos campos Html, o campo de Texto não carrega um editor WYSIWYG. Os usuários veem uma área de texto simples sem barra de ferramentas de formatação. O que eles digitam é exatamente o que é armazenado no banco de dados, com quebras de linha preservadas.

Interação com o Odoo ORM

Do ponto de vista de um desenvolvedor, ler e escrever campos de Texto no desenvolvimento do Odoo é simples. Você acessa o valor diretamente no objeto do registro, e o ORM cuida de toda a persistência. Quebras de linha são armazenadas como estão. Não há sanitização ou escape automático aplicados a campos de Texto simples, que é uma das razões pelas quais é distinto do campo Html, onde o Odoo aplica sanitização para prevenir problemas de XSS.

Casos de Uso Empresariais

Os campos de Texto aparecem em todo o Odoo em lugares onde os usuários precisam escrever mais de uma única linha. Aqui estão cinco exemplos concretos de fluxos de trabalho empresariais reais.

Vendas: Notas Internas do Pedido

O campo note nos pedidos de venda e o campo internal_note usado em algumas implementações são campos de Texto. Os representantes de vendas os utilizam para registrar instruções de entrega, requisitos especiais de embalagem ou preferências do cliente que não se encaixam perfeitamente em um campo estruturado. Essas notas acompanham o pedido e são visíveis para as equipes de operações sem serem impressas nos documentos do cliente.

Inventário: Notas Internas do Produto

No formulário do produto, o Odoo fornece uma aba Notas com um campo de Texto para comentários internos. As equipes de armazém usam isso para documentar instruções de manuseio, avisos de fragilidade ou informações específicas do fornecedor. Como é texto simples e não é exibido no site ou nos documentos do cliente, é seguro escrever detalhes operacionais que partes externas não devem ver.

Compras: Termos do Fornecedor e Instruções de Entrega

Nos pedidos de compra, um campo de Texto para notas do fornecedor permite que as equipes de compras documentem acordos específicos ou restrições de entrega que foram confirmadas por e-mail ou telefone. Ter essas informações anexadas ao registro do pedido evita mal-entendidos quando os produtos chegam e a conversa original não é mais fácil de encontrar.

CRM: Resumos de Oportunidades e Notas de Reuniões

As equipes de vendas que trabalham através do pipeline do CRM frequentemente adicionam um campo de Texto aos registros de oportunidades para notas livres de reuniões com clientes, objeções levantadas ou contexto sobre o processo de compra. Ao contrário das mensagens de bate-papo, um campo de Texto dedicado mantém essas informações estruturadas e fáceis de ler à primeira vista quando outra pessoa assume a liderança.

RH: Comentários de Funcionários e Candidatos

As equipas de RH frequentemente precisam capturar notas de entrevistas, comentários sobre integração ou observações de desempenho em um campo que permaneça anexado ao registro do funcionário ou candidato. Um campo de Texto no modelo de funcionário é uma maneira limpa e simples de armazenar isso sem criar um modelo separado. É pesquisável, imprimível e fácil de incluir em relatórios personalizados de RH.

Criando ou Personalizando o Campo de Texto

Existem três maneiras principais de adicionar um campo de Texto a um modelo Odoo, dependendo do seu contexto técnico e abordagem de implantação.

Usando Odoo Studio (Sem Código)

O Odoo Studio é a rota mais fácil para usuários de negócios e consultores que não querem escrever código. Para adicionar um campo de Texto sem trabalho de desenvolvimento:

1. Abra o Odoo Studio a partir do menu principal (requer o aplicativo Studio).
2. Navegue até o formulário onde você deseja o campo.
3. Arraste um campo Texto de Múltiplas Linhas da barra lateral do Studio para o formulário.
4. Defina o rótulo, o status de obrigatoriedade e qualquer valor padrão no painel de propriedades do campo.
5. Salve e feche o Studio.

O Studio cuida da criação do campo e da atualização da visualização automaticamente. O campo recebe um prefixo x_studio_ e está imediatamente disponível no formulário sem qualquer migração de banco de dados ou reinício do servidor.

Usando Python em um Módulo Personalizado

Para qualquer personalização que precise ser controlada por versão e implantada em vários ambientes, definir o campo em Python é a abordagem correta. Esta é a prática padrão de desenvolvimento do Odoo:

from odoo import fields, models

class ResPartner(models.Model):
    _inherit = 'res.partner'

    x_client_notes = fields.Text(
        string='Notas do Cliente',
        translate=False,
        copy=False,
    )

Após definir o campo no arquivo do modelo, você precisa adicioná-lo à visualização XML relevante para que apareça na interface. O Odoo cria a coluna do banco de dados automaticamente quando você instala ou atualiza o módulo. Esta é a abordagem recomendada para qualquer personalização do Odoo em produção que precise ser mantida ao longo do tempo.

Usando a API XML-RPC

Se você estiver gerenciando campos do Odoo programaticamente, por exemplo, como parte de um script de implantação ou um caderno de configuração remota, você pode criar campos de Texto via API XML-RPC:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_client_notes',
        'field_description': 'Notas do Cliente',
        'model_id': model_id,
        'ttype': 'text',
        'state': 'manual',
        'translate': False,
        'copy': False,
    }]
)

O valor ttype: text informa ao Odoo para criar um campo de Texto (em oposição a char para um campo Char ou html para um campo Html). A configuração state: manual indica que este campo foi criado fora de um módulo, o que é correto para campos criados através do Studio ou programaticamente via API. Esta é a abordagem que a Dasolo utiliza ao implantar configurações de campos remotos para clientes.

Melhores Práticas

1. Use Texto quando o conteúdo realmente precisar de várias linhas

O erro mais comum é recorrer a um campo de Texto quando um campo Char seria suficiente. Se o valor for um nome, um código, uma referência ou qualquer coisa que caiba em uma linha, use Char. Reserve Texto para conteúdo onde se espera que os usuários escrevam frases ou parágrafos. Usar um campo de Texto para uma entrada curta de valor único cria uma experiência de usuário desajeitada e um modelo de dados enganoso.

2. Use Html quando a formatação importa

Se os usuários precisarem adicionar listas com marcadores, texto em negrito, hyperlinks ou qualquer formatação visual ao conteúdo, o campo Texto é a escolha errada. Use um campo Html em vez disso. Campos de Texto suportam apenas texto simples. Pedir aos usuários que escrevam conteúdo formatado em uma área de texto simples levará a usuários frustrados que esperam opções de formatação que não estão disponíveis.

3. Ative a tradução para conteúdo multilíngue voltado para o usuário

Em empresas que utilizam Odoo em vários idiomas, qualquer campo de Texto que apareça em documentos voltados para o cliente ou no site deve ter translate=True. Isso permite que os tradutores forneçam versões específicas do idioma do conteúdo sem sobrescrever o trabalho uns dos outros. Para notas internas e comentários operacionais que os usuários escrevem por conta própria, a tradução geralmente não é necessária.

4. Defina copy=False para notas que não devem ser duplicadas

Quando os usuários duplicam um pedido de venda ou um produto, os campos de Texto são copiados por padrão. Para notas que capturam o contexto específico do registro original, como uma conversa com o cliente ou um problema específico de entrega, isso pode criar confusão. Defina copy=False nesses campos para que os registros duplicados comecem com uma seção de notas limpa.

5. Use compute com store=True para resumos gerados automaticamente

Os campos de Texto podem ser computados dinamicamente no Odoo. Um padrão útil é construir um campo de resumo gerado automaticamente que concatena valores de outros campos no registro. Com store=True e os apropriados @api.depends() triggers, o texto computado é salvo no banco de dados e se torna pesquisável em visualizações de lista e filtros. Esta é uma técnica prática de campos computados do Odoo para criar resumos internos leves sem construir um relatório separado.

Armadilhas Comuns

Escolhendo Texto quando Html é necessário

Se um campo deve conter conteúdo exibido no site ou em um relatório PDF formatado, usar Texto em vez de Html removerá toda a formatação. Usuários que colam conteúdo com marcadores ou texto em negrito em um campo de Texto verão isso renderizado como prosa plana e não formatada. Sempre pergunte se o canal de saída precisa de formatação antes de escolher o tipo de campo.

Escolhendo Texto quando Char é a escolha certa

Um campo de Texto é renderizado como uma área de texto alta e redimensionável. Se um campo vai conter apenas um valor curto, como um número de rastreamento ou um código de variante de produto, usar Texto torna o formulário desnecessariamente volumoso. Conteúdo de uma linha pertence a um campo Char, que é renderizado como uma entrada de texto compacta que se encaixa naturalmente em um layout de formulário.

Esquecendo traduzir rótulos e descrições multilíngues

Em instâncias do Odoo implantadas em vários países, a falta do atributo translate=True em um campo de Texto voltado para o usuário significa que todos os usuários veem o mesmo valor, independentemente de sua configuração de idioma. Isso é especialmente problemático para descrições de produtos e notas de categoria que são visíveis na interface. A correção é simples, mas adicioná-la após os dados já estarem no sistema requer uma migração cuidadosa para evitar sobrescrever valores existentes.

Usando Texto para dados estruturados

Um campo de Texto que armazena JSON, valores separados por pipe ou outros formatos estruturados feitos à mão é um problema de manutenção esperando para acontecer. Se os dados têm uma estrutura consistente, eles devem ser armazenados nos tipos de campo apropriados do Odoo: Seleção para opções fixas, Many2one para relacionamentos, ou um modelo relacionado com campos adequados. Codificar estrutura dentro de um campo de texto livre torna impossível filtrar, agrupar ou relatar os dados de forma confiável.

Não adicionar o campo à vista de pesquisa

Um campo de Texto que contém informações importantes, mas não está incluído na vista de pesquisa do modelo, não pode ser filtrado a partir da barra de pesquisa da vista de lista. Os utilizadores acabam por rolar através dos registos para encontrar o que precisam, em vez de simplesmente digitar uma palavra-chave. Se um campo de Texto armazena informações que os utilizadores desejam pesquisar, adicione-o à definição da vista de pesquisa ao criar o campo.

Conclusão

O campo de Texto é um desses blocos de construção na estrutura do Odoo que parece pouco notável até que comece a desenhar formulários a sério.

 Escolher entre Char, Text e Html é uma das primeiras decisões que você enfrenta em qualquer projeto de personalização do Odoo, e acertar desde o início evita retrabalho e problemas de qualidade de dados mais adiante.

Quer você esteja adicionando um campo de notas através do Odoo Studio, definindo-o em um módulo Python ou criando-o programaticamente via API, os padrões neste guia o ajudarão a tomar a decisão certa e a configurar o campo corretamente para o seu caso de uso.

Um modelo de dados Odoo bem projetado é construído com base em pequenas decisões bem escolhidas. Escolher o tipo de campo certo para cada pedaço de informação é uma delas, e o campo de Texto, usado no contexto certo, é uma ferramenta confiável e flexível para capturar o tipo de conteúdo que não se encaixa perfeitamente em campos estruturados.

Na Dasolo, ajudamos empresas a implementar, personalizar e otimizar o Odoo em todos os departamentos. Quer você precise de ajuda para desenhar um modelo de dados limpo, construir campos e fluxos de trabalho personalizados, ou configurar uma implementação completa do Odoo do zero, nossa equipe está aqui para apoiá-lo. Entre em contato e vamos conversar sobre o seu projeto Odoo.