Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Personnalisation

Personnaliser les boutons et badges

Créer dans un script client des boutons et des badges au style de l'interface avec les helpers frappe.ui.button et frappe.ui.badge.

Personnaliser les boutons et badges

Cette page s'adresse aux développeurs et aux administrateurs qui écrivent des scripts client. Les helpers frappe.ui.button et frappe.ui.badge créent des boutons et des badges au style de l'interface (classes es-button et es-badge).

Chaque helper existe sous deux formes :

frappe.ui.button(opts) et frappe.ui.badge(opts) renvoient un élément jQuery.
frappe.ui.button.html(opts) et frappe.ui.badge.html(opts) renvoient le code HTML, à insérer dans un modèle.

Les textes sont échappés. Traduisez-les avant de les passer, avec __().

Options des boutons

Option	Valeurs	Rôle
`label`	texte	Texte du bouton.
`variant`	`solid`, `subtle` (défaut), `outline`, `ghost`	Style du bouton. `solid` sert à l'action principale.
`theme`	`gray` (défaut), `red`	`red` signale une action destructive.
`size`	`xs`, `sm` (défaut), `md`, `lg`	Taille.
`icon` ou `icon_left`, `icon_right`	nom d'icône Lucide	Icône avant ou après le texte. Un bouton sans texte devient un bouton-icône : donnez-lui un `tooltip` ou un `title`.
`tooltip`, `title`	texte	Info-bulle.
`href`	URL	Affiche un lien avec l'apparence d'un bouton.
`disabled`, `loading`	booléen	Bouton désactivé, ou en cours de traitement (indicateur de chargement).
`loading_label`	texte	Texte pendant le traitement. Par défaut pour « Enregistrer », « Supprimer » et « Valider ».
`onclick`	fonction	Action du clic (forme jQuery uniquement). Si la fonction renvoie une promesse, le bouton reste occupé jusqu'à sa fin.
`css_class`, `attrs`	texte, objet	Classes et attributs supplémentaires.

Options des badges

Option	Valeurs	Rôle
`label`	texte	Texte du badge.
`theme`	`gray` (défaut), `blue`, `green`, `amber` (ou `orange`), `red`, `violet`	Couleur.
`variant`	`solid`, `subtle` (défaut), `outline`, `ghost`	Style.
`size`	`sm`, `md` (défaut), `lg`	Taille.
`icon` ou `icon_left`, `icon_right`	nom d'icône Lucide	Icône avant ou après le texte.
`title`	texte	Info-bulle.
`css_class`, `label_class`, `attrs`	texte, objet	Classes et attributs supplémentaires.

Exemple

Exemple fictif. Un type de document personnalisé « Demande d'achat interne » a un champ Statut et une méthode serveur mon_app.api.relancer. Le script client ajoute un badge de statut et un bouton de relance.

frappe.ui.form.on("Demande d'achat interne", {
    refresh(frm) {
        const valide = frm.doc.statut === "Validé";
        frm.dashboard.set_headline(
            frappe.ui.badge.html({
                label: valide ? __("Validé") : __("En attente"),
                theme: valide ? "green" : "amber",
                icon: valide ? "check" : "clock",
            })
        );

        if (!valide) {
            const section = frm.dashboard.add_section("", __("Actions"));
            frappe.ui
                .button({
                    label: __("Relancer"),
                    variant: "solid",
                    icon: "send",
                    onclick: () => frappe.xcall("mon_app.api.relancer", { name: frm.doc.name }),
                })
                .appendTo(section);
        }
    },
});

Pendant l'appel à mon_app.api.relancer, le bouton affiche un indicateur de chargement et ignore les nouveaux clics.

Pour ajouter un bouton dans la barre du formulaire, utilisez plutôt frm.add_custom_button(__("Relancer"), action, __("Groupe")).