Pole Char w Odoo — Kompletny przewodnik dla deweloperów

Wstęp

Pole Char to jedno z najbardziej powszechnych pól w modelu danych Odoo. Gdy wpisujesz imię kontaktu, oznaczenie produktu lub krótką notatkę w zamówieniu sprzedaży, najczęściej pracujesz właśnie z polem Char — choć wiele osób nie zdaje sobie z tego sprawy.

Znajomość tego typu pola jest przydatna zarówno dla użytkowników biznesowych, którzy konfigurować formularze w Odoo Studio, jak i dla deweloperów tworzących moduły czy konsultantów projektujących strukturę systemu dla klientów.

Na pierwszy rzut oka pole Char wydaje się proste, ale ma kilka istotnych właściwości i zachowań, które warto znać, żeby uniknąć błędów. Ten przewodnik objaśnia, co pole przechowuje, jak wygląda w interfejsie, jak je tworzyć i dopasowywać oraz pokazuje praktyczne scenariusze użycia w firmie.

Czym jest pole Char w Odoo

W modelu ORM Odoo pole Char przeznaczone jest do przechowywania krótkich łańcuchów tekstowych. W zależności od ustawień odpowiada kolumnie VARCHAR lub TEXT w PostgreSQL — głównie zależnie od tego, czy określisz limit długości.

Z punktu widzenia użytkownika pole Char wyświetla się jako pojedyncze pole tekstowe w formularzu i jako zwykły tekst w widoku listy. To domyślny wybór do przechowywania nazw, kodów, referencji i innych krótkich fragmentów tekstu mieszczących się w jednym wierszu.

Przykład definicji pola w pliku Pythona pokaże, jak technicznie dodać takie pole do modelu.

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,
    )

Parametr string określa etykietę widoczną w interfejsie. size (opcjonalne) ogranicza liczbę znaków. index tworzy indeks bazodanowy, przyspieszający wyszukiwanie po tym polu.

W Odoo Studio ten sam rodzaj pola nazwany jest "Text (single line)" — po stworzeniu automatycznie dostaje prefiks x_studio_. W kodzie lub przez API techniczną nazwę wybierasz ręcznie.

Jak działa to pole

Definiując pole Char w module, Odoo samo zadba o dodanie odpowiedniej kolumny w bazie podczas instalacji lub aktualizacji modułu — nie musisz pisać migracji SQL ręcznie.

Technicznie pola Char bez określonego limitu zapisywane są jako TEXT, a z limitem jako VARCHAR(n). PostgreSQL dobrze radzi sobie z obiema opcjami, więc wybór dotyczy głównie wymuszania długości, a nie wydajności.

Kluczowe atrybuty pola

Oto najważniejsze właściwości pola Char w Odoo, które warto znać przy projektowaniu modeli danych:

• size: Maksymalna liczba znaków. Brak tego ustawienia oznacza brak ograniczenia długości na poziomie bazy danych.
• translate: Przy True wartość pola może mieć tłumaczenia na różne języki — przydatne w wielojęzycznych instalacjach.
• required: Wymusza uzupełnienie pola w interfejsie i na poziomie modelu.
• default: Ustawia wartość domyślną przy tworzeniu nowych rekordów.
• index: Tworzy indeks w bazie dla szybszych filtrów i wyszukiwań po tym polu.
• compute: Pozwala powiązać pole z metodą Pythona, która oblicza wartość dynamicznie — przydatne przy polach pochodnych.
• store: W połączeniu z compute decyduje, czy obliczona wartość ma być zapisana w bazie.
• copy: Określa, czy wartość pola jest kopiowana przy duplikowaniu rekordu. Domyślnie True.

Jak pole prezentuje się w widokach

W formularzach Char renderuje się jako standardowy <input type="text">. W listach pokazuje się jako prosty tekst. W widoku wyszukiwania obsługuje operatory typu zawiera, równa się czy zaczyna się od — gotowe do użycia bez dodatkowej konfiguracji.

Możesz zmieniać sposób wyświetlania przez użycie widgetów — np. widget email zamienia pole na klikalny adres e‑mail, a url otwiera link w nowej karcie przeglądarki.

Interakcja z ORM Odoo

Dla programisty odczyt i zapis pól Char działa tak samo jak innych pól w ORM: odwołujesz się do wartości na obiekcie rekordu, a framework zajmuje się walidacją i sanitacją zgodnie z definicją pola. Brak skomplikowanych transformacji sprawia, że pole Char jest wygodne w codziennej pracy z modułami Odoo.

Zastosowania biznesowe

Pole Char pojawia się praktycznie w każdym obszarze wdrożenia Odoo. Poniżej pięć typowych biznesowych zastosowań, gdzie takie pole jest naturalnym wyborem.

CRM: numer referencyjny klienta

