Введение
Поля для бинарных данных — незаметные, но повсюду в реальной практике Odoo. Каждый раз, когда сотрудник прикрепляет подписанный договор, загружает технический паспорт товара или сохраняет логотип компании в карточке, за этим стоит Binary-поле. Понимание того, как данные в нём хранятся, куда они попадают и когда лучше выбрать другой тип поля, существенно влияет на производительность, удобство и безопасность при разработке форм и расширении моделей Odoo.
В этом материале мы разберём, что именно хранит Binary-поле, как режим вложений влияет на место хранения и скорость работы, как добавить и настроить такое поле через Odoo Studio или в Python-модуле, а также приведём практические примеры использования в CRM, HR, складском учёте и других сценариях бизнеса.
Что такое поле Binary в Odoo
Внутри ORM Odoo Binary-поле (fields.Binary) предназначено для хранения «сырых» двоичных данных: файлов, документов, изображений — всего того, что пользователь загружает в карточку. В интерфейсе это выглядит как контрол для загрузки/скачивания файла: одно нажатие — загрузить, одно — сохранить локально. С технической точки зрения поле служит контейнером для контента, который пользователь прикрепил к записи.
Ключевой момент — это место хранения содержимого. В современных версиях Odoo бинарные файлы по умолчанию хранятся в системе вложений: запись об файле лежит в таблице ir.attachment и в файловом хранилище сервера, тогда как колонка модели содержит лишь ссылку на это вложение. Такой подход уменьшает размер основных таблиц базы данных и упрощает управление файлами в масштабных установках.
В Odoo Studio Binary-поле в списке полей называется File и отображается как простая панель загрузки/скачивания в формах. Для изображений в Odoo предусмотрен специализированный тип — fields.Image, который умеет автоматически менять размер и показывать превью; про него поговорим отдельно там, где это уместно.
Пример того, как Binary-поле объявляется в Python-модели:
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Signed Contract',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Signed Contract Filename',
)Обратите внимание на сопутствующее поле x_signed_contract_filename типа Char. Привычный шаблон разработки в Odoo — всегда добавлять такое поле для хранения оригинального имени файла. Интерфейс использует его, чтобы показать или восстановить исходное имя при скачивании; без него пользователи получают безличные имена вроде «download».
Принцип работы поля
При объявлении Binary-поля в модели Odoo автоматически создаст необходимые колонки при установке или обновлении модуля — ручной SQL не требуется.
Режимы хранения
Параметр attachment у Binary-поля определяет, где именно будут лежать байты файла:
- attachment=True (рекомендуется): контент сохраняется в
ir.attachmentи в файловом хранилище сервера, а колонка модели хранит ссылку на вложение. Это делает таблицы моделей компактнее и использует встроенную систему хранения Odoo. - attachment=False: сырые данные в виде base64 сохраняются прямо в колонке модели. Такой режим ведёт к быстрому росту таблиц и замедлению запросов — избегайте его для всего, что больше миниатюрных изображений.
Формат данных
Binary-поля хранят и возвращают данные в виде base64-строк. При чтении через ORM или XML-RPC вы получаете base64, при записи — должны передать base64-строку.
На практике это означает: перед записью кодируйте файл в base64, после чтения — декодируйте обратно в байты.
import base64
# Запись файла в Binary-поле
with open('document.pdf', 'rb') as f:
encoded = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encoded})
# Чтение файла из Binary-поля
raw_bytes = base64.b64decode(record.x_signed_contract)Ключевые атрибуты поля
Ниже — основные параметры Binary-поля, которые чаще всего настраивают при разработке в Odoo:
- attachment: Boolean. Сохранять в
ir.attachment(True) или в колонке модели (False). В современных версиях по умолчанию True. - string: Метка поля в интерфейсе.
- required: Обязательность заполнения перед сохранением записи.
- compute: Привязка к методу Python для динамической генерации содержимого (например, генерация PDF на лету).
- store: При использовании с
compute— сохраняет вычисленное значение в базе. - groups: Ограничение доступа к полю по группам пользователей — важно для конфиденциальных документов.
- copy: Управляет копированием значения при дублировании записи; поведение зависит от режима attachment и версии Odoo.
Подкласс fields.Image
fields.Image — специализированный вариант fields.Binary (введён с Odoo 13). Он автоматически приводит изображение к заданным максимальным размерам, поддерживает превью и показывает миниатюру в форме. Для фотографий сотрудников, картинок товаров и логотипов используйте именно fields.Image: это экономит место и улучшает пользовательский опыт.
Отображение в представлениях
В формах Binary-поле по умолчанию рендерится как контрол загрузки/скачивания. Для изображений можно применить виджет image, чтобы увидеть миниатюру. В списковых представлениях бинарные данные обычно не отображают целиком — выгоднее показывать индикатор наличия файла или иконку, иначе браузер будет тянуть лишние байты для каждой строки.
Бизнес-сценарии применения
Где это реально используется — практические примеры
CRM: хранение подписанных NDA и контрактов в карточке клиента
В продажах удобно прикреплять подписанные соглашения прямо к карточке клиента или лида. Binary-поле на res.partner или crm.lead даёт менеджеру быстрый доступ к документу без внешних систем — всё нужное находится там, где работают сотрудники в процессе продаж.
HR: хранение документов сотрудников
Для HR важно сохранять копии паспортов, разрешений на работу, подписанных трудовых контрактов и сертификатов. Binary-поле на hr.employee позволяет хранить такие файлы под управлением стандартных правил доступа Odoo. Через параметр groups видимость можно ограничить только HR-менеджерам, а остальным дать доступ к форме без возможности скачивать файлы — это частая настройка в компаниях с высокими требованиями к конфиденциальности.
Склад и производство: технические паспорта и паспорта безопасности
Для технических товаров часто требуются PDF‑спецификации, паспорта безопасности и сертификаты качества. Binary-поле на product.template даёт возможность хранить и быстро открывать эти документы прямо из карточки товара — распространённая и простая до реализации кастомизация в дистрибуции и производстве.
Продажи: печатный штамп или подпись компании
Иногда нужно, чтобы в распечатанных коммерческих предложениях или подтверждениях заказа автоматически вставлялся штамп или подпись. Хранение такого изображения в fields.Image на res.company позволяет ссылаться на него в QWeb‑шаблонах и печатать документы с подписью без ручной подстановки — удобно для объёмных операций и уменьшает риск отправить неокончательный документ.
Бухгалтерия: сканы чеков к расходам
Процессы возмещения затрат требуют прикрепления скана чека или счёта к каждой записи расхода. В стандартных сценариях это умеет делать система вложений Odoo, но в кастомных моделях Binary-поле — чистый способ хранить изображение или PDF чека прямо на записи и встроить его в логику согласования.
Создание и кастомизация Binary-поля
Способы добавления Binary-поля
Существует три основных способа добавить Binary-поле в модель Odoo, в зависимости от уровня доступа и потребностей по контролю версий.
Через Odoo Studio (без кода)
- Odoo Studio — встроенный low-code инструмент. Чтобы добавить поле File без программирования:
- Откройте Odoo Studio из главного меню.
- Перейдите в форму, куда нужно добавить поле.
- Перетащите поле File из палитры на форму.
- Задайте метку и опции видимости в панели свойств.
Сохраните изменения и закройте Studio.
Studio создаёт поле с префиксом x_studio_ и автоматически включает attachment‑режим. Это быстрый способ дать пользователям загрузку файлов без привлечения разработчиков.
Через Python в кастомном модуле
Если требуется контроль версий и развёртывание по средам, определяйте Binary-поля в Python — это стандарт для серьёзных кастомизаций Odoo:
После объявления поля включите его в форму через XML‑вид с виджетом binary и указанием атрибута filename, ссылающегося на сопутствующее Char‑поле. Odoo сам создаст колонки при установке или обновлении модуля, и такой подход одинаково хорошо работает на Odoo.sh и on‑premise.
Через XML‑RPC API
Если вы автоматизируете конфигурацию удалённо (скрипты развёртывания, ноутбуки настройки), можно создать поле через XML‑RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_document',
'field_description': 'Custom Document',
'model_id': model_id,
'ttype': 'binary',
'state': 'manual',
}]
)Значение state: 'manual' показывает, что поле создано вручную, а не модулем. В текущих версиях поля, создаваемые через API, по умолчанию используют режим вложений — этот метод удобен для автоматизированных конфигураций и развёртываний.
Рекомендации и хорошие практики
1. Всегда используйте attachment=True
Если нет крайней причины хранить байты прямо в колонке, используйте режим вложений. Он сохраняет компактность таблиц, ускоряет запросы и использует файловое хранилище Odoo. Для любого файла, превышающего миниатюрный размер, attachment‑режим обязателен.
2. Сопутствующее поле для имени файла
Добавляйте рядом Char‑поле с суффиксом _filename для хранения оригинального имени файла. Без него виджет загрузки не сможет отобразить имя, и скачанный файл получит безликое имя. Это простая привычка, которая заметно улучшает UX.
3. Для картинок — fields.Image
Для фотографий и логотипов выбирайте fields.Image. Он ограничит размеры, покажет превью и сохранит отдельно уменьшенную версию, что экономит место и ускоряет работу интерфейса. Подбирать тип поля под ожидаемый контент — базовое правило грамотного проектирования модели данных в Odoo.
4. Ограничивайте доступ через groups
Чувствительные документы (личные дела сотрудников, финансовые бумаги, подписанные контракты) должны иметь ограничения доступа через параметр groups. Это важно и с точки зрения конфиденциальности, и для соблюдения требований аудита в регулируемых отраслях.
5. Корректно работайте с base64 в коде
При программной работе с Binary‑полями всегда явно кодируйте и декодируйте base64. Используйте base64.b64encode(file_bytes).decode('utf-8') перед записью и base64.b64decode(field_value) после чтения. Ошибки в формате — частая причина багов при интеграции с Odoo ORM.
Типичные ошибки и ловушки
Опасность хранения больших файлов в колонке
Если ставить attachment=False для крупных файлов, таблица PostgreSQL быстро раздуется: несколько десятков PDF могут добавить сотни мегабайт к одной таблице и замедлить все запросы к ней. Это одна из наиболее серьёзных ошибок в управлении Odoo‑базой; исправление требует миграции данных и аккуратного скрипта для переноса во вложения.
Забыть про поле имени файла
Отсутствие сопутствующего Char‑поля приводит к неудобствам: скачанные файлы получают generic‑имена и создают ощущение незавершённости интеграции. Решение простое и быстрое — добавить поле имени файла при первом же создании Binary‑поля для формы.
Путаница между Binary и Image
Использование plain Binary для изображений лишает вас автоматического ресайза и превью, пользователи могут загружать тяжёлые картинки, что тормозит интерфейс. Обратная ошибка — применять fields.Image к не‑изображениям (PDF) — это вызовет обработку как картинки и приведёт к ошибкам. Правило простое: выбирайте тип поля по ожидаемому содержимому.
Включать Binary в список — плохая идея
Добавление Binary‑поля в list view заставляет Odoo загружать полный контент для каждой строки. Для пятидесяти записей это может означать мегабайты лишнего трафика. Если нужно показать, что файл прикреплён, лучше использовать вычисляемое булево поле или иконку вместо прямого показа Binary‑поля в списке.
Не проверять False перед обработкой
Если Binary‑поле пустое, в Python оно возвращает False, а не пустую строку или пустые байты. Попытка декодировать такое значение без проверки приведёт к TypeError. Всегда оборачивайте обработку проверкой: if record.x_document: data = base64.b64decode(record.x_document). Это важно в compute‑методах, серверных действиях и любых сценариях, где поле может быть пустым.
Заключение
Итог о Binary‑поле
Binary‑поле — простой, но критичный элемент модели Odoo. Оно аккуратно интегрирует хранение файлов с системой вложений, интерфейсом и контролем доступа. Выработав несколько стабильных правил, вы избежите большинства проблем ещё на этапе проектирования.
Важные привычки: всегда использовать attachment‑режим, добавлять поле для имени файла, применять fields.Image для изображений, ограничивать доступ для конфиденциальных документов и корректно обрабатывать base64 в коде. Эти меры предотвращают основные неисправности до выхода в продакшен.
Если нужна помощь с Odoo Наша команда в Dasolo оказывает услуги по внедрению, кастомизации и оптимизации Odoo для всех отделов компании. Мы поможем спроектировать модель данных, выбрать корректные типы полей, настроить рабочие процессы с файлами или разработать полноценный модуль под ваши задачи. Свяжитесь с нами