#Faire un composant de champ personnalisé

Dans NocoBase, les composants de champ servent à afficher et éditer les données dans les tableaux et formulaires. Cet exemple montre comment créer un composant d'affichage de champ personnalisé avec ClickableFieldModel — il ajoute des crochets [] autour de la valeur du champ et est lié à l'interface input.

#Résultat final

Nous allons créer un composant d'affichage de champ personnalisé :

• Étend ClickableFieldModel avec une logique de rendu personnalisée
• Affiche [] autour de la valeur du champ
• Lie le composant à l'interface input (texte sur une ligne) via bindModelToInterface

Une fois le plugin activé, dans un bloc tableau, trouvez la colonne d'un champ texte sur une ligne, cliquez sur le bouton de configuration de la colonne et, dans le menu déroulant « Composant de champ », vous verrez l'option DisplaySimpleFieldModel. En basculant dessus, la valeur sera affichée au format [value].

Code source complet : @nocobase-example/plugin-field-simple. Pour le faire tourner directement en local :

yarn pm enable @nocobase-example/plugin-field-simple

Construisons ce plugin pas à pas, à partir de zéro.

#Étape 1 : créer le squelette du plugin

À la racine du dépôt :

yarn pm create @my-project/plugin-field-simple

Voir Écrire votre premier plugin pour les détails.

#Étape 2 : créer le modèle de champ

Créez src/client-v2/models/DisplaySimpleFieldModel.tsx. C'est le cœur du plugin — il définit le rendu du champ et l'interface à laquelle il est lié.

// src/client-v2/models/DisplaySimpleFieldModel.tsx
import React from 'react';
import { ClickableFieldModel } from '@nocobase/client-v2';
import { DisplayItemModel } from '@nocobase/flow-engine';
import { tExpr } from '../locale';

export class DisplaySimpleFieldModel extends ClickableFieldModel {
  public renderComponent(value: string) {
    // this.context.record permet de récupérer l'enregistrement complet de la ligne courante
    console.log('Enregistrement courant :', this.context.record);
    console.log('Index de l\'enregistrement courant :', this.context.recordIndex);
    return <span>[{value}]</span>;
  }
}

// Définit le nom affiché dans le menu déroulant « Composant de champ »
DisplaySimpleFieldModel.define({
  label: tExpr('Simple field'),
});

// Lie le modèle à l'interface 'input' (texte sur une ligne)
DisplayItemModel.bindModelToInterface('DisplaySimpleFieldModel', ['input']);

Quelques points clés :

• renderComponent(value) — reçoit la valeur courante du champ en paramètre et renvoie le JSX
• this.context.record — récupère l'enregistrement complet de la ligne courante
• this.context.recordIndex — récupère l'index de la ligne courante
• ClickableFieldModel — étend FieldModel avec la capacité d'interaction au clic
• define({ label }) — définit le nom affiché dans le menu déroulant « Composant de champ » ; sans ce label, le nom de classe serait affiché à la place
• DisplayItemModel.bindModelToInterface() — lie le modèle de champ à un type d'interface de champ (par exemple input pour les champs texte sur une ligne) ; ce composant d'affichage devient alors sélectionnable sur les champs du type correspondant

#Étape 3 : ajouter les fichiers de traduction

Modifiez les fichiers de traduction sous src/locale/ du plugin et ajoutez les clés utilisées par tExpr() :

// src/locale/zh-CN.json
{
  "Simple field": "简单字段"
}

// src/locale/en-US.json
{
  "Simple field": "Simple field"
}

Pour l'écriture des fichiers de traduction et plus d'utilisations de tExpr(), voir Internationalisation i18n.

#Étape 4 : enregistrer dans le plugin

Modifiez src/client-v2/plugin.tsx et utilisez registerModelLoaders pour le chargement à la demande :

// src/client-v2/plugin.tsx
import { Plugin } from '@nocobase/client-v2';

export class PluginFieldSimpleClient extends Plugin {
  async load() {
    this.flowEngine.registerModelLoaders({
      DisplaySimpleFieldModel: {
        loader: () => import('./models/DisplaySimpleFieldModel'),
      },
    });
  }
}

export default PluginFieldSimpleClient;

#Étape 5 : activer le plugin

yarn pm enable @my-project/plugin-field-simple

Une fois activé, dans un bloc tableau, trouvez la colonne d'un champ texte sur une ligne, cliquez sur le bouton de configuration de la colonne et, dans le menu déroulant « Composant de champ », vous pourrez basculer vers ce composant d'affichage personnalisé.

#Code source complet

• @nocobase-example/plugin-field-simple — exemple complet de composant de champ personnalisé

#Récapitulatif

Capacités utilisées dans cet exemple :

#Liens connexes

• Écrire votre premier plugin — créer le squelette d'un plugin de zéro
• Aperçu de FlowEngine — utilisation de base de FlowModel
• FlowEngine → Extension de champ — FieldModel, ClickableFieldModel, bindModelToInterface
• FlowEngine → Extension de bloc — bloc personnalisé
• Component vs FlowModel — quand utiliser FlowModel
• Plugin — point d'entrée et cycle de vie load()
• Internationalisation i18n — écriture des fichiers de traduction et utilisation de tExpr
• Documentation complète FlowEngine — référence complète FlowModel, Flow, Context