Firmy często nadają klientom wewnętrzne kody. Pole Char na modelu res.partner jest idealne do przechowywania takiego identyfikatora — pozwala na szybkie wyszukiwanie klienta na liście i wyświetlanie go na zamówieniach czy fakturach, co zmniejsza ryzyko pomyłek przy podobnych nazwiskach.

Sprzedaż: referencje z zamówień klientów

Klienci podają numer zamówienia (PO), który powinien pojawić się na fakturach i dokumentach wysyłkowych. Wbudowane pole client_order_ref w sale.order to właśnie pole Char — jego wartość przepływa na faktury, eliminując konieczność manualnych doprecyzowań z klientem.

Magazyn: wewnętrzne kody produktów

Pole default_code w product.template przechowuje wewnętrzny numer katalogowy — wykorzystywany w magazynie, przy skanowaniu kodów kreskowych czy przy zamówieniach zakupowych. Utrzymanie porządku w tym polu to jedno z kluczowych zadań poprawy jakości danych w magazynie.

Księgowość: numery podatkowe i rejestracyjne

NIP, VAT i inne identyfikatory firm zwykle zapisuje się jako pola Char na rekordach partnerów. Przy poprawnej konfiguracji te wartości automatycznie pojawiają się na fakturach i dokumentach zakupu, co oszczędza wiele ręcznej korekty, zwłaszcza przy działalności międzynarodowej.

HR: identyfikatory pracowników i kody kart dostępu

Działy HR przechowują numery identyfikacyjne, kody kart lub identyfikatory z systemów płacowych i kontroli dostępu w polach Char na modelu pracownika — ułatwia to powiązanie rekordów Odoo z zewnętrznymi narzędziami bez konieczności natychmiastowej integracji.

Tworzenie i dostosowywanie pola Char

Sposoby dodawania pola Char do modelu

Masz trzy podstawowe ścieżki w zależności od poziomu technicznego i sposobu wdrożenia.

Przez Odoo Studio (bez kodowania)

1. Odoo Studio to narzędzie low-code do szybkich modyfikacji. Aby dodać pole Char bez pisania kodu:
2. Uruchom Odoo Studio z menu głównego.
3. Przejdź do formularza, w którym chcesz dodać pole.
4. Przeciągnij pole "Text (single line)" z paska narzędzi na formularz.
5. Ustaw etykietę, wymagane pole i opcjonalny limit długości w panelu właściwości.

Zapisz i zamknij Studio.

Studio automatycznie utworzy pole z prefiksem x_studio_ i doda je do widoku formularza — nie trzeba uruchamiać migracji bazy danych ręcznie.

Przez Pythona w module niestandardowym

Dla deweloperów, którzy versionują zmiany i wdrażają je na wielu środowiskach, zalecane jest definiowanie pól w kodzie. Przykład:

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, )

Po dodaniu pola do modelu trzeba umieścić je również w odpowiednim pliku XML widoku, aby było widoczne w interfejsie. Odoo sam utworzy kolumnę w bazie przy instalacji lub aktualizacji modułu.

Przez API XML-RPC

Jeżeli zarządzasz konfiguracją programowo (np. w pipeline’ie wdrożeniowym lub skryptach zdalnych), pole Char można stworzyć przez XML-RPC:

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

Dobre praktyki

Ustawienie state: 'manual' oznacza, że pole zostało utworzone ręcznie (nie przez moduł) — to właściwa wartość dla pól generowanych przez Studio lub API.

1. Ustal limit, jeśli znasz maksymalną długość

Jeśli pole przechowuje kody ISO, numery telefonów czy identyfikatory o stałej długości, ustal size. To nie tylko kontrola jakości danych, ale także jasna informacja dla innych programistów i administratorów — pole na dwuznakowy kod kraju nie powinno przyjmować 500 znaków.

2. Dodaj indeks dla często wyszukiwanych pól

Gdy użytkownicy regularnie filtrują po polu Char (np. kod klienta czy numer zamówienia), ustaw index=True. Na dużych tabelach indeks może zmienić wyszukiwanie z kilku sekund do ułamka sekundy.

3. Włącz tłumaczenia dla treści wielojęzycznych

Jeżeli użytkownicy pracują w różnych językach i pole zawiera tekst, który powinien być lokalizowany (np. nazwy produktów, stanowiska), użyj translate=True, aby zapewnić poprawne wyświetlanie wartości zależnie od języka użytkownika.

4. Nadawaj czytelne nazwy techniczne

W modułach niestandardowych używaj opisowych nazw: x_customer_erp_id jest bardziej zrozumiały niż x_field1. W Studio warto zmienić nazwę techniczną przed wdrożeniem, bo późniejsza zmiana staje się skomplikowana po zapisaniu danych.

5. Używaj compute dla pól pochodnych

