Introdução
Quando navegas pela ficha de um produto numa loja online construída com Odoo, aquele texto com títulos em negrito, listas e imagens não é magia — vem de um único tipo de campo: o campo Html. É um dos elementos mais flexíveis do modelo de dados do Odoo e aparece em muitas áreas onde os utilizadores esperam conteúdo rico e formatado.
Ao contrário de um campo de texto simples que guarda apenas cadeias de caracteres, o campo Html armazena conteúdo enriquecido com formatação. Por isso é ideal sempre que precisares de escrever textos estruturados — descrições de produto, modelos de e-mail, notas internas ou secções de site — onde o formato importa para a comunicação.
Este guia explica o que é o campo Html, como ele se comporta no ORM e na base de dados do Odoo, em que fluxos de trabalho empresariais ele costuma aparecer e como o adicionar ou personalizar — quer uses o Odoo Studio, quer escrevas código Python. Também apontamos os erros mais comuns para evitá-los em produção.
O que é o campo Html no Odoo
No ORM do Odoo, o campo Html existe para guardar HTML formatado. Na base de dados PostgreSQL traduz-se numa coluna do tipo TEXT e o valor armazenado é uma string HTML. Odoo encarrega‑se da renderização e da filtragem de segurança, de modo que os utilizadores interajam com um editor visual em vez de ver código bruto.
Para o utilizador, um campo Html surge como um editor WYSIWYG — o que vês é o que obténs. Dá para aplicar negrito, itálico, cabeçalhos, listas, hiperlinks, tabelas e colocar imagens. Tudo o que o utilizador formata é guardado, nos bastidores, como HTML estruturado.
Exemplo em código — como se define no modelo Python
from odoo import fields, models
class ProductTemplate(models.Model):
_inherit = 'product.template'
x_technical_specs = fields.Html(
string='Technical Specifications',
sanitize=True,
sanitize_tags=True,
)
O parâmetro string define o rótulo visível no formulário. O atributo sanitize indica se o Odoo deve eliminar HTML potencialmente perigoso antes de gravar — é uma camada de segurança crítica e está ativa por padrão.
No Odoo Studio, este tipo de campo aparece como Html ou Rich Text. Quando criado por Studio recebe um prefixo x_studio_. Em definições feitas por Python ou via API, podes escolher o nome técnico livremente.
Como funciona o campo
Ao declarar um campo Html, o Odoo cria automaticamente uma coluna TEXT em PostgreSQL. Não há limite de comprimento na base de dados, o que o torna adequado para conteúdos longos. O motor do Odoo aplica a sanitização antes de escrever o valor na base de dados.
Sanitização e segurança
O que distingue o campo Html de outros tipos é a camada de sanitização. Por defeito, o Odoo remove tags ou atributos que possam ser usados em ataques XSS. Esse comportamento é governado por vários atributos do campo:
- sanitize: Quando True (padrão), o Odoo executa o processo de limpeza completo antes de gravar. Só desativares isto se tiveres a certeza absoluta de que o conteúdo vem de uma fonte 100% confiável e precisa de manter HTML cru.
- sanitize_tags: Quando True, o Odoo elimina tags que não estejam na lista de permitidas. Desativar isto autoriza tags arbitrárias, mas só deve ser feito com cuidado e compreensão dos riscos.
- sanitize_attributes: Controla se os atributos das tags HTML também são filtrados.
- sanitize_style: Regula a limpeza de estilos inline. Por padrão, algumas propriedades CSS são permitidas enquanto outras potencialmente perigosas são removidas.
- strip_style: Se True, remove totalmente estilos inline do conteúdo armazenado.
- strip_classes: Se True, elimina os atributos de classe CSS do HTML guardado.
Graças a esta filtragem, o campo Html é seguro para receber conteúdo criado por utilizadores, razão pela qual é usado em formulários orientados a clientes e templates de e-mail.
Atributos chave do campo
Além da sanitização, o campo Html partilha atributos comuns a outros campos do Odoo:
- translate: Quando True, o conteúdo do campo pode ser traduzido por idioma. O Odoo guarda versões separadas do HTML para cada língua ativa, o que é essencial em sites e documentos multilingues.
- required: Torna o campo obrigatório. Atenção: se o campo só contiver espaços ou tags vazias, a interface pode considerá‑lo não vazio, por isso a validação funciona melhor em valores realmente em branco.
- default: Permite definir um HTML padrão para novos registos, útil para pré‑popular modelos de e-mail ou descrições padrão de produto.
- compute: Define um método Python que gera o HTML dinamicamente. Com store=True, o resultado é armazenado na base de dados.
- copy: Controla se o conteúdo é duplicado ao copiar um registo. Por defeito é True.
Como aparece nas vistas
Em vistas de formulário, o campo Html apresenta o editor rich text com uma barra de ferramentas e área de conteúdo para texto formatado, imagens e links. Em vistas de lista, o Odoo costuma mostrar um resumo sem tags HTML para manter a legibilidade.
O atributo widget no XML permite alterar a apresentação. O widget padrão é o editor rich text, mas podes usar o widget html para exibir o conteúdo formatado em modo de leitura — útil em relatórios PDF ou páginas de portal onde não queres a barra de edição.
Interação com o ORM do Odoo
Do ponto de vista do desenvolvedor, ler um campo Html devolve uma string com o markup HTML. Ao gravar, espera‑se também uma string HTML. A sanitização é aplicada no nível do ORM antes da escrita na base de dados, portanto até chamadas via XML‑RPC passam pela mesma limpeza quando sanitize=True.
Implicações práticas: se precisares de guardar tags ou atributos personalizados que não estão na lista de permitidos pelo Odoo, terás de usar sanitize=False ou ajustar os flags de sanitização no campo — uma configuração avançada que exige cuidado com segurança.
Casos de uso na empresa
O campo Html surge em muitas áreas de uma implementação Odoo. Seguem cinco exemplos práticos usados com frequência em empresas.
Inventário e Comércio Eletrónico: Descrições de Produto
O uso mais comum do campo Html é a descrição de venda (description_sale) em product.template. É a informação que os clientes veem na loja online e nas linhas de encomenda. Permite às equipas de merchandising criar descrições estruturadas com listas, títulos e imagens — algo que melhora a conversão no e‑commerce. O mesmo registo alimenta back‑office e storefront, evitando duplicação.
Marketing por E‑mail: Corpos de Templates
Os templates de e‑mail no Odoo usam fortemente campos Html. O body_html em mail.template guarda o corpo do e‑mail com layout, imagens e marcadores dinâmicos que são substituídos no envio. As equipas de marketing conseguem criar conteúdo rico directamente no Odoo, sem ferramentas externas, reaproveitando templates em campanhas e automações.
CRM: Notas e Descrições de Oportunidades
Equipa de vendas precisa frequentemente de registar contexto detalhado sobre leads e oportunidades. Campos Html em CRM permitem notas estruturadas com formatação e links para documentos externos. Isso facilita a partilha entre a equipa e mantém a formatação ao gerar relatórios ou imprimir documentos.
Contabilidade: Termos em Faturas
Muitas empresas incluem condições de pagamento ou cláusulas legais nas faturas e encomendas. O campo note em ordens de venda e faturas é Html, permitindo formatar esses textos de forma clara. O resultado aparece corretamente nos PDFs gerados, preservando quebras de linha e ênfases.
Recursos Humanos: Descrições de Cargos
Em recrutamento, as descrições de vagas são armazenadas em campos Html em hr.job e hr.applicant. Isso permite listar responsabilidades, requisitos e benefícios com secções bem definidas — essencial para uma apresentação profissional na página de carreiras e para atrair candidatos adequados.
Criar ou personalizar o campo Html
Três formas principais de adicionar um campo Html a um modelo Odoo, conforme o teu cenário técnico.
Com Odoo Studio (sem código)
O Odoo Studio facilita acrescentar um campo Html a um formulário sem programar:
- Abre o Odoo Studio no menu principal.
- Vai até ao formulário onde queres o novo campo.
- Arrasta na barra lateral um campo Html ou Rich Text para o formulário.
- Define o rótulo e as propriedades no painel de propriedades do campo.
- Guarda e fecha o Studio.
O Studio cria automaticamente o campo com prefixo x_studio_, adiciona‑o à vista e faz a coluna na base de dados. Não é necessário migrar ou fazer deploy — o campo fica disponível imediatamente.
Com Python num módulo personalizado
Para desenvolvedores que criam módulos Odoo, definem‑se campos Html em ficheiros Python — recomendado quando precisas de controlo de versão e deploy entre ambientes:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_delivery_instructions = fields.Html(
string='Delivery Instructions',
sanitize=True,
translate=True,
)
Depois de declarar o campo no modelo, adiciona‑o à vista XML correspondente. Ao instalar ou atualizar o módulo, o Odoo cria a coluna TEXT na base de dados. Em formulários, o campo aparece automaticamente como editor rich text.
Via API XML‑RPC
Se gerires customizações de forma programática, podes criar campos Html através da API XML‑RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_notes',
'field_description': 'Custom Notes',
'model_id': model_id,
'ttype': 'html',
'state': 'manual',
}]
)
O ttype: 'html' instrui o Odoo a criar um campo Html. state: 'manual' indica que é um campo definido pelo utilizador, não por um módulo. Esta abordagem é útil em automações de configuração remota quando não há acesso direto ao servidor.
Note que opções de sanitização (sanitize, sanitize_tags, etc.) não são sempre configuráveis via ir.model.fields pela API da mesma forma que em Python — o comportamento padrão de sanitização aplica‑se a campos criados via API.
Boas práticas
1. Mantém sanitize ativado salvo motivo forte
A sanitização por defeito protege a tua instância contra vulnerabilidades XSS. Na maioria dos casos funciona bem com sanitização ligada. Só desativa quando o conteúdo vier de um processo interno totalmente confiável e nunca para entradas de utilizadores ou fontes externas.
2. Usa translate=True para conteúdos multilíngues
Se tens várias línguas ativas, define translate=True em campos Html que aparecem no site ou em documentos de cliente. Assim podes manter versões do conteúdo por idioma e garantir que cada cliente vê a descrição no seu idioma, evitando fallback para a língua padrão.
3. Evita depender de recursos externos dentro do HTML
Incluir imagens ou scripts externos cria dependências que podem quebrar quando URLs mudam. Usa o sistema de anexos do Odoo para hospedar imagens internamente e referencia‑as por URLs relativas. Isso torna o conteúdo mais portátil entre migrações e servidores.
4. Usa campos Html computados para conteúdo dinâmico
Para conteúdo gerado programaticamente — por exemplo um resumo formatado de linhas de encomenda — um campo compute com store=True é uma solução elegante. A lógica vive num único sítio, o resultado é guardado para acesso rápido e aparece corretamente na interface e em PDFs.
5. Pensa no contexto de renderização antes de escolher Html vs Text
Se o conteúdo só for lido como texto simples no backend, um campo Text pode bastar. Usa Html quando a formatação faz diferença — site, documentos impressos ou e‑mails. Criar um campo Html onde um Text seria suficiente complica a vida aos utilizadores com um editor rich text desnecessário.
Erros frequentes
Desativar sanitize e esquecer
Definir sanitize=False num campo editável por utilizadores é um risco de segurança. É comum fazê‑lo durante desenvolvimento para resolver um problema de formatação e depois esquecer de reverter antes de ir a produção. Documenta e revê sempre essa decisão antes do deploy.
Colar conteúdo externo com HTML danificado
Ao colar textos de Word, Google Docs ou páginas web, o HTML resultante pode ficar desorganizado, com tags inválidas ou caracteres invisíveis. Isso leva a renderizações inconsistentes e valores inchados que afectam performance. Incentiva os utilizadores a colar como texto simples e reaplicar a formatação no editor do Odoo.
Confundir campo Html com conteúdo do construtor de site
O construtor de site do Odoo usa blocos e componentes Owl; o HTML guardado por esse sistema não é o mesmo que de um campo Html normal. Copiar HTML complexo do website builder para um campo de modelo raramente funciona e pode ser removido pelo sanitizador.
Esquecer translate em ambientes multilíngues
Num Odoo com várias línguas, um campo Html sem translate=True mostra o mesmo conteúdo a todos os utilizadores. Isso é aceitável para uso interno, mas problemático para descrições de produto, templates de e‑mail e qualquer conteúdo exposto a clientes. É fácil esquecer esta opção durante a configuração inicial e difícil de corrigir depois com conteúdo já criado.
Usar Html onde se espera texto simples
Some parts of Odoo, such as email subjects, report titles, or external API responses, expect plain text strings. If you store an Html field value in a context where the HTML tags are not stripped, your users will see raw markup like <p>Hello</p> instead of clean text. Always check how and where the field value will be consumed before choosing Html over Char or Text.
Conclusão
O campo Html é um dos tipos mais potentes do modelo Odoo. Trabalha nos bastidores de descrições de produto, templates de e‑mail, anúncios de vagas e notas de fatura, permitindo conteúdo formatado sem recorrer a ferramentas externas.
Saber como ele funciona — sobretudo a sanitização, o suporte a tradução e o comportamento em diferentes contextos de renderização — permite tomar decisões mais acertadas ao desenhar ou personalizar uma instância Odoo. Quer uses Studio, módulos Python ou a API, estes princípios aplicam‑se de forma consistente.
Como em muitas partes do Odoo, o campo em si é simples quando percebes o que acontece por trás. O verdadeiro ganho vem de o colocar nos locais certos, com as definições certas, para o tipo de conteúdo correto.
Na Dasolo, ajudamos empresas a implementar, personalizar e optimizar Odoo em todos os departamentos. Se precisares de apoio para desenhar um modelo de dados limpo, adicionar campos personalizados ou desenvolver módulos completos adaptados ao teu negócio, a nossa equipa pode ajudar. Contacta‑nos e vamos conversar sobre o teu projeto Odoo.