Groupe d'avatars

Le composant frappe.ui.avatar_group affiche une série d'avatars qui se chevauchent. Il limite le nombre d'avatars visibles et ajoute un cercle « +N » pour le reste. Vous pouvez l'utiliser pour représenter des personnes affectées à une tâche, des spectateurs d'un document ou des destinataires d'un partage.

Prérequis

• frappe.ui.avatar_group est disponible côté navigateur dans le desk Dodock.
• Les options de chaque avatar correspondent à celles de frappe.ui.avatar (label, image, theme, title, indicator).

Appeler le composant

Forme jQuery

frappe.ui.avatar_group(opts) renvoie un élément jQuery interactif. C'est la forme à privilégier pour le desk et les pages construites en jQuery.

const $group = frappe.ui.avatar_group({
    avatars: [
        { label: "Camille Martin", image: "/assets/camille.jpg" },
        { label: "Idris Benali" },
        { label: "Sara Lemoine" },
        { label: "Léa Costa" },
        { label: "Yan Girard" },
    ],
    max: 3,
    size: "md",
    shape: "circle",
    theme: "auto",
    onclick: (avatar, e) => {
        frappe.ui.toast({ message: `Clic sur ${avatar.label}` });
    },
});
$("#mon-conteneur").append($group);

Forme HTML

frappe.ui.avatar_group.html(opts) renvoie une chaîne de balisage, sans gestionnaires d'événements ni info-bulles enrichies. C'est utile dans les vues de liste ou les colonnes Kanban où l'interface est construite à partir de chaînes HTML.

const html = frappe.ui.avatar_group.html({
    avatars: users.map((u) => {
        const { fullname, image } = frappe.user_info(u);
        return {
            label: fullname,
            image,
            css_class: "filterable",
            attrs: { "data-filter": `_assign,like,%${u}%` },
        };
    }),
    max: 4,
    size: "md",
});

Options

Comportements clés

Débordement « +N »

Au-delà de max avatars, un cercle « +N » indique combien de personnes sont masquées. Si une seule personne est masquée, le composant affiche son avatar plutôt qu'un « +1 ». En lecture seule, la liste détaillée s'ouvre au survol et se ferme quand le pointeur quitte la zone. Avec onclick, la liste s'ouvre au clic et chaque ligne déclenche l'action.

Thème automatique

Le thème "auto" calcule une couleur à partir du libellé. Un même nom obtient toujours la même couleur, sans configuration supplémentaire. Un thème explicite sur un avatar ou sur le groupe passe avant "auto".

Bouton d'ajout

L'option add ajoute un bouton à la fin du groupe. Il peut servir à affecter une nouvelle personne ou à ouvrir un dialogue. Le bouton est masqué si add n'est pas fourni.

Accessibilité

Quand onclick est fourni, les avatars deviennent des éléments <button> et la liste « +N » s'ouvre au clic. Sans onclick, la liste est en lecture seule : le cercle « +N » reçoit un attribut tabindex et un aria-label listant les noms masqués, de façon à rester accessible au clavier et aux lecteurs d'écran. La carte de survol (hover_card) n'est pas accessible au toucher : prévoyez un autre moyen d'accès pour toute action essentielle.

Exemples

Bouton d'affectation

frappe.ui.avatar_group({
    avatars: assignees,
    add: {
        title: __("Affecter"),
        onclick: () => ouvrir_dialogue_affectation(),
    },
});

Carte de survol personnalisée

frappe.ui.avatar_group({
    avatars: viewers,
    hover_card: (avatar, card) => {
        const $card = $('<div class="flex gap-3 items-center"></div>');
        $card.append(
            frappe.ui.avatar({ ...avatar, size: "xl" }),
            $('<div></div>').append(
                $('<div class="text-base-medium text-ink-gray-8"></div>').text(avatar.label),
                $('<div class="text-sm text-ink-gray-5"></div>').text("En cours de consultation")
            )
        );
        return $card;
    },
});