HTML-поле в Odoo: Полное руководство для разработчиков и администраторов

Введение

Когда вы читаете карточку товара в интернет-магазине на Odoo и видите аккуратно оформленные заголовки, списки и изображения, за всем этим обычно стоит один тип поля — Html. Это универсальное поле в модели данных Odoo, которое встречается гораздо чаще, чем думают многие пользователи.

В отличие от обычного текстового поля, которое хранит просто строку, Html-поле сохраняет форматированный контент: теги, разметку, изображения и прочие элементы. Благодаря этому оно незаменимо там, где нужно представлять структурированный или стилизованный текст — от описания товаров до шаблонов писем и фрагментов сайта.

Это руководство объясняет, что такое Html-поле, как оно устроено в ORM и базе данных Odoo, где часто применяется в реальных бизнес-процессах и как его добавить или изменить через Odoo Studio или код на Python. Также разберём распространённые ошибки при работе с этим типом поля.

Что такое Html-поле в Odoo

Внутри ORM Odoo Html-поле предназначено для хранения HTML-контента. В базе данных PostgreSQL ему соответствует колонка типа TEXT, а в записи сохраняется HTML-строка. Odoo автоматически отвечает за рендеринг и очистку содержимого, поэтому интерфейс показывает визуальный редактор, а не сырые теги.

Для пользователя Html-поле выглядит как визуальный WYSIWYG-редактор. В нём доступны жирный и курсив, заголовки, списки, ссылки, таблицы и вставка изображений. Всё это сохраняется в базе как структурированный HTML, обеспечивая предсказуемое отображение на сайтах и в документах.

Ниже — пример того, как поле определяется в 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,
    )

Параметр string задаёт метку поля, видимую в интерфейсе. Параметр sanitize отвечает за удаление опасных HTML-частей при сохранении — это важная мера безопасности, включённая по умолчанию.

В Odoo Studio этот тип поля называется Html или Rich Text. Studio создаёт такие поля с префиксом x_studio_. При определении через Python или API вы сами выбираете техническое имя поля.

Как это поле работает

При определении Html-поля фреймворк создаёт в PostgreSQL колонку типа TEXT. На уровне БД нет ограничения длины, поэтому поле подходит для длинного контента. Саму очистку (санитизацию) Odoo выполняет до записи значения в базу.

Санитизация и безопасность

Ключевая особенность Html-поля — слой санитизации. По умолчанию Odoo удаляет теги и атрибуты, которые могут быть использованы для XSS-атак. Поведение регулируется набором атрибутов поля.

• sanitize: при True (по умолчанию) Odoo применяет полную очистку перед сохранением. Отключайте это только если полностью уверены, что контент поступает из доверенного источника и нужно сохранить «сырой» HTML.
• sanitize_tags: при True удаляются теги, не входящие в разрешённый список. Отключение даёт свободу тегов, но резко повышает риск уязвимостей.
• sanitize_attributes: управляет очисткой атрибутов HTML-тегов.
• sanitize_style: отвечает за очистку inline-стилей. По умолчанию некоторые CSS-свойства разрешены, потенциально опасные удаляются.
• strip_style: при True удаляет все inline-стили полностью.
• strip_classes: при True удаляет все атрибуты class из сохраняемого контента.

Благодаря этой очистке Html-поле безопасно использовать для контента, вводимого пользователями, поэтому его часто применяют в формах, видимых клиентам, и в шаблонах писем.

Ключевые атрибуты поля

Кроме санитизации, Html-поле поддерживает стандартные атрибуты Odoo:

• translate: при True содержимое поля можно переводить по языкам. Odoo хранит отдельную версию HTML для каждого активного языка.
• required: делает поле обязательным. Учтите, что поле, содержащее только пустые теги или пробелы, интерфейс может считать заполненным, поэтому проверка «обязательности» лучше строится на действительно пустых значениях.
• default: задаёт HTML по умолчанию для новых записей — удобно для шаблонов писем или стандартных описаний товаров.
• compute: связывает поле с методом на Python, который динамически формирует HTML. При store=True результат сохраняется в базе.
• copy: контролирует копирование содержимого при дублировании записи; по умолчанию True.

Как поле отображается в видах

В формах Html-поле отображается как визуальный редактор с панелью инструментов. В списках Odoo обычно показывает краткий текст без HTML-тегов, чтобы таблицы оставались читаемыми.

