Documentation • Components V2

V2 Builder

Une petite couche de composition pour construire des interfaces Discord V2 plus nettes, plus cohérentes et beaucoup plus confortables à maintenir. Pensé pour les menus, pages de config, profils, panneaux d'aide et écrans interactifs du bot.

Commencer Voir les exemples

25+helpers exposés

1pattern principal avec wrap()

4zones d'usage majeures dans le bot

100%hors ligne, standalone

Vue d'ensemble

Le builder v2 transforme des blocs simples en objets compatibles avec Discord Components V2. Il standardise le rendu et évite d'écrire à la main des structures JSON répétitives.

Fichier source: utils/v2.js

Ce qu'il fait bien

Structurer des pages avec titres, sections, séparateurs, galeries, miniatures et rangées Discord.js sans perdre en lisibilité côté code.

Le pattern mental

On construit un tableau de blocs, puis on passe ce tableau à v2.wrap() pour l'envoyer dans components.

Menus de config Pages d'aide Profils utilisateurs Confirmations simples Navigation par boutons

Quick Start

Le workflow minimal tient en trois étapes: importer, composer, envoyer.

Le plus utile au quotidien

1. Importer v2.

2. Construire des blocs avec text(), header(), separator(), row()…

3. Retourner v2.wrap(blocks) dans components.

basic.js

const v2 = require("../../utils/v2");
const { MessageFlags } = require("discord.js");

await message.reply({
  flags: MessageFlags.IsComponentsV2,
  components: v2.wrap([
    v2.h1("Mon panneau"),
    v2.separator(),
    v2.text("Bienvenue sur l'interface."),
  ], { accentColor: v2.colors.blurple }),
});

Pattern principal

Le builder devient vraiment agréable quand tu composes les vues comme des blocs successifs, très proches du rendu final.

Composable et lisible

pattern.js

const blocks = [
  v2.h2("Configuration"),
  v2.separatorLg(),
  v2.header("Statut"),
  v2.text("AutoMod: ✅\nLogs: ✅"),
  v2.separator(),
  v2.row(mySelectMenuRow),
];

return v2.wrap(blocks, {
  accentColor: v2.colors.blurple
});

API Texte

Les helpers de base pour afficher du contenu textuel avec une structure claire.

Type 10 principalement

v2.text(content)

Crée un bloc texte brut. C'est la base de presque tout le builder.

v2.h1(text) / h2(text) / h3(text)

Ajoute un titre markdown. Parfait pour les titres de page et sous-sections.

v2.header(text)

Affiche un sous-titre en gras. Très pratique pour découper une page.

v2.italic(text) / bold(text)

Petits helpers de mise en forme pour les messages d'aide, notes et états.

v2.quote(lines)

Construit un bloc cité à partir d'un tableau de lignes, idéal pour des statuts ou résumés.

v2.code(content, lang = "")

Sans langage: inline code. Avec langage: bloc de code multi-lignes.

text-api.js

v2.h1("Dashboard")
v2.header("Paramètres")
v2.text("AutoMod activé")
v2.quote([
  "Prefix: >",
  "Langue: fr",
  "Logs: activés",
])
v2.code("&help")
v2.code("const x = 1;", "js")

API Structure

Ce sont les helpers qui donnent du rythme visuel à la page.

Séparateurs et rows

v2.separator()

Séparateur visuel compact pour découper une zone sans prendre trop de place.

v2.separatorLg()

Version plus ample pour les transitions majeures entre sections.

v2.spacer(spacing = 1)

Ajoute de l'air sans dessiner de trait séparateur.

v2.row(...components)

Sérialise proprement une Action Row Discord.js ou plusieurs composants avec toJSON().

Astuce. Si tu as déjà un ActionRowBuilder, tu peux le passer tel quel à v2.row(existingRow).

API Médias

Pour enrichir visuellement les pages avec miniatures, galeries et fichiers.

Types 11, 12, 13

v2.thumbnail(url, description, spoiler)

Crée une miniature réutilisable, souvent utilisée comme accessoire de section.

v2.gallery(items)

Affiche plusieurs médias à partir d'une liste d'objets contenant au minimum une URL.

v2.galleryFromUrls(urls)

Raccourci pratique si tu n'as qu'une liste d'URLs sans métadonnées.

v2.file(url, spoiler = false)

Ajoute un fichier distant à l'interface V2.

media.js