Typowe pułapki

Char można obliczać dynamicznie — np. łączyć rok i numer sekwencyjny. Z store=True wynik zostanie zapisany w bazie i będzie dostępny w filtrach i raportach, a logika obliczeniowa pozostanie w jednym miejscu.

Brak limitu długości sprzyja złym danym

Bez size użytkownicy mogą wkleić całe akapity do pola, które później trafi na dokumenty drukowane lub do systemów z restrykcyjnymi limitami znaków. Tam, gdzie długość ma znaczenie, warto ustawić rozsądny limit.

Brak indeksu na często używanych polach

Jeżeli pole używane w filtrach nie ma indeksu, wyszukiwanie wymaga pełnego skanowania tabeli. Wiele zespołów odkrywa ten problem dopiero po wzroście bazy do dużej skali — lepiej dodać indeks od początku.

Mylne użycie Char zamiast Text

Char służy do krótkich, jednolinijkowych wartości. Text jest dedykowany dłuższym, wielolinijkowym treściom. Wpisywanie adresów czy opisów w Char prowadzi do złego UX — brak łamania linii i ograniczona czytelność. Jeśli spodziewasz się zdań wielowierszowych, wybierz Text.

Zapominanie o tłumaczeniach w polach wielojęzycznych

W firmach międzynarodowych brak translate=True dla pola widocznego dla klientów oznacza, że wszyscy zobaczą tę samą wartość w swoim języku interfejsu — co może prowadzić do nieporozumień na dokumentach klienta.

Używanie Char tam, gdzie powinien być Selection lub relacja

Najczęściej zadawane pytania

Jeżeli pole ma ograniczony zestaw wartości (np. kategoria, status, kraj), lepszym wyborem jest Selection albo relacja Many2one. Zamiast wolnego tekstu z literówkami i wariantami, relacje i wybory zapewniają spójność, ułatwiają grupowanie i raportowanie.

Jaka jest różnica między Char a Text w Odoo?

Char przechowuje krótkie jednolinijkowe teksty i renderuje się jako pole input. Text przechowuje dłuższe, wielolinijkowe treści i renderuje się jako textarea. Użyj Char dla nazw, kodów i referencji; Text dla opisów, notatek i dłuższych wpisów.

Czy mogę ograniczyć liczbę znaków w polu Char?

Tak — w Pythonie ustawiasz size, np. fields.Char(size=64). W Studio określasz limit w panelu właściwości. Jeśli nie ustawisz limitu, baza danych nie wymusi długości.

Jak dodać pole Char do paska wyszukiwania?

Dodaj pole do widoku <search> modelu. W Studio włącz opcję wyszukiwania w panelu właściwości pola. W kodzie umieść <field name="your_char_field"/> wewnątrz definicji <search>. Po dodaniu użytkownicy będą mogli filtrować po tym polu bezpośrednio z paska wyszukiwania.

Czy mogę przechowywać liczby w polu Char?

Technicznie tak, ale nie jest to dobre rozwiązanie tam, gdzie potrzebne są obliczenia lub porównania numeryczne. Użyj Integer/Float do ilości i kwot. Char sprawdza się dla numerów traktowanych jako tekst — kody pocztowe, numery telefonu, IBAN czy numery seryjne.

Jak stworzyć obliczane pole Char, które jest też zapisywane w bazie?

Podsumowanie

Zdefiniuj pole z compute='_compute_my_field' i store=True. Napisz metodę obliczającą i oznacz ją dekoratorem @api.depends(), wskazując pola, które triggerują przeliczenie. Z store=True wartość będzie zapisana i dostępna w filtrach oraz eksportach bez konieczności przeliczania przy każdym odczycie.

Pole Char bywa niedoceniane — większość użytkowników korzysta z dziesiątek takich pól codziennie, nie myśląc o ich specyfice. Tymczasem dobrze dobrane ustawienia i wybór między Char a innymi typami pól wpływają bezpośrednio na jakość modelu danych i wygodę pracy w systemie.

Niezależnie od tego, czy dodajesz referencję klienta przez Studio, definiujesz pole w module Python czy tworzysz je przez API, zasady z tego przewodnika pomogą zrobić to poprawnie już za pierwszym razem.

Solidnie przemyślana struktura danych oparta na właściwych typach pól to fundament udanego wdrożenia Odoo. Pole Char to mały, ale istotny element tej układanki — warto poznać je dobrze. W Dasolo pomagamy firmom wdrażać, dostosowywać i optymalizować Odoo w całej organizacji. Jeśli potrzebujesz pomocy przy projektowaniu modelu danych, dodawaniu pól do procesów biznesowych lub budowie modułu od podstaw, chętnie wesprzemy. Skontaktuj się z nami i porozmawiajmy o Twoim projekcie Odoo.