В XML-видах атрибут widget позволяет управлять рендерингом. По умолчанию используется rich text-редактор. Для отображения немодифицируемого HTML (например, в отчётах или на портале) применяют виджет html — он выводит форматированный контент без панели редактирования.

Взаимодействие с ORM

При чтении Html-поля разработчик получает строку с HTML-разметкой; запись тоже ожидает HTML-строку. Санитизация выполняется на уровне ORM перед сохранением в базу, поэтому даже значения, записанные через XML-RPC, проходят ту же очистку при sanitize=True.

Практический вывод: если нужно хранить особые теги или атрибуты, не входящие в белый список Odoo, придётся отключать sanitize или настраивать флаги. Это продвинутый сценарий, требующий оценки рисков для безопасности.

Сценарии использования в бизнесе

Html-поле встречается во множестве участков стандартной конфигурации Odoo. Ниже пять типичных бизнес-примеров.

Склад и интернет-магазин: описания товаров

Самое распространённое применение — поле description_sale в product.template. Именно оно отвечает за описание товара на витрине и в строках заказа. Благодаря Html-формату команды мерчандайзинга могут делать понятные карточки с пунктами, заголовками и изображениями, что положительно влияет на конверсию. Одна и та же запись обслуживает и бэк-офис, и витрину — ничего не дублируется.

Email-маркетинг: тело шаблонов

Шаблоны писем в Odoo хранят тело в формате HTML (body_html у mail.template). Там оформляют макет, вставляют изображения и плейсхолдеры, которые подставляются при отправке. Маркетологи могут создавать богатые письма прямо в Odoo без внешних редакторов — контент версионируется и переиспользуется в кампаниях и автоматизациях.

CRM: заметки и описания возможностей

Торговые команды часто фиксируют детальные заметки по сделкам. Html-поля в лидах и возможностях позволяют оформлять заметки с заголовками, списками и ссылками на документы. Это удобнее простого текста, когда записи пересылают коллегам или включают в печатные отчёты — форматирование сохраняется.

Бухгалтерия: условия в счётах

Во многих компаниях внизу счёта или заказа печатают платёжные условия, юридические оговорки или гарантии. Поле note на заказах и счетах — это Html-поле, позволяющее красиво оформить эти блоки. В PDF-печатях структура и выделения сохраняются корректно.

HR: описания вакансий

При размещении вакансий через модуль рекрутинга описание работы хранится в Html-поле на hr.job и hr.applicant. Это позволяет формировать чёткие разделы обязанностей, требований и преимуществ — такие объявления выглядят профессионально на странице вакансий и помогают привлечь подходящих кандидатов.

Как добавить или настроить Html-поле

Три способа добавить Html-поле в модель Odoo, в зависимости от уровня доступа и подхода к внедрению.

Через Odoo Studio (без кода)

Odoo Studio позволяет добавить Html-поле на форму без написания кода — это самый простой путь для бизнес-пользователей:

1. Откройте Odoo Studio из главного меню.
2. Перейдите на форму, куда хотите добавить поле.
3. Из боковой панели перетащите поле Html или Rich Text на форму.
4. Задайте метку и параметры в панели свойств поля.
5. Сохраните изменения и закройте Studio.

Studio автоматически создаст поле с префиксом x_studio_, добавит его в вид и создаст колонку в базе — миграций и развертываний со стороны администратора не требуется, поле сразу доступно для ввода данных.

Через Python в модуле (для разработчиков)

Если вы создаёте модуль и хотите управлять изменениями через систему контроля версий, Html-поля определяют в Python-файлах модели. Этот подход подходит для развёртывания на разных средах:

from odoo import fields, models

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

    x_delivery_instructions = fields.Html(
        string='Delivery Instructions',
        sanitize=True,
        translate=True,
    )

После объявления поля его нужно добавить в соответствующий XML-вид, чтобы оно отображалось. При установке или обновлении модуля Odoo создаст TEXT-колонку в базе, а поле автоматически отобразится как визуальный редактор в форме.

Через XML-RPC API

Если вы автоматизируете конфигурацию или развертывание удалённо, Html-поля можно создать программно через XML-RPC API:

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',
    }]
)

Параметр ttype: 'html' указывает, что создаётся Html-поле. state: 'manual' помечает его как поле, созданное пользователем, а не модулем. Такой подход удобен для автоматизированных конфигураций в клиентских средах.

