Поле Char в Odoo: Полное Руководство для Разработчиков

Введение

Поле Char — один из базовых типов данных в модели Odoo. Когда вы видите имя контакта, артикул товара или заметку в заказе, чаще всего это простая строка, сохранённая именно в Char-поле.

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

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

Что такое поле Char в Odoo

В ORM Odoo Char используется для коротких текстовых значений. В базе данных PostgreSQL оно отображается как VARCHAR с указанной длиной или как TEXT, если ограничение длины не задано.

Для пользователя Char — это однострочное текстовое поле в форме и обычный текст в списке записей. Оно идеально подходит для имён, кодов, артикулов, идентификаторов и любых других коротких строк, которые комфортно читаются в одну строку.

Ниже — пример определения поля в 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,
    )

Параметр string задаёт метку в интерфейсе; size (необязательный) ограничивает число символов; index создаёт индекс в БД для ускорения поиска.

В Odoo Studio такой элемент называется Text (single line). Studio автоматически даёт техническое имя с префиксом x_studio_, тогда как при создании через код или API вы сами выбираете имя поля.

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

Когда вы добавляете Char в модель, Odoo сам создаёт соответствующую колонку в базе при установке или обновлении модуля — ручные SQL-миграции не требуются.

В PostgreSQL поля Char без указанного size хранятся как TEXT, а с ограничением — как VARCHAR(n). Для производительности между ними обычно нет серьёзной разницы; главное — соблюдение ограничений по длине, если это важно для данных.

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

Основные параметры Char-поля в Odoo, на которые стоит обращать внимание:

• size: максимальная длина в символах. Если не задан — ограничение на уровне БД отсутствует.
• translate: при True значение поля можно переводить для разных языков — актуально для многоязычных систем.
• required: делает поле обязательным на уровне модели и интерфейса.
• default: задаёт значение по умолчанию при создании записи.
• index: создаёт индекс для ускорения фильтрации и поиска по полю.
• compute: связывает поле с методом Python, который вычисляет значение динамически — удобно для производных строк.
• store: вместе с compute определяет, будет ли вычисленное значение сохранено в базе.
• copy: управляет копированием значения при дублировании записи; по умолчанию True.

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

В формах Char рендерится как обычное <input type="text">, в списках — как текст, в поиске поддерживает операторы «содержит», «равно», «начинается с» и т. п.

Поле можно комбинировать с виджетами для изменения отображения: виджет email превращает поле в кликабельную ссылку, url — в ссылку, открывающуюся в новой вкладке и т.д.

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

Для разработчика чтение и запись Char-полей ведётся привычно: значение доступно как атрибут записи, а фреймворк сам выполняет базовую валидацию и очистку. Сложных преобразований здесь нет, поэтому Char удобен для повседневных задач.

Практические бизнес-сценарии

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

CRM: внутренние коды клиентов

Компании часто присваивают клиентам внутренние референсы. Char на модели res.partner хранит этот код — он доступен в списках, заказах и выставляемых счетах, что позволяет быстро находить нужного клиента даже при похожих именах.

Продажи: ссылки на заказ клиента

Когда клиент присылает PO-номер, его нужно видеть на счётах и накладных. Стандартное поле client_order_ref в sale.order — это Char, которое автоматически переносится в счёт, снижая количество запросов к клиенту по поводу отсутствующих ссылок.

Склад: внутренние артикулы товаров

Поле default_code у шаблона товара — Char, где хранятся внутренние коды, используемые в складах, при сканировании и в заказах. Поддержание этого поля в порядке — важная задача качества данных для складских процессов.

Бухгалтерия: налоговые и регистрационные номера

VAT, ИНН и регистрационные номера компаний хранятся как Char у партнёра. При правильной настройке они автоматически печатаются в документах, что особенно важно для компаний, работающих в нескольких юрисдикциях.

Кадры: идентификаторы сотрудников и коды пропусков

HR хранит табельные номера, коды бейджей и внешние идентификаторы в Char-полях сотрудников. Это упрощает связывание записей Odoo с системами учёта рабочего времени или контрольно-пропускной системой без полной интеграции.

Создание и настройка поля Char

Способы добавить Char-поле в модель

Существует три основных подхода — в зависимости от уровня доступа и процессов доставки.

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

