Introduction
Les champs binaires ne sont pas glamour, mais ils sont omniprésents dans une véritable implémentation d'Odoo. Chaque fois qu'un utilisateur télécharge un contrat signé, joint une fiche produit ou stocke un logo d'entreprise sur un enregistrement, un champ binaire fonctionne en arrière-plan. Comprendre comment il stocke les données, où ces données se retrouvent et quand utiliser un autre type de champ fait une réelle différence lorsque vous construisez des formulaires personnalisés ou étendez les modèles Odoo.
Ce guide couvre ce que le champ binaire stocke, comment le mode de pièce jointe affecte le stockage et les performances, comment le créer et le personnaliser en utilisant Odoo Studio ou Python, et des cas d'utilisation commerciale pratiques dans les domaines du CRM, des RH, de l'inventaire, et plus encore.
Qu'est-ce que le champ binaire dans Odoo
Dans l'ORM Odoo, le champ binaire (fields.Binary) stocke des données binaires brutes : fichiers, documents, images ou tout contenu qu'un utilisateur télécharge sur un enregistrement. Du point de vue de l'utilisateur, cela apparaît comme un bouton de téléchargement de fichier dans les vues de formulaire. Une fois qu'un fichier est joint, le même bouton permet aux utilisateurs de le télécharger d'un simple clic.
Le détail technique le plus important est où ces données se retrouvent réellement. Par défaut, dans les versions modernes d'Odoo, les champs binaires utilisent le mode de pièce jointe. Cela signifie que le contenu du fichier est stocké dans la table ir.attachment et sur le filestore du serveur, et non directement dans la colonne du modèle. La colonne du modèle ne contient qu'un ID de référence pointant vers l'enregistrement de la pièce jointe. Cette approche garde vos tables de base de données principales légères et permet à Odoo de gérer les fichiers de manière efficace.
Dans Odoo Studio, le champ Binaire est étiqueté Fichier dans le sélecteur de champs. Il s'affiche comme un simple contrôle de téléchargement et d'importation dans les vues de formulaire. Pour le contenu d'image spécifiquement, Odoo fournit également un type dédié fields.Image qui ajoute un redimensionnement automatique et un aperçu miniature. Nous aborderons cela dans les sections pertinentes ci-dessous.
Voici à quoi ressemble un champ Binaire dans une définition de modèle Python :
from odoo import fields, models
class ResPartner(models.Model):
_inherit = 'res.partner'
x_signed_contract = fields.Binary(
string='Contrat Signé',
attachment=True,
)
x_signed_contract_filename = fields.Char(
string='Nom de Fichier du Contrat Signé',
)Notez le champ compagnon x_signed_contract_filename de type Char. Associer un champ Binaire avec un champ Char pour le nom de fichier est un modèle de développement standard dans Odoo. Odoo utilise le champ _filename pour se souvenir et afficher le nom de fichier original dans l'interface. Sans cela, les fichiers téléchargés peuvent recevoir un nom générique.
Comment fonctionne le champ
Lorsque vous définissez un champ Binaire dans le modèle de données Odoo, le framework gère automatiquement la création de la colonne lors de l'installation ou de la mise à jour du module. Aucune SQL manuelle n'est nécessaire de votre part.
Modes de Stockage
Le paramètre attachment sur un champ Binaire contrôle où les octets du fichier sont réellement stockés :
- attachment=True (recommandé) : Le contenu du fichier est stocké dans
ir.attachment, lié à l'enregistrement par le nom du modèle et l'ID de l'enregistrement. La colonne du modèle ne contient qu'un ID de référence. Cela garde les tables de modèle petites et exploite le système de stockage de fichiers d'Odoo. - attachment=False : Les données brutes encodées en base64 sont stockées directement dans la colonne de base de données du modèle. Cela fait que les tables deviennent très grandes, ralentissant les requêtes à travers tout le modèle. Évitez ce mode pour tout ce qui est plus grand qu'une petite miniature d'image.
Format de Données
Les champs Binaires stockent et renvoient des données sous forme d'octets encodés en base64. Lorsque vous lisez un champ Binaire via l'ORM Odoo ou l'API XML-RPC, vous recevez une chaîne base64. Lorsque vous y écrivez, vous devez également fournir une chaîne encodée en base64.
En pratique, cela signifie encoder avant d'écrire et décoder après avoir lu :
import base64
# Écriture d'un fichier dans un champ Binaire
avec open('document.pdf', 'rb') comme f:
encodé = base64.b64encode(f.read()).decode('utf-8')
record.write({'x_signed_contract': encodé})
# Lecture d'un fichier depuis un champ Binaire
raw_bytes = base64.b64decode(record.x_signed_contract)Attributs du Champ Clé
Ce sont les attributs les plus importants que vous pouvez configurer sur un champ Binaire dans le framework Odoo :
- attachment : Booléen. Indique s'il faut stocker dans
ir.attachment(Vrai) ou directement dans la colonne (Faux). Par défaut : Vrai dans les versions récentes d'Odoo. - string : Étiquette d'affichage montrée dans l'interface.
- required : Rend le champ obligatoire avant d'enregistrer l'enregistrement.
- compute : Lie une méthode Python pour calculer la valeur du champ dynamiquement, par exemple en générant un PDF à la volée en tant que champ calculé Odoo.
- store : Lorsqu'il est utilisé avec
compute, enregistre la valeur calculée dans la base de données. - groups : Restreint l'accès au champ à des groupes d'utilisateurs Odoo spécifiques. Important pour les documents sensibles.
- copy : Contrôle si la valeur est dupliquée lors de la copie d'un enregistrement. Les valeurs par défaut varient en fonction du mode d'attachement et de la version d'Odoo.
La Sous-classe fields.Image
fields.Image est une sous-classe spécialisée de fields.Binary introduite dans Odoo 13. Elle ajoute un redimensionnement automatique des images à une dimension maximale configurable, une taille d'aperçu optionnelle pour les vignettes, et rend un aperçu d'image approprié dans les vues de formulaire. Pour stocker des images de produits, des photos de partenaires, des logos d'entreprise ou tout contenu visuel, utilisez fields.Image plutôt qu'un champ Binaire classique. Cela empêche les téléchargements excessivement volumineux et offre une bien meilleure expérience utilisateur pour les données d'image.
Comment cela apparaît dans les vues
Dans les vues de formulaire, le widget par défaut pour un champ binaire est un bouton de téléchargement et de téléchargement. Pour le contenu image, appliquez le widget image pour obtenir un aperçu miniature à la place. Dans les vues de liste, les champs binaires ne sont généralement pas affichés directement car le chargement du contenu complet des fichiers pour chaque ligne visible crée un transfert de données inutile. L'approche standard consiste à afficher un indicateur booléen ou une icône dans les vues de liste pour signaler si un fichier est joint.
Cas d'utilisation commerciale
Le champ binaire apparaît dans de nombreux modules Odoo dans des mises en œuvre réelles. Voici cinq exemples pratiques issus de flux de travail commerciaux courants.
CRM : Stockage des NDA ou contrats signés sur les dossiers clients
De nombreuses entreprises ont besoin de joindre un document signé directement à un dossier client ou prospect dans Odoo CRM. Un champ binaire sur res.partner ou crm.lead donne aux équipes de vente un accès en un clic au contrat pertinent sans quitter l'interface Odoo. Cela élimine le besoin d'un outil de gestion de documents séparé pour le stockage de fichiers de base, et cela garde l'information exactement là où l'équipe s'attend à la trouver pendant le processus de vente.
RH : Stockage de documents des employés
Les départements RH ont régulièrement besoin de stocker des copies de documents d'identité des employés, de permis de travail, de contrats de travail signés ou de certificats de formation. Un champ binaire sur hr.employee stocke ces fichiers en toute sécurité dans le système de contrôle d'accès d'Odoo. En utilisant l'attribut groups, vous pouvez restreindre la visibilité afin que seuls les responsables RH puissent voir les documents sensibles, tandis que d'autres responsables voient le formulaire sans accéder aux fichiers réels. C'est une demande de personnalisation Odoo courante dans les entreprises ayant des exigences strictes en matière de confidentialité des données.
Inventaire : Fiches de spécifications des produits et données de sécurité
Les produits techniques sont souvent accompagnés de fiches de spécifications PDF, de fiches de données de sécurité ou de certificats de qualité du fabricant. Un champ binaire sur product.template permet aux équipes d'approvisionnement et au personnel d'entrepôt d'accéder à la documentation appropriée directement à partir de l'enregistrement du produit dans Odoo. C'est l'une des ajouts de personnalisation Odoo les plus fréquemment demandés dans les entreprises de fabrication et de distribution, et il est simple à mettre en œuvre avec Odoo Studio ou un module Python personnalisé.
Ventes : Image du tampon de l'entreprise ou de la signature autorisée
Certains contextes commerciaux nécessitent un tampon d'entreprise ou une signature autorisée sur les devis imprimés ou les confirmations de commande. Un champ fields.Image sur res.company stocke cet actif visuel, qui peut ensuite être référencé dans un modèle de rapport QWeb. Cela permet aux documents imprimés d'inclure automatiquement le tampon sans aucune manipulation manuelle par document, ce qui permet de gagner du temps dans les opérations de vente à fort volume et réduit le risque d'envoyer accidentellement des devis non signés.
Comptabilité : Pièce jointe de reçu scanné sur les dossiers de dépenses
Les flux de travail de gestion des dépenses nécessitent généralement de joindre un reçu ou une facture scanné à chaque enregistrement de dépense comme preuve pour le remboursement. Pour les dépenses standard d'Odoo, le système de pièces jointes gère cela nativement. Mais sur des modèles de dépenses personnalisés, des flux de travail de factures fournisseurs ou des intégrations tierces, un champ Binaire offre un moyen propre de stocker l'image ou le PDF du reçu directement sur l'enregistrement et de l'inclure dans la logique de routage d'approbation sans dépendre du panneau de pièces jointes générique.
Créer ou personnaliser le champ binaire
Il existe trois principales façons d'ajouter un champ Binaire à un modèle Odoo, en fonction de votre contexte technique et du niveau de contrôle dont vous avez besoin.
Utiliser Odoo Studio (Sans Code)
Odoo Studio est l'outil de personnalisation low-code intégré. Pour ajouter un champ Binaire sans écrire de code :
- Ouvrez Odoo Studio depuis le menu principal.
- Naviguez vers le formulaire où vous souhaitez ajouter le champ.
- Faites glisser un champ Fichier depuis le sélecteur de champs vers le formulaire.
- Définissez l'étiquette et toutes les conditions de visibilité optionnelles dans le panneau des propriétés.
- Enregistrez et fermez Studio.
Studio crée le champ avec un préfixe x_studio_ et utilise automatiquement le mode de pièce jointe. Aucune configuration de base de données n'est nécessaire de votre part. C'est l'un des champs Odoo studio les plus accessibles pour les utilisateurs professionnels qui ont besoin de la capacité de téléchargement de fichiers sur leurs formulaires sans l'intervention d'un développeur.
Utiliser Python dans un Module Personnalisé
Pour le développement Odoo qui doit être contrôlé par version et déployé sur plusieurs environnements, l'approche standard consiste à définir des champs Binaires directement en Python. C'est l'approche recommandée dans tout guide de développeur Odoo pour un travail de personnalisation Odoo sérieux :
from odoo import fields, models
class HrEmployee(models.Model):
_inherit = 'hr.employee'
x_id_document = fields.Binary(
string='Document d'identité',
attachment=True,
groups='hr.group_hr_user',
)
x_id_document_filename = fields.Char(
string='Nom de fichier du document d'identité',
)Après avoir ajouté le champ au modèle, incluez-le dans la vue de formulaire XML avec le widget binary et l'attribut filename pointant vers le champ Char compagnon. Odoo gère automatiquement la colonne de base de données lors de l'installation ou de la mise à niveau du module. Cette approche fonctionne proprement sur tous les types de déploiement Odoo, y compris Odoo.sh et les installations sur site.
Utilisation de l'API XML-RPC
Si vous gérez la création de champs Odoo par programmation, par exemple via un script de configuration à distance ou un carnet de déploiement, vous pouvez créer des champs Binary via l'API XML-RPC :
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_custom_document',
'field_description': 'Document personnalisé',
'model_id': model_id,
'ttype': 'binary',
'state': 'manual',
}]
)La valeur state: manual indique à Odoo que ce champ a été créé manuellement plutôt que installé par un module. Les champs créés via l'API utilisent le mode d'attachement par défaut dans les versions actuelles d'Odoo. C'est l'approche utilisée dans les scripts de configuration Odoo automatisés et les flux de travail de déploiement à distance.
Meilleures pratiques
1. Utilisez toujours attachment=True
À moins que vous n'ayez une raison technique très spécifique de stocker le contenu des fichiers directement dans la colonne de la base de données, utilisez le mode d'attachement. Cela garde les tables de modèle petites, empêche les requêtes lentes et permet à Odoo de gérer les fichiers via son filestore intégré. C'est également le comportement par défaut dans les versions récentes, donc omettre simplement le paramètre attachment suffit dans la plupart des cas. Pour tout fichier plus grand qu'une petite vignette, le mode d'attachement n'est pas optionnel.
2. Associez les champs Binary avec un champ Char de nom de fichier
Ajoutez toujours un champ Char compagnon _filename à côté de tout champ Binary utilisé dans une vue de formulaire. Sans cela, le widget de téléchargement de fichiers ne peut pas afficher ou restaurer le nom de fichier d'origine, et les utilisateurs qui téléchargent le fichier se retrouvent avec un nom générique comme download. Cette petite addition prend une ligne de code et fait une différence notable dans l'expérience utilisateur du formulaire.
3. Utilisez fields.Image pour le contenu visuel
Si vous stockez des photos de produits, des portraits de partenaires, des logos d'entreprise ou d'autres images, utilisez fields.Image au lieu d'un champ Binary classique. Cela limite automatiquement la taille de téléchargement aux dimensions maximales configurées, rend une vignette dans l'interface et inclut un champ séparé pour l'image de prévisualisation redimensionnée. Utiliser le bon type de champ pour le bon contenu est un principe fondamental dans la conception d'un modèle de données Odoo propre.
4. Restreindre l'accès avec le paramètre groupes
Les champs binaires qui stockent des documents sensibles tels que des dossiers d'employés, des contrats signés ou des dossiers financiers doivent définir des restrictions d'accès en utilisant le paramètre groups. Cela limite qui peut lire ou écrire dans le champ, ce qui est important tant pour la confidentialité des données que pour les exigences de traçabilité dans des environnements réglementés.
5. Manipuler l'encodage base64 avec soin dans le code
Lors de la lecture ou de l'écriture de champs binaires par programmation, il est toujours nécessaire de gérer explicitement l'encodage base64. Utilisez base64.b64encode(file_bytes).decode('utf-8') pour convertir les octets avant l'écriture, et base64.b64decode(field_value) pour convertir à nouveau en octets après la lecture. Ne supposez pas que les données sont déjà dans le format dont vous avez besoin. C'est une source courante de bogues dans les intégrations Odoo ORM qui ne se manifestent que lorsque de vrais fichiers sont traités.
Pièges courants
Définir attachment=False pour les gros fichiers
Stocker le contenu des fichiers directement dans une colonne de base de données peut considérablement gonfler vos tables PostgreSQL. Quelques dizaines de documents PDF stockés avec attachment=False peuvent ajouter des centaines de mégaoctets à une seule table de modèle, ralentissant chaque requête sur ce modèle. C'est l'une des erreurs de configuration les plus impactantes dans la gestion des bases de données Odoo. Une fois les données stockées de cette manière et que la table devient grande, la migration vers le mode d'attachement nécessite un script personnalisé et une planification minutieuse.
Oublier le champ compagnon pour le nom de fichier
Sans un champ Char associé pour le nom de fichier, les utilisateurs qui téléchargent un fichier à partir d'un champ binaire obtiennent souvent un nom de fichier générique. C'est un petit mais persistant problème qui donne l'impression que l'implémentation est inachevée. Ajouter le champ compagnon prend moins d'une minute et devrait faire partie de toute définition de champ binaire qui apparaît dans une vue de formulaire destinée aux utilisateurs.
Confondre les champs Binaire et Image
Utiliser un champ binaire simple pour le contenu d'image manque le redimensionnement automatique et le rendu des vignettes que fields.Image fournit. Les utilisateurs peuvent télécharger des fichiers image très volumineux qui ralentissent le chargement des formulaires et consomment un espace de stockage inutile. Inversement, utiliser fields.Image pour des fichiers non-image comme des PDF provoque des erreurs car Odoo essaie de traiter le contenu comme une image. La règle est simple : associez le type de champ au type de contenu attendu.
Inclure des champs binaires directement dans les vues de liste
Ajouter un champ binaire à une vue de liste amène Odoo à charger le contenu complet du fichier pour chaque ligne visible. Pour une liste de cinquante enregistrements, cela peut signifier le transfert de mégaoctets de données juste pour rendre la page. Si vous devez indiquer la présence d'un fichier dans une vue de liste, utilisez un champ booléen calculé ou un bouton d'icône au lieu du champ binaire directement. C'est un problème de performance courant dans les implémentations Odoo qui ne devient visible qu'à des volumes de données réels.
Ne pas vérifier pour False avant de traiter dans le code
Un champ Binaire sans valeur renvoie False en Python, pas une chaîne vide et pas des octets vides. Si vous essayez de décoder une valeur de champ Binaire sans vérifier d'abord pour False, vous obtenez une TypeError qui fait planter la méthode. Protégez toujours avec : if record.x_document: data = base64.b64decode(record.x_document). Cela est important dans les méthodes de calcul, les actions serveur et tout code qui traite des valeurs Binaires de manière conditionnelle.
Conclusion
Le champ Binaire est une partie simple mais importante du modèle de données Odoo. Il gère le stockage de fichiers et de documents d'une manière qui s'intègre naturellement avec l'interface d'Odoo, son système de pièces jointes et son cadre de contrôle d'accès.
Les principales habitudes à développer : utilisez toujours le mode pièce jointe, associez les champs Binaires avec un champ Char pour le nom de fichier, choisissez fields.Image pour le contenu visuel, restreignez l'accès pour les documents sensibles et gérez soigneusement l'encodage base64 dans le code personnalisé. Ces pratiques empêchent les problèmes les plus courants avant qu'ils n'aient la chance de se manifester en production.
Que vous ajoutiez un champ de téléchargement de fichiers via Odoo Studio, construisiez un module Python personnalisé ou gériez la création de champs via l'ORM Odoo ou l'API XML-RPC, bien gérer les champs Binaires dès le départ conduit à une mise en œuvre Odoo plus propre et plus fiable dans l'ensemble.
Chez Dasolo, nous aidons les entreprises à mettre en œuvre, personnaliser et optimiser Odoo dans tous les départements. Que vous ayez besoin d'aide pour concevoir un modèle de données avec les bons types de champs, construire des flux de travail de gestion de fichiers personnalisés ou développer un module Odoo complet, notre équipe est là pour vous soutenir. Contactez-nous et parlons de votre projet Odoo.