Некоторые опции санитизации нельзя задать через ir.model.fields API так же гибко, как в Python — при создании через API применяется поведение очистки по умолчанию.

Рекомендации по использованию

1. Оставляйте sanitize включённым, если нет крайней необходимости отключать

Стандартная очистка защищает систему от XSS. В большинстве случаев её достаточно. Отключайте sanitize только для доверенных внутренних потоков (например, серверной генерации HTML), но никогда — для контента, введённого пользователями.

2. Используйте translate=True для мультиязычных описаний

Если у вас мультиязычный сайт, Html-поля, показываемые клиентам, должны быть переводимыми. Это позволяет хранить отдельные версии HTML для каждого языка и показывать покупателю контент на его языке, а не перевод-запас.

3. Не храните контент, завязанный на внешние ресурсы

Встраивание внешних картинок или скриптов создаёт зависимости, которые могут сломаться при смене URL или отключении сторонних сервисов. Храните изображения во встроенных вложениях Odoo и используйте относительные ссылки — это делает контент переносимым при миграциях и переносе серверов.

4. Для динамического содержимого используйте вычисляемые Html-поля

Если нужно программно собирать оформленный текст (например, сводка по позициям заказа или условие гарантии), лучше сделать compute-поле с store=True. Логика генерации централизована, результат сохраняется в базе и быстро доступен для интерфейса и PDF-отчётов.

5. Подумайте, нужен ли вам Html или достаточно Text

Если содержимое будет читаться только в бэк-офисе и форматирование не важно, хватит Text-поля. Html нужен там, где оформление действительно имеет значение: на сайте, в печатных документах или письмах. Лишний Html-редактор усложняет интерфейс при простых заметках.

Типичные ошибки

Отключили sanitize и забыли об этом

Установка sanitize=False для редактируемого пользователями поля — риск безопасности. Часто это делается временно в ходе разработки, а потом про это забывают. Всегда документируйте причины отключения и планируйте ревью перед выходом в продакшен.

Вставка из внешних источников с «плохим» HTML

При вставке текста из Word, Google Docs или сайтов в поле часто появляется неочищенный HTML: лишние теги, невидимые символы или невалидная разметка. Это приводит к проблемам с отображением, поиском и росту размера данных. Просите пользователей сначала вставлять как plain text и затем форматировать внутри редактора Odoo.

Путаница между Html-полем и контентом конструктора сайта

Конструктор сайта Odoo использует блоки и компоненты Owl — HTML, который он генерирует, отличается от обычного HTML-поля в модели. Копирование сложной разметки из конструктора в стандартное Html-поле обычно не срабатывает и может быть удалено санитайзером.

Забыли включить translate в мультиязычных развёртываниях

Если Html-поле не помечено translate=True в мультиязычной системе, пользователи всех языков увидят одно и то же содержимое. Для внутренних полей это допустимо, но для публичных описаний и шаблонов писем это станет проблемой. Исправлять это задним числом неудобно, особенно если контент уже введён на одном языке.

Использование Html там, где ожидается plain text

Некоторые элементы Odoo (темы писем, заголовки отчётов, внешние API) требуют простого текста. Если туда попадёт HTML, пользователи увидят сырые теги вместо аккуратного текста. Проверьте контекст потребления значения перед тем, как выбирать Html вместо Char или Text.

Заключение

Html-поле — один из самых мощных типов полей в модели Odoo. Оно незаметно поддерживает описания продуктов, шаблоны писем, вакансии и примечания в документах, позволяя показывать форматированный контент без внешних инструментов.

Понимание принципов работы — особенно слоя санитизации, поддержки переводов и поведения в разных режимах отображения — помогает грамотнее проектировать и настраивать систему. Будь вы пользователь Studio, разработчик модуля или инженер, создающий поля удалённо через API, эти рекомендации применимы в любом подходе.

Как и многое в Odoo, само поле просто, когда ясно, что происходит «под капотом». Ценность приходит тогда, когда вы используете его в подходящих местах с корректными настройками для нужного типа контента.

В компании Dasolo мы помогаем внедрять, настраивать и оптимизировать Odoo по всем отделам. Если нужно спроектировать аккуратную модель данных, добавить кастомные поля или разработать модуль под бизнес‑процессы — мы готовы помочь. Свяжитесь с нами и обсудим ваш Odoo‑проект.