1. Odoo Studio — инструмент low-code для быстрой кастомизации. Чтобы добавить Char без программирования:
2. Откройте Odoo Studio из меню.
3. Перейдите на форму, куда хотите добавить поле.
4. Перетащите компонент Text (single line) из панели справа на форму.
5. Задайте метку, обязательность и при необходимости ограничение длины в свойствах поля.

Сохраните и закройте Studio.

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

Через Python в кастомном модуле

Для разработчиков стандартный путь — объявить поле в Python-модели; так лучше вести версионирование и деплой across environments:

from odoo import fields, models class ResPartner(models.Model): _inherit = 'res.partner' x_erp_customer_id = fields.Char( string='ERP Customer ID', size=32, index=True, copy=False, )

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

Через XML-RPC API

Если вы автоматизируете настройки или используете внешний скрипт для конфигурации, поля можно создавать по API:

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

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

Параметр state: 'manual' указывает, что поле создано вручную (не модулем) — это корректно для полей Studio или тех, что создаются через API.

1. Указывайте size, если знаете максимальную длину

Для ISO-кодов, телефонных номеров или фиксированных идентификаторов задавайте size. Это помогает избежать ситуаций, когда в поле случайно попадают слишком длинные строки.

2. Добавляйте индекс для часто ищущихся полей

Если по полю часто фильтруют или ищут, например по коду клиента — ставьте index=True. На больших таблицах это серьёзно сокращает время отклика.

3. Включайте translate=True для мультиязычного контента

Если пользователи работают на разных языках и ожидают видеть локализованные значения (названия товаров, должности и т. п.), активируйте перевод для поля.

4. Давайте полям понятные технические имена

В модулях используйте осмысленные имена типа x_customer_erp_id, а не x_field1. Техническое имя потом менять трудно, особенно после начала использования поля.

5. Применяйте compute для производных значений

Распространённые ошибки

Char можно вычислять динамически — например, собирать ссылку из года и порядкового номера. Если поставить store=True, такое значение сохраняется в базе и доступно для поиска и отчётов.

Отсутствие ограничения длины ведёт к плохим данным

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

Отсутствие индексов на часто используемых полях

Без индекса фильтрация по Char на большой таблице — это полное сканирование. Многие замечают лаги только после того, как БД вырастает, поэтому индекс лучше добавить заранее.

Путаница между Char и Text

Char — для коротких однострочных значений; Text — для длинных многострочных. Использование Char для адреса или описания ухудшает удобство: ввод не переносится и нельзя вставить абзацы.

Забыли включить translate для мультиязычных полей

Если поле должно быть локализовано, а translate=True не выставлен, пользователи других языков увидят одно и то же значение, что может запутать на клиентских документах.

Использование Char вместо Selection или связи

Часто задаваемые вопросы

Когда поле должно принимать ограниченный набор значений (статус, категория, страна), лучше использовать Selection или Many2one. Свободный ввод через Char приводит к опечаткам и ломает группировки и отчёты.

В чём разница между Char и Text?

Char хранит короткую однострочную строку и отображается как текстовый input. Text — для длинных многострочных заметок и отображается как textarea. Char — для имён, кодов, ссылок; Text — для описаний и примечаний.

Как ограничить количество символов в Char?

Задайте size при определении поля, например fields.Char(size=64). В Studio ограничение можно выставить в свойствах поля. Без size длина не ограничивается на уровне БД.

Как сделать поле Char доступным в строке поиска?

Добавьте поле в <search>-вид модели. В Studio включите опцию поиска в свойствах поля. В коде вставьте <field name="your_char_field"/> в определение <search>, тогда по нему можно будет фильтровать прямо из поисковой панели.

Можно ли хранить числа в Char?

Технически — да, но для вычислений это плохой выбор. Для числовых операций используйте Integer или Float. Char подходит для кодов, ZIP, номеров телефонов, IBAN и серийных номеров — когда значение рассматривается как текст.

Как создать вычисляемое Char-поле и сохранить его значение?

Заключение

Определите поле с compute='_compute_my_field' и store=True, напишите метод с декоратором @api.depends(), указывающим зависимости. Сохранённое значение будет доступно в фильтрации и экспортe без повторных вычислений.

Char кажется тривиальным, и большинство пользователей ежедневно взаимодействуют с множеством таких полей, не задумываясь. Тем не менее при проектировании Odoo-системы понимание его свойств и областей применения заметно повышает качество модели данных.

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

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