v2.gallery([
  { url: avatarUrl, description: "Avatar" },
  { url: bannerUrl, description: "Banner" },
])

v2.galleryFromUrls([avatarUrl, bannerUrl])
v2.file("https://example.com/file.png")

Sections & Containers

Le cœur du rendu visuel: sections composées, containers colorés et wrapper final.

Types 9 et 17

v2.section(components, accessory = null)

Construit une section V2. Tu peux y attacher une miniature en accessoire.

v2.sectionWithThumbnail(content, imageUrl, description)

Raccourci pour du texte principal accompagné d'une miniature.

v2.container(components, options)

Encapsule les composants avec une couleur d'accent et éventuellement un spoiler.

v2.wrap(components, options)

Le helper le plus utilisé. Il renvoie directement le tableau prêt pour components.

containers.js

return v2.wrap([
  v2.h2("Profil utilisateur"),
  v2.separatorLg(),
  v2.section(
    [v2.text("Whalebot protège votre serveur.")],
    v2.thumbnail(client.user.displayAvatarURL(), "Avatar du bot")
  ),
], {
  accentColor: v2.colors.blurple
});

Helpers de composition

Ces helpers retournent directement des sous-ensembles de blocs à injecter dans une page.

Productivité

v2.colors

Palette de couleurs embarquée: blurple, green, yellow, red, etc.

v2.titleBlock(title, description, level)

Retourne un ensemble de blocs de titre prêt à étendre avec l'opérateur ....

v2.statusBlock(header, lines)

Combine un en-tête et un bloc quote, utile pour afficher des statuts ou résumés techniques.

v2.editBlock(selectRow)

Bloc standard pour la partie modification d'une page de config.

v2.navBlock(categorySelectRow)

Bloc de navigation pour les changements de catégories.

v2.page(title, sections, editSelectRow, categoryRow, options)

Helper haut niveau pour assembler une page complète avec titre, corps, édition et navigation.

Exemples complets

Des snippets proches de l'usage réel du bot, inspirés des écrans config, help et userinfo.

Usage réel

Page de configuration

config-page.js

return v2.wrap([
  v2.h1("⚙️ Configuration du serveur"),
  v2.separatorLg(),
  v2.header("📊 Statut actuel"),
  v2.text([
    "Prefix: `>`",
    "Langue: `fr`",
    "AutoMod: ✅",
  ].join("\n")),
  v2.separator(),
  v2.italic("Sélectionnez une catégorie ci-dessous."),
  v2.separator(),
  v2.row(categorySelectRow()),
  v2.separator(),
  v2.row(closeRow()),
], { accentColor: v2.colors.blurple });

Fiche utilisateur

userinfo-card.js

const blocks = [];

blocks.push(v2.galleryFromUrls([avatarUrl]));
blocks.push(v2.h2(`${displayName} 🟢`));
blocks.push(v2.text("Membre du serveur depuis 2 ans"));
blocks.push(v2.separator());
blocks.push(v2.header("📋 Informations"));
blocks.push(v2.text([
  `**ID :** \`${user.id}\``,
  `**Créé le :** <t:${Math.floor(user.createdTimestamp / 1000)}:F>`,
].join("\n")));

return v2.wrap(blocks, {
  accentColor: v2.colors.blurple
});

Message de confirmation rapide

simple-update.js

return interaction.update({
  components: v2.wrap([
    v2.text("✅ Menu fermé.")
  ])
});

Notes importantes

Quelques détails qui évitent les bugs les plus fréquents.

À ne pas oublier

Flag V2 requis. Pense à envoyer MessageFlags.IsComponentsV2 quand tu replies avec cette structure.

wrap() renvoie déjà un tableau. Utilise components: v2.wrap([...]), pas un tableau autour.

row() accepte une row existante. Tu peux lui passer un ActionRowBuilder complet.

Helper avatar(). Il existe dans le fichier, mais il est assez atypique et peu aligné avec le reste de l'API actuelle.

Références dans le projet

Les meilleurs exemples vivants du builder dans ce repo.

Codebase

`commands/admin/config.js`

Le plus complet pour voir des pages longues, accent colors, rows et navigation.

`commands/public/help.js`

Très bon exemple de page info, sections et appels à l'action.

`commands/public/userinfo.js`

Montre bien l'usage de galeries, headers, blocs conditionnels et composition dynamique.

`utils/v2.js`

La source officielle, utile pour vérifier exactement la signature de chaque helper.